Writing Script Objects

Introduction

A script object is an object that is written in the idTech4 scripting language, and an be attached to arbitrary entities. Each entity can have only one script object.

Script objects can call script events, these provide access to functions provided by the C++ code. They also have access to the spawnargs of the entity they are attached to, other entities (and their spawnargs!), as well as global functions (like "sys.wait"), and CVARs.

An script object should have at least a definition, and one constructor. To prevent that inclusion of that script file defines the object twice, we also use "ifndef" and "define" to guard against this.

Writing your own Script Object

Here is an example:

#ifndef __NAME_HERE__
#define __NAME_HERE__

object the_script_object_name_here
{
    /**
    * Define a float variable that the script code can access. The "m_" prefix
    * will remind us that this is a member:
    **/
    float   m_updatePeriod;

    /**
    * Define the constructor, will be called automatically _once_:
    */
    void   init();

    /**
    * Optional: Define a routine that gets called when a savegame is loaded:
    */
    void   RestoreScriptObject();

    /**
    * Optional: Define a routine that can work periodically.
    */
    void   updateLoop();
};

// now define the routines and their code
void the_script_object_name_here::init()
{
    // print out that we are constructed for debugging:
    sys.println ("the_script_object_name_here::init() called");

    // initialize our member from a spanwarg from the entity this
    // script object is attached to:
    m_updatePeriod = getFloatKey( "update_period" );

    // Done now. If you want to do some work be done periodically,
    // call it here once, and let it loop.
    updateLoop();
};

void the_script_object_name_here::RestoreScriptObject()
{
    // print out that we are constructed for debugging:
    sys.println ("the_script_object_name_here::RestoreScriptObject() called");

    // We have to do nothing by default, everything is already restored
    // but if your script object plays some sounds, you might want to
    // restart them here.     
}

void the_script_object_name_here::updateLoop()
{
    // endless loop
    while (1)
    {

        // do something here

        // then wait the wanted time, and do it again:
        wait( m_updatePeriod );
    }
}

#endif // __NAME_HERE__

For a more complete example see script/tdm_location_settings.script.

Notes

Avoid method names that already exist in the C++ code. For instance "Restore()", "Save()", "Spawn()" etc. These all might cause unwanted side-effects or crashes. They also make it impossible to be called from the C++ code.

Pre-made Script Objects

TDM already contains some useful script objects that you can attach to entities, see Script objects for a list.

tdm_suicide

 "script_object" "tdm_suicide"
 "remove_delay"  "100"              // remove this entity 100 seconds after spawning it

tdm_light_holder

 "script_object" "tdm_light_holder"
 "extinguished"  "1"                // the light starts off, but can be lit by the player

This is typical attached to either lights (an electrical lamp f.i.) or light holders (a candle holder with attached candle + flame, or a torch with attached flame). This script object has handy methods to toggle all lights that this holder has, regardless how many (multiple flames?) or where (flame on holder or flame on candle on holder?).

This script object also makes the entity react to fire stims, an/or triggers like when you link a button/lever/trigger to this entity.