Command Lua Documentation

Events

An event consists of one or more triggers, an optional set of conditions, and one or actions to perform when the trigger(s) and condition(s) are fulfilled.
With Lua, you can create triggers, conditions and actions independently of the editor, and create or modify events with them.

Trigger, Condition and Action
There are separate functions to handle the creation, update and deletion of the components of an event.

(a) ScenEdit_SetTrigger( { table } )
As it sounds, a trigger is something that fires off, and results in a success or fail. Apart from a few common keywords, each trigger has a set of keywords.

The common keywords used in the Lua table are:
1) description - the name given to the trigger. The keyword 'name' can also be used for this.
2) mode - type of operation to perform. Operations are 'list', 'add', 'remove', and 'update'.
3) id - the GUID used to reference the trigger. This is used internally and is only for refernence.

The trigger related keywords are listed below.

Trigger type	Keyword	Comment
Points	SideID	Side to adjust points for
	PointValue	Current points
	ReachDirection	GoOver = 0, MatchExactly = 1, GoUnder = 2
RandomTime	EarliestTime	Earliest date/time to start checks
	LatestTime	Latest date/time to stop checks
RegularTime	Interval	Time interval (1 sec, 2sec, 5sec, etc)
ScenEnded		No additional keywords
ScenLoaded		No additional keywords
Time	Time	Actual date/time to fire on
UnitDamaged	DamagePercent
	TargetFilter	See below
UnitDestroyed	TargetFilter	See below
UnitDetected	TargetFilter	See below
	DetectorSideID	Side doing the detecting
	MCL	Minimum classifcation level
	Area	Table of reference points
UnitEmissions	TargetFilter	See below
	DetectorSideID	Side doing the detecting
UnitEntersArea	TargetFilter	See below
	Area	Table of reference points
	ETOA	Earliest date/time of arrival
	LTOA	Latest date/time of arrival
	NOT	Not in the area
	ExitArea	Leaving area
UnitRemainsInArea	TargetFilter	See below
	Area	Table of reference points
	TD	Time to remain in area in seconds (or as days:hours:minutes:seconds)
UnitBaseStatus	TargetFilter	See below
	TargetStatus	Status number to monitor
UnitCargoMoved	CargoFilter	See below
	TargetLimitReceived	Number received to trigger
	TargetLimitSent	Number sent to trigger

TargetFilter:
A series of filters to apply to units. Only units matching this filter will fire the trigger.

TargetFilter	TargetSide	Side to fillter on
	TargetType	Type of unit (ship, submarine, etc)
	TargetSubType	Subtype of the above unit type
	SpecificUnitClass	Unit class (DBID)
	SpecificUnitID	Actual unit

Note that side is mandatory, but you can specify a unit or type/sub/class. However, if using type/sub/class, you can use
1) type, or
2) type and subtype, or
3) type, subtype (optional as it is inferred from class) and class.

TargetType:

Aircraft	1
Ship	2
Submarine	3
Facility	4
Aimpoint	5
Weapon	6
Satellite	7

CargoFilter:
A series of filters to apply to cargo items, similar to the TargetFilter.

TargetFilter	TargetType	Type of cargo item (personel[1000],etc)
	SpecificUnitClass	Cargo class (DBID)
	SpecificUnitID	Actual cargo item

TargetType:

Aircraft	1
Ship	2
Submarine	3
Facility	4
Aimpoint	5
Weapon	6
Satellite	7

Examples

Create a trigger for a specific unit leaving an area

local a = ScenEdit_SetTrigger({mode='add',type='UnitEntersArea',name='Sagami exiting hot zone', targetfilter={SPECIFICUNIT='AOE 421 Sagami'},area={'rp-1126','rp-1127','rp-1128','rp-1129'},exitarea=true})
The varaiable a will contain the trigger information. It will be 'nil' if the trigger failed in a non-interactive script as in an event.

Modify the trigger to 'any type of AOE entering hot zone'

local a = ScenEdit_SetTrigger({mode='update',type='UnitEntersArea',name='Sagami exiting hot zone', rename='Any AOE entering hot zone', targetfilter={TargetSubType = '5023', TargetType = '2' , TargetSide='sidea'}, area={'rp-1126','rp-1127','rp-1128','rp-1129'}, exitarea=false})

Remove the trigger 'any type of AOE entering hot zone

local a = ScenEdit_SetTrigger({mode='remove',type='UnitEntersArea',name='Any AOE entering hot zone'})
If the trigger is assigned to an event, it can't be removed until removed from the event.

--------------------------------------------

(b) ScenEdit_SetCondition( { table } )
As it sounds, a condition is something that can be further applied once the trigger has fired, and results in a success or fail. Apart from a few common keywords, each condition has a set of keywords.

The common keywords used in the Lua table are:
1) description - the name given to the condition. The keyword 'name' can also be used for this.
2) mode - type of operation to perform. Operations are 'list', 'add', 'remove', and 'update'.
3) id - the GUID used to reference the condition. This is used internally and is only for refernence.

The condition related keywords are listed below.

Condition type	Keyword	Comment
LuaScript	ScriptText	A Lua script
ScenHasStarted	NOT	A NOT modifier for scenario NOT started yet
SidePosture	ObserverSideID	Side that views TargetSide as ...
	TargetSideID
	TargetPosture
	NOT	A NOT modifier to change condition from true to false

For scripts, use '\r\n' to represent new lines, otherwise a multi-line script may not run. ScriptTest='--comment\r\nif unit ~= nil then\r\n return true\r\n else\r\n return false\r\n end'

Examples

Create a condition for sideA being hostile to sideB

local a = ScenEdit_SetCondition({mode='add',type='SidePosture',name='sideA hostile to sideB', ObserverSideId='sidea', TargetSideId='sideb', targetposture='hostile'})
The varaiable a will contain the condition information. It will be 'nil' if the function fails in a non-interactive script as in an event.

--------------------------------------------

(c) ScenEdit_SetAction( { table } )
As it sounds, a action is something that will be done once the trigger (and condition) are successful. Apart from a few common keywords, each action has a set of keywords.

The common keywords used in the Lua table are:
1) description - the name given to the action. The keyword 'name' can also be used for this.
2) mode - type of operation to perform. Operations are 'list', 'add', 'remove', and 'update'.
3) id - the GUID used to reference the action. This is used internally and is only for refernence.

The action related keywords are listed below.

Action type	Keyword	Comment
ChangeMissionStatus	MissionID	Mission identifier
	NewStatus	New status - active(0) or inactive (1)
EndScenario		No additional keywords
LuaScript	ScriptText	A Lua script
Message	SideID	Side to see message
	Text	Message text to show
Points	PointChange	Value to change points by (+/-)
	SideID	Side affected
TeleportInArea	UnitIDs	Table of unit GUIDs
	Area	Table of reference points

For scripts, use '\r\n' to represent new lines, otherwise a multi-line script may not run. ScriptTest='--comment\r\nif unit ~= nil then\r\n return true\r\n else\r\n return false\r\n end'

Examples

Create a action changes points on SideA

local a = ScenEdit_SetAction({mode='add',type='Points',name='sideA loses some ..', SideId='sidea', PointChange=-10})
The varaiable a will contain the action information. It will be 'nil' if the function fails in a non-interactive script as in an event.

Modifying Events
Triggers, conditions and actions (TCA) can be linked to events. A common format is followed for each one.

(a) ScenEdit_SetEventTrigger( eventName, { table } )
(b) ScenEdit_SetEventCondition( eventName, { table } )
(c) ScenEdit_SetEventAction( eventName, { table } )
The common keywords used in the Lua table are:
1) description - the name given to the TCA. The keyword 'name' can also be used for this.
2) mode - type of operation to perform. Operations are 'add', 'remove', and 'replace'.
3) id - the GUID used to reference the TCA. This is used internally and is only for refernence.
The functions will return the TCA on a succes as with the commands above.
For the mode='replace', there is an extra keyword 'ReplacedBy' that swaps the old TCA with the new one. The previous one is returned by the funtion

Examples

Add a new action an existing event

local a = ScenEdit_SetEventAction('test event', {mode='add', name='test action points'})
The varaiable a will contain the action information. It will be 'nil' if the function fails in a non-interactive script as in an event.

Repace an action an existing event

local a = ScenEdit_SetEventAction('test event', {mode='replace', name='test action message', replaceby='test action points'})

--------------------------------------------

Events can also be created and modified thru Lua.
ScenEdit_SetEvent( eventName, { table } )
The common keywords used in the Lua table are:
1) description - the name given to the Event. The keyword 'name' can also be used for this.
2) mode - type of operation to perform. Operations are 'add' and 'update'.
3) id - the GUID used to reference the Event. This is used internally and is only for refernence.
The normal Event keywords are accepted in the 'table'.

Examples

Add a new event

local a = ScenEdit_SetEvent('my new event', {mode='add'})
The varaiable a will contain the event information. It will be 'nil' if the function fails in a non-interactive script as in an event.
The ScenEdit_SetEvent(Trigger/Condition/Action) functions then can be run on the new Event to add the required TCAs.

In addtion, ScenEdit_GetEvent(EventDescriptionOrID, level) has been updated to return information on the Event.
Use level as:
0 - all details, 1 - triggers, 2 - conditions, 3 - actions, 4 - event detail

Special variables: _enumTable_ - List of enumerated variable names and values
_errfnc_ - Lua Function in which error occurred
_errmsg_ - Error message from Lua Function failure

CommandLua

Topics

Reference

Examples