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 typeKeywordComment
PointsSideIDSide to adjust points for
PointValueCurrent points
ReachDirectionGoOver = 0, MatchExactly = 1, GoUnder = 2
RandomTimeEarliestTimeEarliest date/time to start checks
LatestTimeLatest date/time to stop checks
RegularTimeIntervalTime interval (1 sec, 2sec, 5sec, etc)
ScenEndedNo additional keywords
ScenLoadedNo additional keywords
TimeTimeActual date/time to fire on
UnitDamagedDamagePercent
TargetFilterSee below
UnitDestroyedTargetFilterSee below
UnitDetectedTargetFilterSee below
DetectorSideIDSide doing the detecting
MCLMinimum classifcation level
AreaTable of reference points
UnitEntersAreaTargetFilterSee below
AreaTable of reference points
ETOAEarliest date/time of arrival
LTOALatest date/time of arrival
NOTNot in the area
ExitAreaLeaving area
UnitRemainsInAreaTargetFilterSee below
AreaTable of reference points
TDTime to remain in area in seconds (or as days:hours:minutes:seconds)
UnitBaseStatusTargetFilterSee below
TargetStatusStatus number to monitor

TargetFilter:
A series of filters to apply to units. Only units matching this filter will fire the trigger.
TargetFilterTargetSideSide to fillter on
TargetTypeType of unit (ship, submarine, etc)
TargetSubTypeSubtype of the above unit type
SpecificUnitClassUnit class (DBID)
SpecificUnitActual 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.

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 typeKeywordComment
LuaScriptScriptTextA Lua script
ScenHasStartedNOTA NOT modifier for scenario NOT started yet
SidePostureObserverSideIDSide that views TargetSide as ...
TargetSideID
TargetPosture
NOTA 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 typeKeywordComment
ChangeMissionStatusMissionIDMission identifier
NewStatusNew status - active(0) or inactive (1)
EndScenarioNo additional keywords
LuaScriptScriptTextA Lua script
MessageSideIDSide to see message
TextMessage text to show
PointsPointChangeValue to change points by (+/-)
SideIDSide affected
TeleportInAreaUnitIDsTable of unit GUIDs
AreaTable 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

generated by LDoc 1.4.3 Last updated 2017-10-10 21:20:35