Signals

Originally written by Ishtvan on http://forums.thedarkmod.com/topic/4190

D3 has various "signals" that are applied at various times in the SDK, that you can use in scripting to call other scripts.

List of Signals

From Doom3/base/script/doom_defs.script

//
// signals
//
#define SIG_TOUCH            0    // object was touched
// (D3 use NOT frobbing)
#define SIG_USE              1    // object was used
#define SIG_TRIGGER          2    // object was activated (generally by a trigger)
#define SIG_REMOVED          3    // object was removed from the game
#define SIG_DAMAGE           4    // object was damaged
#define SIG_BLOCKED          5    // object was blocked
#define SIG_MOVER_POS1       6    // mover at position 1 (door closed)
#define SIG_MOVER_POS2       7    // mover at position 2 (door open)
#define SIG_MOVER_1TO2       8    // mover changing from position 1 to 2 (door opening)
#define SIG_MOVER_2TO1       9    // mover changing from position 2 to 1 (door closing)

// convenience signals for doors
#define SIG_DOOR_CLOSED      SIG_MOVER_POS1
#define SIG_DOOR_OPEN        SIG_MOVER_POS2
#define SIG_DOOR_OPENING     SIG_MOVER_1TO2
#define SIG_DOOR_CLOSING     SIG_MOVER_2TO1  

What you can do with signals

Assuming you know of a signal that will be sent by the SDK to your entity at a certain time, you can write a script to set up another script to be called when it receives this signal using the following syntax:

sys.onSignal( <SIGNAL>, <entity to listen for the signal on>,  "<script name to call when we get the signal>" )

Example

sys.onSignal( SIG_BLOCKED, $lift_bottom, "map_commoutside::lift_move_blocked" );

Using Signals to set up custom Trigger Behavior in Script

For a while, we've been wanting to change what happens when you trigger an object within scripting, without having to make changes to the SDK. Well, now we can. Simply put, in the entity file:

object <myEntity>
{
     void init( );
     void TriggerScript( );
}

void <myEntity>::init ( )
{
     sys.onSignal( SIG_TRIGGER , self, "<myEntity>::TriggerScript" );
}

void <myEntity>::TriggerScript( )
{
     sys.print("I've been triggered! \n");
}

So now we can change the trigger behavior for various types of entities without needing to modify Event_Activate in the SDK.

Obviously there are a lot of other useful signals too. A lot of them have to do with movers and their states. We might be able to tell if a mover is blocked (something I remember Dram asking about) using SIG_BLOCKED. I'm not sure if our Frobdoors give all those door-related signals, but they might give some, because they do inherit from idMover, and we could code in the others pretty easily.

There's also a way to clear the response you set with onSignal if you don't want it to call that script anymore (you probably also have to do this before you assign a new script to it if you want to do that). The documentation is reproduced here:

// Sets a script callback function for when the given signal is raised on the given entity.
scriptEvent    void     onSignal( float signalNum, entity ent, string functionName );

// Clears the script callback function set for when the given signal is raised on the given entity.
scriptEvent    void     clearSignalThread( float signalNum, entity ent );