Events are delivered to mods in response to certain actions happening in the game. A mod can register a callback for a given event using the LuaBootstrap::on_event function. Events receive a parameter that is a table containing fields name
and tick
specifying the event ID (see defines.events) and the tick the event happened. This table may also contain additional fields that depend on what event it is. Additionally, some events can use filters to provide improved performance when a mod doesn't need or want to react to everything a given event may be triggered by.
CustomInputEvent
Called when a CustomInput is activated.
The player that activated the custom input.
The prototype name of the custom input that was activated.
The mouse cursor position when the custom input was activated.
Information about the prototype that is selected when the custom input is used. nil
if none is selected.
Identifier of the event
Tick the event was generated.
on_area_cloned
Called when an area of the map is cloned.
Identifier of the event
Tick the event was generated.
on_biter_base_built
Called when a biter migration builds a base.
This will be called multiple times for each migration, once for every biter that is sacrificed to build part of the new base.
on_brush_cloned
Called when a set of positions on the map is cloned.
Identifier of the event
Tick the event was generated.
on_build_base_arrived
Called when a defines.command.build_base command reaches its destination, and before building starts.
The unit the command was assigned to.
The unit group the command was assigned to.
Identifier of the event
Tick the event was generated.
on_built_entity
Called when player builds something. Can be filtered using LuaPlayerBuiltEntityEventFilter.
The item prototype used to build the entity. Note this won't exist in some situations (built from blueprint, undo, etc).
The tags associated with this entity if any.
Identifier of the event
Tick the event was generated.
on_cancelled_deconstruction
Called when the deconstruction of an entity is canceled. Can be filtered using LuaEntityDeconstructionCancelledEventFilter.
on_cancelled_upgrade
Called when the upgrade of an entity is canceled. Can be filtered using LuaUpgradeCancelledEventFilter.
on_character_corpse_expired
Called when a character corpse expires due to timeout or all of the items being removed from it.
this is not called if the corpse is mined. See defines.events.on_pre_player_mined_item to detect that.
on_chunk_charted
Called when a chunk is charted or re-charted.
Area of the chunk.
Identifier of the event
Tick the event was generated.
on_chunk_deleted
Called when one or more chunks are deleted using LuaSurface::delete_chunk.
The chunks deleted.
Identifier of the event
Tick the event was generated.
on_chunk_generated
Called when a chunk is generated.
Area of the chunk.
Position of the chunk.
The surface the chunk is on.
Identifier of the event
Tick the event was generated.
on_console_chat
Called when a message is sent to the in-game console, either by a player or through the server interface.
This event only fires for plain messages, not for any commands (including /shout
or /whisper
).
on_console_command
Called when someone enters a command-like message regardless of it being a valid command.
on_cutscene_waypoint_reached
Called when a cutscene is playing, each time it reaches a waypoint in that cutscene.
This refers to an index in the table previously passed to set_controller which started the cutscene.
Due to implementation omission, waypoint_index is 0-based.
on_difficulty_settings_changed
Called when the map difficulty settings are changed.
It's not guaranteed that both settings are changed - just that at least one has been changed.
on_entity_cloned
Called when an entity is cloned. Can be filtered for the source entity using LuaEntityClonedEventFilter.
on_entity_damaged
Called when an entity is damaged. Can be filtered using LuaEntityDamagedEventFilter.
The damage amount before resistances.
The damage amount after resistances.
The health of the entity after the damage was applied.
The entity that did the attacking if available.
The force that did the attacking if any.
Identifier of the event
Tick the event was generated.
This is not called when an entities health is set directly by another mod.
on_entity_destroyed
Called after an entity is destroyed that has been registered with LuaBootstrap::register_on_entity_destroyed
Depending on when a given entity is destroyed this will be fired at the end of the current tick or end of the next tick.
on_entity_died
Called when an entity dies. Can be filtered using LuaEntityDiedEventFilter.
The entity that died.
The entity that did the killing if available.
The loot generated by this entity if any.
The force that did the killing if any.
The damage type if any.
Identifier of the event
Tick the event was generated.
on_entity_logistic_slot_changed
Called when one of an entity's personal logistic slots changes.
"Personal logistic slot" refers to a character or vehicle's personal request / auto-trash slots, not the request slots on logistic chests.
on_equipment_inserted
Called after equipment is inserted into an equipment grid.
The equipment grid inserted into.
The equipment inserted.
Identifier of the event
Tick the event was generated.
on_force_created
Called when a new force is created using game.create_force()
This is not called when the default forces ('player'
, 'enemy'
, 'neutral'
) are created as they will always exist.
on_force_reset
Called when LuaForce::reset is finished.
on_forces_merged
Called after two forces have been merged using game.merge_forces()
.
The source force is invalidated before this event is called and the name can be re-used in this event if desired.
on_game_created_from_scenario
Called when a game is created from a scenario. This is fired for every mod, even when the scenario's save data already includes it. In those cases however, LuaBootstrap::on_init is not fired.
Identifier of the event
Tick the event was generated.
This event is not fired when the scenario is loaded via the map editor.
on_gui_checked_state_changed
Called when LuaGuiElement checked state is changed (related to checkboxes and radio buttons).
on_gui_click
Called when LuaGuiElement is clicked.
The clicked element.
The player who did the clicking.
The mouse button used if any.
If alt was pressed.
If control was pressed.
If shift was pressed.
Identifier of the event
Tick the event was generated.
on_gui_closed
Called when the player closes the GUI they have open.
The player.
The GUI type that was open.
The entity that was open
The item that was open
The equipment that was open
The other player that was open
The custom GUI element that was open
The technology that was automatically selected when opening the research GUI
The tile position that was open
Identifier of the event
Tick the event was generated.
This is only called if the player explicitly closed the GUI.
It's not advised to open any other GUI during this event because if this is run as a request to open a different GUI the game will force close the new opened GUI without notice to ensure the original requested GUI is opened.
on_gui_confirmed
Called when a LuaGuiElement is confirmed, for example by pressing Enter in a textfield.
on_gui_elem_changed
Called when LuaGuiElement element value is changed (related to choose element buttons).
on_gui_location_changed
Called when LuaGuiElement element location is changed (related to frames in player.gui.screen
).
on_gui_opened
Called when the player opens a GUI.
The player.
The GUI type that was opened.
The entity that was opened
The item that was opened
The equipment that was opened
The other player that was opened
The custom GUI element that was opened
Identifier of the event
Tick the event was generated.
on_gui_selected_tab_changed
Called when LuaGuiElement selected tab is changed (related to tabbed-panes).
on_gui_selection_state_changed
Called when LuaGuiElement selection state is changed (related to drop-downs and listboxes).
on_gui_switch_state_changed
Called when LuaGuiElement switch state is changed (related to switches).
on_gui_text_changed
Called when LuaGuiElement text is changed by the player.
on_gui_value_changed
Called when LuaGuiElement slider value is changed (related to the slider element).
on_marked_for_deconstruction
Called when an entity is marked for deconstruction with the Deconstruction planner or via script. Can be filtered using LuaEntityMarkedForDeconstructionEventFilter.
on_marked_for_upgrade
Called when an entity is marked for upgrade with the Upgrade planner or via script. Can be filtered using LuaEntityMarkedForUpgradeEventFilter.
on_mod_item_opened
Called when the player uses the 'Open item GUI' control on an item defined with the 'mod-openable' flag
on_permission_group_edited
Called directly after a permission group is edited in some way.
The player that did the editing.
The group being edited.
The edit type: "add-permission", "remove-permission", "enable-all", "disable-all", "add-player", "remove-player", "rename".
The action when the type
is "add-permission" or "remove-permission".
The other player when the type
is "add-player" or "remove-player".
The old group name when the type
is "rename".
The new group name when the type
is "rename".
Identifier of the event
Tick the event was generated.
on_player_alt_selected_area
Called after a player alt-selects an area with a selection-tool item.
The player doing the selection.
The surface selected.
The area selected.
The item used to select the area.
The entities selected.
The tiles selected.
Identifier of the event
Tick the event was generated.
on_player_built_tile
Called after a player builds tiles.
The surface the tile(s) were built on.
The position data.
The tile prototype that was placed.
The item type used to build the tiles
The stack used to build the tiles (may be empty if all of the items where used to build the tiles).
Identifier of the event
Tick the event was generated.
on_player_cancelled_crafting
Called when a player cancels crafting.
The player that did the crafting.
The crafting items returned to the player's inventory.
The recipe that has been cancelled.
The number of crafts that have been cancelled.
Identifier of the event
Tick the event was generated.
on_player_changed_surface
Called after a player changes surfaces.
In the instance a player is moved off a surface due to it being deleted this is not called.
on_player_configured_blueprint
Called when a player clicks the "confirm" button in the configure Blueprint GUI.
on_player_configured_spider_remote
Called when a player configures spidertron remote to be connected with a given spidertron
on_player_crafted_item
Called when the player finishes crafting an item. This event fires just before the results are inserted into the player's inventory, not when the crafting is queued (see on_pre_player_crafted_item).
The item that has been crafted.
The player doing the crafting.
The recipe used to craft this item.
Identifier of the event
Tick the event was generated.
on_player_deconstructed_area
Called when a player selects an area with a deconstruction planner.
The player doing the selection.
The surface selected.
The area selected.
The item used to select the area.
If normal selection or alt selection was used.
Identifier of the event
Tick the event was generated.
on_player_driving_changed_state
Called when the player's driving state has changed, this means a player has either entered or left a vehicle.
on_player_fast_transferred
Called when a player fast-transfers something to or from an entity.
The player transferred from or to.
The entity transferred from or to.
Whether the transfer was from player to entity. If false
, the transfer was from entity to player.
Identifier of the event
Tick the event was generated.
on_player_flushed_fluid
Called after player flushed fluid
Index of the player
Name of a fluid that was flushed
Amount of fluid that was removed
Entity from which flush was performed
True if flush was requested only on this entity
Identifier of the event
Tick the event was generated.
on_player_mined_entity
Called after the results of an entity being mined are collected just before the entity is destroyed. After this event any items in the buffer will be transferred into the player as if they came from mining the entity. Can be filtered using LuaPlayerMinedEntityEventFilter.
The index of the player doing the mining.
The entity that has been mined.
The temporary inventory that holds the result of mining the entity.
Identifier of the event
Tick the event was generated.
The buffer inventory is special in that it's only valid during this event and has a dynamic size expanding as more items are transferred into it.
on_player_mined_tile
Called after a player mines tiles.
The surface the tile(s) were mined from.
The position data.
Identifier of the event
Tick the event was generated.
on_player_placed_equipment
Called after the player puts equipment in an equipment grid
The equipment put in the equipment grid.
The equipment grid the equipment was put in.
Identifier of the event
Tick the event was generated.
on_player_removed
Called when a player is removed (deleted) from the game. Not to be confused with the player logging of this is different in that the player is deleted as if he never existed in the save file.
on_player_repaired_entity
Called when a player repairs an entity. Can be filtered using LuaPlayerRepairedEntityEventFilter.
on_player_rotated_entity
Called when the player rotates an entity. This event is only fired when the entity actually changes its orientation -- pressing the rotate key on an entity that can't be rotated won't fire this event.
on_player_selected_area
Called after a player selects an area with a selection-tool item.
The player doing the selection.
The surface selected.
The area selected.
The item used to select the area.
The entities selected.
The tiles selected.
Identifier of the event
Tick the event was generated.
on_player_set_quick_bar_slot
Called when a player sets a quickbar slot to anything (new value, or set to empty).
on_player_setup_blueprint
Called when a player selects an area with a blueprint.
The player doing the selection.
The surface selected.
The area selected.
The item used to select the area.
If normal selection or alt selection was used.
The blueprint entity index to source entity mapping. Note: if any mod changes the blueprint this will be incorrect.
Identifier of the event
Tick the event was generated.
on_player_toggled_alt_mode
Called when a player toggles alt mode, also known as "show entity info".
The new alt mode value. This value is a shortcut for accessing GameViewSettings::show_entity_info on the player.
Identifier of the event
Tick the event was generated.
on_player_unbanned
Called when a player is un-banned.
The player un-banned.
The player name un-banned.
The player that did the un-banning if any.
The reason the player was banned if any.
Identifier of the event
Tick the event was generated.
on_player_used_spider_remote
Called when a player uses spidertron remote to send a spidertron to a given position
The player that used the remote.
Spider vehicle which was requested to move.
Goal position to which spidertron was sent to.
If the use was successful. It may fail when spidertron has different driver or when player is on different surface.
Identifier of the event
Tick the event was generated.
on_post_entity_died
Called after an entity dies. Can be filtered using LuaPostEntityDiedEventFilter.
The ghost created by the entity dying if any.
The force that did the killing if any.
Position where the entity died.
The entity prototype of the entity that died.
The damage type if any.
The corpses created by the entity dying if any.
The surface the entity was on.
The unit number the entity had if any.
Identifier of the event
Tick the event was generated.
on_pre_build
Called when players uses an item to build something. Called before on_built_entity.
The player who did the placing.
Where the item was placed.
Item was placed using shift building.
The direction the item was facing when placed.
If building this blueprint was flipped horizontally.
If building this blueprint was flipped vertically.
Item was placed while moving.
Identifier of the event
Tick the event was generated.
on_pre_chunk_deleted
Called before one or more chunks are deleted using LuaSurface::delete_chunk.
The chunks to be deleted.
Identifier of the event
Tick the event was generated.
on_pre_ghost_deconstructed
Called before a ghost entity is destroyed as a result of being marked for deconstruction. Can be filtered using LuaPreGhostDeconstructedEventFilter.
on_pre_player_crafted_item
Called when a player queues something to be crafted.
The player doing the crafting.
The recipe being queued.
The items removed from the players inventory to do the crafting.
The number of times the recipe is being queued.
Identifier of the event
Tick the event was generated.
on_pre_player_mined_item
Called when the player finishes mining an entity, before the entity is removed from map. Can be filtered using LuaPrePlayerMinedEntityEventFilter.
on_pre_player_removed
Called before a player is removed (deleted) from the game. Not to be confused with the player logging of this is different in that the player is deleted as if he never existed in the save file.
on_pre_script_inventory_resized
Called just before a script inventory is resized.
If done by console command; the player who ran the command.
The mod that did the resizing. This will be "core"
if done by console command or scenario script.
The old inventory size.
The new inventory size.
Identifier of the event
Tick the event was generated.
on_pre_surface_cleared
Called just before a surface is cleared (all entities removed and all chunks deleted).
on_research_started
Called when a technology research starts.
The technology being researched
Identifier of the event
Tick the event was generated.
on_resource_depleted
Called when a resource entity reaches 0 or its minimum yield for infinite resources.
on_robot_built_entity
Called when a construction robot builds an entity. Can be filtered using LuaRobotBuiltEntityEventFilter.
The robot that did the building.
The entity built.
The item used to do the building.
The tags associated with this entity if any.
Identifier of the event
Tick the event was generated.
on_robot_built_tile
Called after a robot builds tiles.
The robot.
The position data.
The tile prototype that was placed.
The item type used to build the tiles.
The stack used to build the tiles (may be empty if all of the items where used to build the tiles).
The surface the tile(s) are build on.
Identifier of the event
Tick the event was generated.
on_robot_mined_entity
Called after the results of an entity being mined are collected just before the entity is destroyed. After this event any items in the buffer will be transferred into the robot as if they came from mining the entity. Can be filtered using LuaRobotMinedEntityEventFilter.
The robot doing the mining.
The entity that has been mined.
The temporary inventory that holds the result of mining the entity.
Identifier of the event
Tick the event was generated.
The buffer inventory is special in that it's only valid during this event and has a dynamic size expanding as more items are transferred into it.
on_robot_mined_tile
Called after a robot mines tiles.
The robot.
The position data.
The surface the tile(s) were mined on.
Identifier of the event
Tick the event was generated.
on_robot_pre_mined
Called before a robot mines an entity. Can be filtered using LuaPreRobotMinedEntityEventFilter.
on_runtime_mod_setting_changed
Called when a runtime mod setting is changed by a player.
If the setting_type
is "global"
and it was changed through the mod settings GUI, this is the index of the player that changed the global setting. If the setting_type
is "runtime-per-user"
and it changed a current setting of the player, this is the index of the player whose setting was changed. In all other cases, this is nil
.
The prototype name of the setting that was changed.
Either "runtime-per-user" or "runtime-global".
Identifier of the event
Tick the event was generated.
on_script_inventory_resized
Called just after a script inventory is resized.
If done by console command; the player who ran the command.
The mod that did the resizing. This will be "core"
if done by console command or scenario script.
The old inventory size.
The new inventory size.
Any items which didn't fit into the new inventory size.
Identifier of the event
Tick the event was generated.
on_script_path_request_finished
Called when a LuaSurface::request_path call completes.
The actual path that the pathfinder has determined. nil
if pathfinding failed.
Handle to associate the callback with a particular call to LuaSurface::request_path.
Indicates that the pathfinder failed because it is too busy, and that you can retry later.
Identifier of the event
Tick the event was generated.
on_script_trigger_effect
Called when a script trigger effect is triggered.
The effect_id specified in the trigger effect.
The surface the effect happened on.
Identifier of the event
Tick the event was generated.
on_sector_scanned
Called when an entity of type radar
finishes scanning a sector. Can be filtered for the radar using LuaSectorScannedEventFilter.
The radar that did the scanning.
The chunk scanned.
Area of the scanned chunk.
Identifier of the event
Tick the event was generated.
on_string_translated
Called when a translation request generated through LuaPlayer::request_translation is translated.
The player whose locale was used for the translation.
The localised string being translated.
The translated localised_string
.
Whether the requested localised string was valid and could be translated.
Identifier of the event
Tick the event was generated.
on_surface_cleared
Called just after a surface is cleared (all entities removed and all chunks deleted).
on_surface_created
Called when a surface is created.
This is not called when the default surface is created as it will always exist.
on_technology_effects_reset
Called when LuaForce::reset_technology_effects is finished.
on_tick
It is fired once every tick. Since this event is fired every tick, its handler shouldn't include performance heavy code.
Identifier of the event
Tick the event was generated.
on_train_created
Called when a new train is created either through disconnecting/connecting an existing one or building a new one.
on_train_schedule_changed
Called when a trains schedule is changed either by the player or through script.
on_trigger_created_entity
Called when an entity with a trigger prototype (such as capsules) create an entity AND that trigger prototype defined trigger_created_entity="true"
.
on_trigger_fired_artillery
Called when an entity with a trigger prototype (such as capsules) fire an artillery projectile AND that trigger prototype defined trigger_fired_artillery="true"
.
on_unit_added_to_group
Called when a unit is added to a unit group.
Identifier of the event
Tick the event was generated.
on_unit_group_created
Called when a new unit group is created, before any members are added to it.
Identifier of the event
Tick the event was generated.
on_unit_group_finished_gathering
Called when a unit group finishes gathering and starts executing its command.
Identifier of the event
Tick the event was generated.
on_unit_removed_from_group
Called when a unit is removed from a unit group.
Identifier of the event
Tick the event was generated.
on_worker_robot_expired
Called when a worker (construction or logistic) robot expires through a lack of energy.
script_raised_built
A static event mods can use to tell other mods they built something by script. This event is only raised if a mod does so with LuaBootstrap::raise_event or LuaBootstrap::raise_script_built, or when raise_built
is passed to LuaSurface::create_entity. Can be filtered using LuaScriptRaisedBuiltEventFilter.
script_raised_destroy
A static event mods can use to tell other mods they destroyed something by script. This event is only raised if a mod does so with LuaBootstrap::raise_event or LuaBootstrap::raise_script_destroy, or when raise_destroy
is passed to LuaEntity::destroy. Can be filtered using LuaScriptRaisedDestroyEventFilter.
script_raised_revive
A static event mods can use to tell other mods they revived something by script. This event is only raised if a mod does so with LuaBootstrap::raise_event or LuaBootstrap::raise_script_revive, or when raise_revive
is passed to LuaEntity::revive. Can be filtered using LuaScriptRaisedReviveEventFilter.
script_raised_set_tiles
A static event mods can use to tell other mods they changed tiles on a surface by script. This event is only raised if a mod does so with LuaBootstrap::raise_event or LuaBootstrap::raise_script_set_tiles, or when raise_event
is passed to LuaSurface::set_tiles.