Factorio API Docs

1.1.67 <>

Events

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.


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_brush_cloned

Called when a set of positions on the map is cloned.


on_build_base_arrived

Called when a defines.command.build_base command reaches its destination, and before building starts.


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 a message is sent to the in-game console, either by 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_cancelled

Called when a cutscene is cancelled by the player or by script.


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_destroyed

Called after an entity is destroyed that has been registered with LuaBootstrap::register_on_entity_destroyed.


on_entity_died

Called when an entity dies.


on_entity_logistic_slot_changed

Called when one of an entity's personal logistic slots changes.


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_equipment_inserted

Called after equipment is inserted into an equipment grid.


on_equipment_removed

Called after equipment is removed from an equipment grid.


on_force_cease_fire_changed

Called when the a forces cease fire values change.


on_force_created

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


on_force_friends_changed

Called when the a forces friends change.


on_force_reset

Called when LuaForce::reset is finished.


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


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 the 'mod-openable' flag


on_permission_group_added

Called directly after a permission group is added.


on_permission_group_deleted

Called directly after a permission group is deleted.


on_permission_group_edited

Called directly after a permission group is edited in some way.


on_permission_string_imported

Called directly after a permission string is imported.


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_clicked_gps_tag

Called when a player clicks a gps tag


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.


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_flushed_fluid

Called after player flushed fluid


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_reverse_selected_area

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


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


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_player_used_spider_remote

Called when a player uses spidertron remote to send a spidertron to a given position


on_post_entity_died

Called after an entity dies.


on_pre_build

Called when players uses an item to build something.


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_ghost_upgraded

Called before a ghost entity is upgraded.


on_pre_permission_group_deleted

Called directly before a permission group is deleted.


on_pre_permission_string_imported

Called directly before a permission string is imported.


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_player_toggled_map_editor

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


on_pre_robot_exploded_cliff

Called directly before a robot explodes cliffs.


on_pre_script_inventory_resized

Called just before a script inventory is resized.


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_research_cancelled

Called when research is cancelled.


on_research_finished

Called when a research finishes.


on_research_reversed

Called when a research is reversed (unresearched).


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_inventory_resized

Called just after a script inventory is resized.



on_script_trigger_effect

Called when a script trigger effect is triggered.


on_sector_scanned

Called when an entity of type radar finishes scanning a sector.


on_selected_entity_changed

Called after the selected entity changes for a given player.


on_spider_command_completed

Called when a spider finishes moving to its autopilot position.


on_string_translated

Called when a translation request generated through LuaPlayer::request_translation is translated.


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_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_group_finished_gathering

Called when a unit group finishes gathering and starts executing its command.


on_unit_removed_from_group

Called when a unit is removed from a unit group.


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.


script_raised_destroy

A static event mods can use to tell other mods they destroyed something by script.


script_raised_revive

A static event mods can use to tell other mods they revived something by script.


script_raised_set_tiles

A static event mods can use to tell other mods they changed tiles on a surface by script.

CustomInputEvent

Called when a CustomInput is activated.

player_index
:: uint

The player that activated the custom input.


input_name
:: string

The prototype name of the custom input that was activated.


cursor_position

The mouse cursor position when the custom input was activated.


selected_prototype

Information about the prototype that is selected when the custom input is used. Needs to be enabled on the custom input's prototype. nil if none is selected.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_ai_command_completed

Called when a unit/group completes a command.

unit_number
:: uint

unit_number/group_number of the unit/group which just completed a command.



was_distracted
:: boolean

Was this command generated by a distraction.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_area_cloned

Called when an area of the map is cloned.

source_surface

source_area

destination_surface

destination_area

destination_force
:: LuaForce?

clone_tiles
:: boolean

clone_entities
:: boolean

clone_decoratives
:: boolean

clear_destination_entities
:: boolean

clear_destination_decoratives
:: boolean

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_biter_base_built

Called when a biter migration builds a base.

entity

The entity that was built.


name

Identifier of the event


tick
:: uint

Tick the event was generated.

Note

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.

source_offset

destination_offset

source_surface

source_positions
:: array[TilePosition]

destination_surface

destination_force
:: LuaForce?

clone_tiles
:: boolean

clone_entities
:: boolean

clone_decoratives
:: boolean

clear_destination_entities
:: boolean

clear_destination_decoratives
:: boolean

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_build_base_arrived

Called when a defines.command.build_base command reaches its destination, and before building starts.

unit
:: LuaEntity?

The unit the command was assigned to.


group

The unit group the command was assigned to.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_built_entity

Called when player builds something. Can be filtered using LuaPlayerBuiltEntityEventFilter.

created_entity

player_index
:: uint

stack

item

The item prototype used to build the entity. Note this won't exist in some situations (built from blueprint, undo, etc).


tags
:: Tags?

The tags associated with this entity if any.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_cancelled_deconstruction

Called when the deconstruction of an entity is canceled. Can be filtered using LuaEntityDeconstructionCancelledEventFilter.

entity

player_index
:: uint?

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_cancelled_upgrade

Called when the upgrade of an entity is canceled. Can be filtered using LuaUpgradeCancelledEventFilter.

entity

player_index
:: uint?

target

direction

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_character_corpse_expired

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

corpse

The corpse.


name

Identifier of the event


tick
:: uint

Tick the event was generated.

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.


force

player_index
:: uint?

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_chart_tag_modified

Called when a chart tag is modified by a player.


player_index
:: uint?

force

old_text
:: string

old_icon
:: SignalID?

old_player
:: uint?

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_chart_tag_removed

Called just before a chart tag is deleted.


force

player_index
:: uint?

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_chunk_charted

Called when a chunk is charted or re-charted.

surface_index
:: uint

position

area

Area of the chunk.


force

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_chunk_deleted

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

surface_index
:: uint

positions
:: array[ChunkPosition]

The chunks deleted.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_chunk_generated

Called when a chunk is generated.

area

Area of the chunk.


position

Position of the chunk.


surface

The surface the chunk is on.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_combat_robot_expired

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

robot

owner
:: LuaEntity?

The entity that owns the robot if any.


name

Identifier of the event


tick
:: uint

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.

player_index
:: uint?

The player doing the chatting, if any.


message
:: string

The chat message that was sent.


name

Identifier of the event


tick
:: uint

Tick the event was generated.

Note

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.

player_index
:: uint?

The player if any.


command
:: string

The command as typed without the preceding forward slash ('/').


parameters
:: string

The parameters provided if any.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_cutscene_cancelled

Called when a cutscene is cancelled by the player or by script.

player_index
:: uint

The player the cutscene was shown to.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


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.

player_index
:: uint

The player index of the player viewing the cutscene.


waypoint_index
:: uint

The index of the waypoint we just completed.


name

Identifier of the event


tick
:: uint

Tick the event was generated.

Note

Due to implementation omission, waypoint_index is 0-based.


on_difficulty_settings_changed

Called when the map difficulty settings are changed.

old_recipe_difficulty
:: uint

old_technology_difficulty
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.

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. Can be filtered for the source entity using LuaEntityClonedEventFilter.

source

destination

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_entity_damaged

Called when an entity is damaged. Can be filtered using LuaEntityDamagedEventFilter.

entity

damage_type

original_damage_amount
:: float

The damage amount before resistances.


final_damage_amount
:: float

The damage amount after resistances.


final_health
:: float

The health of the entity after the damage was applied.


cause
:: LuaEntity?

The entity that did the attacking if available.


force
:: LuaForce?

The force that did the attacking if any.


name

Identifier of the event


tick
:: uint

Tick the event was generated.

Note

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.

registration_number
:: uint64

The number returned by register_on_entity_destroyed to uniquely identify this entity during this event.


unit_number
:: uint?

The LuaEntity::unit_number of the destroyed entity, if it had one.


name

Identifier of the event


tick
:: uint

Tick the event was generated.

Note

Depending on when a given entity is destroyed, this event will be fired at the end of the current tick or at the end of the next tick.


on_entity_died

Called when an entity dies. Can be filtered using LuaEntityDiedEventFilter.

entity

The entity that died.


cause
:: LuaEntity?

The entity that did the killing if available.


loot

The loot generated by this entity if any.


force
:: LuaForce?

The force that did the killing if any.


damage_type

The damage type if any.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_entity_logistic_slot_changed

Called when one of an entity's personal logistic slots changes.

player_index
:: uint?

The player who changed the slot, or nil if changed by script.


entity

The entity for whom a logistic slot was changed.


slot_index
:: uint

The slot index that was changed.


name

Identifier of the event


tick
:: uint

Tick the event was generated.

Note

"Personal logistic slot" refers to a character or vehicle's personal request / auto-trash slots, not the request slots on logistic chests.


on_entity_renamed

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

player_index
:: uint?

If by_script is true this will not be included.


by_script
:: boolean

entity

old_name
:: string

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_entity_settings_pasted

Called after entity copy-paste is done.

player_index
:: uint

source

The source entity settings were copied from.


destination

The destination entity settings were copied to.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_entity_spawned

Called when an entity is spawned by a EnemySpawner

spawner

entity

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_equipment_inserted

Called after equipment is inserted into an equipment grid.

grid

The equipment grid inserted into.


equipment

The equipment inserted.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_equipment_removed

Called after equipment is removed from an equipment grid.

grid

The equipment grid removed from.


equipment
:: string

The equipment removed.


count
:: uint

The count of equipment removed.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_force_cease_fire_changed

Called when the a forces cease fire values change.

force

The force who's cease fire changed.


other_force

Which force was added or removed.


added
:: boolean

If the other force was added or removed.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_force_created

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

force

The newly created force.


name

Identifier of the event


tick
:: uint

Tick the event was generated.

Note

This is not called when the default forces ('player', 'enemy', 'neutral') are created as they will always exist.


on_force_friends_changed

Called when the a forces friends change.

force

The force who's friends changed.


other_force

Which force was added or removed.


added
:: boolean

If the other force was added or removed.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_force_reset

Called when LuaForce::reset is finished.

force

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_forces_merged

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

source_name
:: string

The force destroyed.


source_index
:: uint

The index of the destroyed force.


destination

The force entities where reassigned to.


name

Identifier of the event


tick
:: uint

Tick the event was generated.

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

source

The force to be destroyed


destination

The force to reassign entities to.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


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.

name

Identifier of the event


tick
:: uint

Tick the event was generated.

Note

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

element

The element whose checked state changed.


player_index
:: uint

The player who did the change.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_gui_click

Called when LuaGuiElement is clicked.

element

The clicked element.


player_index
:: uint

The player who did the clicking.


button

The mouse button used if any.


alt
:: boolean

If alt was pressed.


control
:: boolean

If control was pressed.


shift
:: boolean

If shift was pressed.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_gui_closed

Called when the player closes the GUI they have open.

This can only be raised when the GUI's player controller is still valid. If a GUI is thus closed due to the player disconnecting, dying, or becoming a spectator in other ways, it won't cause this event to be raised.

player_index
:: uint

The player.


gui_type

The GUI type that was open.


entity
:: LuaEntity?

The entity that was open


item

The item that was open


equipment

The equipment that was open


other_player
:: LuaPlayer?

The other player that was open


element

The custom GUI element that was open


technology

The technology that was automatically selected when opening the research GUI


tile_position

The tile position that was open


inventory

The script inventory that was open


name

Identifier of the event


tick
:: uint

Tick the event was generated.

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 a LuaGuiElement is confirmed, for example by pressing Enter in a textfield.

element

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.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_gui_elem_changed

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

element

The element whose element value changed.


player_index
:: uint

The player who did the change.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_gui_location_changed

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

element

The element whose location changed.


player_index
:: uint

The player who did the change.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_gui_opened

Called when the player opens a GUI.

player_index
:: uint

The player.


gui_type

The GUI type that was opened.


entity
:: LuaEntity?

The entity that was opened


item

The item that was opened


equipment

The equipment that was opened


other_player
:: LuaPlayer?

The other player that was opened


element

The custom GUI element that was opened


inventory

The script inventory that was opened


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_gui_selected_tab_changed

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

element

The tabbed pane whose selected tab changed.


player_index
:: uint

The player who did the change.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_gui_selection_state_changed

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

element

The element whose selection state changed.


player_index
:: uint

The player who did the change.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_gui_switch_state_changed

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

element

The switch whose switch state changed.


player_index
:: uint

The player who did the change.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_gui_text_changed

Called when LuaGuiElement text is changed by the player.

element

The edited element.


player_index
:: uint

The player who did the edit.


text
:: string

The new text in the element.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_gui_value_changed

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

element

The element whose value changed.


player_index
:: uint

The player who did the change.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_land_mine_armed

Called when a land mine is armed.

mine

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_lua_shortcut

Called when a custom Lua shortcut is pressed.

player_index
:: uint

prototype_name
:: string

Shortcut prototype name of the shortcut that was clicked.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_marked_for_deconstruction

Called when an entity is marked for deconstruction with the Deconstruction planner or via script. Can be filtered using LuaEntityMarkedForDeconstructionEventFilter.

entity

player_index
:: uint?

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_marked_for_upgrade

Called when an entity is marked for upgrade with the Upgrade planner or via script. Can be filtered using LuaEntityMarkedForUpgradeEventFilter.

entity

target

player_index
:: uint?

direction

The new direction (if any)


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_market_item_purchased

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

player_index
:: uint

The player who did the purchasing.


market

The market entity.


offer_index
:: uint

The index of the offer purchased.


count
:: uint

The amount of offers purchased.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_mod_item_opened

Called when the player uses the 'Open item GUI' control on an item defined with the 'mod-openable' flag

player_index
:: uint

The player.


item

The item clicked on.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_permission_group_added

Called directly after a permission group is added.

player_index
:: uint

The player that added the group.


group

The group added.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_permission_group_deleted

Called directly after a permission group is deleted.

player_index
:: uint

The player doing the deletion.


group_name
:: string

The group that was deleted.


id
:: uint

The group id that was deleted.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_permission_group_edited

Called directly after a permission group is edited in some way.

player_index
:: uint

The player that did the editing.


group

The group being edited.


type
:: string

The edit type: "add-permission", "remove-permission", "enable-all", "disable-all", "add-player", "remove-player", "rename".


action

The action when the type is "add-permission" or "remove-permission".


other_player_index
:: uint

The other player when the type is "add-player" or "remove-player".


old_name
:: string

The old group name when the type is "rename".


new_name
:: string

The new group name when the type is "rename".


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_permission_string_imported

Called directly after a permission string is imported.

player_index
:: uint

The player that imported the string.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_picked_up_item

Called when a player picks up an item.

item_stack

player_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_alt_selected_area

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

player_index
:: uint

The player doing the selection.


surface

The surface selected.


area

The area selected.


item
:: string

The item used to select the area.


entities
:: array[LuaEntity]

The entities selected.


tiles
:: array[LuaTile]

The tiles selected.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_ammo_inventory_changed

Called after a players ammo inventory changed in some way.

player_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_armor_inventory_changed

Called after a players armor inventory changed in some way.

player_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_banned

Called when a player is banned.

player_index
:: uint?

The player banned.


player_name
:: string

The banned player name.


by_player
:: uint?

The player that did the banning if any.


reason
:: string?

The reason given if any.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_built_tile

Called after a player builds tiles.

player_index
:: uint

surface_index
:: uint

The surface the tile(s) were built on.


tiles
:: array[OldTileAndPosition]

The position data.


tile

The tile prototype that was placed.


item

The item type used to build the tiles


stack

The stack used to build the tiles (may be empty if all of the items where used to build the tiles).


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_cancelled_crafting

Called when a player cancels crafting.

player_index
:: uint

The player that did the crafting.


items

The crafting items returned to the player's inventory.


recipe

The recipe that has been cancelled.


cancel_count
:: uint

The number of crafts that have been cancelled.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_changed_force

Called after a player changes forces.

player_index
:: uint

The player who changed forces.


force

The old force.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_changed_position

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

player_index
:: uint

The player.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_changed_surface

Called after a player changes surfaces.

player_index
:: uint

The player who changed surfaces.


surface_index
:: uint

The surface index the player was on.


name

Identifier of the event


tick
:: uint

Tick the event was generated.

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.

player_index
:: uint

The player.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_cheat_mode_enabled

Called when cheat mode is enabled on a player.

player_index
:: uint

The player.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_clicked_gps_tag

Called when a player clicks a gps tag

player_index
:: uint

Index of the player


position

Map position contained in gps tag


surface
:: string

Surface name contained in gps tag, even when such surface does not exists


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_configured_blueprint

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

player_index
:: uint

The player.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_configured_spider_remote

Called when a player configures spidertron remote to be connected with a given spidertron

player_index
:: uint

The player that configured the remote.


vehicle

Spider vehicle to which remote was connected to.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


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

item_stack

The item that has been crafted.


player_index
:: uint

The player doing the crafting.


recipe

The recipe used to craft this item.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_created

Called after the player was created.

player_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_cursor_stack_changed

Called after a players cursorstack changed in some way.

player_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_deconstructed_area

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

player_index
:: uint

The player doing the selection.


surface

The surface selected.


area

The area selected.


item
:: string

The item used to select the area.


alt
:: boolean

If normal selection or alt selection was used.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_demoted

Called when a player is demoted.

player_index
:: uint

The player.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_died

Called after a player dies.

player_index
:: uint

cause
:: LuaEntity?

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_display_resolution_changed

Called when the display resolution changes for a given player.

player_index
:: uint

The player


old_resolution

The old display resolution


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_display_scale_changed

Called when the display scale changes for a given player.

player_index
:: uint

The player


old_scale
:: double

The old display scale


name

Identifier of the event


tick
:: uint

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.

player_index
:: uint

entity
:: LuaEntity?

The vehicle if any.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_dropped_item

Called when a player drops an item on the ground.

player_index
:: uint

entity

The item-on-ground entity.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_fast_transferred

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

player_index
:: uint

The player transferred from or to.


entity

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.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_flushed_fluid

Called after player flushed fluid

player_index
:: uint

Index of the player


fluid
:: string

Name of a fluid that was flushed


amount
:: double

Amount of fluid that was removed


entity

Entity from which flush was performed


only_this_entity
:: boolean

True if flush was requested only on this entity


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_gun_inventory_changed

Called after a players gun inventory changed in some way.

player_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_joined_game

Called after a player joins the game. This is not called when loading a save file in singleplayer, as the player doesn't actually leave the game, and the save is just on pause until they rejoin.

player_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_kicked

Called when a player is kicked.

player_index
:: uint

The player kicked.


by_player
:: uint?

The player that did the kicking if any.


reason
:: string?

The reason given if any.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_left_game

Called after a player leaves the game. This is not called when closing a save file in singleplayer, as the player doesn't actually leave the game, and the save is just on pause until they rejoin.

player_index
:: uint


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_main_inventory_changed

Called after a players main inventory changed in some way.

player_index
:: uint

name

Identifier of the event


tick
:: uint

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.

player_index
:: uint

The index of the player doing the mining.


entity

The entity that has been mined.


buffer

The temporary inventory that holds the result of mining the entity.


name

Identifier of the event


tick
:: uint

Tick the event was generated.

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.

item_stack

The item given to the player


player_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_mined_tile

Called after a player mines tiles.

player_index
:: uint

surface_index
:: uint

The surface the tile(s) were mined from.


tiles
:: array[OldTileAndPosition]

The position data.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_muted

Called when a player is muted.

player_index
:: uint

The player.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_pipette

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

player_index
:: uint

The player


item

The item put in the cursor


used_cheat_mode
:: boolean

If cheat mode was used to give a free stack of the item.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_placed_equipment

Called after the player puts equipment in an equipment grid

player_index
:: uint

equipment

The equipment put in the equipment grid.


grid

The equipment grid the equipment was put in.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_promoted

Called when a player is promoted.

player_index
:: uint

The player.


name

Identifier of the event


tick
:: uint

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.

player_index
:: uint

The player index that was removed


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_removed_equipment

Called after the player removes equipment from an equipment grid

player_index
:: uint

grid

The equipment grid removed from.


equipment
:: string

The equipment removed.


count
:: uint

The count of equipment removed.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_repaired_entity

Called when a player repairs an entity. Can be filtered using LuaPlayerRepairedEntityEventFilter.

player_index
:: uint

entity

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_respawned

Called after a player respawns.

player_index
:: uint

player_port
:: LuaEntity?

The player port used to respawn if one was used.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_reverse_selected_area

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

player_index
:: uint

The player doing the selection.


surface

The surface selected.


area

The area selected.


item
:: string

The item used to select the area.


entities
:: array[LuaEntity]

The entities selected.


tiles
:: array[LuaTile]

The tiles selected.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


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.

entity

The rotated entity.


previous_direction

The previous direction


player_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_selected_area

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

player_index
:: uint

The player doing the selection.


surface

The surface selected.


area

The area selected.


item
:: string

The item used to select the area.


entities
:: array[LuaEntity]

The entities selected.


tiles
:: array[LuaTile]

The tiles selected.


name

Identifier of the event


tick
:: uint

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

player_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_setup_blueprint

Called when a player selects an area with a blueprint.

player_index
:: uint

The player doing the selection.


surface

The surface selected.


area

The area selected.


item
:: string

The item used to select the area.


alt
:: boolean

If normal selection or alt selection was used.


mapping
:: LuaLazyLoadedValue(dictionary[uintLuaEntity])

The blueprint entity index to source entity mapping. Note: if any mod changes the blueprint this will be incorrect.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_toggled_alt_mode

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

player_index
:: uint

alt_mode
:: boolean

The new alt mode value. This value is a shortcut for accessing GameViewSettings::show_entity_info on the player.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_toggled_map_editor

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

player_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_trash_inventory_changed

Called after a players trash inventory changed in some way.

player_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_unbanned

Called when a player is un-banned.

player_index
:: uint?

The player un-banned.


player_name
:: string

The player name un-banned.


by_player
:: uint?

The player that did the un-banning if any.


reason
:: string?

The reason the player was banned if any.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_unmuted

Called when a player is unmuted.

player_index
:: uint

The player.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_player_used_capsule

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

player_index
:: uint

The player.


item

The capsule item used.


position

The position the capsule was used.


name

Identifier of the event


tick
:: uint

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

player_index
:: uint

The player that used the remote.


vehicle

Spider vehicle which was requested to move.


position

Goal position to which spidertron was sent to.


success
:: boolean

If the use was successful. It may fail when spidertron has different driver or when player is on different surface.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_post_entity_died

Called after an entity dies. Can be filtered using LuaPostEntityDiedEventFilter.

ghost
:: LuaEntity?

The ghost created by the entity dying if any.


force
:: LuaForce?

The force that did the killing if any.


position

Position where the entity died.


prototype

The entity prototype of the entity that died.


damage_type

The damage type if any.


corpses
:: array[LuaEntity]

The corpses created by the entity dying if any.


surface_index
:: uint

The surface the entity was on.


unit_number
:: uint?

The unit number the entity had if any.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_pre_build

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

player_index
:: uint

The player who did the placing.


position

Where the item was placed.


shift_build
:: boolean

Item was placed using shift building.


direction

The direction the item was facing when placed.


flip_horizontal
:: boolean

If building this blueprint was flipped horizontally.


flip_vertical
:: boolean

If building this blueprint was flipped vertically.


created_by_moving
:: boolean

Item was placed while moving.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_pre_chunk_deleted

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

surface_index
:: uint

positions
:: array[ChunkPosition]

The chunks to be deleted.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_pre_entity_settings_pasted

Called before entity copy-paste is done.

player_index
:: uint

source

The source entity settings will be copied from.


destination

The destination entity settings will be copied to.


name

Identifier of the event


tick
:: uint

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.

player_index
:: uint?

The player that did the deconstruction if any.


ghost

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_pre_ghost_upgraded

Called before a ghost entity is upgraded. Can be filtered using LuaPreGhostUpgradedEventFilter.

player_index
:: uint?

The player that did the upgrade if any.


ghost

target

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_pre_permission_group_deleted

Called directly before a permission group is deleted.

player_index
:: uint

The player doing the deletion.


group

The group to be deleted.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_pre_permission_string_imported

Called directly before a permission string is imported.

player_index
:: uint

The player importing the string.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_pre_player_crafted_item

Called when a player queues something to be crafted.

player_index
:: uint

The player doing the crafting.


recipe

The recipe being queued.


items

The items removed from the players inventory to do the crafting.


queued_count
:: uint

The number of times the recipe is being queued.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_pre_player_died

Called before a players dies.

player_index
:: uint

cause
:: LuaEntity?

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_pre_player_left_game

Called before a player leaves the game.

player_index
:: uint


name

Identifier of the event


tick
:: uint

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.

entity

The entity being mined


player_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


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.

player_index
:: uint

The player index that will be removed


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_pre_player_toggled_map_editor

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

player_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_pre_robot_exploded_cliff

Called directly before a robot explodes cliffs.

robot

cliff

item

The cliff explosive used.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_pre_script_inventory_resized

Called just before a script inventory is resized.

player_index
:: uint?

If done by console command; the player who ran the command.


mod
:: string

The mod that did the resizing. This will be "core" if done by console command or scenario script.


inventory

old_size
:: uint

The old inventory size.


new_size
:: uint

The new inventory size.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_pre_surface_cleared

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

surface_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_pre_surface_deleted

Called just before a surface is deleted.

surface_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_research_cancelled

Called when research is cancelled.

research
:: dictionary[stringuint]

A mapping of technology name to how many times it was cancelled.


force

The force whose research was cancelled.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_research_finished

Called when a research finishes.

research

The researched technology


by_script
:: boolean

If the technology was researched by script.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_research_reversed

Called when a research is reversed (unresearched).

research

The technology un-researched


by_script
:: boolean

If the technology was un-researched by script.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_research_started

Called when a technology research starts.

research

The technology being researched


last_research

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_resource_depleted

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

entity

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_robot_built_entity

Called when a construction robot builds an entity. Can be filtered using LuaRobotBuiltEntityEventFilter.

robot

The robot that did the building.


created_entity

The entity built.


stack

The item used to do the building.


tags
:: Tags?

The tags associated with this entity if any.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_robot_built_tile

Called after a robot builds tiles.

robot

The robot.


tiles
:: array[OldTileAndPosition]

The position data.


tile

The tile prototype that was placed.


item

The item type used to build the tiles.


stack

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.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_robot_exploded_cliff

Called directly after a robot explodes cliffs.

robot

item

The cliff explosive used.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_robot_mined

Called when a robot mines an entity.

robot

The robot that did the mining.


item_stack

The entity the robot just picked up.


name

Identifier of the event


tick
:: uint

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.

robot

The robot doing the mining.


entity

The entity that has been mined.


buffer

The temporary inventory that holds the result of mining the entity.


name

Identifier of the event


tick
:: uint

Tick the event was generated.

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.

robot

The robot.


tiles
:: array[OldTileAndPosition]

The position data.


surface_index
:: uint

The surface the tile(s) were mined on.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_robot_pre_mined

Called before a robot mines an entity. Can be filtered using LuaPreRobotMinedEntityEventFilter.

robot

The robot that's about to do the mining.


entity

The entity which is about to be mined.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_rocket_launch_ordered

Called when a rocket silo is ordered to be launched.

rocket

rocket_silo

player_index
:: uint?

The player that is riding the rocket, if any.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_rocket_launched

Called when the rocket is launched.

rocket

rocket_silo
:: LuaEntity?

player_index
:: uint?

The player that is riding the rocket, if any.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_runtime_mod_setting_changed

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

player_index
:: uint?

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.


setting
:: string

The prototype name of the setting that was changed.


setting_type
:: string

Either "runtime-per-user" or "runtime-global".


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_script_inventory_resized

Called just after a script inventory is resized.

player_index
:: uint?

If done by console command; the player who ran the command.


mod
:: string

The mod that did the resizing. This will be "core" if done by console command or scenario script.


inventory

old_size
:: uint

The old inventory size.


new_size
:: uint

The new inventory size.


overflow_inventory

Any items which didn't fit into the new inventory size.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_script_path_request_finished

Called when a LuaSurface::request_path call completes.

path
:: array[PathfinderWaypoint]?

The actual path that the pathfinder has determined. nil if pathfinding failed.


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 that you can retry later.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_script_trigger_effect

Called when a script trigger effect is triggered.

effect_id
:: string

The effect_id specified in the trigger effect.


surface_index
:: uint

The surface the effect happened on.


source_position

source_entity
:: LuaEntity?

target_position

target_entity
:: LuaEntity?

name

Identifier of the event


tick
:: uint

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.

radar

The radar that did the scanning.


chunk_position

The chunk scanned.


area

Area of the scanned chunk.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_selected_entity_changed

Called after the selected entity changes for a given player.

player_index
:: uint

The player whose selected entity changed.


last_entity
:: LuaEntity?

The last selected entity if it still exists and there was one.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_spider_command_completed

Called when a spider finishes moving to its autopilot position.

vehicle

Spider vehicle which was requested to move.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_string_translated

Called when a translation request generated through LuaPlayer::request_translation is translated.

player_index
:: uint

The player whose locale was used for the translation.


localised_string

The localised string being translated.


result
:: string

The translated localised_string.


translated
:: boolean

Whether the requested localised string was valid and could be translated.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_surface_cleared

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

surface_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_surface_created

Called when a surface is created.

surface_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.

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.

surface_index
:: uint

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_surface_imported

Called after a surface is imported.

surface_index
:: uint

original_name
:: string

The original surface name.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_surface_renamed

Called when a surface is renamed.

surface_index
:: uint

old_name
:: string

new_name
:: string

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_technology_effects_reset

Called when LuaForce::reset_technology_effects is finished.

force

name

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.

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_train_changed_state

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

train

old_state

name

Identifier of the event


tick
:: uint

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.

train

old_train_id_1
:: uint?

The first old train id when splitting/merging trains.


old_train_id_2
:: uint?

The second old train id when splitting/merging trains.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_train_schedule_changed

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

train

player_index
:: uint?

The player who made the change if any.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


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

entity

source
:: LuaEntity?

name

Identifier of the event


tick
:: uint

Tick the event was generated.


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

entity

source
:: LuaEntity?

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_unit_added_to_group

Called when a unit is added to a unit group.

unit

group

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_unit_group_created

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

group

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_unit_group_finished_gathering

Called when a unit group finishes gathering and starts executing its command.

group

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_unit_removed_from_group

Called when a unit is removed from a unit group.

unit

group

name

Identifier of the event


tick
:: uint

Tick the event was generated.


on_worker_robot_expired

Called when a worker (construction or logistic) robot expires through a lack of energy.

robot

name

Identifier of the event


tick
:: uint

Tick the event was generated.


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.

entity

The entity that has been built.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


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.

entity

The entity that was destroyed.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


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.

entity

The entity that was revived.


tags
:: Tags?

The tags associated with this entity, if any.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


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.

surface_index
:: uint

The surface whose tiles were changed.


tiles
:: array[Tile]

The tiles that were changed.


name

Identifier of the event


tick
:: uint

Tick the event was generated.


|<

Classes

Events

Concepts

Defines

Builtin types

>|