Factorio » Classes » LuaBootstrapFactorio 1.1.39

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 initialization.
on_load(f) Register a function to be run on save 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 the specified event(s).
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 that can be used to raise custom events with LuaBootstrap::raise_event.
get_event_handler(event) → function(EventData) Find the event handler for an event.
get_event_order() → string Gets the mod event order as a string.
set_event_filter(event, filters) Sets the filters for the given event.
get_event_filter(event) → array[EventFilter] Gets the filters for the given event.
raise_event(event, data) Raise an event.
raise_console_chat{player_index = …, message = …} Raises on_console_chat with the given parameters.
raise_player_crafted_item{item_stack = …, player_index = …, recipe = …} Raises on_player_crafted_item with the given parameters.
raise_player_fast_transferred{player_index = …, entity = …, from_player = …} Raises on_player_fast_transferred with the given parameters.
raise_biter_base_built{entity = …} Raises on_biter_base_built with the given parameters.
raise_market_item_purchased{player_index = …, market = …, offer_index = …, count = …} Raises on_market_item_purchased with the given parameters.
raise_script_built{entity = …} Raises script_raised_built with the given parameters.
raise_script_destroy{entity = …} Raises script_raised_destroy with the given parameters.
raise_script_revive{entity = …, tags = …} Raises script_raised_revive with the given parameters.
raise_script_set_tiles{surface_index = …, tiles = …} Raises script_raised_set_tiles with the given parameters.
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[string → string] [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 initialization. This is only called when a new save game is created or when a save file is loaded that previously didn't contain the mod. During it, the mod gets the chance to set up initial values that it will use for its lifetime. It has full access to LuaGameScript and the global table and can change anything about them that it deems appropriate. No other events will be raised for the mod until it has finished this step.

Parameters
f :: function(): The handler for this event. Passing nil will unregister it.
Example
Initialize a players table in global for later use.
script.on_init(function()
  global.players = {}
end)
on_load(f)

Register a function to be run on save load. This is only called for mods that have been part of the save previously, or for players connecting to a running multiplayer session. It gives the mod the opportunity to do some very specific actions, should it need to. Doing anything other than these three will lead to desyncs, which breaks multiplayer and replay functionality. Access to LuaGameScript and LuaRendering is not available. The global table can be accessed and is safe to read from, but not write to.

The only legitimate uses of this event are these three:
  • Re-setup metatables as they are not persisted through save-load.
  • Re-setup conditional event handlers.
  • Create local references to data stored in the global table.

For all other purposes, LuaBootstrap::on_init, LuaBootstrap::on_configuration_changed or migration scripts should be used instead.

Parameters
f :: function(): The handler for this event. Passing nil will unregister it.
on_configuration_changed(f)

Register a function to be run when mod configuration changes. This is called when the game version or any mod version changes; when any mod is added or removed; or when prototypes or startup mod settings have changed. It allows the mod to make any changes it deems appropriate to both the data structures in its global table or to the game state through LuaGameScript.

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

Register a handler to run on the specified event(s). Each mod can only register once for every event, as any additional registration will overwrite the previous one. This holds true even if different filters are used for subsequent registrations.

Parameters
event :: defines.events or array[defines.events] or string: The event(s) or custom-input to invoke the handler on.
f :: function(EventData): The handler for this event. Passing nil will unregister it.
filters :: array[EventFilter] (optional): The filters for this event. Can only be used when registering for individual events.
Example
Register for the on_tick event to print the current tick to console each tick.
script.on_event(defines.events.on_tick,
function(event) game.print(event.tick) end)
Example
Register for the on_built_entity event, limiting it to only be received when a "fast-inserter" is built.
script.on_event(defines.events.on_built_entity,
function(event) game.print("Gotta go fast!") end,
{{filter = "name", name = "fast-inserter"}})
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[uint]: The nth-tick(s) to invoke the handler on. Passing nil as the only parameter will unregister all nth-tick handlers.
f :: function(NthTickEventData): The handler to run. Passing nil will unregister it for the provided nth-tick(s).
register_on_entity_destroyed(entity) → uint64

Registers an entity so that after it's destroyed, on_entity_destroyed is called. Once an entity is registered, it stays registered until it is actually destroyed, even through save/load cycles. The registration is global across all mods, meaning once one mod registers an entity, all mods listening to on_entity_destroyed will receive the event when it is destroyed. Registering the same entity multiple times will still only fire the destruction event once, and will return the same registration number.

Parameters
entity :: LuaEntity: The entity to register.
Return value
The registration number. It is used to identify the entity in the on_entity_destroyed event.
Note: Depending on when a given entity is destroyed, on_entity_destroyed will either be fired at the end of the current tick or at the end of the next tick.
generate_event_name() → uint

Generate a new, unique event ID that can be used to raise custom events with LuaBootstrap::raise_event.

Return value
The newly generated event ID.
get_event_handler(event) → function(EventData)

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() → string

Gets the mod event order as a string.

set_event_filter(event, filters)

Sets the filters for the given event. The filters are only retained when set after the actual event registration, because registering for an event with different or no filters will overwrite previously set ones.

Parameters
event :: uint: ID of the event to filter.
filters :: array[EventFilter] (optional): The filters or nil to clear them.
Example
Limit the on_marked_for_deconstruction event to only be received when a non-ghost entity is marked for deconstruction.
script.set_event_filter(defines.events.on_marked_for_deconstruction, {{filter = "ghost", invert = true}})
Example
Limit the on_built_entity event to only be received when either a unit or a unit-spawner is built.
script.set_event_filter(defines.events.on_built_entity, {{filter = "type", type = "unit"}, {filter = "type", type = "unit-spawner"}})
Example
Limit the on_entity_damaged event to only be received when a rail is damaged by an acid attack.
script.set_event_filter(defines.events.on_entity_damaged, {{filter = "rail"}, {filter = "damage-type", type = "acid", mode = "and"}})
get_event_filter(event) → array[EventFilter]

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, data)

Raise an event. Only events generated with LuaBootstrap::generate_event_name and the following can be raised:

Parameters
event :: uint: ID of the event to raise.
data :: table: Table with extra data that will be passed to the event handler.
Example
Raise the on_console_chat event with the desired message 'from' the first player.
local data = {player_index = 1, message = "Hello friends!"}
script.raise_event(defines.events.on_console_chat, data)
raise_console_chat{player_index = …, message = …}

Raises on_console_chat with the given parameters.

Parameters
Table with the following fields:
  • player_index :: uint: The player doing the chatting.
  • message :: string: The chat message to send.
raise_player_crafted_item{item_stack = …, player_index = …, recipe = …}

Raises on_player_crafted_item with the given parameters.

Parameters
Table with the following fields:
  • item_stack :: LuaItemStack: The item that has been crafted.
  • player_index :: uint: The player doing the crafting.
  • recipe :: LuaRecipe: The recipe used to craft this item.
raise_player_fast_transferred{player_index = …, entity = …, from_player = …}

Raises on_player_fast_transferred with the given parameters.

Parameters
Table with the following fields:
  • player_index :: uint: The player transferred from or to.
  • entity :: LuaEntity: The entity transferred from or to.
  • from_player :: boolean: Whether the transfer was from player to entity. If false, the transfer was from entity to player.
raise_biter_base_built{entity = …}

Raises on_biter_base_built with the given parameters.

Parameters
Table with the following fields:
  • entity :: LuaEntity: The entity that was built.
raise_market_item_purchased{player_index = …, market = …, offer_index = …, count = …}

Raises on_market_item_purchased with the given parameters.

Parameters
Table with the following fields:
  • player_index :: uint: The player who did the purchasing.
  • market :: LuaEntity: The market entity.
  • offer_index :: uint: The index of the offer purchased.
  • count :: uint: The amount of offers purchased.
raise_script_built{entity = …}

Raises script_raised_built with the given parameters.

Parameters
Table with the following fields:
  • entity :: LuaEntity: The entity that has been built.
raise_script_destroy{entity = …}

Raises script_raised_destroy with the given parameters.

Parameters
Table with the following fields:
  • entity :: LuaEntity: The entity that was destroyed.
raise_script_revive{entity = …, tags = …}

Raises script_raised_revive with the given parameters.

Parameters
Table with the following fields:
  • entity :: LuaEntity: The entity that was revived.
  • tags :: Tags (optional): The tags associated with this entity, if any.
raise_script_set_tiles{surface_index = …, tiles = …}

Raises script_raised_set_tiles with the given parameters.

Parameters
Table with the following fields:
  • surface_index :: uint: The surface whose tiles have been changed.
  • tiles :: array[Tile]: The tiles that have been changed.
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? (The main menu and 'Tips and tricks' use simulations)
  • 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[string → string] [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.