ZDoom

https://github.com/zdoom-docs/staging
Admin
ZDoom is an advanced source port for the classic Doom game engine that provides enhanced modding...
Tokens:52,246
Snippets:1,020
Trust Score:5.5
License:CC0-1.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Version Directive Example

Source: https://github.com/zdoom-docs/staging/blob/master/md/ZScript/TopLevel.md

Specifies the ZScript version to use at the beginning of a file.

```zsc
version "4.3.3"
```

--------------------------------

### ZScript Syntax Example

Source: https://github.com/zdoom-docs/staging/blob/master/md/ZScript.md

Demonstrates the usage of the ExampleElement syntax defined in the documentation, showing how keywords can be combined with commas.

```zsc
keyword example;
keyword example2, example3;
```

--------------------------------

### Include Directive Example

Source: https://github.com/zdoom-docs/staging/blob/master/md/ZScript/TopLevel.md

Includes another file for processing by the ZScript compiler.

```zsc
#include "zscript/MyCoolMod/MyCoolClasses.zsc"
```

--------------------------------

### Flow Statements: Continue

Source: https://github.com/zdoom-docs/staging/blob/master/md/ZScript/Statements.md

Example of using the continue statement to skip an iteration in a loop.

```zsc
// Use of "continue."
for(int i = 0; i < 50; i++)
{
	// Don't do anything when "i" is 25.
	if(i == 25)
		continue;

	DoThing(i);
}
```

--------------------------------

### Conditional Statements

Source: https://github.com/zdoom-docs/staging/blob/master/md/ZScript/Statements.md

Examples of simple if-statements and if-else structures with blocks.

```zsc
// Simple conditional.
if(a)
	B();
```

```zsc
// Simple conditional, with else statement and a block.
if(a)
{
	B();
	c = d;
}
else
	e = f;
```

--------------------------------

### Dynamic Array Lifetime Example

Source: https://github.com/zdoom-docs/staging/blob/master/md/ZScript/Types.md

Demonstrates that dynamic arrays are not scoped to their current block, allowing them to persist and accumulate elements.

```zsc
for(int i = 0; i < 5; i++)
{
	array<int> a;
	a.Push(0);
}
```

--------------------------------

### Flow Statements: Break

Source: https://github.com/zdoom-docs/staging/blob/master/md/ZScript/Statements.md

Example of using the break statement to exit a loop prematurely.

```zsc
// Use of "break."
for(int i = 0; i < 50; i++)
{
	// "break" when "i" is 25.
	if(i == 25)
		break;

	DoThing(i);
}
```

--------------------------------

### Multi-Assignment Statements

Source: https://github.com/zdoom-docs/staging/blob/master/md/ZScript/Statements.md

Example of assigning multiple values at once, commonly used with functions returning multiple values.

```zsc
// Getting the actor out of "A_SpawnItemEx."
Actor mo; bool spawned; [spawned, mo] = A_SpawnItemEx("MyCoolActor");
```

--------------------------------

### Flow Statements: Return

Source: https://github.com/zdoom-docs/staging/blob/master/md/ZScript/Statements.md

Examples of using the return statement to exit functions or return values, including multiple return values.

```zsc
// Use of `return` in various contexts.
void ReturnsNothing()
{
	// Exit early if "m_Thing" isn't 50.
	if(m_Thing != 50)
		return;

	DoThing(m_Thing);
}
```

```zsc
int ReturnsInt()
{
	// "m_Thing" is 50, so return 50.
	if(m_Thing == 50)
		return 50;

	// Must have a return, eventually.
	return 0;
}
```

```zsc
int, int ReturnsTwoInts()
{
	// Returns 1 and 2.
	return 1, 2;
}
```

--------------------------------

### string Mid(int pos = 0, int len = int.Max)

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Basic/String.md

Returns a substring of len bytes starting at pos.

```APIDOC
## string Mid(int pos = 0, int len = int.Max)

### Description
Returns `len` bytes starting at `pos` as a new string.
```

--------------------------------

### int, int GetNextCodePoint(int pos)

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Basic/String.md

Returns the next character and the byte position of the next character starting from a given position.

```APIDOC
## int, int GetNextCodePoint(int pos)

### Description
Returns the next character from the byte `pos` onwards, and the byte position of the next character.
```

--------------------------------

### int IndexOf(string substr, int startIndex = 0)

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Basic/String.md

Returns the first index of a substring starting from the left.

```APIDOC
## int IndexOf(string substr, int startIndex = 0)

### Description
Returns the first index of `substr` starting from the left at `start`.
```

--------------------------------

### PostBeginPlay

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Base/Thinker.md

Initialization callback for the thinker.

```APIDOC
## virtual void PostBeginPlay()

### Description
Called at the very end of this Thinker's initialization.
```

--------------------------------

### Method argument lists with default and named arguments

Source: https://github.com/zdoom-docs/staging/blob/master/md/ZScript/Methods.md

Demonstrates how to define a function with default arguments and call it using positional or named arguments.

```zsc
// With the function:
void DoSomething(int one, int two, int a = 0, int b = 0) {}

// One could do the following:
DoSomething(4, 5);
DoSomething(5, 6, 7);
DoSomething(6, 7, 8, 9);

// Or using named default arguments,
DoSomething(5, 6, a: 7);

// Equivalent to:
DoSomething(5, 6, 7);

// And more examples:
DoSomething(6, 7, b: 8);
DoSomething(7, 8, a: 9, b: 10);
DoSomething(7, 8, 9, 10);
```

--------------------------------

### Object Instantiation and Class Handling

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Globals.md

Functions for creating objects and retrieving default class values.

```APIDOC
## Object New(class typeName)

### Description
Creates an object with the specified type. Defaults to using the class of the calling object.

## Actor GetDefaultByType(class<Actor> typeName)

### Description
Returns an object containing the default values for each member of the Actor type provided as they would be set in Actor.BeginPlay. The returned object is a pseudo-object stored in-memory.
```

--------------------------------

### Define a basic enumeration

Source: https://github.com/zdoom-docs/staging/blob/master/md/ZScript/Enumerations.md

A standard enumeration where values increment automatically starting from 0.

```zsc
// Basic enumeration.
enum MyCoolEnum
{
	A_THING, // Has value int(0) ...
	BEES, // ... 1 ...
	CALCIUM, // ... 2 ...
	DEXTROSE, // ... and 3.
}
```

--------------------------------

### void EnumColorsets(out array<int> data)

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Players/PlayerClass.md

Enumerates the available color sets for the player class.

```APIDOC
## void EnumColorsets(out array<int> data)

### Description
Populates the provided array with available color set indices.

### Parameters
- **data** (out array<int>) - Required - The array to be populated with color set data.
```

--------------------------------

### Define a simple ZScript structure

Source: https://github.com/zdoom-docs/staging/blob/master/md/ZScript/Structures.md

A basic example of a structure definition containing integer members.

```zsc
// Simple structure.
struct MyCoolStructure
{
	int X;
	int Y;
	int Z;
}
```

--------------------------------

### S_StartSound

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Base/Object.md

Plays a sound with no source.

```APIDOC
## static void S_StartSound(sound soundId, ESoundFlags channel, ESoundFlags flags = 0, float volume = 1.0, float attenuation = ATTN_NORM, float pitch = 0.0, float startTime = 0.0)

### Description
Plays a sound with no source.
```

--------------------------------

### void Remove(int index, int amount)

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Basic/String.md

Removes amount bytes starting at index in-place.

```APIDOC
## void Remove(int index, int amount)

### Description
Removes `amount` bytes starting at `index` in-place.
```

--------------------------------

### Zero-Initializing a textureId

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Basic/TextureId.md

The recommended way to initialize a textureId to the null index.

```zsc
textureId tex;
tex.SetNull();
```

--------------------------------

### Expression Statements

Source: https://github.com/zdoom-docs/staging/blob/master/md/ZScript/Statements.md

Examples of basic expression statements in ZScript, including function calls, assignments, and standalone expressions.

```zsc
// Some basic expressions.
MyCoolFunction(5, 4);
m_MyCoolMember = 500;
```

```zsc
// Does nothing, of course, but valid.
5 * 5;
```

--------------------------------

### static string Format(string format, ...)

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Basic/String.md

Creates a new string using a format string and a variable number of arguments.

```APIDOC
## static string Format(string format, ...)

### Description
Creates a string using a format string and any amount of arguments.

### Parameters
- **format** (string) - Required - The format string template.
- **...** (varArg) - Optional - Arguments to be formatted into the string.
```

--------------------------------

### Font Instance Methods

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Drawing/Font.md

Methods for querying font metrics and processing text strings.

```APIDOC
## bool CanPrint(string text)

### Description
Returns true if all characters in text are printable.

## double GetBottomAlignOffset(int code)

### Description
Returns the baseline for the character code.

## int GetCharWidth(int code)

### Description
Returns the width in pixels of a character code.

## string GetCursor()

### Description
Returns the string used as a blinking cursor graphic for this font.

## int GetDisplacement()

### Description
Returns the largest vertical displacement in pixels of all characters in the font.

## int GetHeight()

### Description
Returns the line height in pixels of the font.

## int GetMaxAscender(string text)

### Description
Gets the maximum ascender for the first line in text.

## int StringWidth(string text)

### Description
Returns the width in pixels of the string.

## BrokenLines BreakLines(string text, int maxLen)

### Description
Breaks text up into a BrokenLines structure according to the screen and clip region.
```

--------------------------------

### Random Number Generation with Named RNG Table

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Globals.md

Example of using a named RNG table with the Random function.

```zsc
int myRandomNumber = Random[MyCoolRng](50, 100);
```

--------------------------------

### int RightIndexOf(string substr, int endIndex = int.Max)

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Basic/String.md

Returns the first index of a substring starting from the right.

```APIDOC
## int RightIndexOf(string substr, int endIndex = int.Max)

### Description
Returns the first index of `substr` starting from the right at `end`.
```

--------------------------------

### void Replace(string pattern, string replacement)

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Basic/String.md

Replaces all instances of pattern with replacement in-place.

```APIDOC
## void Replace(string pattern, string replacement)

### Description
Replaces all instances of `pattern` with `replacement` in-place.
```

--------------------------------

### Font Static Methods

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Drawing/Font.md

Methods for retrieving font instances and color information.

```APIDOC
## static Font FindFont(name fontName)

### Description
Gets a font by name without loading it.

## static int FindFontColor(name color)

### Description
Returns the color range number for a named color.

## static Font GetFont(name fontName)

### Description
Gets a font by name, loading it if it doesn't exist.
```

--------------------------------

### Console::PrintF

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Drawing/Console.md

Prints a formatted string to the console.

```APIDOC
## static varArg void PrintF(string fmt, ...)

### Description
Prints a formatted string to the console using standard format string syntax.

### Parameters
- **fmt** (string) - Required - The format string.
- **...** (varArg) - Optional - Arguments for the format string.
```

--------------------------------

### Class Property Definitions

Source: https://github.com/zdoom-docs/staging/blob/master/md/ZScript/Classes.md

Defines a class with properties and a default block for initialization.

```zsc
// A class with some properties.
class MyCoolActor : Actor
{
	// You can set defined properties in a "default" block like in DECORATE.
	// This will also be available in DECORATE code that inherits your class!
	default
	{
		MyCoolActor.MyCoolMember 5000;
		MyCoolActor.MyCoolMemberList 501, 502;
	}

	// Declare some members.
	int m_MyCoolMember;
	int m_CoolMember1, m_CoolMember2;

	// Declare some properties attached to our members.
	property MyCoolMember: m_MyCoolMember;
	property MyCoolMemberList: m_CoolMember1, m_CoolMember2;
}
```

--------------------------------

### Wads Class Methods

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Base/Wads.md

A collection of static methods for querying and reading data from the virtual file system.

```APIDOC
## static int CheckNumForFullName(string name)

### Description
Returns the handle of the first file named `name`, matching only the full path to it, including the extension, or `-1` if the file was not found. Only works with files defined in resource archives.

## static int CheckNumForName(string name, Wads.WadNamespace ns, int wadnum = -1, bool exact = false)

### Description
Returns the handle of the first lump named `name` within namespace `ns`. If `wadnum` is not `-1`, then it signifies, if `exact` is false, the number of the last archive to search in, or the only archive to search in if `exact` is `true`.

## static int FindLump(string name, int startlump = 0, Wads.FindLumpNamespace ns = Wads.GLOBALNAMESPACE)

### Description
Returns the handle of the first lump named `name` starting at `startlump` in either the global namespace or any namespace. Returns `-1` if there are no lumps with that name left.

## static string ReadLump(int lump)

### Description
Reads the whole contents of `lump` into a string and returns the result. If `lump` is not valid, returns an empty string.

## static int GetNumLumps()

### Description
Returns the number of files throughout the entire loaded virtual file system.

## static string GetLumpName(int lump)

### Description
Returns the shortened 8-character name of the lump.

## static string GetLumpFullName(int lump)

### Description
Returns the full name of the lump, or the short name if one does not exist.

## static Wads.WadNamespace GetLumpNamespace(int lump)

### Description
Returns the namespace this lump is in.
```

--------------------------------

### GetAspectRatio

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Drawing/Screen.md

Retrieves the screen aspect ratio.

```APIDOC
## static double GetAspectRatio()

### Description
Returns the aspect ratio of the screen.
```

--------------------------------

### void AppendFormat(string format, ...)

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Basic/String.md

Appends a formatted string to the current string.

```APIDOC
## void AppendFormat(string format, ...)

### Description
Works like `Format`, but appends the result to the string.
```

--------------------------------

### CVar Static Methods

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Base/CVar.md

Methods for retrieving CVar instances by name.

```APIDOC
## static CVar FindCVar(name n)

### Description
Returns a server CVar by name, or null if none is found.

## static CVar GetCVar(name n, PlayerInfo player = null)

### Description
Returns a user or server CVar by name, with player as the user if applicable, or null if none is found.
```

--------------------------------

### GetWidth / GetHeight

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Drawing/Screen.md

Retrieves screen dimensions.

```APIDOC
## static int GetWidth()
## static int GetHeight()

### Description
Returns the width or height of the screen respectively.
```

--------------------------------

### Basic Class Header

Source: https://github.com/zdoom-docs/staging/blob/master/md/ZScript/Classes.md

Defines a class that automatically inherits from Object.

```zsc
// Automatically inherits Object, similar to the "actor" keyword in DECORATE.
class MyCoolObject
{
}
```

--------------------------------

### Console::MidPrint

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Drawing/Console.md

Prints text to the middle of the screen for 1.5 seconds.

```APIDOC
## static void MidPrint(Font font, string text, bool bold = false)

### Description
Prints text (optionally a LANGUAGE string) in the specified font to the middle of the screen for 1.5 seconds. Uses msgmidcolor for non-bold messages and msgmidcolor2 for bold messages.

### Parameters
- **font** (Font) - Required - The font to use for the text.
- **text** (string) - Required - The text to display.
- **bold** (bool) - Optional - If true, prints even if the player is a spectator and uses the bold color.
```

--------------------------------

### void Truncate(int newlen)

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Basic/String.md

Truncates the string to newlen bytes in-place.

```APIDOC
## void Truncate(int newlen)

### Description
Truncates the string to `len` bytes in-place.
```

--------------------------------

### string Left(int len)

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Basic/String.md

Returns the first len bytes as a new string.

```APIDOC
## string Left(int len)

### Description
Returns the first `len` bytes as a new string.
```

--------------------------------

### string MakeUpper()

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Basic/String.md

Converts all characters in the string to uppercase and returns a new string.

```APIDOC
## string MakeUpper()

### Description
Converts all characters in the string to uppercase and returns the new string.
```

--------------------------------

### S_ChangeMusic

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Base/Object.md

Changes the background music.

```APIDOC
## static bool S_ChangeMusic(string musicName, int order = 0, bool looping = true, bool force = false)

### Description
Changes the music to the specified name. If name is "*", the music will be set to the default music for this level.
```

--------------------------------

### void Split(out array<string> tokens, string delimiter, EmptyTokenType keepEmpty = TOK_KEEPEMPTY)

Source: https://github.com/zdoom-docs/staging/blob/master/md/Api/Basic/String.md

Splits the string by each delimiter into tokens.

```APIDOC
## void Split(out array<string> tokens, string delimiter, EmptyTokenType keepEmpty = TOK_KEEPEMPTY)

### Description
Splits the string by each delimiter into tokens. `keepEmpty` describes whether the function should keep or discard empty strings found while splitting.
```
Tokens:
Raw