ZDoom utilities

Constants

int MAX_PLAYERS – maximum amount of players in Zandronum multiplayer.

Engine information

IsZandronum

bool IsZandronum()

Returns true if the mod is being played in Zandronum.

Example

if (IsZandronum())
// Use workarounds
else
// Use ZDoom 2.7.1 features

CVar functions

GetCVarFixed

fixed a_GetCVarFixed(str name)

Returns the value of the fixed-point CVar with the given name, or 0 if the cvar does not exist or is not a fixed-point number.

This function is called a_GetCVarFixed and not GetCVarFixed because GDCC has a function with the same name.

GetCVarPercentage

fixed GetCVarPercentage(str name)

Returns the value of the given integer CVar divided by 100. If the integer value of the CVar could not be retrieved, returns 0. This is useful for CVars that are percentages.

Video settings information

These functions can be used to find out the player's video settings.

AspectRatio

fixed AspectRatio()

Returns the aspect ratio of the current resolution as a fixed-point number.

IsOpenGL

bool IsOpenGL()

Returns true if the OpenGL renderer is being used at the moment, false if software.

When used serverside, this function always returns true and emits a ProgramError.

This function may return an incorrect value in the following cases: vid_renderer or gl_nogl changed mid-game. A config from GZDoom or Zandronum used in ZDoom and having vid_renderer != 0.

ScreenHeight

int ScreenHeight()

Returns the current vertical resolution in pixels.

ScreenWidth

int ScreenWidth()

Returns the current horizontal resolution in pixels.

StatusBarShown

bool StatusBarShown()

Returns true if the status bar is currently shown.

HudMessage functions

See also: hudlib.

ClearHudMessage

void ClearHudMessage(int id)

Clears the HudMessage with the given id. A shorthand for HudMessage(s:“”; HUDMSG_PLAIN, id, 0, 0, 0, 0, 0).

Inventory functions

SetInventory

void SetInventory(str item, int amount)

Sets the amount of items of the given type in the activator's inventory to amount.

Example

SetInventory("Shells", 8); // The player will now have exactly 8 shells.
SetInventory("IsReloading", 0); // Set the "IsReloading" flag to 0.

SetActorInventory

void SetActorInventory(int tid, str item, int amount)

Same as SetInventory, but affects the given actor instead of the activator.

GiveMaxInventory

void GiveMaxInventory(str item)

Gives the activator the maximum amount of items of the given type it can carry.

GiveMaxActorInventory

void GiveMaxActorInventory(int tid, str item)

Same as GiveMaxInventory, but affects the given actor instead of the activator.

TakeAllInventory

void TakeAllInventory(str item);

Takes away all items of the given type from the activator's inventory.

TakeAllActorInventory

void TakeAllActorInventory(int tid, str item)

Same as TakeAllInventory, but affects the given actor instead of the activator.

ToggleInventory

void ToggleInventory(str item)

If the activator has at least one item, takes them all away. If he has none, gives one item.

Example

ToggleInventory("IsReloading");

ToggleActorInventory

void ToggleActorInventory(int tid, str item)

Same as ToggleInventory, but affects the given actor instead of the activator.

Player information functions

PlayerName

str PlayerName(int player)

Returns the name of the specified player. A shorthand for StrParam(n:player+1).

PlayerIsConnected

bool PlayerIsConnected(int player)

Returns true if the specified player is connected to the server.

BotCount

int BotCount()

Returns the amount of ZDoom bots present on the server.

ClientCount

int ClientCount()

Returns the amount of clients connected to the server (including bots).

SpectatorCount

int SpectatorCount()

Returns the amount of spectators connected to the server.

PickRandomPlayer

int PickRandomPlayer()

Returns the player number of a random player out of those who are in game.

PickRandomSpectator

int PickRandomSpectator()

Returns the player number of a random spectator.

PickRandomBot

int PickRandomBot()

Returns the player number of a random ZDoom bot.

Actor utility functions

ActorPlayerNumber

int ActorPlayerNumber(int tid)

Returns the player number of the given actor, or -1 if the actor is not a player.

ActorIsPlayer

bool ActorIsPlayer(int tid)

Returns true if the given actor is a player.

ActivatorName

str ActivatorName()

Returns the activator's actor class name, or player name if the activator is a player. Shorthand for StrParam(n:0).

GetActorName

str GetActorName(int tid)

Returns the actor's class name, or player name if the actor is a player.

IsAlive

bool IsAlive()

Returns true if the activator is alive.

ActorIsAlive

bool ActorIsAlive(int tid)

Returns true if the given actor is alive.

Actor math functions

These functions can save you some typing when doing math on actors.

ActorDistance

fixed ActorDistance(int tid1, int tid2)

Returns the distance between two actors.

ActorDistance2D

fixed ActorDistance2D(int tid1, int tid2)

Returns the distance between two actors, ignoring the Z dimension.

GetActorCurrentSpeed

fixed GetActorCurrentSpeed(int tid)

Returns the current speed of actor.

GetActorCurrentSpeed2D

fixed GetActorCurrentSpeed2D(int tid)

Returns the current speed of actor, ignoring the Z dimension.

Actor utility functions

HasRoom

bool HasRoom(str classname, fixed x, fixed y, fixed z)

Returns true if an actor of the given class has enough room to occupy the specified point.

LookAtPoint

void LookAtPoint(int tid, fixed x, fixed y, fixed z)

Rotates the actor so that it looks at the specified point, taking the actor's view height into account.

LookAt

void LookAt(int camera, int target)

Rotates the “camera” actor so that it looks at the specified “target” actor, taking into account the view height of both actors.

Activator swapping

Some ZDoom functions only work on the activator. To convert them to functions that can take any tid, use this pair of functions:

SwapActivator

int, int SwapActivator(int tid)

Temporarily makes the given actor the activator of the script and returns two values, allowing you to restore the previous activator.

This function returns multiple values.

RestoreActivator

void RestoreActivator(int a, int b)

Restores the activator from the two values returned by SwapActivator.

SwapActivator changes the current activator's tid, do not allow any delay between SwapActivator and RestoreActivator if you don't want tid problems!
When using SwapActivator multiple times, perform calls to RestoreActivator in the exact reverse order.

Example

PlayerNumber can only return the activator's player number. Here's how it's converted to work on an arbitrary tid:

function int ActorPlayerNumber(int tid)
{
// Swap the activator and save two numbers to restore it later.
SwapActivator(tid);
int a = r1;
int b = r2;
// Retrieve the result of the activator-only function.
int result = PlayerNumber();
// Restore the previous activator using the two saved numbers.
RestoreActivator(a, b);
// Return the saved result of the activator-only function.
return result;
}

Internationalization

lang

str lang(str id)

Returns a translated string from LANGUAGE. Shorthand for StrParam(l:id).

Multiplayer functions

IsServer

bool IsServer()

Returns true if the script is running on a server or in a non-network game. Use this function to check whether server logic needs to be run.

IsClient

bool IsClient()

Returns true if the script is running on a client or in a non-network game. Use this function to check whether client logic needs to be run.

A player is considered both a server and a client in a non-network game (including singleplayer games and multiplayer emulation).

Example

// This code will work both in true multiplayer and in singleplayer.
if (IsServer())
DoServersideStuff();
if (IsClient())
DoClientsideStuff();

Actor property shorthands

Not only are these shorter than [Get/Set]ActorProperty(tid, APROP_SOMETHING), but the setters also don't set the value if it's the same, saving bandwidth when used serverside.

There are shorthands for the following properties:

Health

SpawnHealth

Speed

GetActor<Property>

int GetActor<Property>(int tid)

Returns the <Property> of the actor.

SetActor<Property>

int SetActor<Property>(int tid, int value)

Sets the <Property> of the actor if the new value is not the same as the current value. This saves bandwidth when used serverside, allowing you to write the code like this:

while (true)
{
SetActorSpeed(tid, SomeValue());
Delay(1);
}

without wasting any bandwidth.