ACSUtils Wiki

An ACS library for ZDoom-based ports

User Tools

Site Tools


functions:zdoom

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
functions:zdoom [2016/08/12 14:16] – [IsZandronum] korshunfunctions:zdoom [2017/06/12 18:35] (current) – removed korshun
Line 1: Line 1:
-====== 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.8.0 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. 
- 
-<note important>This function is called ''a_GetCVarFixed'' and not ''GetCVarFixed'' because GDCC has a function with the same name.</note> 
- 
-==== 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. 
- 
-<note important>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. 
-</note> 
- 
-==== 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** 
- 
-<code> 
-ToggleInventory("IsReloading"); 
-</code> 
- 
-==== 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. 
- 
-[[..mulretval|This function returns multiple values.]] 
- 
-==== RestoreActivator ==== 
-''void RestoreActivator(int a, int b)'' 
- 
-Restores the activator from the two values returned by ''SwapActivator''. 
- 
-<note warning>''SwapActivator'' changes the current activator's tid, do not allow any delay between ''SwapActivator'' and ''RestoreActivator'' if you don't want tid problems!</note> 
- 
-<note important>When using ''SwapActivator'' multiple times, alwaysperform calls to ''RestoreActivator'' in the exact reverse order, or the tids won't be restored correctly.</note> 
- 
-**Example** 
- 
-[[zdoom>PlayerNumber]] can only return the activator's player number. Here's how it's converted to work on an arbitrary tid: 
- 
-<code> 
-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; 
-} 
-</code> 
- 
-<note tip>The example function is already in ACSUtils: ''[[functions:zdoom#actorplayernumber|ActorPlayerNumber]]''.</note> 
-===== Internationalization ===== 
- 
-==== lang ==== 
-''str lang(str id)'' 
- 
-Returns a translated string from [[zdoom>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. 
- 
-<note tip>A player is considered **both a server and a client** in a non-network game (including singleplayer games and multiplayer emulation).</note> 
- 
-**Example** 
- 
-<code> 
-// This code will work both in true multiplayer and in singleplayer. 
-if (IsServer()) 
-    DoServersideStuff(); 
-     
-if (IsClient()) 
-    DoClientsideStuff(); 
-</code> 
- 
-===== 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: 
- 
-<code> 
-while (true) 
-{ 
-    SetActorSpeed(tid, SomeValue()); 
-    Delay(1); 
-} 
-</code> 
- 
-without wasting any bandwidth. 
- 
-===== Functions for mappers ===== 
- 
-==== SyncSpeed ==== 
-''function int SyncSpeed(int newdistance, int syncdistance, int syncspd)'' 
- 
-[[zdoom>Syncspeed]] 
- 
-FIXME Needs proper documentation FIXME 
  
functions/zdoom.1471000602.txt.gz · Last modified: 2016/08/12 14:16 by korshun