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.

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	Additional Info

Other Events

Event ID	Required Context	Optional Context	Reactions	Additional Info