Dark Engine games interact with scripts with messages. Each message describes a specific event that has occurred in the game. In addition to the predefined game messages, many scripts will send their own messages for use by other scripts. The common TurnOn and TurnOff messages are used only by scripts. The messages can be used for any purpose.
Messages are named based on the events that trigger them. When sending custom messages, you should not use a name that already has a meaning to the game. Extra information about the event is passed to the message function in a table.
The message table should not be used after your function returns. If you need to save fields of the message, you should copy the values.
All messages contain these fields:
|From||The object ID that sent the message.|
|To||The object ID the message is sent to.|
|Message||The name of the message.|
|Time||The simulation time that the message was sent.|
|Data||An array of three values. This is the extra data sent with the message.|
Messages sent by the game have specific meanings and often provide extra fields with details about the message.
Sent to all objects when the script is loaded. Usually the same time a game starts.
Sent to all objects when the script is unloaded. Usually when the game ends.
Sent to an object that is created after the game starts. A newly created object will receive BeginScript, then Create. If applicable, there will be an ObjRoomTransit message. Finally, it gets DarkGameModeChange with the fEntering field set to
Indicates that a mission is starting or ending.
|fStarting||Is true for the first Sim message sent in a game.|
The game is changing from game-mode to a menu or book, or vice-versa. The first DarkGameModeChange message sent after BeginScript will have the fEntering flag set to
|fEntering||Is true when switching into game-mode.|
Sent when the AIMode property of an AI changes.
|mode||The new AI mode.|
|previous_mode||The mode the AI was at before.|
Sent when the AIAlertness property of an AI changes.
|level||Current alertness level.|
|oldLevel||Previous alertness level.|
Sent when an action that the AI was instructed to do by a script or psuedo-script has finished.
|action||1=Goto, 2=Frob, 3=Maneuver|
|result||0=Done, 1=Failed, 2=Not attempted|
|result_data||Extra data associated with the action.|
|target||The target of a frob or goto action.|
Sent when an AI reaches a patrol point.
|patrolObj||The object ID of the marker.|
Sent when a named signal is sent to an AI. Signals are an auxiliary message system for AI.
|signal||The name of the signal.|
Sent when an AI begins an attack maneuver. Either swinging a weapon or firing a projectile.
|weapon||The object ID of the weapon being swung.|
Sent when an attack maneuver is finished.
|weapon||The object ID of the weapon.|
Sent when an object is merged into the stack count of another object.
|combiner||The object that will have its stack count changed.|
Sent to the destination of a Contains link when the link changes. See the Container message for event descriptions.
|event||Container event number.|
|container||The source of the Contains link.|
Sent to the source of a Contains link when the link changes. The event is 2 when adding a link, 3 when removing a link, and 4 when combining with another object. Events 0 and 1 are rarely used.
|event||Container event number.|
|containee||The destination of the Contains link.|
Sent to an object when its hit points have changed.
|kind||The object ID of the stimulus that caused the damage.|
|damage||Change in hit points. If this is negative, the object increased its hit points.|
|culprit||The object that was the source of the stimulus.|
Sent to an object when it is about to be removed from existence.
Sent to objects that have the DiffScript property and the appropriate flag of the property is set.
|difficulty||Current difficulty level.|
The messages sent when a door moves are: DoorClose, DoorClosing, DoorHalt, DoorOpen, DoorOpening. The door action is 0 when the door is open, 1 when the door is closed, 2 when the door is opening, 3 when it is closing, and 4 when the door has stopped part-way between open and closed.
|ActionType||What the door is doing now.|
|PrevActionType||What the door was doing previously.|
Sent to an AI (from itself) when it starts being frozen, and when it stops being frozen. AIs become frozen only via script services.
These are sent when an object is looked at in the inventory or in the world.
WorldSelect, WorldDeSelect: sent to an object with FrobInfo: World/FocusScript when it is highlighted or unhighlighted in the world by looking at it.
InvSelect, InvDeSelect: sent to an object with FrobInfo: Inventory/FocusScript when the item is scrolled to, or selected with a hotkey in the inventory (or weapon inventory). If an object’s hotkey is pressed but it was already the current inventory item, InvSelect is not sent.
InvFocus, InvDeFocus: sent to an object with FrobInfo: Inventory/FocusScript when the inventory is displayed (by scrolling), or dismissed (by timing out, or with Backspace). If the inventory is not displayed, and an object’s hotkey is pressed but it was already the current inventory item, InvFocus is not sent (this feels like a bug).
WorldFocus, WorldDeFocus: these messages are declared, but I have never observed them being sent in Thief.
The behaviours of these messages probably differ in System Shock 2, when using the mouse cursor with the inventory and/or the world.
There are many ways to frob objects. The messages that will be sent depend on the flags set in the FrobInfo property.
Messages are FrobInvBegin, FrobInvEnd, FrobToolBegin, FrobToolEnd, FrobWorldBegin, FrobWorldEnd.
|SrcObjId||The object being used in a tool frob.|
|DstObjId||The object being frobbed.|
|SrcLoc||Where the frob is taking place. 0=World, 1=Inventory, 2=Tool.|
|DstLoc||Where the object being frobbed is.|
|Sec||When a frob ends, this is the number of seconds it lasted.|
|Abort||If the frob was interrupted by the game, this will be true.|
Sent when the AIAlertness property of an AI changes to 3 from a lower level.
|level||Current alertness level. Should always be 3.|
|oldLevel||Previous alertness level.|
Sent to projectiles.
Sent to an AnimLight object, if it has subscribed to updates (using the Light.Subscribe() service).
|data||The light’s current brightness.|
|data2||The light’s minimum brightness.|
|data3||The light’s maximum brightness.|
When a script instructs an AI to play a motion, it gets the messages MotionStart, MotionEnd, and MotionFlagReached.
|ActionType||0=Start, 1=End, 2=Flag reached.|
|MotionName||Name of the motion.|
|FlagValue||Type of flag reached.|
Sent to an object when it becomes locked. This can be because the Lock property was set, or there is a Lock link and the linked object has become locked.
Sent to an object when it is unlocked.
Sent to an object that uses the AdvPickCfg property.
|PrevState||The old pick state.|
|NewState||The new pick state.|
All the physics messages require an object to subscribe to the events that it wants to receive. The messages use a common data structure, but only those fields relevant to the message will be valid.
Physics messages are sent for each sub-model, so you will often get the same message repeated for the same object, but different sub-models.
Sent when an object has collided with another object or solid terrain.
Sent when two objects touch each other.
Sent when two objects that were touching seperate.
Sent when an object moves into a physics model. Obviously, the CollisionType of the entered object can’t be
Sent when an object moves out of a physics model.
Sent when an object comes to a complete stop.
Sent when the physics model of an object is deactivated.
Sent when the physics model of an object is activated.
Sent when an object that was still begins moving again.
Sent when a pressure plate begins moving down.
Sent when a pressure plate is fully depressed.
Sent when a pressure plate begins moving up.
Sent when a pressure plate has returned to the raised position.
Room messages are sent when an object moves between rooms. A single room can be made up of many room brushes to suit the architecture of a mission. No matter how many brushes an object passes through, if the brushes are all created from the same room object, then it never leaves the room. A room brush must be created from a concrete room object.
There are multiple messages for rooms to distinguish different types of objects.
|FromObjId||The ID of the room the object exitted.|
|ToObjId||The ID of the room being entered.|
|MoveObjId||The ID of the object that is moving.|
|ObjType||0=Player, 1=Remote player, 2=Creature, 3=Other object.|
|TransitionType||0=Enter, 1=Exit, 2=Transit.|
Sent to a room when an AI enters.
Sent to a room when an AI exits.
Sent to a room when an object that isn’t a player nor AI enters.
Sent to a room when an object that isn’t a player nor AI exits.
Sent to an object (including players and AI) when the room it’s in changes.
Sent to a room when the Player object enters.
Sent to a room when the Player object exits.
Sent to a room object when a networked player enters.
Sent to a room object when a networked player exits.
Sent to an object when its hit points have fallen to 0 or less. This message is sent before the SlayResult actions take effect.
|culprit||The source of the stimulus that caused the damage.|
|kind||Object ID of the stimulus.|
Sent to the host object for a schema when it has completed.
|coordinates||The location that the schema played at.|
|targetObject||Object the schema played on.|
|name||Name of the schema.|
Sent to the host object for a sound when it has completed.
|coordinates||The location that the sound played at.|
|targetObject||Object the sound played on.|
|name||Name of the sound.|
A stimulus can send a script message to an object. Messages are sent if the Send to Scripts receptron action is used, or if the script subscribes to the stimulus. Either one is sufficient, and you should not do both at the same time.
The name of a stimulus message is the stimulus archetype name plus the word “Stimulus”. So, for example, the message sent when a WaterStim stimulus is received will be WaterStimStimulus.
|stimulus||Object ID of the stimulus archetype.|
|intensity||Amount of stimulus received.|
|sensor||The ID of a StimSensor link.|
|source||The ID of an arSrc link.|
Sent to an AI (from itself) when it starts being stunned, and when it stops being stunned. AIs become stunned when flashbombed, or when surprised (that is, when an Alertness message indicating a leap to level 3 from level 0 or 1 alertness). AIs can also be stunned via script services.
Sent with the script_test <obj> console command. This will still send the message when in edit mode in Dromed, which can occasionally be useful.
Sent when a script requests a timed message.
|Name||The name used to set the timer.|
Sent to an object when a tweq event occurs.
|Type||0=Scale, 1=Rotate, 2=Joints, 3=Models, 4=Delete, 5=Emit, 6=Blink|
|Op||2=Halt, 5=FrameEvent (flicker)|
Sent to a moving terrain object to instruct it to move to a waypoint. The waypoint to move to is the source of the message.
Sent to a waypoint when a moving terrain object has reached it.
|moving_terrain||The object ID of the moving terrain.|
Sent to a moving terrain object when it reaches a waypoint.
|waypoint||The object ID of the waypoint.|
Sent to an object when moving into or out of water. Only activated by an AI with the Track Medium property set. The medium type for air is 1, the type for water is 2. (Solid is 0, but I don’t think it matters.)
Sent to an object that has subscribed to a quest variable.
|m_pName||Name of the variable.|
|m_oldValue||Previous value of the variable.|
|m_newValue||Current value of the variable.|
Sent when a yes-or-no prompt is used. Only available in System Shock 2.
|YorN||Is true if the player pressed “Yes”.|
Sent when a keypad is used. Only available in System Shock 2.
|code||The number that was entered in the keypad.|
The DarkHook service lets you subscribe to changes to a property, link, or object. Your script is notified of changes with a DHNotify message. Different types of hooks have different fields. The typeDH field is available in all DHNotify messages.
|typeDH||The type of hook. “Property”, “Relation”, “Object”, or “Trait”.|
Property hooks have these fields.
|event||1=Change, 2=Add, 3=Remove.|
|PropName||The name of the property.|
|idObj||ID of the object.|
Relation hooks have these fields.
|event||1=Change, 2=Add, 3=Remove.|
|RelName||Name of the relation.|
|LinkId||ID of the link.|
|LinkSource||Source object ID.|
|LinkDest||Destination object ID.|
Object hooks have these fields.
|idObj||The object ID.|
Hierarchy hooks have these fields.
|event||0=Add metaproperty, 1=Remove metaproperty, 2=Add child, 3=Remove child.|
|idSubj||The object being added or removed.|
To use the DarkHook service, you need the
DH2.osl module from Public Scripts.