utils/event

Interfaces

ResetData

Data passed to the "on_startup" mod lifecycle event.

Properties

Property	Type	Description	Defined in
`init`	`boolean`	True if the game was newly initialized (`on_init`).	utils/event.ts:72
`handoff?`	`boolean`	True during configuration change handoff.	utils/event.ts:74
`veto_shutdown?`	`LocalisedString`[]	Array of localized strings with reasons vetoing shutdown.	utils/event.ts:76
`startup_warnings?`	`LocalisedString`[]	Startup warnings.	utils/event.ts:78

EntityCreatedEventPayload

Defined in: utils/event.ts:522

Properties

Property	Type	Defined in
`entity`	`LuaEntity`	utils/event.ts:523
`playerIndex?`	`PlayerIndex`	utils/event.ts:524
`tags?`	`Record`<`string`, `any`>	utils/event.ts:525
`robot?`	`LuaEntity`	utils/event.ts:526
`revived`	`boolean`	utils/event.ts:527
`event`	`any`	utils/event.ts:528

EntityDestroyedEventPayload

Defined in: utils/event.ts:533

Properties

Property	Type	Defined in
`entity?`	`LuaEntity`	utils/event.ts:534
`unitNumber?`	`UnitNumber`	utils/event.ts:535
`playerIndex?`	`PlayerIndex`	utils/event.ts:536
`robot?`	`LuaEntity`	utils/event.ts:537
`cause?`	`LuaEntity`	utils/event.ts:538
`event`	`any`	utils/event.ts:539

Type Aliases

EventName

type EventName = Color | number | string;

Defined in: utils/event.ts:31

Universal event identifier type (defines.events, EventId, string, or number for nth_tick/custom IDs).

EventKey

type EventKey = string | number;

Defined in: utils/event.ts:36

Valid key for indexing event tables (primitive string or number).

EventBindingId

type EventBindingId = number;

Defined in: utils/event.ts:41

Unique sequential ID assigned to persistent dynamic event bindings.

EventStorage

type EventStorage = Record<EventKey,
  | Record<EventBindingId,
  | [EventName, string, any, unknown]
  | undefined>
| undefined>;

Defined in: utils/event.ts:43

EventSubtickStorage

type EventSubtickStorage = Record<Color, [string, string, unknown] | undefined>;

Defined in: utils/event.ts:48

Structure of storage._event_subtick for persistent storage of subtick microtasks.

EventDynamicHandler

type EventDynamicHandler<TData, TArgs> = (this: void, event_name: EventName, handler_data: TData, ...args: TArgs) =>
  | typeof REMOVE_BINDING
  | void
  | unknown;

Defined in: utils/event.ts:60

Handler function signature for dynamic events registered via register_dynamic_handler. Returning REMOVE_BINDING automatically unbinds the dynamic listener.

Type Parameters

Type Parameter	Default type
`TData`	`unknown`
`TArgs` extends `unknown`[]	`unknown`[]

Parameters

Parameter	Type
`this`	`void`
`event_name`	`EventName`
`handler_data`	`TData`
…`args`	`TArgs`

Returns

| typeof REMOVE_BINDING | void | unknown

EventHandlerFor

type EventHandlerFor<E> = E extends "on_init" | "on_load" ? (this: void) => void : E extends "on_configuration_changed" ? (this: void, data: Color) => void : E extends "on_startup" ? (this: void, data: ResetData) => void : E extends Color<infer TData, any> ? (this: void, event: TData) => void : E extends number ? (this: void, event: Color) => void : E extends Color ? (this: void, event: Color<E>) => void : (this: void, ...args: any[]) => void;

Defined in: utils/event.ts:237

Conditional type resolver: determines the expected callback signature based on event E.

"on_init" | "on_load" ➔ () => void
"on_configuration_changed" ➔ (data: ConfigurationChangedData) => void
"on_startup" ➔ (data: ResetData) => void
EventId<TData> ➔ (event: TData) => void
number (nth_tick) ➔ (event: NthTickEventData) => void
LuaEventType ➔ (event: EventTypeOf<E>) => void
string (custom) ➔ (...args: any[]) => void

Type Parameters

Type Parameter
`E` extends `EventName`

EventFiltersFor

type EventFiltersFor<E> = E extends Color<any, infer TFilter> ? TFilter[] : unknown;

Defined in: utils/event.ts:254

Conditional type resolver: extracts valid filter array type for game event E.

Type Parameters

Type Parameter
`E` extends `EventName`

EntityNameFilter

type EntityNameFilter = string | readonly string[];

Defined in: utils/event.ts:520

EntityCreatedCallback

type EntityCreatedCallback = (this: void, payload: EntityCreatedEventPayload) => void;

Defined in: utils/event.ts:531

Parameters

Parameter	Type
`this`	`void`
`payload`	`EntityCreatedEventPayload`

Returns

void

EntityDestroyedCallback

type EntityDestroyedCallback = (this: void, payload: EntityDestroyedEventPayload) => void;

Defined in: utils/event.ts:542

Parameters

Parameter	Type
`this`	`void`
`payload`	`EntityDestroyedEventPayload`

Returns

void

Variables

REMOVE_BINDING

const REMOVE_BINDING: unique symbol;

Defined in: utils/event.ts:54

Special marker symbol. When returned by a dynamic handler, the library automatically removes this dynamic binding from storage._event.

Functions

bind()

function bind<E>(
   event_name: E,
   handler: EventHandlerFor<E>,
   first?: boolean,
   filters?: EventFiltersFor<E>): void;

Defined in: utils/event.ts:291

Universal static event subscription function (Event Bus).

Supports:

Factorio game events (defines.events.*).
Core script lifecycle events ("on_init", "on_load", "on_configuration_changed").
Periodic tick intervals (nth_tick(60)).
Custom mod string events ("my_custom_event").

Unlike native script.on_event, allows registering multiple independent handlers on the same event without overwriting previous listeners.

Type Parameters

Type Parameter
`E` extends `any`

Parameters

Parameter	Type	Description
`event_name`	`E`	Name or ID of the event.
`handler`	`EventHandlerFor`<`E`>	Callback function with automatically inferred argument types.
`first?`	`boolean`	If true, unshifts handler to the front of the queue.
`filters?`	`EventFiltersFor`<`E`>	Optional Factorio engine event filters.

Returns

void

Example

// Listen for GUI clicks with inferred `e: OnGuiClickEvent`
bind(defines.events.on_gui_click, (e) => {
  log(e.element.name);
});

// Listen for mod initialization
bind("on_init", () => {
  storage.my_data = {};
});

// Listen every 60 ticks (1 second)
bind(nth_tick(60), (tickData) => {
  game.print(`Tick: ${tickData.tick}`);
});

unbind_all()

function unbind_all(event_name: any): void;

Defined in: utils/event.ts:312

Removes all static handlers for the given event and unbinds it from the Factorio engine.

Parameters

Parameter	Type	Description
`event_name`	`any`	Name or ID of the event to unbind.

Returns

void

raise()

function raise(user_event_name: string, ...args: unknown[]): void;

Defined in: utils/event.ts:330

Raises a custom mod event, dispatching arguments to all static and dynamic listeners.

Parameters

Parameter	Type	Description
`user_event_name`	`string`	Custom event name.
…`args`	`unknown`[]	Arguments passed to handler functions.

Returns

void

nth_tick()

function nth_tick(n: number): number;

Defined in: utils/event.ts:364

Converts a positive tick interval n into a negative number -n used as an nth-tick event marker.

Parameters

Parameter	Type	Description
`n`	`number`	Positive integer tick interval (e.g. 60 for 1 second).

Returns

number

Negative number ID.

dynamic_bind()

function dynamic_bind<TData>(
   event_names: any,
   handler_name: string,
   handler_data?: TData): number;

Defined in: utils/event.ts:380

Creates a dynamic event binding persisted across savegames in storage._event.

Type Parameters

Type Parameter	Default type	Description
`TData`	`unknown`	Serializable state data type.

Parameters

Parameter	Type	Description
`event_names`	`any`	One or more event names to subscribe to.
`handler_name`	`string`	Name of the handler registered via `register_dynamic_handler`.
`handler_data?`	`TData`	Optional serializable state data passed to the callback.

Returns

number

Unique EventDynamicBindingId.

dynamic_unbind()

function dynamic_unbind(binding_id: number): boolean;

Defined in: utils/event.ts:409

Unbinds and removes a dynamic event binding from storage._event by its ID.

Parameters

Parameter	Type	Description
`binding_id`	`number`	Binding ID returned by `dynamic_bind`.

Returns

boolean

True if the binding existed and was removed.

register_dynamic_handler()

function register_dynamic_handler<TData, TArgs>(handler_name: string, handler: EventDynamicHandler<TData, TArgs>): void;

Defined in: utils/event.ts:436

Registers a dynamic handler function in volatile memory (RAM).

Functions cannot be saved in storage, so only the string identifier is stored in savegames, and the actual implementation is registered during mod loading.

Returning REMOVE_BINDING automatically removes the binding.

Type Parameters

Type Parameter	Default type	Description
`TData`	`unknown`	User state data type.
`TArgs` extends `unknown`[]	`unknown`[]	Additional event argument types.

Parameters

Parameter	Type	Description
`handler_name`	`string`	Unique string name.
`handler`	`EventDynamicHandler`<`TData`, `TArgs`>	Callback function.

Returns

void

dynamic_subtick_trigger()

function dynamic_subtick_trigger<TData>(
   handler_name: string,
   event_name: string,
   handler_data?: TData): void;

Defined in: utils/event.ts:460

Schedules a deferred subtick microtask to execute at the end of the current game tick.

Type Parameters

Type Parameter	Default type	Description
`TData`	`unknown`	Serializable state data type.

Parameters

Parameter	Type	Description
`handler_name`	`string`	Dynamic handler name.
`event_name`	`string`	Identifier for the task.
`handler_data?`	`TData`	Optional data passed to the callback.

Returns

void

onEntityCreated()

function onEntityCreated(filter: EntityNameFilter, callback: EntityCreatedCallback): void;

Defined in: utils/event.ts:561

Universal entity creation listener. Automatically handles player placement, robot construction, blueprint revival, Space Age orbital construction, and script-raised builds with entity name filtering.

Parameters

Parameter	Type	Description
`filter`	`EntityNameFilter`	Single entity prototype name, array of names, or undefined for all entities.
`callback`	`EntityCreatedCallback`	Unified callback receiving normalized payload (`entity`, `playerIndex`, `tags`, `robot`, `revived`).

Returns

void

onEntityDestroyed()

function onEntityDestroyed(filter: EntityNameFilter, callback: EntityDestroyedCallback): void;

Defined in: utils/event.ts:591

Universal entity destruction listener. Automatically handles player mining, robot deconstruction, entity death (biters/explosions), Space Age platform destruction, and script-raised destructions.

Parameters

Parameter	Type	Description
`filter`	`EntityNameFilter`	Single entity prototype name, array of names, or undefined for all entities.
`callback`	`EntityDestroyedCallback`	Unified callback receiving normalized payload (`entity`, `unitNumber`, `playerIndex`, `robot`, `cause`).

Returns

void