Events and Context

The Events System

Lancer is a system famous for its numerous reactions and counter-reactions. In Lancer Tactics, this is handled by generating EventCore objects and then queueing them to each other in one big stack. EventCores each have an EventBase resource in their base variable, which defines the type of event it is. The EventCore object is typically called activation, event or core.

The execution sequence for running a particular event is:

• Run the execute_preblock() function for the event's EventBase:

• For events which can be reacted to, fetch the events for every reaction with timing ReactionBus.TIMING.PRE.

• The reaction events are ordered according to their priority (low to high).

• Loop through the reaction events and run the whole execution sequence for each reaction event in turn.

• If the event is aborted (event.aborted == true), or the Context object does not contain the required data, execution stops here.
• Run the execute() function for the event's EventBase:

• Executes any functionality the event has (for example, clearing heat for an event_unit_cool).

• For events which can be reacted to, fetch the events for every reaction with timing ReactionBus.TIMING.POST.

• The reaction events are ordered according to their priority (low to high). • Loop through the reaction events and run the whole execution sequence for each reaction event in turn.

• Run child events:

• These are events queued to the EventCore with event.queue_event().

• The child events are ordered according to their priority (low to high).

• Loop through the child events and run the whole execution sequence for child event in turn.

TODO - provide an example

Olive's devlog on the subject (which you should check out just for the meme).

Context

Data is passed between events within a Context object, which contains any parameters an event needs in order to execute. The Context is checked by an event immediately before calling its execute() function to see if it is able to run. Reactions with ReactionBus.TIMING. PRE can modify the Context of the event they are reacting to before the event itself occurs, which allows them to change the event's behavior.

Whether the Context object contains a specific variable can be queried using the context.is_property_present() function.

The Context objects contains the following variables:

Variable	Type	Additional Info
action	Action	See Actions and Reactions.
array	Array
boolean	bool
buff	BuffCore
category	Variant	Represents an enum or id string.
category_int	int	The category variable, typed as an int. Setting this will modify the category variable.
category_string	StringName	The category variable, typed as a StringName. Setting this will modify the category variable.
event	EventCore	Usually the parent event of the current event.
flags	Array	Usually contains enums.
gear	GearCore
map	MapState	Always populated.
number	int
object	Variant
resource	Resource
string	String
target_tiles	Array[Vector2i]
target_tile	Vector2i	target_tiles[0], or Tile.INVALID if it is empty. Setting this will add the Vector2i to target_tiles at index 0.
target_units	Array[Unit]
target_unit	Unit	target_units[0], or null if it is empty. Setting this will add the Unit to target_units at index 0.
unit	Unit

Event Creation

A Context object is usually created from a dictionary, where each key corresponds to the name of a variable:

var context = Context.create({
	string = "Example Context",
	boolean = true
})

Events are almost always created using the functions on their parent event, although it is possible to create one directly to make a virtual event not queued to any other event.

An event can be queued to the activation event with:

activation.queue_event(&"event_example_id", {
	string = "Example Event",
	boolean = true
}, Priority.ACTIVATE.late_followup)

Events can also be executed immediately:

await activation.execute_event(&"event_example_id", {
	string = "Example Event",
	boolean = true
})

As with any other await function, check your references are not null before proceeding.

Event Types

The scripts defining the game's events can be found in the res://content/events/ folder.

TODO - fill these out

Events with Reactions

Event ID	Required Context	Optional Context	Reactions
event_combat_end	boolean - victory?		combat_end
event_combat_set_state	string object		modified_combat_state
event_combat_start			combat_start
event_combat_trigger_signal	string	number boolean unit object array - if given, emits the signal more than once for each item in the array	trigger_signal
event_gear_activate	unit gear action	target_tiles - targeting hint target_units - targeting hint event - parent event during reactions flags - Action.FLAG object - Pathfinder if can move before taking action string - id of variant Action to be used	unit_action - generates a fake Context matching that of event_unit_action. Context cannot be modified by PRE events stabilize
event_gear_destroy	unit gear		gear_destruction
event_gear_reload	unit (gear and/or array - Array[GearCore])		reload
event_map_damage	target_tiles number	flags - EventMapDamage.FLAG object - elevation to destroy down to (int) boolean - set to true if terrain got destroyed	terrain_damage
event_unit_attack	target_unit - attacked unit unit - attacking unit gear action resource - DeclaredAttackSummary event - event_unit_attack_declared	flags - Action.FLAG	attack
event_unit_attack_declared	unit gear action resource - DeclaredAttackSummary		attack_declared
event_unit_brace	unit		brace
event_unit_damage	unit number	category - Lancer.DAMAGE_TYPE - default kinetic object - AttackRoll flags - EventService.DAMAGE_FLAG target_unit - attacker gear - attacker gear action - attacker Action	damage
event_unit_move	unit (target_tiles - path or single tile to path to. in PRE reactions to step, holds the tile the unit is about to step into or array - Array[Pathfinder.Step] - final path)	resource - MovementType flags - EventUnitMove.FLAG object - SpecificAction which caused the move	step entire_movement

Other Events

Event ID	Required Context	Optional Context
event_buff_activate	buff unit - the unit the buff is applied to. event - the event which triggered the activation.
event_camera_move	target_tiles - moves so it can see all these	number - move speed in milliseconds, 0 by default flags
event_camera_set_locked	boolean	flags
event_combat_banner_intro
event_combat_highlight_ui	boolean string - compcon_id(?)	flags - GoldenPathHighlight.AUTO_CLEAR
event_combat_set_objective	number - index of objective to change boolean - is complete?	string - objective text array - [2,4] => "Search all zones! (2/4)" flags
event_combat_set_round_max	number
event_combat_set_triggers_enabled	string - name of trigger group boolean
event_delay	number - milliseconds
event_dialogue	string - conversation id	unit - for dynamic text target_units - for dynamic text
event_dialogue_bark	unit string - line id or raw text	target_units - for dynamic text flags
event_dialogue_emoji	unit category - Emoji.TYPE	number - length to show in milliseconds
event_dialogue_face	unit target_tiles - tiles to look at
event_gear_choose_and_use	unit gear action array - Array[SpecificAction] - actions to pick from	boolean - is overwatch? string - variant action id if mandatory flags - Action.FLAG (if Action.FLAG.TARGETS_ARE_MANDATORY: target_units - mandatory targets target_tiles - mandatory targets)
event_map_block_add	target_tiles category - block id (int) number - elevation	flags - EventMapBlockAdd.FLAG
event_map_block_remove	target_tiles number - elevation	flags - EventMapBlockAdd.FLAG
event_map_dangerous	unit category - Lancer.DAMAGE_TYPE - type of damage to do on failure	resource - MovementType
event_map_doodad_add	target_tiles category - doodad id	number - rotation (0-3) flags