Scripting basics

Doom 3 scripts are text files with a .script extension, typically located in the script directory. (FIXME: Are these requirements or conventions?)

Syntax

The syntax of the scripts is vaguely C++-like, though the scripts are nowhere near as powerful. 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 only have 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, 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 listing of the 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 just create a .script file and dump it into 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. Maps scripts are loaded when the corresponding map is loaded, but they must be named the same as the map file. For example, the map script for mymap.map must be called 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 doom_include.script (FIXME: is this correct?). 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_include.script directly. Instead, we use #include directives to pull in scripts with different names. For example, darkmod_include.script is #included from doom_include.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.

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.