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.

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.
• 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.

TODO: More detail.

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. 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/doom_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 doom_main.script directly. Instead, we use #include directives to pull in scripts with different names. For example, darkmod_include.script is #included from doom_main.script.

Most of the TDM-specific scripts, including ai_darkmod_base.script, are #included from darkmod_include.script. We could also put further #include directives into ai_darkmod_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.

Script invocation

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

Note the doom_main function in doom_main.script; presumably this is called on level load???

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.