Level scripting

This page is in urgent need of attention because: Unfinished sections

If you disagree with this, please explain why on its talk page .

Note: Enemy Territory: Quake Wars only:
ETQW uses a script object for it’s map script. See script object , this tutorial , or the splash damage wiki [ [1] ].

Level scripting refers to scripting that is parsed during a level runtime. Level scripting is a very powerful tool used to control various entities within a level. If you have played through Doom 3 you will have undoubtedly noticed the complex machinery with various moving parts, lights, and effects. Machines like this are just one example of level scripting. Listing all of the various examples of level scripts would be next to impossible as the power of level scripting is virtually endless. This section is dedicated to an overview of the syntax and power of level scripts.

What’s this?

Scripting quick reference

- Script events

Creating the .SCRIPT File

It is important to first understand where the engine looks for the script. Level scripts should be placed in the map folder where the map is. The script file must be named exactly the same as the map file with a .SCRIPT file format instead of .MAP.

  • Locate the map - it will most likely reside in Doom3\base\maps\
  • Find yourmap.map (where “yourmap” is the actual name of the map)
  • Create a file named yourmap.script (where “yourmap” is the actual name of the map)
  • Edit this .script file with your favorite script editor to begin level scripting.

The Basics

General Syntax

Level scripting syntax follows a similar syntax to that of C or JavaScript language. Refer to the SCRIPT file format article for a basic overview of syntax and the Scripting_basics article for beginning scripting tutorials.

Example

Here is an example of a simple level script:

void setup_objects()  {
    $fanblade.bind($rotator);
}
 
 
void main()  {
    setup_objects();
}

With a basic understanding of scripting syntax, the above script breaks down as follows:

  • We are first declaring a new function called setup_objects. The void indicates the type of variable the function will return – in this case nothing.
  • We are referencing the entity called “fanblade” and telling it to bind itself to an entity called “rotator”.
  • We then move onto the main function, which will tell the function setup_objects to run on level load.

It is important to note a few things in level scripting:

  1. The main() function is always called when a level loads.
  2. You must declare any functions and/or global variables before you attempt to call them with main().

A Note on Variables and Functions

Level scripts work with variables and functions as described in the SCRIPT_(file_format) article and the Scripting_basics article.

How to Interact With Level Scripts

Level scripts are nothing unless we can interact with them as a player in the level. There are 3 primary ways to accomplish level-to-script interaction.

Triggers in the Level

Every trigger (apart from trigger_fade and trigger_hurt) has a built in key/val pair for calling script functions. The key/val is - call:script_function.

In the editor, double click on the call keyword within the entity dialog and fill in the name of the script function you wish to call. When the trigger is triggered the it will call that function. The function must be declared in the .script file before attempting this.

Note: You cannot pass arguments to a script function using a trigger. This is an unfortunate limitation - see hacking around limitations for more details.

GUIs

In-game GUIs can function very much like triggers placed in the map. To call a script from a GUI first you must attach a GUI to a model or entity that supports a GUI display. Depending upon how the GUI was built, you must use a gui_parm with the name of a script function to call. Most GUIs will list which gui_parm is attached to which button.

Example

In the Doom 3 editor reference the gui guis/monorail/lower_klaxxon.gui.

Notice the comment on the gui:“runs the script in gui_parm6”

This means that on the entity that contains the GUI if you input a key/val of gui_parm6:myscript, the myscript function will be called whenever the GUI is clicked.

Notes

GUIs are a different animal when it comes to scripting. GUI Scripting is beyond the scope of this article. While different buttons within a GUI can be made to call specific script functions, it is heavily dependent upon the type of GUI in use. You must refer to comments associated with a GUI to understand which gui_parms will call scripts. Later on it may be necessary to write a custom GUI to handle specific needs within a map. While GUIs come in all designs and functions the basic principle that a gui_parm must be used to call a script function remains true.

With that said, note that every GUI will be different and as such this article cannot provide enough examples for each GUI, the level creator must use his judgment and will to determine how each GUI will interact.

The main() Function

Lastly, as stated in the example, the main function may be used to call functions upon map load.

Extended Examples

Examples needed

Hacking Around Limitations

To be created…

follows along the lines of:

 
void setArea(entity ent)
{
    area = ent.getFloatKey("area");
 
    sys.println("Area: " + area);
}

This page is a Stub. You can help us by expanding it.