Table of Contents
Script Messages
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.
BeginScript
Sent to all objects when the script is loaded. Usually the same time a game starts.
EndScript
Sent to all objects when the script is unloaded. Usually when the game ends.
Create
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 false.
Sim
Indicates that a mission is starting or ending.
| fStarting | Is true for the first Sim message sent in a game. |
DarkGameModeChange
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 false.
| fEntering | Is true when switching into game-mode. |
AIModeChange
Sent when the AIMode property of an AI changes.
| mode | The new AI mode. |
| previous_mode | The mode the AI was at before. |
| Mode | Value |
|---|---|
| Asleep | 0 |
| Super-efficient | 1 |
| Efficient | 2 |
| Normal | 3 |
| Combat | 4 |
| Dead | 5 |
Alertness
Sent when the AIAlertness property of an AI changes.
| level | Current alertness level. |
| oldLevel | Previous alertness level. |
ObjActResult
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. |
PatrolPoint
Sent when an AI reaches a patrol point.
| patrolObj | The object ID of the marker. |
SignalAI
Sent when a named signal is sent to an AI. Signals are an auxiliary message system for AI.
| signal | The name of the signal. |
StartAttack
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. |
EndAttack
Sent when an attack maneuver is finished.
| weapon | The object ID of the weapon. |
Combine
Sent when an object is merged into the stack count of another object.
| combiner | The object that will have its stack count changed. |
Contained
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. |
Container
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. |
Damage
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. |
Destroy
Sent to an object when it is about to be removed from existence.
Difficulty
Sent to objects that have the DiffScript property and the appropriate flag of the property is set.
| difficulty | Current difficulty level. |
Door Messages
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. |
Freeze, Unfreeze
Sent to an AI (from itself) when it starts being frozen, and when it stops being frozen. AIs become frozen only via script services.
Focus and Select Messages
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.
Frob Messages
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. |
| Frobber | |
| 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. |
HighAlert
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. |
Launch
Sent to projectiles.
LightChange
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. |
Motion Messages
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. |
NowLocked
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.
NowUnlocked
Sent to an object when it is unlocked.
PickStateChange
Sent to an object that uses the AdvPickCfg property.
| PrevState | The old pick state. |
| NewState | The new pick state. |
Physics Messages
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.
| Submod |
| collType |
| collObj |
| collSubmod |
| collMomentum |
| collNormal |
| collPt |
| contactType |
| contactObj |
| contactSubmod |
| transObj |
| transSubmod |
PhysCollision
Sent when an object has collided with another object or solid terrain.
PhysContactCreate
Sent when two objects touch each other.
PhysContactDestroy
Sent when two objects that were touching seperate.
PhysEnter
Sent when an object moves into a physics model. Obviously, the CollisionType of the entered object can’t be Bounce.
PhysExit
Sent when an object moves out of a physics model.
PhysFellAsleep
Sent when an object comes to a complete stop.
PhysMadeNonPhysical
Sent when the physics model of an object is deactivated.
PhysMadePhysical
Sent when the physics model of an object is activated.
PhysWokeUp
Sent when an object that was still begins moving again.
Pressure Plate Messages
PressurePlateActivating
Sent when a pressure plate begins moving down.
PressurePlateActive
Sent when a pressure plate is fully depressed.
PressurePlateDeactivating
Sent when a pressure plate begins moving up.
PressurePlateInactive
Sent when a pressure plate has returned to the raised position.
Room Messages
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. |
CreatureRoomEnter
Sent to a room when an AI enters.
CreatureRoomExit
Sent to a room when an AI exits.
ObjectRoomEnter
Sent to a room when an object that isn’t a player nor AI enters.
ObjectRoomExit
Sent to a room when an object that isn’t a player nor AI exits.
ObjRoomTransit
Sent to an object (including players and AI) when the room it’s in changes.
PlayerRoomEnter
Sent to a room when the Player object enters.
PlayerRoomExit
Sent to a room when the Player object exits.
RemotePlayerRoomEnter
Sent to a room object when a networked player enters.
RemotePlayerRoomExit
Sent to a room object when a networked player exits.
Slain
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. |
SchemaDone
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. |
SoundDone
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. |
Stimulus Messages
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. |
Stun, Unstun
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.
Test
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.
Timer
Sent when a script requests a timed message.
| Name | The name used to set the timer. |
TweqComplete
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) |
| Dir | 0=Forward, 1=Reverse |
Call
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.
WaypointReached
Sent to a waypoint when a moving terrain object has reached it.
| moving_terrain | The object ID of the moving terrain. |
MovingTerrainWaypoint
Sent to a moving terrain object when it reaches a waypoint.
| waypoint | The object ID of the waypoint. |
MediumTransition
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.)
| nFromType |
| nToType |
QuestChange
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. |
YorN
Sent when a yes-or-no prompt is used. Only available in System Shock 2.
| YorN | Is true if the player pressed “Yes”. |
Keypad
Sent when a keypad is used. Only available in System Shock 2.
| code | The number that was entered in the keypad. |
DHNotify
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.
| event | 0=Create, 1=Destroy. |
| idObj | The object ID. |
Hierarchy hooks have these fields.
| event | 0=Add metaproperty, 1=Remove metaproperty, 2=Add child, 3=Remove child. |
| idObj | This object. |
| idSubj | The object being added or removed. |
To use the DarkHook service, you need the DH2.osl module from Public Scripts.
