Events

All events Every event contains at least the name and tick attributes.
on_ai_command_completed Called when a unit/group completes a command.
on_area_cloned Called when an area of the map is cloned.
on_biter_base_built Called when a biter migration builds a base.
on_built_entity Called when player builds something.
on_cancelled_deconstruction Called when the deconstruction of an entity is canceled.
on_cancelled_upgrade Called when the upgrade of an entity is canceled.
on_character_corpse_expired Called when a character corpse expires due to timeout or all of the items being removed from it.
on_chart_tag_added Called when a chart tag is created.
on_chart_tag_modified Called when a chart tag is modified by a player.
on_chart_tag_removed Called just before a chart tag is deleted.
on_chunk_charted Called when a chunk is charted or re-charted.
on_chunk_deleted Called when one or more chunks are deleted using LuaSurface::delete_chunk.
on_chunk_generated Called when a chunk is generated.
on_combat_robot_expired Called when a combat robot expires through a lack of energy, or timeout.
on_console_chat Called when someone talks in-game either a player or through the server interface.
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.
on_difficulty_settings_changed Called when the map difficulty settings are changed.
on_entity_cloned Called when an entity is cloned.
on_entity_damaged Called when an entity is damaged.
on_entity_died Called when an entity dies.
on_entity_renamed Called after an entity has been renamed either by the player or through script.
on_entity_settings_pasted Called after entity copy-paste is done.
on_entity_spawned Called when an entity is spawned by a EnemySpawner
on_force_created Called when a new force is created using game.create_force()
on_forces_merged Called after two forces have been merged using game.merge_forces().
on_forces_merging Called when two forces are about to be merged using game.merge_forces().
on_game_created_from_scenario Called when a game is created from a scenario.
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.
on_gui_closed Called when the player closes the GUI they have open.
on_gui_confirmed Called when LuaGuiElement is confirmed.
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.
on_gui_opened Called when the player opens a GUI.
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_land_mine_armed Called when a land mine is armed.
on_lua_shortcut Called when a custom Lua shortcut is pressed.
on_marked_for_deconstruction Called when an entity is marked for deconstruction with the Deconstruction planner or via script.
on_marked_for_upgrade Called when an entity is marked for upgrade with the Upgrade planner or via script.
on_market_item_purchased Called after a player purchases some offer from a Market entity.
on_mod_item_opened Called when the player uses the 'Open item GUI' control on an item defined with 'can_be_mod_opened' as true
on_picked_up_item Called when a player picks up an item.
on_player_alt_selected_area Called after a player alt-selects an area with a selection-tool item.
on_player_ammo_inventory_changed Called after a players ammo inventory changed in some way.
on_player_armor_inventory_changed Called after a players armor inventory changed in some way.
on_player_banned Called when a player is banned.
on_player_built_tile Called after a player builds tiles.
on_player_cancelled_crafting Called when a player cancels crafting.
on_player_changed_force Called after a player changes forces.
on_player_changed_position Called when the tile position a player is located at changes.
on_player_changed_surface Called after a player changes surfaces.
on_player_cheat_mode_disabled Called when cheat mode is disabled on a player.
on_player_cheat_mode_enabled Called when cheat mode is enabled on a player.
on_player_configured_blueprint Called when a player clicks the "confirm" button in the configure Blueprint GUI.
on_player_crafted_item Called when the player crafts an item (just before inserting into player's inventory, not clicking the button to craft).
on_player_created Called after the player was created.
on_player_cursor_stack_changed Called after a players cursorstack changed in some way.
on_player_deconstructed_area Called when a player selects an area with a deconstruction planner.
on_player_demoted Called when a player is demoted.
on_player_died Called after a player dies.
on_player_display_resolution_changed Called when the display resolution changes for a given player.
on_player_display_scale_changed Called when the display scale changes for a given player.
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_dropped_item Called when a player drops an item on the ground.
on_player_fast_transferred Called when a player fast-transfers something to or from an entity.
on_player_gun_inventory_changed Called after a players gun inventory changed in some way.
on_player_joined_game Called after a player joins the game.
on_player_kicked Called when a player is kicked.
on_player_left_game Called after a player leaves the game.
on_player_main_inventory_changed Called after a players main inventory changed in some way.
on_player_mined_entity Called after the results of an entity being mined are collected just before the entity is destroyed.
on_player_mined_item Called when the player mines something.
on_player_mined_tile Called after a player mines tiles.
on_player_muted Called when a player is muted.
on_player_pipette Called when a player invokes the "smart pipette" over an entity.
on_player_placed_equipment Called after the player puts equipment in an equipment grid
on_player_promoted Called when a player is promoted.
on_player_removed Called when a player is removed (deleted) from the game.
on_player_removed_equipment Called after the player removes equipment from an equipment grid
on_player_repaired_entity Called when a player repairs an entity.
on_player_respawned Called after a player respawns.
on_player_rotated_entity Called when the player rotates an entity.
on_player_selected_area Called after a player selects an area with a selection-tool item.
on_player_setup_blueprint Called when a player selects an area with a blueprint.
on_player_toggled_alt_mode Called when a player toggles alt mode, also known as "show entity info".
on_player_toggled_map_editor Called when a player toggles the map editor on or off.
on_player_trash_inventory_changed Called after a players trash inventory changed in some way.
on_player_unbanned Called when a player is un-banned.
on_player_unmuted Called when a player is unmuted.
on_player_used_capsule Called when a player uses a capsule that results in some game action.
on_post_entity_died Called after an entity dies.
on_pre_chunk_deleted Called before one or more chunks are deleted using LuaSurface::delete_chunk.
on_pre_entity_settings_pasted Called before entity copy-paste is done.
on_pre_ghost_deconstructed Called before a ghost entity is destroyed as a result of being marked for deconstruction.
on_pre_player_crafted_item Called when a player queues something to be crafted.
on_pre_player_died Called before a players dies.
on_pre_player_left_game Called before a player leaves the game.
on_pre_player_mined_item Called when the player finishes mining an entity, before the entity is removed from map.
on_pre_player_removed Called before a player is removed (deleted) from the game.
on_pre_robot_exploded_cliff Called directly before a robot explodes cliffs.
on_pre_surface_cleared Called just before a surface is cleared (all entities removed and all chunks deleted).
on_pre_surface_deleted Called just before a surface is deleted.
on_put_item Called when players uses an item to build something.
on_research_finished Called when a research finishes.
on_research_started Called when a technology research starts.
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.
on_robot_built_tile Called after a robot builds tiles.
on_robot_exploded_cliff Called directly after a robot explodes cliffs.
on_robot_mined Called when a robot mines an entity.
on_robot_mined_entity Called after the results of an entity being mined are collected just before the entity is destroyed.
on_robot_mined_tile Called after a robot mines tiles.
on_robot_pre_mined Called before a robot mines an entity.
on_rocket_launch_ordered Called when a rocket silo is ordered to be launched.
on_rocket_launched Called when the rocket is launched.
on_runtime_mod_setting_changed Called when a runtime mod setting is changed by a player.
on_script_path_request_finished Called when a script path request completes.
on_sector_scanned Called when the radar finishes scanning a sector.
on_selected_entity_changed Called after the selected entity changes for a given player.
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.
on_surface_deleted Called after a surface is deleted.
on_surface_imported Called after a surface is imported.
on_surface_renamed Called when a surface is renamed.
on_technology_effects_reset Called when LuaForce::reset_technology_effects is finished.
on_tick It is fired once every tick.
on_train_changed_state Called when a train changes state (started to stopped and vice versa)
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.
on_unit_group_created Called when a new unit group is created, before any members are added to it.
on_unit_removed_from_group Called when a unit is removed from a unit group.
script_raised_built A static event mods can use to tell other mods they built something with a script.
script_raised_destroy A static event mods can use to tell other mods they destroyed something with a script.
script_raised_revive A static event mods can use to tell other mods they revived something with a script.
All events

Every event contains at least the name and tick attributes. Other events may include some additional attributes, specific to the event.

Contains
name :: defines.events: Identifier of the event
tick :: uint: Tick the event was generated.
on_tick

It is fired once every tick. Since this event is fired every tick, its handler shouldn't include performance heavy code.

on_ai_command_completed

Called when a unit/group completes a command.

Contains
unit_number :: uint: unit_number/group_number of the unit/group which just completed a command.
on_area_cloned

Called when an area of the map is cloned.

Contains
source_surface :: LuaSurface
source_area :: BoundingBox
destination_surface :: LuaSurface
destination_area :: BoundingBox
destination_force :: LuaForce (optional)
clone_tiles :: boolean
clone_entities :: boolean
clone_decoratives :: boolean
clear_destination :: boolean
on_biter_base_built

Called when a biter migration builds a base.

Contains
entity :: LuaEntity: The built entity.
Note: This will be called multiple times as each biter in a given migration is sacrificed and builds part of the base.
on_built_entity

Called when player builds something.

Contains
created_entity :: LuaEntity
player_index :: uint
stack :: LuaItemStack
item :: LuaItemPrototype (optional): The item prototype used to build the entity. Note this won't exist in some situations (built from blueprint, undo, etc).
on_cancelled_deconstruction

Called when the deconstruction of an entity is canceled.

Contains
entity :: LuaEntity
player_index :: uint (optional)
on_cancelled_upgrade

Called when the upgrade of an entity is canceled.

Contains
entity :: LuaEntity
player_index :: uint (optional)
on_character_corpse_expired

Called when a character corpse expires due to timeout or all of the items being removed from it.

Contains
corpse :: LuaEntity: The corpse.
Note: this is not called if the corpse is mined. See defines.events.on_pre_player_mined_item to detect that.
on_chart_tag_added

Called when a chart tag is created.

Contains
force :: LuaForce
player_index :: uint (optional)
on_chart_tag_modified

Called when a chart tag is modified by a player.

Contains
player_index :: uint (optional)
force :: LuaForce
old_text :: string
old_icon :: SignalID
old_player_index :: uint (optional)
on_chart_tag_removed

Called just before a chart tag is deleted.

Contains
force :: LuaForce
player_index :: uint (optional)
on_chunk_charted

Called when a chunk is charted or re-charted.

Contains
surface_index :: uint
position :: ChunkPosition
force :: LuaForce
on_chunk_deleted

Called when one or more chunks are deleted using LuaSurface::delete_chunk.

Contains
surface_index :: uint
positions :: array of ChunkPosition: The chunks deleted.
on_chunk_generated

Called when a chunk is generated.

Contains
area :: BoundingBox: Area of the chunk
surface :: LuaSurface: The surface the chunk is on
on_combat_robot_expired

Called when a combat robot expires through a lack of energy, or timeout.

Contains
robot :: LuaEntity
owner :: LuaEntity (optional): The entity that owns the robot if any.
on_console_chat

Called when someone talks in-game either a player or through the server interface.

Contains
player_index :: uint (optional): The player if any.
message :: string: The chat message.
on_console_command

Called when someone enters a command-like message regardless of it being a valid command.

Contains
player_index :: uint (optional): The player if any.
command :: string: The command as typed without the preceding forward slash ('/').
parameters :: string: The parameters provided if any.
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.

Contains
player_index :: uint: The player index of the player viewing the cutscene.
waypoint_index :: uint: The index of the waypoint we just completed.
on_difficulty_settings_changed

Called when the map difficulty settings are changed.

Contains
old_recipe_difficulty :: uint
old_technology_difficulty :: uint
Note: 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.

Contains
source :: LuaEntity
destination :: LuaEntity
on_entity_damaged

Called when an entity is damaged.

Contains
entity :: LuaEntity
damage_type :: LuaDamagePrototype
original_damage_amount :: float
final_damage_amount :: float
cause :: LuaEntity (optional): The entity that did the attacking if available.
force :: LuaForce (optional): The force that did the attacking if any.
Note: This is not called when an entities health is set directly by another mod.
on_entity_died

Called when an entity dies.

Contains
entity :: LuaEntity
cause :: LuaEntity (optional): The entity that did the killing if available.
loot :: LuaInventory: The loot generated by this entity if any.
force :: LuaForce (optional): The force that did the killing if any.
on_entity_renamed

Called after an entity has been renamed either by the player or through script.

Contains
player_index :: uint (optional): If by_script is true this will not be included
by_script :: boolean
entity :: LuaEntity
old_name :: string
on_entity_settings_pasted

Called after entity copy-paste is done.

Contains
player_index :: uint
source :: LuaEntity: The source entity settings have been copied from.
destination :: LuaEntity: The destination entity settings have been copied to.
on_entity_spawned

Called when an entity is spawned by a EnemySpawner

Contains
spawner :: LuaEntity
entity :: LuaEntity
on_force_created

Called when a new force is created using game.create_force()

Contains
force :: LuaForce: The newly created force.
on_forces_merged

Called after two forces have been merged using game.merge_forces().

Contains
source_name :: string: The force destroyed.
source_index :: uint: The index of the destroyed force.
destination :: LuaForce: The force entities where reassigned to.
Note: The source force is invalidated before this event is called and the name can be re-used in this event if desired.
on_forces_merging

Called when two forces are about to be merged using game.merge_forces().

Contains
source :: LuaForce: The force to be destroyed
destination :: LuaForce: The force to reassign entities to.
on_game_created_from_scenario

Called when a game is created from a scenario.

on_gui_checked_state_changed

Called when LuaGuiElement checked state is changed (related to checkboxes and radio buttons)

Contains
element :: LuaGuiElement: The element whose checked state changed
player_index :: uint: The player who did the change.
on_gui_click

Called when LuaGuiElement is clicked.

Contains
element :: LuaGuiElement: The clicked element.
player_index :: uint: The player who did the clicking.
button :: defines.mouse_button_type: The mouse button used if any.
alt :: boolean: If alt was pressed.
control :: boolean: If control was pressed.
shift :: boolean: If shift was pressed.
on_gui_closed

Called when the player closes the GUI they have open.

Contains
player_index :: uint: The player.
gui_type :: defines.gui_type: The GUI type that was open.
entity :: LuaEntity (optional): The entity that was open
item :: LuaItemStack (optional): The item that was open
equipment :: LuaEquipment (optional): The equipment that was open
other_player :: LuaPlayer (optional): The other player that was open
element :: LuaGuiElement (optional): The custom GUI element that was open
technology :: LuaTechnology (optional): The technology that was automatically selected when opening the research GUI
tile_position :: TilePosition (optional): The tile position that was open
Note: This is only called if the player explicitly closed the GUI.
Note: 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 LuaGuiElement is confirmed.

Contains
element :: LuaGuiElement: The confirmed element.
player_index :: uint: The player who did the confirming.
alt :: boolean: If alt was pressed.
control :: boolean: If control was pressed.
shift :: boolean: If shift was pressed.
on_gui_elem_changed

Called when LuaGuiElement element value is changed (related to choose element buttons)

Contains
element :: LuaGuiElement: The element whose selection state changed
player_index :: uint: The player who did the change.
on_gui_location_changed

Called when LuaGuiElement element location is changed (related to frames in player.gui.screen)

Contains
element :: LuaGuiElement: The element whose selection state changed
player_index :: uint: The player who did the change.
on_gui_opened

Called when the player opens a GUI.

Contains
player_index :: uint: The player.
gui_type :: defines.gui_type: The GUI type that was opened.
entity :: LuaEntity (optional): The entity that was opened
item :: LuaItemStack (optional): The item that was opened
equipment :: LuaEquipment (optional): The equipment that was opened
other_player :: LuaPlayer (optional): The other player that was opened
element :: LuaGuiElement (optional): The custom GUI element that was opened
on_gui_selected_tab_changed

Called when LuaGuiElement selected tab is changed (related to tabbed-panes)

Contains
element :: LuaGuiElement: The tabbed pane whose selected tab changed
player_index :: uint: The player who did the change.
on_gui_selection_state_changed

Called when LuaGuiElement selection state is changed (related to drop-downs and listboxes)

Contains
element :: LuaGuiElement: The element whose selection state changed
player_index :: uint: The player who did the change.
on_gui_switch_state_changed

Called when LuaGuiElement switch state is changed (related to switches)

Contains
element :: LuaGuiElement: The tabbed pane whose selected tab changed
player_index :: uint: The player who did the change.
on_gui_text_changed

Called when LuaGuiElement text is changed by the player

Contains
element :: LuaGuiElement: The edited element.
player_index :: uint: The player who did the edit.
on_gui_value_changed

Called when LuaGuiElement slider value is changed (related to the slider element)

Contains
element :: LuaGuiElement: The element whose value changed
player_index :: uint: The player who did the change.
on_land_mine_armed

Called when a land mine is armed.

Contains
mine :: LuaEntity
on_lua_shortcut

Called when a custom Lua shortcut is pressed.

Contains
player_index :: uint
prototype_name :: string: Shortcut prototype name of the shortcut that was clicked.
on_marked_for_deconstruction

Called when an entity is marked for deconstruction with the Deconstruction planner or via script.

Contains
entity :: LuaEntity
player_index :: uint (optional)
on_marked_for_upgrade

Called when an entity is marked for upgrade with the Upgrade planner or via script.

Contains
entity :: LuaEntity
player_index :: uint (optional)
on_market_item_purchased

Called after a player purchases some offer from a Market entity.

Contains
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 count of offers purchased.
on_mod_item_opened

Called when the player uses the 'Open item GUI' control on an item defined with 'can_be_mod_opened' as true

Contains
player_index :: uint: The player.
item :: LuaItemPrototype: The item clicked on.
on_picked_up_item

Called when a player picks up an item.

Contains
item_stack :: SimpleItemStack
player_index :: uint
on_player_alt_selected_area

Called after a player alt-selects an area with a selection-tool item.

Contains
player_index :: uint: The player doing the selection.
area :: BoundingBox: The area selected.
item :: string: The item used to select the area.
entities :: array of LuaEntity: The entities selected.
tiles :: array of LuaTile: The tiles selected.
on_player_ammo_inventory_changed

Called after a players ammo inventory changed in some way.

Contains
player_index :: uint
on_player_armor_inventory_changed

Called after a players armor inventory changed in some way.

Contains
player_index :: uint
on_player_banned

Called when a player is banned.

Contains
player_index :: uint (optional): The player banned.
player_name :: string: The banned player name.
by_player :: uint (optional): The player that did the banning if any.
reason :: string (optional): The reason given if any.
on_player_built_tile

Called after a player builds tiles.

Contains
player_index :: uint
surface_index :: uint: The surface the tile(s) were built on.
tiles :: array of OldTileAndPosition: The position data.
tile :: LuaTilePrototype: The tile prototype that was placed.
item :: LuaItemPrototype (optional): The item type used to build the tiles
stack :: LuaItemStack (optional): The stack used to build the tiles (may be empty if all of the items where used to build the tiles).
on_player_cancelled_crafting

Called when a player cancels crafting.

Contains
player_index :: uint
items :: LuaInventory
recipe :: LuaRecipe
cancel_count :: uint
on_player_changed_force

Called after a player changes forces.

Contains
player_index :: uint: The player who changed forces.
force :: LuaForce: The old force.
on_player_changed_position

Called when the tile position a player is located at changes.

Contains
player_index :: uint: The player.
on_player_changed_surface

Called after a player changes surfaces.

Contains
player_index :: uint: The player who changed surfaces.
surface_index :: uint: The surface index the player was on.
Note: In the instance a player is moved off a surface due to it being deleted this is not called.
on_player_cheat_mode_disabled

Called when cheat mode is disabled on a player.

Contains
player_index :: uint: The player.
on_player_cheat_mode_enabled

Called when cheat mode is enabled on a player.

Contains
player_index :: uint: The player.
on_player_configured_blueprint

Called when a player clicks the "confirm" button in the configure Blueprint GUI.

Contains
player_index :: uint: The player.
on_player_crafted_item

Called when the player crafts an item (just before inserting into player's inventory, not clicking the button to craft). It is called for each item crafted as well as what was clicked.

Contains
item_stack :: LuaItemStack: The crafted item
player_index :: uint: The player who did the crafting
recipe :: LuaRecipe: The recipe that resulted in this item being crafted
on_player_created

Called after the player was created.

Contains
player_index :: uint
on_player_cursor_stack_changed

Called after a players cursorstack changed in some way.

Contains
player_index :: uint
on_player_deconstructed_area

Called when a player selects an area with a deconstruction planner.

Contains
player_index :: uint: The player doing the selection.
area :: BoundingBox: The area selected.
item :: string: The item used to select the area.
alt :: boolean: If normal selection or alt selection was used.
on_player_demoted

Called when a player is demoted.

Contains
player_index :: uint: The player.
on_player_died

Called after a player dies.

Contains
player_index :: uint
cause :: LuaEntity (optional)
on_player_display_resolution_changed

Called when the display resolution changes for a given player.

Contains
player_index :: uint: The player
old_resolution :: DisplayResolution: The old display resolution
on_player_display_scale_changed

Called when the display scale changes for a given player.

Contains
player_index :: uint: The player
old_scale :: double: The old display scale
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.

Contains
player_index :: uint
entity :: LuaEntity (optional): The vehicle if any.
on_player_dropped_item

Called when a player drops an item on the ground.

Contains
player_index :: uint
entity :: LuaEntity: The item-on-ground entity.
on_player_fast_transferred

Called when a player fast-transfers something to or from an entity.

Contains
player_index :: uint
entity :: LuaEntity
from_player :: boolean: If the transfer was from player to entity or entity to player.
on_player_gun_inventory_changed

Called after a players gun inventory changed in some way.

Contains
player_index :: uint
on_player_joined_game

Called after a player joins the game.

Contains
player_index :: uint
on_player_kicked

Called when a player is kicked.

Contains
player_index :: uint: The player kicked.
by_player :: uint (optional): The player that did the kicking if any.
reason :: string (optional): The reason given if any.
on_player_left_game

Called after a player leaves the game.

Contains
player_index :: uint
on_player_main_inventory_changed

Called after a players main inventory changed in some way.

Contains
player_index :: uint
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.

Contains
player_index :: uint: The index of the player doing the mining.
entity :: LuaEntity: The entity that has been mined.
buffer :: LuaInventory: The temporary inventory that holds the result of mining the entity.
Note: 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_item

Called when the player mines something.

Contains
item_stack :: SimpleItemStack: The item given to the player
player_index :: uint
on_player_mined_tile

Called after a player mines tiles.

Contains
player_index :: uint
surface_index :: uint: The surface the tile(s) were mined from.
tiles :: array of OldTileAndPosition: The position data.
on_player_muted

Called when a player is muted.

Contains
player_index :: uint: The player.
on_player_pipette

Called when a player invokes the "smart pipette" over an entity.

Contains
player_index :: uint: The player
item :: LuaItemPrototype: The item put in the cursor
used_cheat_mode :: boolean: If cheat mode was used to give a free stack of the item.
on_player_placed_equipment

Called after the player puts equipment in an equipment grid

Contains
player_index :: uint
equipment :: LuaEquipment: The equipment put in the equipment grid.
grid :: LuaEquipmentGrid: The equipment grid the equipment was put in.
on_player_promoted

Called when a player is promoted.

Contains
player_index :: uint: The player.
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.

Contains
player_index :: uint: The player index that was removed
on_player_removed_equipment

Called after the player removes equipment from an equipment grid

Contains
player_index :: uint
grid :: LuaEquipmentGrid: The equipment grid removed from.
equipment :: string: The equipment removed.
count :: uint: The count of equipment removed.
on_player_repaired_entity

Called when a player repairs an entity.

Contains
player_index :: uint
entity :: LuaEntity
on_player_respawned

Called after a player respawns.

Contains
player_index :: uint
player_port :: LuaEntity (optional): The player port used to respawn if one was used.
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.

Contains
entity :: LuaEntity: The rotated entity.
previous_direction :: defines.direction: The previous direction
player_index :: uint
on_player_selected_area

Called after a player selects an area with a selection-tool item.

Contains
player_index :: uint: The player doing the selection.
area :: BoundingBox: The area selected.
item :: string: The item used to select the area.
entities :: array of LuaEntity: The entities selected.
tiles :: array of LuaTile: The tiles selected.
on_player_setup_blueprint

Called when a player selects an area with a blueprint.

Contains
player_index :: uint: The player doing the selection.
area :: BoundingBox: The area selected.
item :: string: The item used to select the area.
alt :: boolean: If normal selection or alt selection was used.
on_player_toggled_alt_mode

Called when a player toggles alt mode, also known as "show entity info".

Contains
player_index :: uint
on_player_toggled_map_editor

Called when a player toggles the map editor on or off.

Contains
player_index :: uint
on_player_trash_inventory_changed

Called after a players trash inventory changed in some way.

Contains
player_index :: uint
on_player_unbanned

Called when a player is un-banned.

Contains
player_index :: uint (optional): The player un-banned.
player_name :: string: The player name un-banned.
by_player :: uint (optional): The player that did the un-banning if any.
reason :: string (optional): The reason the player was banned if any.
on_player_unmuted

Called when a player is unmuted.

Contains
player_index :: uint: The player.
on_player_used_capsule

Called when a player uses a capsule that results in some game action.

Contains
player_index :: uint: The player.
item :: LuaItemPrototype: The capsule item used.
position :: Position: The position the capsule was used.
on_post_entity_died

Called after an entity dies.

Contains
ghost :: LuaEntity (optional): The ghost created by the entity dying if any.
force :: LuaForce (optional): The force that did the killing if any.
position :: Position: Position where the entity died.
prototype :: LuaEntityPrototype: The entity prototype of the entity that died.
corpses :: array of LuaEntity: The corpses created by the entity dying if any.
surface_index :: uint: The surface the entity was on.
on_pre_chunk_deleted

Called before one or more chunks are deleted using LuaSurface::delete_chunk.

Contains
surface_index :: uint
positions :: array of ChunkPosition: The chunks to be deleted.
on_pre_entity_settings_pasted

Called before entity copy-paste is done.

Contains
player_index :: uint
source :: LuaEntity: The source entity settings will be copied from.
destination :: LuaEntity: The destination entity settings will be copied to.
on_pre_ghost_deconstructed

Called before a ghost entity is destroyed as a result of being marked for deconstruction.

Contains
player_index :: uint (optional): The player that did the deconstruction if any.
ghost :: LuaEntity
on_pre_player_crafted_item

Called when a player queues something to be crafted.

Contains
player_index :: uint: The player.
recipe :: LuaRecipe: The recipe.
items :: LuaInventory: The items removed from the players inventory to do the crafting.
on_pre_player_died

Called before a players dies.

Contains
player_index :: uint
cause :: LuaEntity (optional)
on_pre_player_left_game

Called before a player leaves the game.

Contains
player_index :: uint
on_pre_player_mined_item

Called when the player finishes mining an entity, before the entity is removed from map.

Contains
entity :: LuaEntity: The entity being mined
player_index :: uint
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.

Contains
player_index :: uint: The player index that will be removed
on_pre_robot_exploded_cliff

Called directly before a robot explodes cliffs.

Contains
robot :: LuaEntity
cliff :: LuaEntity
item :: LuaItemPrototype: The cliff explosive used.
on_pre_surface_cleared

Called just before a surface is cleared (all entities removed and all chunks deleted).

Contains
surface_index :: uint
on_pre_surface_deleted

Called just before a surface is deleted.

Contains
surface_index :: uint
on_put_item

Called when players uses an item to build something. Called before on_built_entity.

Contains
position :: Position: Where the item was placed.
player_index :: uint: The player who did the placing.
shift_build :: boolean: Item was placed using shift building.
built_by_moving :: boolean: Item was placed while moving.
direction :: defines.direction: The direction the item was facing when placed.
on_research_finished

Called when a research finishes.

Contains
research :: LuaTechnology: The researched technology
by_script :: boolean: If the technology was researched by script.
on_research_started

Called when a technology research starts.

Contains
research :: LuaTechnology: The technology being researched
last_research :: LuaTechnology (optional)
on_resource_depleted

Called when a resource entity reaches 0 or its minimum yield for infinite resources.

Contains
entity :: LuaEntity
on_robot_built_entity

Called when a construction robot builds an entity.

Contains
robot :: LuaEntity: The robot that did the building.
created_entity :: LuaEntity: The entity built.
stack :: LuaItemStack: The item used to do the building.
on_robot_built_tile

Called after a robot builds tiles.

Contains
robot :: LuaEntity: The robot.
tiles :: array of OldTileAndPosition: The position data.
tile :: LuaTilePrototype: The tile prototype that was placed.
item :: LuaItemPrototype: The item type used to build the tiles.
stack :: LuaItemStack: The stack used to build the tiles (may be empty if all of the items where used to build the tiles).
surface_index :: uint: The surface the tile(s) are build on.
on_robot_exploded_cliff

Called directly after a robot explodes cliffs.

Contains
robot :: LuaEntity
item :: LuaItemPrototype: The cliff explosive used.
on_robot_mined

Called when a robot mines an entity.

Contains
robot :: LuaEntity: The robot that did the mining.
item_stack :: SimpleItemStack: The entity the robot just picked up.
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.

Contains
robot :: LuaEntity: The robot doing the mining.
entity :: LuaEntity: The entity that has been mined.
buffer :: LuaInventory: The temporary inventory that holds the result of mining the entity.
Note: 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.

Contains
robot :: LuaEntity: The robot.
tiles :: array of OldTileAndPosition: The position data.
surface_index :: uint: The surface the tile(s) were mined on.
on_robot_pre_mined

Called before a robot mines an entity.

Contains
robot :: LuaEntity: The robot that's about to do the mining.
entity :: LuaEntity: The entity which is about to be mined.
on_rocket_launch_ordered

Called when a rocket silo is ordered to be launched.

Contains
rocket :: LuaEntity
rocket_silo :: LuaEntity
player_index :: uint (optional): The player that is riding the rocket, if any.
on_rocket_launched

Called when the rocket is launched.

Contains
rocket :: LuaEntity
rocket_silo :: LuaEntity (optional)
player_index :: uint (optional): The player that is riding the rocket, if any.
on_runtime_mod_setting_changed

Called when a runtime mod setting is changed by a player.

Contains
player_index :: uint: The player who changed the setting or nil if changed by script.
setting :: string: The setting name that changed
setting_type :: string: The setting type: "runtime-per-user", or "runtime-global"
on_script_path_request_finished

Called when a script path request completes. LuaSurface::request_path

Each Waypoint is a table:

  • position :: Position
  • needs_destroy_to_reach :: boolean: true if the path from the previous Waypoint to this one goes through an entity that must be destroyed.

path will be nil if pathfinding failed.

Contains
path :: array of Waypoint (optional)
id :: uint: Handle to associate the callback with a particular call to LuaSurface::request_path.
try_again_later :: boolean: Indicates that the pathfinder failed because it is too busy, and you can retry later.
on_sector_scanned

Called when the radar finishes scanning a sector.

Contains
radar :: LuaEntity: The radar that did the scanning.
chunk_position :: Position: The chunk scanned.
on_selected_entity_changed

Called after the selected entity changes for a given player.

Contains
player_index :: uint: The player whose selected entity changed.
last_entity :: LuaEntity (optional): The last selected entity if it still exists and there was one.
on_surface_cleared

Called just after a surface is cleared (all entities removed and all chunks deleted).

Contains
surface_index :: uint
on_surface_created

Called when a surface is created.

Contains
surface_index :: uint
Note: This is not called when the default surface is created as it will always exist.
on_surface_deleted

Called after a surface is deleted.

Contains
surface_index :: uint
on_surface_imported

Called after a surface is imported.

Contains
surface_index :: uint
original_name :: string: The original surface name.
on_surface_renamed

Called when a surface is renamed.

Contains
surface_index :: uint
old_name :: string
new_name :: string
on_technology_effects_reset

Called when LuaForce::reset_technology_effects is finished.

Contains
force :: LuaForce
on_train_changed_state

Called when a train changes state (started to stopped and vice versa)

Contains
train :: LuaTrain
old_state :: defines.train_state
on_train_created

Called when a new train is created either through disconnecting/connecting an existing one or building a new one.

Contains
train :: LuaTrain
old_train_id_1 :: uint (optional): The first old train id when splitting/merging trains.
old_train_id_2 :: uint (optional): The second old train id when splitting/merging trains.
on_train_schedule_changed

Called when a trains schedule is changed either by the player or through script.

Contains
train :: LuaTrain
player_index :: uint (optional): The player who made the change if any.
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".

Contains
entity :: LuaEntity
source :: LuaEntity (optional)
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".

Contains
entity :: LuaEntity
source :: LuaEntity (optional)
on_unit_added_to_group

Called when a unit is added to a unit group.

Contains
unit :: LuaEntity
group :: LuaUnitGroup
on_unit_group_created

Called when a new unit group is created, before any members are added to it.

Contains
group :: LuaUnitGroup
on_unit_removed_from_group

Called when a unit is removed from a unit group.

Contains
unit :: LuaEntity
group :: LuaUnitGroup
script_raised_built

A static event mods can use to tell other mods they built something with a script. This is event is only raised if a mod uses it with script.raise_event() or when 'raise_built' is passed to LuaSurface::create_entity.

Contains
entity :: LuaEntity
script_raised_destroy

A static event mods can use to tell other mods they destroyed something with a script. This is event is only raised if a mod uses it with script.raise_event() or when 'raise_destroy' is passed to LuaEntity::destroy.

Contains
entity :: LuaEntity
script_raised_revive

A static event mods can use to tell other mods they revived something with a script. This is event is only raised if a mod uses it with script.raise_event() or when 'raise_revive' is passed to LuaEntity::revive.

Contains
entity :: LuaEntity