ZScript variables

Access modifiers determine what fields and functions classes are capable of seeing from another class. If no modifier is specified then it is treated as public: every class has access to that field or function.

• protected - Only this class and its child classes have access to this
• private - Only this class has access to this

Scope modifiers determine which scope to place a class, struct, field, or function in. For fields (including structs) and functions it will automatically inherit the scope of the class/struct it's defined in, but this can be changed by manually specifying a different scope. Anything that inherits from Thinker (e.g. Actor) will be in the play scope. By default classes or structs are placed in the data scope if no modifier is specified.

• virtualscope - Any non-static function marked with this will assume the scope of the class or struct it's being called from
• clearscope - If a function is in either the play or ui scope, this will set it back to being data scoped
• play - Any field, function, class, or struct marked with this will be put in the play scope
• ui - Any field, function, class, or struct marked with this will be put in the ui scope

class MyClass play
{
}

// if defined as a field in a play scoped class this will still be ui scoped
struct MyStruct ui
{
}
// this will become play scoped if defined as a field in a play scoped class
struct MyStruct2
{
}

ui int myField;
virtualscope void MyFunction() {}

The transient keyword can be used to mark a field as non-serializable. Non-serializable fields will not be stored in save files. This can be useful for certain types that cannot be saved such as CVars and SecPlanes. It can also be useful if you want to force data to be cleared every time the game is reopened.

transient CVar myCVar; // this allows CVars to be safely stored as a field

The static keyword marks a function as not being tied to any particular instance of a class or struct. They can be called directly by using the class/struct name followed by the name of the function. Be warned that static functions will not have access to any fields within that class/struct. If field access is required, consider making it non-static or passing a reference to an object that has those fields.

class MyClass
{
  static void MyStaticFunction() {}
}

MyClass.MyStaticFunction(); // how to invoke the method

The action modifier is specifically for non-static Actor functions that are callable from PSprites. Since PSprites are not Actors, the way they pass information to a State's function is different. This is done by passing the State's owner as the invoker while the player themselves is passed as the self pointer. A stateInfo pointer is also passed that contains information about the State the function was called from. For regular Actors this modifier does nothing and shouldn't be used.

action void MyWeaponFunction() {}

The virtual keyword allows child classes to override a non-static function defined in a parent class. This can allow for custom behavior of an object even if only knowing its base type. The override keyword is used in place of virtual when overriding it from a child. The function's signature must match one-to-one with the parent's function excluding parameter names. While technically parameters with default arguments can be left out in the override, this is done for future compatibility should a virtual function gain more parameters. Any parameters left out will be inaccessible to the override. Default parameters cannot be defined in an override. A child's function will completely override the function of its parents. To avoid this behavior, the super keyword can be used.

class A
{
  virtual void MyFunction(int arg1, int arg2 = 0) // arg2 has a default argument
  {
    DoThing(arg1, arg2);
  }
}

class B : A
{
  override void MyFunction(int arg1, int arg2) // arg2 doesn't have a default in the override
  {
    super.MyFunction(arg1, arg2); // make sure to still call A's function

    DoMoreThings(arg1, arg2);
  }
}

These modifiers can't be used by modders but are documented here for game developers using GZDoom who wish to expand the internal pk3 for their games.

• native

For fields, this is declared and used by the engine itself. For functions, this method is defined within the engine. For classes and structs, these types are defined and used by the engine itself.

class EngineClass native
{
}

struct EngineStruct native
{
}

native int engineValue;
native void EngineFunction();

• internal

If a field is set to readonly but your ZScript still needs to modify it, internal can be used to allow this without having to either obscure the field or give full write access. Code outside of the internal pk3 will still only be able to read from it and not write.

native readonly internal int engineValue;

• vararg

This specifies that a native function takes a variable amount of arguments. Putting ... as the last parameter marks when the variable arguments start. No other parameters can be defined after this point.

native vararg void MyFunction(int arg1, int arg2, ...);

• @

Some native arrays may contain a native struct type with an @ prefixing its type name. This denotes that the content of the array comes from structs created internally and are handled via references.

native Array<@EngineStruct> engineArray;

The readonly keyword can be used to make it so an Actor field cannot be written to. This can be useful for creating pseudo constant values that you might want to change on a per-Actor basis via their properties. It can also be used to pass readonly reference handles to functions. Readonly fields must be set in the Default block as a property.

readonly int prop;

// references set as readonly use readonly<T> syntax
void MyFunction(readonly<Actor> mo) {}

For developers using GZDoom to create their games, readonly can also be used as a way to pass information from the engine to the front end without allowing modders to directly modify it. For instance, radius is set to readonly in ZScript but can still be modified within the engine itself. This allows for easy read access while forcing an API for write access.

The meta keyword is a special modifier that marks an Actor field as both static and readonly. Static in this case means the field is not stored on each individual Actor but instead shared in a single spot in memory across all of them. If you have values that aren't tied to a particular instance of an Actor, this can be used to save memory. A virtual getter function can be created to allow classes to modify it conditionally. Due to the nature of being readonly, this can only be set via the Default block as a property.

meta int GibHealth;

virtual int GetGibHealth()
{
  return -GibHealth;
}

Unlike variable consts, the const keyword for non-static functions denotes that the function does not modify the object's fields in its body. Unlike traditional C++ this does not actually prevent the function from modifying fields but instead acts like a hint that it won't do so. As a result this should only be used with functions where nothing but local variables are being modified. It's often used for getter functions so that they can be called from any scope.

clearscope bool GetValue() const {} // This should be paired with clearscope to denote it won't modify the play or ui scopes

Local arrays can be defined with a set number of index spots, but cannot be initialized until after their declaration. Changing the array's contents must be done inside an anonymous or named function. These can also be declared inside of said functions for temporary existence.

int MyArray[2];
MyArray[0] = 5;
MyArray[1] = 10;

Constant arrays are different from normal constants.

• Can be defined in (anonymous) functions
• Must have all their fields initialized immediately.
• Must have a type, and the static word present.

// static const <type> <name>[] =
static const Color SecondaryColor[] =
{
    "Red",
    "Yellow",
    "Green",
    "Blue" // Unlike enums, the last member must not have a comma.
};

Dynamic arrays are similar to local arrays but can be resized at any time. They are similar to vectors in C++.

Array<int> myNumbers;
myNumbers.Push(5);
myNumbers.Push(10);