Scripting basics

Doom 3 scripts are text files containing script code in a proprietary syntax. By convention, they are given a .script extension. Game-wide script files are located in the script directory, while map-specific script files are located in the same directory as the corresponding map.

Starting with scripting

This article is an overview over the basics of scripting. If you are impatient and just want to implement a specific functionality, see My first map script for a start into scripting.

Syntax

Doom 3 scripts have a vaguely C++-like syntax, though they are nowhere near as powerful as C++. They have standard braces-and-semicolons syntax, and a notion of "classes". Class members are defined inside a class declaration and defined separately, rather like C++. Unlike C++, there are no separate header files; everything goes into one script file.

Doom 3 scripts have only a few data types:

• float - A number, integer or floating point.
• boolean - can be false or true.
• string - A string (sequence of characters).
• vector - Three numbers in one variable; useful for representing locations, velocities, etc.
• entity - A reference to an entity (a pointer, in C++ parlance).

Note the complete lack of a dedicated integer type (use float instead), or any ability to define complex data structures! If data structures are needed, they are typically created in the SDK and scriptevents (see below) are provided to allow scripts to manipulate them.

For a more detailed specification of Doom 3 script syntax, see Modwiki's SCRIPT file reference.

The float data type

All numeric values are stored in float data types, which is the only numeric type. Neither int, double nor short, unsigned or other numeric keywords known from C exist in D3 Scripting. Still, most of the operators are applicable, like ++, +, -, +=, *=, etc.

The boolean data type

The data type boolean can only hold two values, namely true or false (TRUE or FALSE work as well). Behind the scenes, this is just another float variable.

Note: you can also use float as argument of conditional expressions, like this:

float myFloat = 1; // this will evaluate to TRUE when used in conditional expr.
if (myFloat) {
  // do something, 
}

The string data type

Strings hold sequences of characters, like the keys or values of entity spawnargs. Their use is quite intuitive, the + operator can be used to concatenate them:

string myStr = $player1.getKey("name");   // Retrieve the value of the "name" spawnarg of the player entity
myStr = "The name of player 1 is " + myStr + "\n";
sys.println(myStr);   // Print the text to the console

The vector data type

The data type vector implements a three-component vector. As arrays and their native operator [] is not implemented in D3 scripting, the elements of vectors are accessed like this:

vector myVec;    // declare a new vector
myVec_x = 20;
myVec_y = 0;
myVec_z = 0;
// myVec now holds the 3D vector <20,0,0>

Alternatively, you can assign a string to a vector variable, like this (the string gets converted correctly, but be sure to use single quotes):

myVec = '0 10 0';

As an example, the getOrigin() methods return a vector.

The entity data type

References to other entities are stored in the entity data type. Entities can be looked up by name, like this:

entity myEnt;     // declare myEnt to be of type entity
myEnt = $player1; // Let myEnt refer to the player entity, which by convention has the name "player1".

The entity data type can be compared to the pointers (that's also how they are stored internally) - there also exists a NULL entity, named $null_entity.

The sys entity

Script events always have to be called on an entity, like this:

$player1.kill();      // kill the player

However, there are a lot of scriptEvents which are unrelated to a specific entity, like cos(), sin(), spawn() and such. These "generic" events are invoked on the sys entity, like this:

entity myLight = sys.spawn("light_moving");   // spawn a new light entity
myLight.setOrigin($player1.getOrigin());      // move it to the point where the player is currently residing

Script Events

You can find a list of existing script events in the following two files:

• scripts/doom_events.script
• scripts/tdm_events.script

demagogue: The Editing FAQ adds this information about script events.

Q. What are script events (aka commands or functions)?

A. A script event is a pre-made object that does something for you, usually to some game item you specify, just when you write it in your code (like $item.eventX(); does X to item). Sometimes it wants parameters or arguments to run (the stuff in parentheses) and will give an error if you don't put the arguments in the parentheses in exactly the way it wants, with the right number of them & right data types, etc. And some of them return values too, especially the "get" functions, which are handed over to a variable (e.g., X = getValue();, now X has the value. If X is an entity, you can even act on X as if it's the entity itself. Just be sure the data type of X and Value are the same, e.g. float, or string, or entity, etc, or you'll get an error).

Q. What are some common or useful script events for editing?

A. A list of all Doom3 script events with links to their proper syntax is here [23]. Note that TDM has some of its own script events, like setFrobable. (I can't seem to find a full list. =o ). A quick list of common or useful script events good for editing is here: Script_Events_User-Friendly_List, with syntax and description, and including TDM events. It doesn't list all script events and all details, just common & useful ones for actual mapping IMO.

Discovery (or, why is Doom 3 ignoring my script file?)

Doom 3 will automatically find and load some kinds of files, such as .def files. However, it does not do the same for script files; if you merely create a .script file and place it in the script directory, Doom 3 will blithely ignore it.

There are two ways to make Doom 3 use a script:

• Place it in a map script. This is the recommended way for mappers. Map scripts are loaded when the corresponding map is loaded. They must be given the same name and placed in the same location as the corresponding map file, but with a .script extension instead of a .map extension. For example, the map script for maps/mydir/mymap.map must be called maps/mydir/mymap.script. Map scripts are used to implement map-specific behaviours; as such, mappers will often use them but mod coders typically won't.

• There is only one script that Doom 3 loads for all maps. It's called script/tdm_main.script, and is loaded before the map-specific script. Since this script would be extremely long if it contained all the general-purpose script code in the entire mod, we don't put any script code in tdm_main.script directly. Instead, we use #include directives to pull in scripts with different names. For example, tdm_events.script is #included from tdm_main.script.

Most of the TDM-specific scripts, including tdm_ai_base.script, are #included from tdm_main.script. We could also put further #include directives into tdm_ai_base.script, and so on. As long as a script gets #included at least once, it will get loaded in all maps. Note that you should be careful not to #include the same script twice, or Doom 3 will complain about multiple definitions - one common way to avoid accidental double-inclusion is to place so-called "inclusion guards" in your script file (C/C++ programmers will be familiar with this kind of preprocessor trickery):

#ifndef __TDM_MOVERS__
#define __TDM_MOVERS__

// your code here will get included exactly once

#endif //__TDM_MOVERS__

Script invocation

TODO: Describe the various ways in which functions in script files can get called.

The tdm_main function in script/tdm_main.script will be called right before the level starts to load. It's not recommended to put map-specific scripting in there. For map-specific script setup, use the map's own script file and place a void main() function in there, which will get called by the game.

demagogue: The Editing FAQ has this entry for calling functions in scripts in-game.

Q. How do I run a script in-game?

A. A few common ways of calling a script object thread in-game are (1) creating a target_callscriptfunction entity with the spawnarg: "call" "<name of your script object>", then creating some other entity (such as a button or trigger brush) that "targets" that entity; (2) creating a button with the property "state_change_callback" "<script object>", which runs the script when pushed or triggered, (3) Using Location_Settings#Script_calls to call a script when you enter or leave a location; (4) triggering a script with the Objectives_Editor when you fulfill or fail an objective (possibly a hidden objective only for triggering the script); (5) A script can call another thread in itself with the "thread" function; see the command in the link below. (6) An entity can call a script when it spawns. Add a property/value either in the .def file or as a spawnarg on the entity: "ScriptEvent void <script object>(<parameters>);". (7) The script "void main();" is always called at game start. So if you add code under that heading in your script file, it will run at game start. There are other methods too. (Note, if you call a persistent script, i.e., it runs all game, be especially sure to avoid performance hits, or make it non-persistent if possible.)

Interfacing with the SDK

No language can operate usefully in a vacuum - at some point it needs to go out and do stuff.

TODO: Describe the various ways in which the SDK can interface with Doom 3 scripts; scriptevents, scriptvars (instances of idScriptVar), etc.

Vanilla Doom 3 script reference: http://www.modwiki.net/wiki/Script_events_%28Doom_3%29

Also need refs for Dark Mod's scriptevents.

Things that don't exist in D3 scripting

This is a non-comprehensive list of things that don't exist in D3 scripting, but may be expected or known from other languages.

• structs
• pointers (including dereference operators ->, *)
• integers (use floats instead)
• arrays (including the array operator[])
• exceptions
• "crashes" (you can call scriptEvents on any entity, even if that entity doesn't support it, the script won't crash).
• char data types, which implies that const char* is also missing (use string instead)
• private/public/protected
• multiple inheritance

See also

• My first map script