Scripts

What is a script?

Scripts are the foundation of ZScript. You cannot do anything in ZScript without scripts. Every script has a void run() function, the entry point for the script.

Each script type runs its scripts based on different things occurring in the engine - for example, an npc script runs when an npc (an enemy) is alive.

• Script Types

Instance Variables

Declaring variables inside a script creates ‘instance variables’. These variables will hold a different value for each instance of the script that is running. The this variable of scripts is now an instance variable.

A variable declared with the static keyword will be a global variable instead, holding one value for all instances of the script. Constants are automatically static.

The compiler option DEFAULT_STATIC_SCRIPT_MEMBERS strongly affects instance variables. It may mark all script variables and functions as static depending on the setting; this is used to preserve old scripts.

While static global variables in a script can be accessed using ScriptName.var_name, instance variables cannot be accessed except by the script they belong to.

Exported Variables

Script-scope variables can be annotated with some export-related annotations. Exported variables can have their initial value modified in the Editor when setting up the script, similarly to InitD[].

If an exported variable has an initializer, the initializer value will be used as a default value, used automatically if no value is specified in the editor. A button in the editor also allows “resetting to default” an exported variable’s value.

A value in [square brackets] indicates an ‘optional’ value.

Annotation Name	Values	Purpose
@Export	Name: String (256) Help Text: [String (65535)] Type: [“D”, “H”, “LD”, “LH”, “B”, “-1”]	Exports the specified variable to be modifiable Sets the label, helptext, and input field type of the textbox for the exported variable. Name must be specified, help text defaults to blank, and type defaults based on variable type, as: int, float, untyped -> “D” long -> “LD” bool -> “B” rgb -> “LH” else -> “-1”
@ExportRange	Min: int Max: int	Sets a range for the exported variable. The field in the editor will not allow setting its value outside of the specified range. If used on a non-exported variable, errors. If used on a boolean variable, errors.

Static Functions

Functions declared inside scripts work very similarly to variables; an ‘instance function’ can access all instance variables of the script, but any functions declared as static will be unable to access instance variables from the script. Static variables can still be accessed as normal.

The compiler option DEFAULT_STATIC_SCRIPT_MEMBERS affects script functions in almost the exact same way it affects variables; the main difference is that the void run() function will not be made static by it.

Marking a void run() function as static is an error.

Script Annotations

Scripts are capable of being targetted with a number of annotations.

For String values, the number in parentheses is the maximum length, in characters.

These annotations take a single value:

Annotation Name	Value	Purpose
@Author	String (256)	Indicate who authored the script.
@Attribute0 - @Attribute9	String (256)	Sets labels in the Combo / Item editors.
@AttributeHelp0 - @AttributeHelp9	String (65535)	Sets help text in the Combo / Item editors.
@Flag0 - @Flag15	String (256)	Sets labels in the Combo / Item editors.
@FlagHelp0 - @FlagHelp15	String (65535)	Sets help text in the Combo / Item editors.
@Attribyte0 - @Attribyte7	String (256)	Sets labels in the Combo editor.
@AttribyteHelp0 - @AttribyteHelp7	String (65535)	Sets help text in the Combo editor.
@Attrishort0 - @Attrishort7	String (256)	Sets labels in the Combo editor.
@AttrishortHelp0 - @AttrishortHelp7	String (65535)	Sets help text in the Combo editor.
@InitD0 - @InitD7	String (256)	Sets labels for the void run parameters. Defaults to the parameter names.
@InitDHelp0 - @InitDHelp7	String (65535)	Sets help text for the void run parameters.
@InitDType0 - @InitDType7	“D”, “H”, “LD”, “LH”, “B”, “-1”	Sets the input field type of the textbox for inputting the void run parameters. Default based on void run parameter type, as: int, float, untyped -> “D” long -> “LD” bool -> “B” rgb -> “LH” else -> “-1”
@InitScript	int	Only valid on global scripts. Marks that the script should be ‘merged’ into the global script ‘~Init’ that is auto-generated by the compiler. This means that this script will run once, for 1 frame, when the player begins a ‘New Game’. The ‘int’ parameter determines the order that these will run in, starting with the lower numbers and counting up. A global script named Init will always be merged this way, using 0 as the value if this annotation is not provided.
@ScriptInfo	String (65535)	Sets an info / summary / description of the script, shown in the editor UI.
@ScriptSetup	String (65535)	Sets a ‘setup instructions’ string, shown in the editor UI.

These annotations take a varying amount of values. A value in [square brackets] indicates an ‘optional’ value.

Annotation Name	Values	Purpose
@ExportInitD0 - @ExportInitD7	Name: String (256) Help Text: [String (65535)] Type: [“D”, “H”, “LD”, “LH”, “B”, “-1”]	Sets the labels, helptext, and input field type of the textbox for the specified void run parameters. Name defaults to the variable name, help text defaults to blank, and type defaults based on variable type, as: int, float, untyped -> “D” long -> “LD” bool -> “B” rgb -> “LH” else -> “-1”