* [Random Number Generation](#random-number-generation)
* [Math](#math)
* [Game](#game)
* [Sound](#sound)
* [System](#system)
* [Global Variables](#global-variables)
* [Static Info](#static-info)
* [Game State](#game-state)
* [Client](#client)
* [Players](#players)
* [Types](#types)
* [Built-in Types](#built-in-types)
* [Array](#array)
* [Color](#color)
* [FixedArray](#fixedarray)
* [String](#string)
* [TextureID](#textureid)
* [Vector2/Vector3](#vector2vector3)
* [Base Objects](#base-objects)
* [Object](#object)
* [Thinker](#thinker)
* [CVar](#cvar)
* [GIFont](#gifont)
* [State](#state)
* [StringTable](#stringtable)
* [Globals](#globals)
2018-11-23 16:31:53 -08:00
* [DEHInfo](#dehinfo)
* [FOptionMenuSettings](#foptionmenusettings)
2018-11-18 08:44:41 -08:00
* [GameInfoStruct](#gameinfostruct)
* [LevelLocals](#levellocals)
* [Level Data](#level-data)
* [Vertex](#vertex)
* [Side](#side)
* [Line](#line)
* [Sector](#sector)
* [SectorPortal](#sectorportal)
* [SectorEffect](#sectoreffect)
* [SectorAction](#sectoraction)
* [SecSpecial](#secspecial)
* [SecPlane](#secplane)
* [F3DFloor](#f3dfloor)
* [FColorMap](#fcolormap)
* [SectorTagIterator](#sectortagiterator)
* [LineIdIterator](#lineiditerator)
* [Players](#players-1)
* [PlayerInfo](#playerinfo)
* [PlayerClass](#playerclass)
* [PlayerSkin](#playerskin)
* [Team](#team)
* [Weapons](#weapons)
* [PSprite](#psprite)
* [Weapon](#weapon)
* [Drawing](#drawing)
* [BrokenLines](#brokenlines)
* [Console](#console)
* [Font](#font)
* [Shape2D](#shape2d)
* [Screen](#screen)
* [TexMan](#texman)
* [Sounds](#sounds)
* [SeqNode](#seqnode)
<!-- vim-markdown-toc -->
API
===
The ZScript API is vast and has some holes which are hard to explain. Some parts are implemented in ways that don't make sense to user code, but are fine to the engine. Because of this, the API shall be documented in pseudo-ZScript which gives an idea of how it works for the modder rather than for the engine.
Type Symbols
============
Integer and floating-point types have symbols which can be accessed through `typename.name`. Here is a list of them.
## Integer types
-`Max`
Maximum value of type.
-`Min`
Minimum value of type.
## Floating-point types
-`Dig`
Number of decimal digits in type.
-`Epsilon`
ε value of type.
-`Infinity`
∞ value of type.
-`Mant_Dig`
Number of mantissa bits in type.
-`Max`
Maximum value of type.
-`Max_Exp`
Maximum exponent bits value of type.
-`Max_10_Exp`
Maximum exponent of type.
-`Min_Denormal`
Minimum positive subnormal value of type.
-`Min_Exp`
Minimum exponent bits value of type.
-`Min_Normal`
Minimum value of type.
-`Min_10_Exp`
Minimum exponent of type.
-`NaN`
Not-a-Number value of type.
Global Data
===========
Global Functions
----------------
### Class Handling
```
Type GetDefaultByType(TypeName);
Type New(class typename = ThisClass);
```
-`GetDefaultByType`
Gets the default value of any built-in type.
-`New`
Typically spelled lowercase (`new`), creates an object with type `typename`. Defaults to using the class of the calling object.
### Random Number Generation
All of these functions may have `[identifier]` between the function name and the argument list to specify a named RNG table to use.
```
double FRandom(double min, double max);
double FRandomPick(double...);
int Random(int min = 0, int max = 255);
int Random2(uint mask = uint.Max);
int RandomPick(int...);
void SetRandomSeed(uint num);
```
-`FRandom`
Returns a random float between `min` and `max`.
-`FRandomPick`
Same as `RandomPick`, but with floats.
-`Random`
Returns a random integer between `min` and `max`.
-`Random2`
Returns a random integer value between `-mask` and `mask`. `mask` is used as a bit mask, so it is recommended to use a value of one less than a power of two (i.e. 3, 7, 15, 31, 63, 127, 255...)
-`RandomPick`
Returns one of the provided parameters randomly.
-`SetRandomSeed`
Sets the seed of the RNG table to `num`.
### Math
```
Type Abs(Type n);
double ATan2(double y, double x);
uint BAM(double angle);
Type Clamp(Type n, Type minimum, Type maximum);
Type Max(Type n, Type maximum);
Type Min(Type n, Type minimum);
double VectorAngle(double x, double y);
```
-`Abs`
Returns `|n|` (absolute of `n`.)
-`ATan2`
Computes the arctangent of `y / x` using the arguments' signs to determine the correct quadrant.
-`BAM`
Returns a byte angle of `angle` (`degrees * (0x40000000 / 90.0)`.)
-`Clamp`
Returns `n` if `n` is more than `minimum` and less than `maximum`, or either of those values if it is not.
-`Max`
Returns `n` if `n` is less than `maximum`, or `maximum`.
-`Min`
Returns `n` if `n` is more than `minimum`, or `minimum`.
-`VectorAngle`
Same as `ATan2`, but with arguments reversed.
### Game
```
string G_SkillName();
int G_SkillPropertyInt(int p);
double G_SkillPropertyFloat(int p);
vector3, int G_PickDeathmatchStart();
vector3, int G_PickPlayerStart(int pnum, int flags = 0);
```
-`G_SkillName`
The name of the skill in play.
-`G_SkillPropertyInt`
Returns a skill property. `p` may be:
| Name |
| ---- |
| `SKILLP_ACSReturn` |
| `SKILLP_AutoUseHealth` |
| `SKILLP_DisableCheats` |
| `SKILLP_EasyBossBrain` |
| `SKILLP_EasyKey` |
| `SKILLP_FastMonsters` |
| `SKILLP_Infight` |
| `SKILLP_NoPain` |
| `SKILLP_PlayerRespawn` |
| `SKILLP_RespawnLimit` |
| `SKILLP_Respawn` |
| `SKILLP_SlowMonsters` |
| `SKILLP_SpawnFilter` |
-`G_SkillPropertyFloat`
Returns a skill property. `p` may be:
| Name |
| ---- |
| `SKILLP_Aggressiveness` |
| `SKILLP_AmmoFactor` |
| `SKILLP_ArmorFactor` |
| `SKILLP_DamageFactor` |
| `SKILLP_DropAmmoFactor` |
| `SKILLP_FriendlyHealth` |
| `SKILLP_HealthFactor` |
| `SKILLP_MonsterHealth` |
-`G_PickDeathmatchStart`
Returns the position and angle of a random deathmatch start location.
-`G_PickPlayerStart`
Returns the position and angle of a player start for player `pnum`. `flags` may be:
| Name | Description |
| ---- | ----------- |
| `PPS_FORCERANDOM` | Always picks a random player spawn for this player. |
| `PPS_NOBLOCKINGCHECK` | Does not check if an object is blocking the player spawn. |
### Sound
```
void SetMusicVolume(float vol);
bool S_ChangeMusic(string music_name, int order = 0, bool looping = true, bool force = false);
Sets the volume of the music relative to the user's volume. Range is 0-1, inclusive.
-`S_ChangeMusic`
Changes the music to `music_name`. If `music_name` is `"*"`, the music will be set to the default music for this level. Will loop if `looping` is `true`. `force` will force the music to play even if a playlist (from the `playlist` console command) is playing.
`order` may mean something different based on the music format:
| Format | Meaning |
| ------ | ------- |
| Tracker music (`.mod`, `.xm`, etc.) | Specifies the order the song will start at. |
| Multi-track `.ogg`, `.flac`, etc. | Specifies the track to begin playing at. |
| Any other format | No meaning, will be ignored. |
-`S_GetLength`
Returns the length of a sound in seconds. **Potentially non-deterministic if all users in a networked game are not using the same sounds.**
-`S_PauseSound`
Pauses music if `notmusic` is `false` and all game sounds if `notsfx` is `false`. Used for instance in the time stop power-up.
-`S_ResumeSound`
Resumes playing music and, if `notsfx` is `false`, all game sounds as well.
-`S_Sound`
Plays a sound (as defined in `SNDINFO`) from the calling object if it has world presence (is an actor or sector etc.)
`channel` may be:
| Name | Description |
| ---- | ----------- |
| `CHAN_AUTO` | Automatically assigns the sound to a free channel (if one exists.) |
| `CHAN_BODY` | For footsteps and generally anything else. |
| `CHAN_ITEM` | For item pickups. |
| `CHAN_VOICE` | For player grunts. |
| `CHAN_WEAPON` | For weapon noises. |
| `CHAN_5` | Extra sound channel. |
| `CHAN_6` | Extra sound channel. |
| `CHAN_7` | Extra sound channel. |
`channel` may also have the following flags applied with the binary OR operator `|`:
| Name | Description |
| ---- | ----------- |
| `CHAN_LISTENERZ` | Sound ignores height entirely, playing at the listener's vertical position. |
| `CHAN_LOOP` | Continues playing the sound on loop until it is stopped manually. |
| `CHAN_MAYBE_LOCAL` | Does not play sound to other players if the silent pickup compatibility flag is enabled. |
| `CHAN_NOPAUSE` | Does not pause in menus or when `S_PauseSound` is called. |
| `CHAN_NOSTOP` | Does not start a new sound if the channel is already playing something. |
| `CHAN_UI` | Does not record sound in saved games or demos. |
Additionally, `CHAN_PICKUP` is equivalent to `CHAN_ITEM | CHAN_MAYBE_LOCAL`.
`attenuation` determines the drop-off distance of the sound. The higher the value, the quicker it fades. Constants include:
| `ATTN_NONE` | `0` | Does not drop off at all, plays throughout the whole map. |
| `ATTN_NORM` | `1` | Drops off using the `close_dist` and `clipping_dist` defined in `SNDINFO`. Default. |
| `ATTN_STATIC` | `3` | Drops off quickly, at around 512 units. |
### System
```
uint MSTime();
vararg void ThrowAbortException(string format, ...);
```
-`MSTime`
Returns the number of milliseconds since the engine was started. **Not deterministic.**
-`ThrowAbortException`
Kills the VM and ends the game (without exiting) with a formatted error.
Global Variables
----------------
These variables are accessible in any context and are not bound by any specific object.
### Static Info
```
readonly array<class<Actor>> AllActorClasses;
readonly array<PlayerClass> PlayerClasses;
readonly array<PlayerSkin> PlayerSkins;
readonly array<Team> Teams;
2018-11-23 16:31:53 -08:00
play DEHInfo DEH;
2018-11-18 08:44:41 -08:00
readonly GameInfoStruct GameInfo;
readonly FOptionMenuSettings OptionMenuSettings;
readonly textureid SkyFlatNum;
readonly Weapon WP_NOCHANGE;
```
-`AllActorClasses`
As the name implies, an array of every actor class type reference.
-`PlayerClasses`
An array of all player classes as defined in `MAPINFO`/GameInfo and `KEYCONF`.
-`PlayerSkins`
An array of all player skins as defined in `SKININFO` and `S_SKIN`.
-`Teams`
An array of all teams. Maximum index is `Team.Max`.
-`DEH`
Static DeHackEd information.
-`GameInfo`
Static information from `MAPINFO`/GameInfo.
-`OptionMenuSettings`
2018-11-23 16:31:53 -08:00
Defaults for `OptionMenu`s as defined in `MENUDEF`'s `OptionMenuSettings` block and `MAPINFO`/GameInfo.
2018-11-18 08:44:41 -08:00
-`SkyFlatNum`
The texture ID for sky flats. `F_SKY1` by default in Doom.
-`WP_NOCHANGE`
A constant denoting that the weapon the player is currently holding shouldn't be switched from.
### Game State
```
readonly bool AutomapActive;
readonly bool DemoPlayback;
play uint GameAction;
readonly int GameState;
readonly int GameTic;
readonly uint8 GlobalFreeze;
play LevelLocals Level;
int ValidCount;
```
-`AutomapActive`
`true` if the auto-map is currently open on the client. **Not deterministic.**
-`DemoPlayback`
User is watching a demo.
-`GameAction`
Current global game action. May be one of:
| Name | Description |
| ---- | ----------- |
| `ga_autoloadgame` | Don't use this. |
| `ga_autosave` | Creates an autosave. |
| `ga_completed` | Don't use this. |
| `ga_fullconsole` | Don't use this. |
| `ga_loadgamehideicon` | Don't use this. |
| `ga_loadgameplaydemo` | Don't use this. |
| `ga_loadgame` | Don't use this. |
| `ga_loadlevel` | Don't use this. |
| `ga_newgame2` | Don't use this. |
| `ga_newgame` | Don't use this. |
| `ga_nothing` | Does nothing. |
| `ga_playdemo` | Don't use this. |
| `ga_recordgame` | Don't use this. |
| `ga_savegame` | Don't use this. |
| `ga_screenshot` | Takes a screenshot. |
| `ga_slideshow` | Don't use this. |
| `ga_togglemap` | Toggles the auto-map. |
| `ga_worlddone` | Don't use this. |
-`GameState`
Current global game state. May be one of:
| Name | Description |
| ---- | ----------- |
| `GS_DEMOSCREEN` | Inside a level but watching a demo in the main menu. |
| `GS_FINALE` | Reading a cluster end text or at the end sequence. |
| `GS_FULLCONSOLE` | Outside of a level, console only. |
| `GS_HIDECONSOLE` | Outside of a level, console hidden (i.e. main menu.) |
| `GS_INTERMISSION` | In between levels. |
| `GS_LEVEL` | Inside a level. |
| `GS_STARTUP` | Game not yet initialized. |
| `GS_TITLELEVEL` | Watching a `TITLEMAP` in the main menu. |
-`GameTic`
Number of game tics passed since engine initialization. **Not deterministic.**
-`GlobalFreeze`
TODO: I have no idea what the difference between this and `Level.Frozen` is.
-`Level`
All level info as defined in `LevelLocals`.
-`ValidCount`
Don't use this.
### Client
```
KeyBindings AutomapBindings;
KeyBindings Bindings;
readonly Font BigFont;
readonly int CleanHeight;
readonly int CleanHeight_1;
readonly int CleanWidth;
readonly int CleanWidth_1;
readonly int CleanXFac;
readonly int CleanXFac_1;
readonly int CleanYFac;
readonly int CleanYFac_1;
readonly Font ConFont;
readonly Font IntermissionFont;
readonly Font SmallFont;
readonly Font SmallFont2;
ui float BackbuttonAlpha;
ui int BackbuttonTime;
ui int MenuActive;
ui BaseStatusBar StatusBar;
int LocalViewPitch;
```
-`AutomapBindings`
TODO
-`Bindings`
TODO
-`BigFont`
The `bigfont` for the current game.
-`CleanHeight`
The current screen height divided by `CleanYFac`. **Not deterministic.**
-`CleanHeight_1`
The current screen height divided by `CleanYFac_1`. **Not deterministic.**
-`CleanWidth`
The current screen width divided by `CleanXFac`. **Not deterministic.**
-`CleanWidth_1`
The current screen width divided by `CleanYFac_1`. **Not deterministic.**
-`CleanXFac`
Integral scaling factor for horizontal positions to scale from 320x200 to the current virtual resolution. **Not deterministic.**
-`CleanXFac_1`
Integral scaling factor for horizontal positions to scale from 320x200 to the current virtual resolution, accounting for aspect ratio differences. **Not deterministic.**
-`CleanYFac`
Integral scaling factor for vertical positions to scale from 320x200 to the current virtual resolution. **Not deterministic.**
-`CleanYFac_1`
Integral scaling factor for vertical positions to scale from 320x200 to the current virtual resolution, accounting for aspect ratio differences. **Not deterministic.**
-`ConFont`
The console font.
-`IntermissionFont`
The font used in intermission screens.
-`SmallFont`
The `smallfnt` for the current game.
-`SmallFont2`
The alternate `smallfnt`.
-`BackbuttonAlpha`
Alpha of the back button in menus.
-`BackbuttonTime`
The time until the back button starts fading out in menus.
-`MenuActive`
The current active menu state. One of:
| Name | Description |
| ---- | ----------- |
| `Menu.Off` | No active menu. |
| `Menu.OnNoPause` | Menu is opened, but the game is not paused. |
| `Menu.On` | Menu is open, game is paused. |
| `Menu.WaitKey` | Menu is opened, waiting for a key for a controls menu binding. |
-`StatusBar`
TODO
-`LocalViewPitch`
The pitch angle (in degrees) of `ConsolePlayer`'s view. **Not deterministic.**
### Players
```
readonly int ConsolePlayer;
readonly bool Multiplayer;
readonly int Net_Arbitrator;
readonly bool PlayerInGame[MAXPLAYERS];
play PlayerInfo Players[MAXPLAYERS];
```
-`ConsolePlayer`
Number of the player running the client. **Not deterministic.**
-`Multiplayer`
Game is networked.
-`Net_Arbitrator`
Number of the player who initiated or currently hosts the game.
-`PlayerInGame`
`true` if the player is currently in-game.
-`Players`
`PlayerInfo` structures for each player.
Types
=====
Built-in Types
--------------
### Array
While ZScript does not have proper user-facing generics, `Array` is one such type that does have a type parameter. It mirrors the internal `TArray` type.
```
struct Array<Type>
{
void Clear();
void Copy(array<Type> other);
void Delete(uint index, int count = 1);
uint Find(Type item) const;
void Grow(uint amount);
void Insert(uint index, Type item);
uint Max() const;
void Move(array<Type> other);
bool Pop();
uint Push(Type item);
uint Reserve(uint amount);
void Resize(uint amount);
void ShrinkToFit();
uint Size() const;
}
```
-`Clear`
Clears out the entire array.
-`Copy`
Copies another array's contents into this array.
-`Delete`
Deletes `count` object(s) at `index`. Moves objects after them into their place.
-`Find`
Finds the index of `item` in the array, or `Size` if it couldn't be found.
-`Grow`
Ensures the array can hold at least `amount` new members.
-`Insert`
Inserts `item` at `index`. Moves objects after `index` to the right.
-`Max`
Returns the allocated size of the array.
-`Move`
Moves another array's contents into this array.
-`Pop`
Deletes the last item in the array. Returns `false` if there are no items in the array.
-`Push`
Places `item` at the end of the array, calling `Grow` if necessary.
-`Reserve`
Adds `amount` new entries at the end of the array, increasing `Size`. Calls `Grow` if necessary.
-`Resize`
Changes the allocated array size to `amount`. Deletes members if `amount` is smaller than `Size`.
-`ShrinkToFit`
Shrinks the allocated array size `Max` to `Size`.
-`Size`
Returns the amount of objects in the array.
### Color
Colors simply store red, green, blue and alpha components. Each component has a range 0 to 255, inclusive.
```
struct Color
{
uint8 r, g, b, a;
}
```
### FixedArray
Fixed-size arrays have a size method attached to them for convenience purposes.
```
struct FixedArray
{
uint Size() const;
}
```
-`Size`
Returns the size of the array. This is a compile-time constant.
### String
```
struct String
{
static vararg string Format(string format, ...);
vararg void AppendFormat(string format, ...);
string CharAt(int pos) const;
int CharCodeAt(int pos) const;
string Filter();
int IndexOf(string substr, int start = 0) const;
string Left(int len) const;
uint Length() const;
string Mid(int pos = 0, int len = int.Max) const;
void Remove(int index, int amount);
void Replace(string pattern, string replacement);
int RightIndexOf(string substr, int end = int.Max) const;
deprecated("3.5.1") int LastIndexOf(string substr, int end = int.Max) const;
}
```
-`Format`
Creates a string using a format string and any amount of arguments.
-`AppendFormat`
Works like `Format`, but appends the result to the string.
-`CharAt`
Returns the character at `pos` as a new string.
-`CharCodeAt`
Returns the character at `pos` as an integer.
-`Filter`
Replaces escape sequences in a string with escaped characters as a new string.
-`IndexOf`
Returns the first index of `substr` starting from the left at `start`.
-`Left`
Returns the first `len` characters as a new string.
-`Length`
Returns the number of characters in this string.
-`Mid`
Returns `len` characters starting at `pos` as a new string.
-`Remove`
Removes `amount` characters starting at `index` in place.
-`Replace`
Replaces all instances of `pattern` with `replacement` in place.
-`RightIndexOf`
Returns the first index of `substr` starting from the right at `end`.
-`Split`
Splits the string by each `delimiter` into `tokens`. `keepEmpty` may be either `TOK_SKIPEMPTY` (the default) or `TOK_KEEPEMPTY`, which will keep or discard empty strings found while splitting.
-`ToDouble`
Interprets the string as a double precision floating point number.
-`ToInt`
Interprets the string as a base `base` integer, guessing the base if it is `0`.
-`ToLower`
Converts all characters in the string to lowercase in place.
-`ToUpper`
Converts all characters in the string to uppercase in place.
-`Truncate`
Truncates the string to `len` characters in place.
-`LastIndexOf`
Broken. Use `RightIndexOf` instead.
### TextureID
Texture IDs can be explicitly converted to integers, but not the other way around. You can add and subtract integers with a `textureid`, however. (This only works with the integer on the right hand side.)
```
struct TextureID
{
bool Exists() const;
bool IsNull() const;
bool IsValid() const;
void SetInvalid();
void SetNull();
}
```
-`Exists`
Checks if the texture exists within the texture manager at all.
-`IsNull`
Checks if the texture is the null index (`0`.)
-`IsValid`
Checks if the texture index is not the invalid index (`-1`.)
-`SetInvalid`
Sets the texture index to `-1`.
-`SetNull`
Sets the texture index to `0`.
The proper way to zero-initialize a `textureid` is:
```
textureid tex;
tex.SetNull();
```
### Vector2/Vector3
```
struct Vector2
{
double x, y;
double Length() const;
vector2 Unit() const;
}
struct Vector3
{
double x, y, z;
vector2 xy;
double Length() const;
vector3 Unit() const;
}
```
-`Length`
Returns the length (magnitude) of the vector.
-`Unit`
Returns a normalized vector. Equivalent to `vec / vec.Length()`.
Base Objects
------------
### Object
The base class of all `class` types.
```
class Object
{
bool bDESTROYED;
class GetClass();
string GetClassName();
class GetParentClass();
virtualscope void Destroy();
virtual virtualscope void OnDestroy();
}
```
-`bDESTROYED`
This object wants to be destroyed but has not yet been garbage collected.
-`GetClass`
Returns the class type of this object.
-`GetClassName`
Returns a string representation of the class type of this object.
-`GetParentClass`
Returns the class type of this object's parent class.
-`Destroy`
Destroys this object. Do not use the object after calling this. References to it will be invalidated.
-`OnDestroy`
2018-11-20 15:16:46 -08:00
Called just before the object is collected by the garbage collector. **Not deterministic** unless the object is linked into the thinker list, in which case it is destroyed earlier in a deterministic setting. Not all `Thinker`s are linked into this list, so be careful when overriding this. Any `Actor` will generally be safe.
2018-11-18 08:44:41 -08:00
### Thinker
A class representing any object in the game that runs logic every game tick, i.e., "thinks." Most classes derive from `Thinker`, directly or indirectly.
All thinkers are grouped by their "stat" number, or "statnum," which specifies the ordering of which thinkers are run, first to last. There are 127 stat numbers total, 20 of which are not used by the engine and may be used for any purpose.
The user-defined stat numbers begin at `Thinker.STAT_USER` and end at `Thinker.STAT_USER_MAX`. Do not attempt to use normal integers as stat numbers except as relative to these two.
(Note to authors: These tables are not alphabetically organized as their ordering is meaningful.)
Thinkers which do not think and are elided from many checks:
| Name | Description |
| ---- | ----------- |
| `Thinker.STAT_INFO` | Info queue (used by `SpecialSpot` and its descendants.) |
| `Thinker.STAT_DECAL` | Decals that cannot be deleted. |
| `Thinker.STAT_AUTODECAL` | Decals that can be deleted (were not placed by the map.) |
| `Thinker.STAT_CORPSEPOINTER` | An entry in Hexen's corpse queue. |
| `Thinker.STAT_TRAVELLING` | Any actor travelling between maps in a hub. |
| `Thinker.STAT_STATIC` | Thinkers persistent across maps. |
Thinkers which do think and are mandatory to many checks:
| Name | Description |
| ---- | ----------- |
| `Thinker.STAT_SCROLLER` | Texture scrollers and carriers. |
| `Thinker.STAT_PLAYER` | All `PlayerPawn` actors. |
| `Thinker.STAT_LIGHTTRANSFER` | Sector lighting transfer thinkers. |
| `Thinker.STAT_EARTHQUAKE` | Quake effects. |
| `Thinker.STAT_MAPMARKER` | All `MapMarker` actors. |
| `Thinker.STAT_DLIGHT` | Dynamic lights. |
| `Thinker.STAT_DEFAULT` | Anything not in any other category. Most actors go here. |
| `Thinker.STAT_SECTOREFFECT` | Sector effects that cause floor or ceiling movement. |
| `Thinker.STAT_ACTORMOVER` | All `ActorMover` actors. |
| `Thinker.STAT_SCRIPTS` | The ACS VM. |
| `Thinker.STAT_BOT` | All bot logic. This is not bound to their actor. |
```
class Thinker play
{
const TICRATE;
virtual void ChangeStatNum(int stat);
virtual void PostBeginPlay();
virtual void Tick();
static clearscope int Tics2Seconds(int tics);
}
```
-`TICRATE`
The number of game ticks in a second. This value is always `int(35)`.
-`ChangeStatNum`
Changes the statnum of this `Thinker`.
-`PostBeginPlay`
Called at the very end of this Thinker's initialization.
-`Tick`
Called every game tick. The order between this thinker's `Tick` and every other thinker in the same statnum is unspecified.
-`Tics2Seconds`
Roughly converts a number of tics to an integral amount of seconds. Equivalent to `tics / TICRATE`.
### CVar
A **C**onsole **Var**iable, either defined in `CVARINFO` or by the engine. **Not serializable. Do not use as a member unless marked as `transient`.**
All Get and Set operations will work regardless of the real type of the CVar, as they aren't "strongly" typed.
```
struct CVar
{
static CVar FindCVar(name n);
static CVar GetCVar(name n, PlayerInfo player = null);
bool GetBool();
double GetFloat();
int GetInt();
string GetString();
void SetBool(bool v);
void SetFloat(double v);
void SetInt(int v);
void SetString(string v);
int GetRealType();
int ResetToDefault();
}
```
-`FindCVar`
Returns a server CVar by name, or `null` if none is found.
-`GetCVar`
Returns a user or server CVar by name, with `player` as the user if applicable, or `null` if none is found.
-`GetBool`
Returns a boolean representing the value of the CVar, or `false` if it cannot be represented.
-`GetFloat`
Returns a float representing the value of the CVar, or `0.0` if it cannot be represented.
-`GetInt`
Returns an integer representing the value of the CVar, or `0` if it cannot be represented.
-`GetString`
Returns a string representing the value of the CVar. CVars can always be represented as strings.
-`SetBool`
-`SetFloat`
-`SetInt`
-`SetString`
Sets the representation of the CVar to `v`. May only be used on mod-defined CVars.
-`GetRealType`
Returns the type of the CVar as it was defined, which may be one of the following:
| Name |
| ---- |
| `CVar.CVAR_Bool` |
| `CVar.CVAR_Color` |
| `CVar.CVAR_Float` |
| `CVar.CVAR_Int` |
| `CVar.CVAR_String` |
-`ResetToDefault`
Resets the CVar to its default value and returns 0. The purpose of the return is unknown. May only be used on mod-defined CVars.
### GIFont
A font as defined in `MAPINFO`/GameInfo.
```
struct GIFont
{
name Color;
name FontName;
}
```
-`Color`
The color of the font.
-`FontName`
The name of the font.
### State
Represents a state on an `Actor` or `StateProvider`. Data in `State` is read-only and is copied as needed to its respective locations for modification, as it is merely a look into the global constant state table.
A pointer to the next state in the global state table.
-`Sprite`
The sprite ID of this state.
-`Tics`
The number of game ticks this state lasts.
-`Misc1`
-`Misc2`
2018-11-23 16:31:53 -08:00
Primarily used in DeHackEd compatibility. Don't use this.
2018-11-18 08:44:41 -08:00
-`TicRange`
2018-11-23 16:31:53 -08:00
The maximum amount of tics to add for random tic durations, or `0` if the duration is not random. For example, `TNT1 A random(5, 7)` would have a `Tics` value of `5` and a `TicRange` of `2`.
2018-11-18 08:44:41 -08:00
-`UseFlags`
2018-11-23 16:31:53 -08:00
The scope of this state. See *Action Scoping*. Can have any of the `DefaultStateUsage` flags.
2018-11-18 08:44:41 -08:00
-`bCANRAISE`
2018-11-23 16:31:53 -08:00
State has the `CANRAISE` flag, allowing `A_VileChase` to target this actor for healing without entering an infinitely long state.
2018-11-18 08:44:41 -08:00
-`bDEHACKED`
2018-11-23 16:31:53 -08:00
`true` if the state has been modified by DeHackEd.
2018-11-18 08:44:41 -08:00
-`bFAST`
2018-11-23 16:31:53 -08:00
State has the `FAST` flag, halving the duration when fast monsters is enabled.
2018-11-18 08:44:41 -08:00
-`bFULLBRIGHT`
State has the `BRIGHT` flag, making it fully bright regardless of other lighting conditions.
-`bNODELAY`
State has the `NODELAY` flag, forcing the associated action function to be run if the actor is in its first tic.
-`bSAMEFRAME`
2018-11-23 16:31:53 -08:00
`true` if the state's frame is to be kept from the last frame used, i.e., is `#`.
2018-11-18 08:44:41 -08:00
-`bSLOW`
2018-11-23 16:31:53 -08:00
State has the `SLOW` flag, doubling the duration when slow monsters is enabled.
2018-11-18 08:44:41 -08:00
-`DistanceTo`
2018-11-23 16:31:53 -08:00
Returns the offset between this state and `other` in the global frame table. Only works if both states are owned by the same actor.
2018-11-18 08:44:41 -08:00
-`ValidateSpriteFrame`
2018-11-23 16:31:53 -08:00
Returns `true` if the sprite frame actually exists.
2018-11-18 08:44:41 -08:00
-`GetSpriteTexture`
2018-11-23 16:31:53 -08:00
Returns the texture, if the texture should be flipped horizontally, and scaling of this state's sprite. Scaling will return `scale` unless `skin` is nonzero. `skin` determines the player skin used.
2018-11-18 08:44:41 -08:00
### StringTable
The localized string table as defined by `LANGUAGE`.
Returns the localized variant of `val`. If `prefixed` is `true`, the string is returned as-is unless it is prefixed with `$` where the `$` character itself is ignored. **Not deterministic** unless there is only one variant of `val`. This is generally fine because this should only be used for visual strings anyway.
Globals
-------
2018-11-23 16:31:53 -08:00
### DEHInfo
2018-11-18 08:44:41 -08:00
Static DeHackEd information.
```
2018-11-23 16:31:53 -08:00
struct DEHInfo
2018-11-18 08:44:41 -08:00
{
readonly int BFGCells;
readonly int BlueAC;
readonly double ExplosionAlpha;
readonly uint8 ExplosionStyle;
readonly int MaxSoulsphere;
readonly int NoAutofreeze;
}
```
-`BFGCells`
The amount of ammunition `A_FireBFG` will deplete. Default is 40.
-`BlueAC`
Multiple of 100 for `BlueArmor`'s `Armor.SaveAmount`. Default is 2 for 200 armor.
-`ExplosionAlpha`
For actors with the `DEHEXPLOSION` flag, the alpha to set the actor to on explosion.
-`ExplosionStyle`
For actors with the `DEHEXPLOSION` flag, the render style to be applied on explosion.
-`MaxSoulsphere`
The `Inventory.MaxAmount` for `Soulsphere`. Default is 200.
-`NoAutofreeze`
Overrides generic freezing deaths if not zero, making all actors act as if they had the `NOICEDEATH` flag.
2018-11-23 16:31:53 -08:00
### FOptionMenuSettings
Defaults for `OptionMenu`s as defined in `MENUDEF`'s `OptionMenuSettings` block and `MAPINFO`/GameInfo.
```
struct FOptionMenuSettings
{
int mTitleColor;
int mFontColor;
int mFontColorValue;
int mFontColorMore;
int mFontColorHeader;
int mFontColorHighlight;
int mFontColorSelection;
int mLineSpacing;
}
```
-`mTitleColor`
TODO
-`mFontColor`
TODO
-`mFontColorValue`
TODO
-`mFontColorMore`
TODO
-`mFontColorHeader`
TODO
-`mFontColorHighlight`
TODO
-`mFontColorSelection`
TODO
-`mLineSpacing`
The spacing in virtual pixels between two lines in an `OptionMenu`.
2018-11-18 08:44:41 -08:00
### GameInfoStruct
2018-11-23 16:31:53 -08:00
Static information from `MAPINFO`/GameInfo.
2018-11-18 08:44:41 -08:00
```
struct GameInfoStruct
{
double Armor2Percent;
string ArmorIcon1;
string ArmorIcon2;
name BackpackType;
int GameType;
double GibFactor;
array<name> InfoPages;
bool IntermissionCounter;
bool NoRandomPlayerClass;
string mBackButton;
name mSliderColor;
GIFont mStatScreenEnteringFont;
GIFont mStatScreenFinishedFont;
GIFont mStatScreenMapNameFont;
}
```
### LevelLocals
Most map-relative data is stored in this structure.
```
struct LevelLocals
{
// Map data
array<Line> Lines;
array<Sector> Sectors;
array<Side> Sides;
internal array<SectorPortal> SectorPortals;
readonly array<Vertex> Vertexes;
// Stats
int Found_Items;
int Found_Secrets;
int Killed_Monsters;
int Total_Items;
int Total_Monsters;
int Total_Secrets;
// Time
readonly int MapTime;
readonly int ParTime;
readonly int StartTime;
readonly int SuckTime;
readonly int Time;
readonly int TotalTime;
// Map sequencing
readonly int Cluster;
readonly int ClusterFlags;
readonly string LevelName;
readonly int LevelNum;
readonly string MapName;
string NextMap;
string NextSecretMap;
readonly int MapType;
// Music
readonly string Music;
readonly int MusicOrder;
// Sky
readonly textureid SkyTexture1;
readonly textureid SkyTexture2;
float SkySpeed1;
float SkySpeed2;
// Physics
play double AirControl
play double AirFriction;
play int AirSupply;
play double Gravity;
// State
bool AllMap;
bool Frozen;
// Static info
string F1Pic;
readonly bool ActOwnSpecial;
readonly bool AllowRespawn;
readonly bool CheckSwitchRange;
readonly int FogDensity;
readonly bool Infinite_Flight;
readonly bool MissilesActivateImpact;
readonly bool MonsterFallingDamage;
readonly bool MonstersTelefrag;
readonly bool NoInventoryBar;
readonly bool NoMonsters;
readonly bool No_Dlg_Freeze;
readonly int OutsideFogDensity;
readonly float PixelStretch;
readonly bool PolyGrind;
readonly int SkyFog;
readonly bool SndSeqTotalCtrl;
readonly double TeamDamage;
double GetUDMFFloat(int type, int index, name key);
int GetUDMFInt(int type, int index, name key);
string GetUDMFString(int type, int index, name key);
bool ExecuteSpecial(int special, Actor activator, Line linedef, bool lineside, int arg1 = 0, int arg2 = 0, int arg3 = 0, int arg4 = 0, int arg5 = 0);
Also known as a "sidedef." One of the textured sides of a line. Each sidedef has three portions: Upper, middle, and lower. The middle texture is special as it can have translucency.
The three portions of a sidedef can be referred to with:
TODO: "This is for handling Legacy-style color maps which use a different formula to calculate how the color affects lighting."
-`Desaturation`
How much to desaturate colors in this sector. Range is 0 to 255, inclusive.
-`FadeColor`
The color of fog in this sector. None if all components are 0.
-`LightColor`
The color of the sector. Default if all components are 0.
### SectorTagIterator
TODO
### LineIdIterator
Iterates over line indices with a specified tag.
```
class LineIdIterator
{
static LineIdIterator Create(int tag);
int Next();
}
```
-`Create`
Creates a new iterator over lines with tag `tag`.
-`Next`
Returns the index of the current line and advances the iterator. Returns -1 when the list is exhausted.
Players
-------
### PlayerInfo
TODO
### PlayerClass
A player class as defined in either `MAPINFO`/GameInfo or `KEYCONF`.
```
struct PlayerClass
{
uint Flags;
array<int> Skins;
class<Actor> Type;
bool CheckSkin(int skin);
void EnumColorsets(out array<int> data);
name GetColorsetName(int setnum);
}
```
-`Flags`
Not currently implemented correctly, `PCF_NOMENU` does not exist in ZScript, but its value is `1` if you need to check for that.
-`Skins`
Skin indices available to this player class.
-`Type`
The class type reference for this player class.
-`CheckSkin`
Checks if `skin` is in `Skins`.
-`EnumColorsets`
TODO
-`GetColorsetName`
TODO
### PlayerSkin
A player skin as defined in `SKININFO` or `S_SKIN`.
```
struct PlayerSkin
{
int CrouchSprite;
string Face;
uint8 Gender;
int NameSpc;
bool OtherGame;
uint8 Range0End;
uint8 Range0Start;
vector2 Scale;
string SkinName;
int Sprite;
}
```
-`CrouchSprite`
The crouching sprite ID for this skin.
-`Face`
Prefix for statusbar face graphics.
-`Gender`
Default gender of the skin. May be one of the following:
| Name | Value | Description |
| ---- | :---: | ----------- |
| `GENDER_FEMALE` | `1` | Feminine. |
| `GENDER_MALE` | `0` | Masculine. |
| `GENDER_NEUTRAL` | `2` | Neutral. |
| `GENDER_OTHER` | `3` | Other (robot, zombie, etc.) |
-`NameSpc`
If this skin was defined in S_SKIN, this is the lump ID of the marker itself.
-`OtherGame`
The player skin is made for another game and needs to be color remapped differently.
-`Range0End`
The end index of the translation range to be used for changing the player sprite's color.
-`Range0Start`
The beginning index of the translation range to be used for changing the player sprite's color.
-`Scale`
The scaling factor used for the player sprite.
-`SkinName`
Name of the skin.
-`Sprite`
The sprite ID for this skin.
### Team
A team as defined in `TEAMINFO`.
```
struct Team
{
const Max;
const NoTeam;
string mName;
}
```
-`Max`
The maximum number of teams.
-`NoTeam`
A constant index for a player with no team.
-`mName`
The name of the team.
Weapons
-------
### PSprite
A **P**layer **Sprite**, paradoxically, is not the player themself, but the sprite *within their view*, such as their weapon. PSprites are arbitrarily layered by number, somewhat similar to HUDMessages. They are drawn ordered from lowest to highest.
The predefined layers are:
| Name | Value | Description |
| ---- | :---: | ----------- |
| `PSprite.Flash` | `1000` | The layer used by `A_GunFlash` for gun flashes. |
| `PSprite.StrifeHands` | `-1` | The hands brought up by `A_ItBurnsItBurns` when the player in Strife dies of fire. |
| `PSprite.TargetCenter` | `int.Max - 2` | The middle of the targeting system view in Strife. |
| `PSprite.TargetLeft` | `int.Max - 1` | The left side of the targeting system view in Strife. |
| `PSprite.TargetRight` | `int.Max` | The right side of the targeting system view in Strife. |
| `PSprite.Weapon` | `1` | The default layer for all weapons. |
Hides the console if it is open and `gamestate` is not `GS_FULLCONSOLE`.
-`MidPrint`
Prints `text` (possibly a `LANGUAGE` string if prefixed with `$`) in `font` to the middle of the screen for 1½ seconds. Will print even if the player is a spectator if `bold` is `true`. Uses the `msgmidcolor` CVar for non-bold messages and `msgmidcolor2` for bold messages.
-`Printf`
Prints a formatted string to the console.
### Font
A font as defined in `FONTDEFS` or a bitmap font file. **Not serializable. Do not use as a member unless marked as `transient`.**
```
struct Font
{
static Font FindFont(name fontname);
static int FindFontColor(name color);
static Font GetFont(name fontname);
int GetCharWidth(int code);
string GetCursor();
int GetHeight();
int StringWidth(string code);
BrokenLines BreakLines(string text, int maxlen);
}
```
-`FindFont`
Gets a font as defined in `FONTDEFS`.
-`FindFontColor`
Returns the color range enumeration for a named color.
-`GetFont`
Gets a font either as defined in `FONTDEFS` or a ZDoom/bitmap font.
-`GetCharWidth`
Returns the width in pixels of a character code.
-`GetCursor`
Returns the string used as a blinking cursor graphic for this font.
-`GetHeight`
Returns the line height of the font.
-`StringWidth`
Returns the width in pixels of the string.
-`BreakLines`
Breaks `text` up into a `BrokenLines` structure according to the screen and clip region, as well as appropriately accounting for a maximum width in pixels of `maxlen`.
### Shape2D
Represents an arbitrary polygonal 2D shape.
```
class Shape2D
{
void Clear(int which = C_Verts | C_Coords | C_Indices);
void PushCoord(vector2 c);
void PushTriangle(int a, int b, int c);
void PushVertex(vector2 v);
}
```
-`Clear`
Clears data out of a shape. Uses these as a bit flag:
static void SetClipRect(int x, int y, int w, int h);
}
```
-`DrawChar`
TODO
-`DrawShape`
TODO
-`DrawText`
TODO
-`DrawTexture`
TODO
-`Clear`
Draws a rectangle from `top left` to `bottom right` in screen coordinates of `cr` color. Does not support translucent colors. `palcolor` is a palette index to use as a color in paletted renderers or `-1` for automatic conversion from the given RGB color.
-`Dim`
Draws a rectangle at `x y` of `w h` size in screen coordinates of `cr` color. Does not support translucent colors, but `amount` may be used to specify the translucency in a range of 0-1 inclusive.
-`DrawFrame`
Draws a frame around a rectangle at `x y` of `w h` size in screen coordinates, using the border graphics as defined in `MAPINFO`/GameInfo.
-`DrawLine`
Draws a one pixel wide line from `x0 y0` to `x1 y1` in screen coordinates of color `cr`. Does not support translucent colors.
-`DrawThickLine`
Draws a `thickness` pixel wide line from `x0 y0` to `x1 y1` in screen coordinates of color `cr`. Supports translucent colors.
-`GetAspectRatio`
Returns the aspect ratio of the screen.
-`GetHeight`
Returns the height of the screen.
-`GetWidth`
Returns the width of the screen.
-`PaletteColor`
Returns a `color` for a given palette index.
-`VirtualToRealCoords`
TODO
-`ClearClipRect`
Clears the clipping rectangle if there is one.
-`GetClipRect`
Returns the clipping rectangle's `x`/`y`/`w`/`h`.
-`GetViewWindow`
Returns the 3D viewing window, which may be smaller than the screen size with any given `screenblocks` setting.
-`SetClipRect`
Sets the clipping rectangle to restrict further drawing to the region starting at `x y` of size `w h` in screen coordinates.
### TexMan
The **Tex**ture **Man**ager is used for loading, finding, replacing and getting information on textures.
```
struct TexMan
{
static textureid CheckForTexture(string name, int usetype, int flags = TexMan.TryAny);
static int CheckRealHeight(textureid tex);
static string GetName(textureid tex);
static vector2 GetScaledOffset(textureid tex);
static vector2 GetScaledSize(textureid tex);
static int, int GetSize(textureid tex);
static void ReplaceTextures(string from, string to, int flags);