Factorio.com|Forums|Wiki|Mod Portal|API Docs

# Factorio Runtime Docs Version 2.0.77

# LuaBootstrap - Runtime Docs

## Class LuaBootstrap

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

## Members

on_init(handler) |  | Register a function to be run on mod initialization. [...]
Register a function to be run on mod initialization. [...]
on_load(handler) |  | Register a function to be run on save load. [...]
Register a function to be run on save load. [...]
on_configuration_changed(handler) |  | Register a function to be run when mod configuration changes. [...]
Register a function to be run when mod configuration changes. [...]
on_event(event, handler, filters?) |  | Register a handler to run on the specified event(s). [...]
Register a handler to run on the specified event(s). [...]
on_nth_tick(tick, handler) |  | Register a handler to run every nth-tick(s). [...]
Register a handler to run every nth-tick(s). [...]
register_on_object_destroyed(object) | → uint64, uint64, defines.target_type | Registers an object so that after it's destroyed, on_object_destroyed is called. [...]
Registers an object so that after it's destroyed, on_object_destroyed is called. [...]
register_metatable(name, metatable) |  | Register a metatable to have linkage recorded and restored when saving/loading. [...]
Register a metatable to have linkage recorded and restored when saving/loading. [...]
generate_event_name() | → defines.events | Generate a new, unique event ID that can be used to raise custom events with LuaBootstrap::raise_event.
Generate a new, unique event ID that can be used to raise custom events with LuaBootstrap::raise_event.
get_event_id(event) | → defines.events | Converts LuaEventType into related value of defines.events. [...]
Converts LuaEventType into related value of defines.events. [...]
get_event_handler(event) | → function(EventData)? | Find the event handler for an event.
Find the event handler for an event.
get_event_order() | → string | Gets the mod event order as a string.
Gets the mod event order as a string.
set_event_filter(event, filters?) |  | Sets the filters for the given event. [...]
Sets the filters for the given event. [...]
get_event_filter(event) | → EventFilter? | Gets the filters for the given event.
Gets the filters for the given event.
raise_event(event, data) |  | Raise an event. [...]
Raise an event. [...]
raise_console_chat{player_index=…, message=…} |  |
raise_player_crafted_item{item_stack=…, player_index=…, recipe=…} |  |
raise_player_fast_transferred{player_index=…, entity=…, from_player=…, is_split=…} |  |
raise_biter_base_built{entity=…} |  |
raise_market_item_purchased{player_index=…, market=…, offer_index=…, count=…} |  |
raise_script_built{entity=…} |  |
raise_script_destroy{entity=…} |  |
raise_script_revive{entity=…, tags?=…} |  |
raise_script_teleported{entity=…, old_surface_index=…, old_position=…} |  |
raise_script_set_tiles{surface_index=…, tiles=…} |  |
raise_script_destroy_segmented_unit{segmented_unit=…} |  |
mod_name | :: R string | The name of the mod from the environment this is used in.
The name of the mod from the environment this is used in.
level | :: R table | Information about the currently running scenario/campaign/tutorial.
Information about the currently running scenario/campaign/tutorial.
active_mods | :: R dictionary[string → string] | A dictionary listing the names of all currently active mods and mapping them to their version.
A dictionary listing the names of all currently active mods and mapping them to their version.
feature_flags | :: R table | A dictionary of feature flags mapping to whether they are enabled.
A dictionary of feature flags mapping to whether they are enabled.
object_name | :: R string | The class name of this object. [...]
The class name of this object. [...]

## Methods

### on_init(handler)

Register a function 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 storage 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.

For more context, refer to the Data Lifecycle page.

#### Parameters

handler | :: function() or nil | The handler for this event. Passing `nil` will unregister it.
The handler for this event. Passing `nil` will unregister it.

#### Example

    -- Initialize a `players` table in `storage` for later use
    script.on_init(function()
      storage.players = {}
    end)

### on_load(handler)

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 rectify potential differences in local state introduced by the save/load cycle. Doing anything other than the following three will lead to desyncs, breaking multiplayer and replay functionality. Access to LuaGameScript is not available. The storage table can be accessed and is safe to read from, but not write to, as doing so will lead to an error.

The only legitimate uses of this event are these:

- Re-setup metatables as they are not persisted through the save/load cycle.

- Re-setup conditional event handlers, meaning subscribing to an event only when some condition is met to save processing time.

- Create local references to data stored in the storage table.

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

For more context, refer to the Data Lifecycle page.

#### Parameters

handler | :: function() or nil | The handler for this event. Passing `nil` will unregister it.
The handler for this event. Passing `nil` will unregister it.

### on_configuration_changed(handler)

Register a function to be run when mod configuration changes.

This is called when the game version or any mod version changed, when any mod was added or removed, when a startup setting has changed, when any prototypes have been added or removed, or when a migration was applied. It allows the mod to make any changes it deems appropriate to both the data structures in its storage table or to the game state through LuaGameScript.

For more context, refer to the Data Lifecycle page.

#### Parameters

handler | :: function(ConfigurationChangedData) or nil | The handler for this event. Passing `nil` will unregister it.
The handler for this event. Passing `nil` will unregister it.

### on_event(event, handler, 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 | :: LuaEventType or array[LuaEventType] | The event(s) or custom-input to invoke the handler on.
The event(s) or custom-input to invoke the handler on.
handler | :: function(EventData) or nil | The handler for this event. Passing `nil` will unregister it.
The handler for this event. Passing `nil` will unregister it.
filters | :: EventFilter? | The filters for this event. Can only be used when registering for individual events.
The filters for this event. Can only be used when registering for individual events.

#### Examples

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

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

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

#### Parameters

tick | :: MapTick or array[MapTick] or nil | The nth-tick(s) to invoke the handler on. Passing `nil` as the only parameter will unregister all nth-tick handlers.
The nth-tick(s) to invoke the handler on. Passing `nil` as the only parameter will unregister all nth-tick handlers.
handler | :: function(NthTickEventData) or nil | The handler to run. Passing `nil` will unregister it for the provided nth-tick(s).
The handler to run. Passing `nil` will unregister it for the provided nth-tick(s).

### register_on_object_destroyed(object) → uint64, uint64, defines.target_type

Registers an object so that after it's destroyed, on_object_destroyed is called.

Once an object 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 object, all mods listening to on_object_destroyed will receive the event when it is destroyed. Registering the same object multiple times will still only fire the destruction event once, and will return the same registration number.

Depending on when a given object is destroyed, on_object_destroyed will either be fired at the end of the current tick or at the end of the next tick.

#### Parameters

object | :: RegistrationTarget | The object to register.
The object to register.

#### Return values

→ uint64 | The registration number. It is used to identify the object in the on_object_destroyed event.
→ uint64 | The useful identifier of the object if it has one or `0` if it doesn't. This identifier is specific to the object type, for example for trains it is the value LuaTrain::id.
→ defines.target_type | Type of the target object.

### register_metatable(name, metatable)

Register a metatable to have linkage recorded and restored when saving/loading.

The metatable itself will not be saved. Instead, only the linkage to a registered metatable is saved, and the metatable registered under that name will be used when loading the table.

`register_metatable()` can not be used in the console, in event listeners or during a `remote.call()`.

The metatable first needs to be defined in the mod's root scope, then registered using this method. From then on, it will be properly restored for tables in storage.

    local metatable =
    {
      __index = function(key)
        return "no value for key " .. key
      end
    }
    script.register_metatable("my_metatable", metatable)

This previously defined `metatable` can then be set on any table as usual:

    local table = {key="value"}
    setmetatable(table, metatable)

#### Parameters

name | :: string | The name of this metatable. Names must be unique per mod.
The name of this metatable. Names must be unique per mod.
metatable | :: table | The metatable to register.
The metatable to register.

### generate_event_name() → defines.events

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

#### Return values

→ defines.events | The newly generated event ID. This will be a new value that does not correspond to any named entry in defines.events.

### get_event_id(event) → defines.events

Converts LuaEventType into related value of defines.events. Value will be provided also if event was not given a constant inside of defines.events.

#### Parameters

event | :: LuaEventType |

### get_event_handler(event) → function(EventData)?

Find the event handler for an event.

#### Parameters

event | :: LuaEventType | The event identifier to get a handler for.
The event identifier to get a handler for.

#### Return values

→ function(EventData)? | Reference to the function currently registered as the handler, if it was found.

### 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.

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}})

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"}})

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"}})

#### Parameters

event | :: LuaEventType | ID of the event to filter.
ID of the event to filter.
filters | :: EventFilter? | The filters or `nil` to clear them.
The filters or `nil` to clear them.

### get_event_filter(event) → EventFilter?

Gets the filters for the given event.

#### Parameters

event | :: LuaEventType | ID of the event to get.
ID of the event to get.

#### Return values

→ EventFilter? | 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:

Events that can be raised manually: 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_teleported script_raised_set_tiles

#### Parameters

event | :: LuaEventType | ID or name of the event to raise.
ID or name of the event to raise.
data | :: table | Table with extra data that will be passed to the event handler. Any invalid LuaObjects will silently stop the event from being raised.
Table with extra data that will be passed to the event handler. Any invalid LuaObjects will silently stop the event from being raised.

#### 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=…}

#### Parameters

Table with the following fields:

player_index | :: uint32 | The player doing the chatting.
The player doing the chatting.
message | :: string | The chat message to send.
The chat message to send.

#### Raised events

on_console_chat instantly | Raised with the provided arguments.

### raise_player_crafted_item{item_stack=…, player_index=…, recipe=…}

#### Parameters

Table with the following fields:

item_stack | :: LuaItemStack | The item that has been crafted.
The item that has been crafted.
player_index | :: uint32 | The player doing the crafting.
The player doing the crafting.
recipe | :: RecipeID | The recipe used to craft this item.
The recipe used to craft this item.

#### Raised events

on_player_crafted_item instantly | Raised with the provided arguments.

### raise_player_fast_transferred{player_index=…, entity=…, from_player=…, is_split=…}

#### Parameters

Table with the following fields:

player_index | :: uint32 | The player transferred from or to.
The player transferred from or to.
entity | :: LuaEntity | The entity transferred from or to.
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.
Whether the transfer was from player to entity. If `false`, the transfer was from entity to player.
is_split | :: boolean | Whether the transfer was a split action (half stack).
Whether the transfer was a split action (half stack).

#### Raised events

on_player_fast_transferred instantly | Raised with the provided arguments.

### raise_biter_base_built{entity=…}

#### Parameters

Table with the following fields:

entity | :: LuaEntity | The entity that was built.
The entity that was built.

#### Raised events

on_biter_base_built instantly | Raised with the provided arguments.

### raise_market_item_purchased{player_index=…, market=…, offer_index=…, count=…}

#### Parameters

Table with the following fields:

player_index | :: uint32 | The player who did the purchasing.
The player who did the purchasing.
market | :: LuaEntity | The market entity.
The market entity.
offer_index | :: uint32 | The index of the offer purchased.
The index of the offer purchased.
count | :: uint32 | The amount of offers purchased.
The amount of offers purchased.

#### Raised events

on_market_item_purchased instantly | Raised with the provided arguments.

### raise_script_built{entity=…}

#### Parameters

Table with the following fields:

entity | :: LuaEntity | The entity that has been built.
The entity that has been built.

#### Raised events

script_raised_built instantly | Raised with the provided arguments.

### raise_script_destroy{entity=…}

#### Parameters

Table with the following fields:

entity | :: LuaEntity | The entity that was destroyed.
The entity that was destroyed.

#### Raised events

script_raised_destroy instantly | Raised with the provided arguments.

### raise_script_revive{entity=…, tags?=…}

#### Parameters

Table with the following fields:

entity | :: LuaEntity | The entity that was revived.
The entity that was revived.
tags | :: Tags? | The tags associated with this entity, if any.
The tags associated with this entity, if any.

#### Raised events

script_raised_revive instantly | Raised with the provided arguments.

### raise_script_teleported{entity=…, old_surface_index=…, old_position=…}

#### Parameters

Table with the following fields:

entity | :: LuaEntity | The entity that was teleported.
The entity that was teleported.
old_surface_index | :: uint8 | The entity's surface before the teleportation.
The entity's surface before the teleportation.
old_position | :: MapPosition | The entity's position before the teleportation.
The entity's position before the teleportation.

#### Raised events

script_raised_teleported instantly | Raised with the provided arguments.

### raise_script_set_tiles{surface_index=…, tiles=…}

#### Parameters

Table with the following fields:

surface_index | :: uint32 | The surface whose tiles have been changed.
The surface whose tiles have been changed.
tiles | :: array[Tile] | The tiles that have been changed.
The tiles that have been changed.

#### Raised events

script_raised_set_tiles instantly | Raised with the provided arguments.

### raise_script_destroy_segmented_unit{segmented_unit=…}

#### Parameters

Table with the following fields:

segmented_unit | :: LuaSegmentedUnit | The segmented unit that was destroyed.
The segmented unit that was destroyed.

#### Raised events

script_raised_destroy_segmented_unit instantly | Raised with the provided arguments.

## Attributes

### mod_name :: Read string

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

### level :: Read table

Information about the currently running scenario/campaign/tutorial.

#### Table fields

is_simulation | :: boolean? | Is this level a simulation? (The main menu and 'Tips and tricks' use simulations)
Is this level a simulation? (The main menu and 'Tips and tricks' use simulations)
is_tutorial | :: boolean? | Is this level a tutorial?
Is this level a tutorial?
campaign_name | :: string? | The campaign name if any.
The campaign name if any.
level_name | :: string | The level name.
The level name.
mod_name | :: string? | The mod name if any.
The mod name if any.

### active_mods :: Read dictionary[string → string]

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

### feature_flags :: Read table

A dictionary of feature flags mapping to whether they are enabled.

#### Table fields

quality | :: boolean |
rail_bridges | :: boolean |
space_travel | :: boolean |
spoiling | :: boolean |
freezing | :: boolean |
segmented_units | :: boolean |
expansion_shaders | :: boolean |

### object_name :: Read string

The class name of this object. Available even when `valid` is false. For LuaStruct objects it may also be suffixed with a dotted path to a member of the struct.