ZScript

ZScript (formerly known as DoomScript) is a text-format lump used to create classes or structs for use in ZDoom. It is similar to C++ in many ways, and allows for more advanced control of actors and levels than DECORATE has.

You can include other lumps for processing similar to DECORATE as so:

#include "ZScript/Const.txt"

Due to how ZScript is processed, it is possible to name a file which conflicts with other mods or the internal files. For example, if you have a file in your mod named ZScript/Const.txt, it will prevent the game from loading this file correctly as it is already defined internally. To avoid such conflicts, it is recommended to have a subfolder named after your mod, such as:

#include "MyMod/Const.txt"

As of GZDoom 2.3.0, ZScript is enabled by default and does not require any command-line parameter. The last development versions of ZDoom past 2.8.1 require the -zscript command line parameter to enable loading of ZScript lumps.

A full ZScript file is known as a translation unit, akin to the C programming language's definition of the term.

Note: All keywords and identifiers in ZScript are case insensitive.

Load order

ZScript is much more relaxed and includes can be done in any order, except for extending classes.

Combining ZScript and DECORATE

It is perfectly possible to use both DECORATE and ZScript simultaneously. For example, ZScript might be used to create some custom action function, which is then available to regular DECORATE actors. The ZScript code is processed and compiled before the DECORATE code; this means that DECORATE actors can inherit from ZScript actors, but not vice-versa. For references that are only needed at run-time, rather than compile-time (such as calling a function to spawn an actor), then there is no such restriction: a ZScript actor can spawn a DECORATE actor, or vice-versa.

ZScript topics

• Coding language differences
• Converting DECORATE code to ZScript
• Custom action functions
• Controlling dynamic lights (GZDoom only: not supported by ZDoom)

• Dynamic arrays
• Object scopes and versions
• Structs
• Using pointers in ZScript
• Using CVars in ZScript
• ZScript actor flags
• ZScript actor functions
• ZScript classes
• ZScript mixins
• ZScript custom properties
• ZScript functions
• ZScript global variables
• ZScript named arguments
• ZScript variables
• ZScript virtual functions
• ZScript special words
• ZScript features

Advanced topics

These sections are for advanced users and programmers who want more control over their mods. The best course of action for modders would be to brush up on a programming language like Java or C++. These topics will assume all who read them know how to work with ZScript, preferably most of the above information.

Also consider opening the gzdoom.pk3 file using SLADE or similar. The base file contains all manner of ZScript code which the modder can learn from as examples.

• Events and handlers
• ZScript menus
• ZScript status bars

Additional documentation

In case any of the above pages do not answer your questions, Marrub has been working on more detailed and comprehensive documentation for ZScript's core language and API. This is a work in progress, but will be added to the wiki when complete. Until then, this additional documentation may be found at the following link: https://github.com/marrub--/zscript-doc/blob/master/README.md