User Tools

Site Tools


lgscript:messages

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.

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, InvDeFocus, InvDeSelect, InvFocus, InvSelect, WorldDeFocus, WorldDeSelect, WorldFocus, WorldSelect

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.

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.

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.

lgscript/messages.txt · Last modified: 2009/09/16 20:40 by telliamed