DoomWare API

Scripts and Functions

The following contains a list of scripts and functions which you can use to assist you during the development of new minigames for DoomWare.

Minigame Functions

The following scripts are to be used to handle basic minigame logic.

Name	Type	Arguments	Return	Description
DoomWare_Server_GameWait	Script	int time	-	Sets the minigame timer to `time`.
DoomWare_Server_TeleportPlayers	Script	int tid bool telesector bool fog	-	Teleports all the players to `tid`. If `telesector` is enabled, the TeleportInSector method will be used. Otherwise, players will be teleported to individual TID's. Enabling `fog` will enable the teleport effect+sound
DoomWare_Server_TeleportSingle	Script	int plynum int destination	-	Teleports a player with PlayerNumber `plynum` to the destination with ThingID `destination`
DoomWare_Server_ReturnPlayers	Script	bool fog	-	Returns all teleported players back to the main lobby. If `fog` is enabled, then a teleport effect+sound will be emitted.

Player Manipulation

The following functions are used to manipulate player states and abilities.

Name	Type	Arguments	Return	Description
Player_Win	Function	int plynum	-	Makes the player with PlayerNumber `plynum` win the current minigame.
Player_Lose	Function	int plynum bool silent	-	Makes the player with PlayerNumber `plynum` lose the current minigame.
Player_SavePosition	Function	int plynum	-	Saves the position of the player with PlayerNumber `plynum` (Used internally by `DoomWare_Server_TeleportPlayers`).
Player_InvalidatePosition	Function	int plynum	-	Clears the stored position of the player with PlayerNumber `plynum`.
Player_Morph	Function	int plynum str class	-	Morphs the player with PlayerNumber `plynum` into the actor `class`.
Player_FreezeTotally	Function	int who	-	Freezes the player totally. Set `who` to 1 to affect all players, or 0 to affect the activator.
Player_UnFreezeTotally	Function	int who	-	Unfreezes the player totally. Set `who` to 1 to affect all players, or 0 to affect the activator.
Give_Achievement	Function	int plynum int achievement	-	Gives the player with PlayerNumber `plynum` the achievement with id `achievement`.

Player Information

The following functions are used to retrieve information about players.

Name	Type	Arguments	Return	Description
Check_LMS	Function	-	-	Iterates through all players and checks if there is only one last man standing. If so, automtically calls `Player_Win` on them.
Check_WonRoundItem	Function	-	-	Iterates through all players and calls `Player_Win` on the ones who have `"WonRoundItem"` in their inventory.
Check_FailRoundItem	Function	-	-	Iterates through all players and calls `Player_Lose` on the ones who have `"FailRoundItem"` in their inventory.
Check_Player_Won	Function	int plynum	bool	Checks if the player with PlayerNumber `plynum` has won this round.
Check_Player_Lost	Function	int plynum	bool	Checks if the player with PlayerNumber `plynum` has lost this round.

Observer System

The following functions relate to the observer system

Name	Type	Arguments	Return	Description
Add_Observer	Function	int TID	-	Adds a camera with ThingID `TID` to the observers list.
Force_Observe	Function	int plynum	-	Forces the player with PlayerNumber `plynum` to use the observers camera. At least one camera needs to be in the observers list for this to work!

Miscellaneous

The following functions don't fit in any other category, but can otherwise prove useful.

Name	Type	Arguments	Return	Description
Calc_Speed	Function	int xvel int yvel	int	Returns the speed from the given x and y velocities `xvel` & `yvel`. The returned value is in Fixed Point format.
Distance	Function	int tid1 int tid2	int	Returns the distance between the actor with `tid1` and `tid2` as an integer.
Max	Function	int a int b	int	Returns the largest number between `a` and `b`.
Abs	Function	int n	int	Returns the absolute value of `n`.
AToI	Function	str s	int	Converts the string `s` to an integer.
SpawnSpotForcedEx	Function	str class int spottid int tid int angle	void	Works exactly like SpawnSpotForced, but applies Wacky Mods to monsters. Click here for more info.
SpawnSpotFacingForcedEx	Function	str class int spottid int tid	void	See above

DECORATE

The following scripts are solely used in DECORATE.

Name	Type	Arguments	Return	Description
DoomWare_Entity_MarkCleanup	Script	-	-	Changes the calling entity's ThingID to `TID_REMOVE`.
DoomWare_Entity_CheckCleanup	Script	-	-	Checks if a minigame is ocurring, and if it isn't, it removes the calling entity. This is needed because sometimes the initial `TID_REMOVE` cleanup fails.

Global Variables

The following contains a list of global variables which you can modify during the execution of your minigame.

Minigame Settings

These global variables should be used to modify minigame settings. Best used in a SERVER script and treated as READ ONLY on CLIENT scripts.

Name	Type	Default	Description
round_winifmid	bool	`false`	Do players win if they're in the midround array? See How a Minigame Works for more information.
round_winifsuicide	bool	`false`	Do players win by dying?
round_noforceend	bool	`false`	Should this game not end early if everyone won/lost?
round_forceobservers	bool	`false`	Does this game require observation (like sidescrolling games)? Used to ensure compatibility with solo play.
minigame_wincondition1	int	`0`	Generic variable for minigames.
minigame_wincondition2	int	`0`	Generic variable for minigames.
minigame_wincondition3	int	`0`	Generic variable for minigames.
minigame_fragpoints	bool	`false`	Can you get points for frags?
minigame_invisiblehats	bool	`false`	Should this minigame hide the player hats?

Player Specific

These global variables are all arrays with a size of MAXPLAYERS, meaning they're specific per player, therefore should be used in a CLIENT script.

Name	Type	Default	Description
minigame_instruction1	str	`""`	Instructions to display about the current minigame.
minigame_instruction2	str	`""`	More instructions to display (best used for clarifying controls).
minigame_instruction3	str	`""`	Even more instructions to display.
player_answer1	int	`0`	A generic player variable for minigames.
player_answer2[4]	int	`{0, 0, 0, 0}`	A generic player variable for minigames, but can store more than one value.
player_viewsprite	str	`""`	A sprite lump to display on the player's HUD, as if it were a fake weapon.

Internal Functions and Scripts

This section contains a list of internal functions and scripts used by DoomWare. You should have very little reason to use them, but they're here for documentation's sake.

Server Logic

The following scripts and functions relate to the initialization of the gamemode, as well as the main gamemode logic.

Name	Type	Arguments	Return	Description
DoomWare_Server_Boot	Script	-	-	Called when the map starts. Initializes some gamemode states and waits for players to join.
DoomWare_Server_Initialize	Script	-	-	Called after two players join or solo play starts. Initializes the rest of the gamemode and creates "threads".
DoomWare_Server_InitMap	Script	-	-	Initializes the map.
DoomWare_Server_InitHints	Script	-	-	Initializes the list of hints to display during speedup.
DoomWare_Server_InitRounds	Script	-	-	Initializes the list of minigames to play.
DoomWare_Server_InitHighscores	Script	-	-	Initializes the highscore table.
DoomWare_Server_InitGlobals	Script	-	-	Initializes all the global variables.
DoomWare_Server_InitWackymods	Script	-	-	Initializes the wacky modifiers.
DoomWare_Server_GameLogic	Script	-	-	Main game logic "thread".
DoomWare_Server_SyncGlobals	Script	-	-	Global variable networking "thread".
255	Script	-	int lineid int angle	Makes the arena wall with ID `lineid` bounce players in the angle `angle`.

Randomization

In order to make the random number generation "feel" more random, DoomWare implemented weighted random sampling for minigame and wackymod selection, as well as shufflebags for selecting when wacky rounds occur. The following RNG functions exist:

Name	Type	Arguments	Return	Description
DoomWare_InitRNG	Function	-	-	Initializes all the RNG stuff.
DoomWare_WRng_Minigames	Function	int totalrounds	-	Fills the round_current array with MAXROUNDS games, using weighted RNG.
DoomWare_WRng_1v1	Function	-	int	Returns a randomly (weighted) selected value from the 1v1 minigames.
DoomWare_WRng_1vM	Function	-	int	Returns a randomly (weighted) selected value from the 1vM minigames.
DoomWare_WRng_WackyMod	Function	-	int	Returns a randomly (weighted) selected value from the WackyMods.
DoomWare_SBagShuffle_NextWacky	Function	-	-	Shuffles the nextwacky shufflebag.
DoomWare_SBagNext_NextWacky	Function	-	int	Gets the next value in the nextwacky shufflebag.

Client Logic

The following scripts relate to the initialization of the player, as well as the main player gamemode logic.

Name	Type	Arguments	Return	Description
DoomWare_Client_Join	Script	-	-	Called when a player joins. Initializes the player and creates "threads".
DoomWare_Client_Initialize	Script	-	-	Initializes variables related to the player.
DoomWare_Client_InitializeMap	Script	-	-	Initializes parts of the map that only work CLIENTSIDE in Multiplayer.
DoomWare_Client_Death	Script	-	-	Called when a player dies. Awards or punishes the player during a minigame.
DoomWare_Client_Disconnect	Script	int gone	-	Called when the player with PlayerNumber `gone` leaves. Cleans up after them.
DoomWare_Client_Respawn	Script	-	-	Called when a player respawns. Clears their inventory, resets their TID, and performs other fixes.
DoomWare_Client_GameLogic	Script	-	-	Main client gamemode logic "thread".
DoomWare_Client_DrawHUD	Script	-	-	HUD drawing "thread".
DoomWare_Client_HUDStatusBars	Function	int CurrentRound int hud_time int hud_spindex int status_w int status_h bool diedinround	-	Handles drawing STATUSBARs in throwback minigames.

Checking Functions

The following functions are used for checking various gamemode states

Name	Type	Arguments	Return	Description
Should_Speedup	Function	-	bool	Checks if we should speedup this round.
Should_TieBreak	Function	-	bool	Checks if we should tiebreak this round.
Is_1v1_TieBreaker	Function	-	bool	Returns if (and only if) the players in first and second place are tied.
No_MidRound_Array	Function	-	bool	Checks if every player has either won or lost the minigame.

Wackymods

The following scripts and functions handle wacky modifier logic.

Name	Type	Arguments	Return	Description
Player_SetWackymod	Function	int plynum	-	Sets the wacky modifier on the player with PlayerNumber `plynum`.
DoomWare_WackyMod_DoubleJump	Script	-	-	A "thread" which handles double jumping on the activator.

Data Networking

The following functions relate to the networking of global variables to CLIENTSIDE scripts.

Name	Type	Arguments	Return	Description
Player_SetCVar	Function	str cvar int value	-	Calls SetCVar on the CVar with name `cvar` only if its value `value` changed.
Player_SetCVarString	Function	str cvar str value	-	Calls SetCVarString on the CVar with name `cvar` only if its value `value` changed.
Pack_Global_Array	Function	str cvar	-	Packs the data relevant to the CVar `cvar` into a string and calls SetCVarString only if its value changed.
Unpack_CVar_Array	Function	str cvar	int	Unpacks the integer data in CVar `cvar` and returns only the data relevant to the activator .
Unpack_CVar_Array_String	Function	str cvar	str	Unpacks the string data in CVar `cvar` and returns only the data relevant to the activator.

Database Handling

The following scripts and functions relate to [player stat tracking](Player-Stats).

Name	Type	Arguments	Return	Description
Load_PlayerDB	Function	int plynum	-	Loads the database of the player with PlayerNumber `plynum`.
DB_NetworkStats	Function	str namespace str cvarname	-	Networks the stats in `namespace` to the CVar that ends with the name `cvarname`.
DoomWare_Server_UpdateDB	Script	-	-	Updates the player database with this rounds' stats.

Highscore Table

The following scripts handle the highscore table.

Name	Type	Arguments	Return	Description
257	Script	-	-	Called when the player presses their highscore table bind.
DoomWare_Server_CalcHighscore	Script	-	-	A "thread" which continually updates the highscore table.
DoomWare_Client_DrawHighscore	Script	-	-	Draws the highscore table for the activator.

Observer System

The following scripts handle the observer system.

Name	Type	Arguments	Return	Description
988	Script	-	-	Called when the player presses their observe minigame bind.
DoomWare_Server_ClearObservers	Script	-	-	Clears the observers array and stops people from observing after a minigame ends.

DoomWare Menu

The following scripts are related to the DoomWare menu.

Name	Type	Arguments	Return	Description
999	Script	-	-	Called when the player presses their observe minigame bind.
DoomWare_Client_DrawMenu	Script	-	-	Draws the DoomWare menu for the activator.
Handle_Menu_Option	Function	int number str command str desc int plynum int mouse_x int mouse_y int w int h	-	Handles drawing and clicking of the menu option linked to the CVar `command`. `number` is the number of the option. `desc` is the description of the CVar. `plynum` is the PlayerNumber of the activator. `mouse_x` and `mouse_y` is the mouse's X and Y position. `w`and `h` is the button's size.
Handle_Menu_Achievement	Function	int achieve_data int number str name str desc str sprite int plynum int mouse_x int mouse_y int w int h	-	Handles the drawing of the achievement with ID `number`. `achieve_data` is the players' achievement bit field. `name` and `desc` is the name and description of the achievement. `sprite` is the achievement sprite lump name. `plynum` is the PlayerNumber of the activator. `mouse_x` and `mouse_y` is the mouse's X and Y position. `w`and `h` is the button's size.

Player Hats

The following scripts and functions handle player hats.

Name	Type	Arguments	Return	Description
IsBetaTester	Function	int plynum	bool	Returns whether the player with PlayerNumber plynum was a beta tester.
DoomWare_Server_Hats	Script	-	-	A "thread" that handles all the player hats.

Miscellaneous

The following scripts did not fit into any other category, but are used in some way by the gamemode.

Name	Type	Arguments	Return	Description
DoomWare_Entity_Cleanup	Script	-	-	Removes all actors with ThingID `TID_REMOVE`.
DoomWare_Entity_SetPlayerTranslation	Script	-	-	Applies translation colors to morphed actors based on the activator's player color.
DoomWare_DoLightning	Script	-	-	A "thread" which handles the skybox lightning during halloween mode.
DoomWare_AchievementLog	Script	int plynum int achievement	-	Prints that the player with PlayerNumber `plynum` obtained the achievement with name `achievement`.

Internal Global Variables

This section contains a list of internal global variables used by DoomWare. Modifying these variables during gameplay can cause undefined behaviour, therefore they should be treated as READ ONLY.

Gamemode State

The following global variables contain information about the gamemode's state:

Name	Type	Description
game_scoreteams[MAXTEAMS]	int	A list of each team's score.
game_extrascoreteams[MAXTEAMS+1]	int	A list of each team's extra score (in case a team member disconnected).
game_highscores[MAXPLAYERS]	int	The global highscore table sorted by winner first.
game_highnames[MAXPLAYERS]	int	The global highscore table of player names sorted by winner first.
game_roundnum	int	A number containing the current round.
game_status	int	A number containing the status of the gamemode's logic, typically one of the `STATUS_` macros.
game_speed	int	A value that represents how fast the gamemode is going, ranging from 0 to `MAXSPEEDUPS`.
game_over	int	The reason the game ended, typically one of the `OVER_` macros.
game_solo	bool	Is someone playing alone?
game_wackymod	int	The currently active wacky modifier, usually one of the `WACKYMOD_` number macros.
game_skin	int	The currently active map seasonal skin, typically one of the `MAPSKIN_` macros.
game_teams	bool	Whether a team game is happening.

Round State

The following global variables contain information about the current round's state:

Name	Type	Description
round_current[MAXROUNDS]	int	An array containing a list of all minigames to be played/that have been played.
round_hints[MAXSPEEDUPS]	str	An array containing a list of all hints to be/that have been displayed.
round_tiebreaker	int	The number value of the tiebreaker round are we playing.
round_is1vmtiebreaker	bool	Are we playing a 1VM Tiebreaker round?
round_observers[NUMOBSERVERS]	int	An array containing all the possible observer TID's.

Minigame State

The following global variables contain information about the current minigame's state:

Name	Type	Description
minigame_timer	str	The current minigame time, or either `TIMER_OFF` or `TIMER_EARLY`.
minigame_canmove	bool	Used to signal that players can move in tiebreaker rounds.
minigame_canobserve	bool	Whether players can observe this minigame.

Player Specific

These global variables are all arrays with a size of MAXPLAYERS, meaning they're specific per player:

Name	Type	Description
player_wonround	bool	Players put here have won the round.
player_lostround	bool	Players in here have lost the round.
player_midround	bool	All players are put in here at the start of each round.
player_viewingscore	bool	List of players looking at the highscore.
player_viewingmenu	bool	List of players looking at the DoomWare Menu.
player_musicwaiting	bool	List of whether players are hearing the waiting/speedup music.
player_musicwinlose	bool	List of whether players are hearing the win/lose music.
player_musicgameover	bool	List of whether players are hearing the game over music.
player_observe	int	List of what camera players are observing.
player_frozen	bool	List of what players have `APROP_TOTALLYFROZEN`.
player_haswackyscript	bool	List of what players that have a wackymod script running.
player_position[3]	int	List player's XYZ pos before a minigame starts.
player_teleporter	int	Helper array to keep track of randomized player spawns.
player_frags	int	List of each player's frags.

Database

The following global variables are all arrays with a size of MAXPLAYERS, which store player stats:

Name	Type	Description
data_points	int	List of points each player has received in total
data_wins	int	List of wins each player has achieved in total
data_deaths	int	List of deaths each player suffered in total
data_1ups	int	List of 1Ups each player got in total
data_role	int	List of each player's role, typically one of the `ROLE_` macros.
data_achieve	int	Bit field each player's achievements
data_bosskills	int	List of each player's boss kills

Randomization

The following global variables contain information about the weighted random number generation and shufflebags:

Name	Type	Description
wrng_minigames[]	global int 01	Minigame weights for Weighted Random Number Generation.
wrng_1v1[]	global int 02	1v1 minigame weights for Weighted Random Number Generation.
wrng_1vM[]	global int 03	1vM minigame weights for Weighted Random Number Generation.
wrng_wackymods[]	global int 04	Wackymod weights for Weighted Random Number Generation.
sbag_nextwacky[]	global int 05	Shufflebag with the next wackyround.
lastlimit_minigames	global int 06	Stores the last minigame round limit (in case we change map).
lastlimit_1v1	global int 07	Stores the last 1v1 minigame round limit (in case we change map).
lastlimit_1vM	global int 08	Stores the last 1vM minigame round limit (in case we change map).
lastlimit_wackychance	global int 09	Stores the last wackymod chance (in case the CVar changes).
sbagtrack_nextwacky	global int 10	Tracks where we are currently in the nextwacky shufflebag.