Action System

The dynamic action system is an SCP addition that provides a way for mods to create custom sequences of events that should happen when a certain event occurs. This system is designed to be highly flexible to allow mods complete control over what effects to trigger and where to place them.

This page will describe the basic ideas behind the system and describe how to use it.

Basic functionality

The basic functionality of the action system is to take a list of "Actions" and execute them over the span of an arbitrary amount of game-frames. This allows a mod to specify quite complex operations without hard-coding that into the engine. Example:

$On Beam Warmdown: ; This defines a "program" to run once a beam weapon has finished firing
	; Timing for effects is important so this allows to delay the execution of the remaining actions by 5 (in-mission) seconds
	+Wait: 5

	; Some actions simply update some internal data which can be used by later actions
	; This data will be kept until it is set again and can be used by an unlimited number of actions
	+Set Position: (8.0 0.0 0.0)
	+Set Direction: (1.0 -1.0 1.0)

	; All positions and directions are local to the attached subobject (turret02 in this case) and will respect animations

	; These actions actually cause some external "thing" by using the previously set "local" data
	+Start Particle Effect: "Beam Warmdown Effect"
	+Play 3D Sound: "18"

	+Set Position: locals.position + (3.0 0.0 0.0)
	+Start Particle Effect: "Beam Warmdown Effect"

	+Wait: 3.0

	; Programs are attached to the object that triggered them so if the object dies before this can run then the sound will not be played
	; The position is still (8, 0, 0) from the previous setting so no need to set it here again
	+Play 3D Sound: "19" ; Actions can be used multiple times with different parameters

This sequence of actions will be called a "program" in this document. When the corresponding event is triggered, the program is started which creates a "program instance". Every instance of a program is completely separate from each other and will also execute concurrently. This means that a "+Wait:" instruction in one program will not have any effect on another program wanting to trigger a sound effect or something similar.

When a program is started it will have some parameters specified at that point. These parameters are used for attaching an action to a specific object and subobject depending on where it has been triggered. A program attached to an object will only execute for as long as that object is present in the mission and will be stopped once the object is gone. If a program instance is attached to a subobject then all operations will be local to that subobject. Offsets and directions specified in actions will be relative to the selected subobject. However, a program instance will not be stopped if a subobject is destroyed.

In tables, an action option ("$On Beam Warmdown:" in the above example) can also be used several times in sequence. This will collect all those programs and when the event is triggered, every program is started at the same time with the same parameters. This allows to separate different effects into their own programs in order to make management of these actions a bit easier.

Action expressions

The value used for actions ("locals.position + (3.0 0.0 0.0)" for "+Set Position: locals.position + (3.0 0.0 0.0)" above) is a so called "Action expression". This is a simple language for expressing mathematical expressions which is used for every parameter of an action. The language follows the usual mathematical rules with some special parts that will be described here.

• ~(<left> <right>): Will evaluate to a random value uniformly distributed without the range between <left> and <right>.
• "<name>": Is a string value. This is necessary for actions taking names of other tables as parameters. For example "+Start Particle Effect".
• (<x> <y> <z>): Will create a 3D vector value. Used for positions and directions. Each of the x, y, and z values can themselves be expressions again.

Variables

Every program instance will have some "local" variables assigned to it. This is a set of values that can be changed by the program and used by other actions for altering their behavior. These values are available within expressions:

• locals.position: A vector value specifying an offset from the host of the program instance. Can be changed with "+Set Position".
• locals.direction: A vector value specifying a direction. Can be changed with "+Set Direction".

Available actions

All of these listed actions can generally be combined freely with each other.

+Wait:

Will delay the execution of subsequent actions by the specified amount of in-game seconds.

Parameter type: Floating point number

+Set Position:

Will alter the value of "locals.position" to the specified value.

Parameter type: 3D Vector

+Set Direction:

Will alter the value of "locals.direction" to the specified value.

Parameter type: 3D Vector

+Move To Subobject:

Will alter what subobject the program instance is attached to. A value of "<parent>" will move to the parent subobject of the current one. Otherwise the name of any other subobject may be specified.

Parameter type: String "<none>" or a valid subobject name.

+Start Particle Effect:

Triggers a particle effect with the specified name. Will use "locals.position" as an offset and "locals.direction" to orient the effect.

Parameter type: String The name of a particle effect to trigger.

+Play 3D Sound:

Plays the specified 3D sound. Will use "locals.position" as an offset to compute the global position of the sound.

Parameter type: String The name of the sound as specified in Sounds.tbl