LuaBootstrap

Entry point for registering event handlers. It is accessible through the global object named script.

class LuaBootstrap - sort
on_init(f) Register a callback to be run on mod init.
on_load(f) Register a function to be run on module load.
on_configuration_changed(f) Register a function to be run when mod configuration changes.
on_event(event, f, filters) Register a handler to run on event or events.
on_nth_tick(tick, f) Register a handler to run every nth tick(s).
register_on_entity_destroyed(entity) → uint64 Registers an entity so that after it's destroyed on_entity_destroyed is called.
generate_event_name() → uint Generate a new, unique event ID.
get_event_handler(event) Find the event handler for an event.
get_event_order() Gets the mod event order.
set_event_filter(event, filters) Sets the filters for the given event.
get_event_filter(event) → table Gets the filters for the given event.
raise_event(event, table) Raise an event.
raise_console_chat(table) Raises on_console_chat
raise_player_crafted_item(table) Raises on_player_crafted_item
raise_player_fast_transferred(table) Raises on_player_fast_transferred
raise_biter_base_built(table) Raises on_biter_base_built
raise_market_item_purchased(table) Raises on_market_item_purchased
raise_script_built(table) Raises script_raised_built
raise_script_destroy(table) Raises script_raised_destroy
raise_script_revive(table) Raises script_raised_revive
raise_script_set_tiles(table) Raises script_raised_set_tiles
mod_name :: string [R] The name of the mod from the environment this is used in.
level :: table [R] Information about the currently running scenario/campaign/tutorial
active_mods :: dictionary stringstring [R] A dictionary listing the names of all currently active mods and mapping them to their version.
object_name :: string [R] This object's name.
on_init(f)

Register a callback to be run on mod init. This is called once when a new save game is created or once when a save file is loaded that previously didn't contain the mod. This is always called before other event handlers and is meant for setting up initial values that a mod will use for its lifetime.

Parameters
f :: function(): The function to call. Passing nil will unregister the handler.
on_load(f)

Register a function to be run on module load. This is called every time a save file is loaded *except* for the instance when a mod is loaded into a save file that it previously wasn't part of. Additionally this is called when connecting to any other game in a multiplayer session and should never change the game state.

This is meant for 3 specific reasons and only 3:

  • re-register conditional event handlers
  • re-setup meta tables
  • create local references to tables stored in the global table

In all other instances the LuaBootstrap::on_init, LuaBootstrap::on_configuration_changed or migration scripts should be used. Doing any other logic when loading a save file can break the replay and cause desync issues if the mod is used in multiplayer.

Parameters
f :: function(): The function to call. Passing nil will unregister the handler.
Note: LuaGameScript and LuaRendering are unavailable in this event.
on_configuration_changed(f)

Register a function to be run when mod configuration changes. This is called any time the game version changes, prototypes change, startup mod settings change, and any time mod versions change including adding or removing mods.

Parameters
f :: function(ConfigurationChangedData): The handler for this event. Passing nil will unregister the handler.
on_event(event, f, filters)

Register a handler to run on event or events.

Parameters
event :: defines.events or array of defines.events or string: The events or custom-input name to invoke the handler on
f :: function(Event): The handler to run. Passing nil will unregister the handler. The handler will receive a table that contains the key name (of type defines.events) specifying the name of the event it was called to handle, and tick that specifies when the event was created. This table will also contain other fields, depending on the type of the event. See the list of Factorio events for a listing of these additional fields.
filters :: Filters (optional): The filters for this single event registration. See the list of event filters for a listing of these filters.
Note: Events raised by LuaBootstrap::raise_event contain mod_name additionally to the above properties.
on_nth_tick(tick, f)

Register a handler to run every nth tick(s). When the game is on tick 0 it will trigger all registered handlers.

Parameters
tick :: uint or array of uint: The nth-tick(s) to invoke the handler on. Passing nil as the only parameter will unregister all nth-tick handlers.
f :: function(NthTickEvent): The handler to run. Passing nil will unregister the handler for the provided ticks.
register_on_entity_destroyed(entity) → uint64

Registers an entity so that after it's destroyed on_entity_destroyed is called.

Parameters
entity :: LuaEntity: The entity to register.
Return value
The registration number.
Note: Once an entity is registered it's registered forever (until it's destroyed) and persists through save/load.
Note: Registered is global across all mods: once an entity is registered the event will be fired for all mods when its destroyed.
Note: An entity registered multiple times will only fire the event once and gives back the same registration number.
Note: Depending on when a given entity is destroyed on_entity_destroyed will be fired at the end of the current tick or end of the next tick.
generate_event_name() → uint

Generate a new, unique event ID.

Return value
The new ID
get_event_handler(event)

Find the event handler for an event.

Parameters
event :: uint: The event identifier to get a handler for
Return value
Reference to the function currently registered as the handler.
get_event_order()

Gets the mod event order. type(string)

set_event_filter(event, filters)

Sets the filters for the given event.

Parameters
event :: uint: ID of the event to filter.
filters :: Filters (optional): The filters or nil to clear the filters
get_event_filter(event) → table

Gets the filters for the given event.

Parameters
event :: uint: ID of the event to get.
Return value
The filters or nil if none are defined.
raise_event(event, table)

Raise an event. Only events generated with LuaBootstrap::generate_event_name and the following can be raised: on_console_chat on_player_crafted_item on_player_fast_transferred on_biter_base_built on_market_item_purchased script_raised_built script_raised_destroy script_raised_revive script_raised_set_tiles

Parameters
event :: uint: ID of the event to raise
table: Table with extra data. This table will be passed to the event handler.
raise_console_chat(table)

Raises on_console_chat

Parameters
raise_player_crafted_item(table)

Raises on_player_crafted_item

Parameters
raise_player_fast_transferred(table)
raise_biter_base_built(table)

Raises on_biter_base_built

Parameters
raise_market_item_purchased(table)
raise_script_built(table)

Raises script_raised_built

Parameters
raise_script_destroy(table)

Raises script_raised_destroy

Parameters
raise_script_revive(table)

Raises script_raised_revive

Parameters
raise_script_set_tiles(table)
mod_name :: string [Read-only]

The name of the mod from the environment this is used in.

level :: table [Read-only]

Information about the currently running scenario/campaign/tutorial

Table with the following fields:
  • is_simulation :: boolean (optional): Is this level a simulation? (menu, tips&tricks)
  • is_tutorial :: boolean (optional): Is this level a tutorial?
  • campaign_name :: string (optional): The campaign name if any.
  • level_name :: string: The level name.
  • mod_name :: string (optional): The mod name if any.

active_mods :: dictionary stringstring [Read-only]

A dictionary listing the names of all currently active mods and mapping them to their version.

Example
This will print the names and versions of all active mods to the console.
for name, version in pairs(script.active_mods) do
  game.print(name .. " version " .. version)
end
object_name :: string [Read-only]

This object's name.