All of the API functionality is implemented via class members. To make any use of the API, therefore, you need to have access to instances of these classes. To facilitate that, these global objects are provided:
local first_player = game.players[1]
first_player.print(first_player.name)
You can browse the overview of Factorio classes or view the documentation for a particular class in the list below:
LuaAISettings | Collection of settings for overriding default ai behavior |
LuaAccumulatorControlBehavior | Control behavior for accumulators. |
LuaAmmoCategoryPrototype | Prototype of a ammo category. |
LuaArithmeticCombinatorControlBehavior | Control behavior for arithmetic combinators. |
LuaAutoplaceControlPrototype | Prototype of an autoplace control. |
LuaBootstrap | Entry point for registering event handlers. |
LuaBurner | A reference to the burner energy source owned by a specific LuaEntity or LuaEquipment. |
LuaBurnerPrototype | Prototype of a burner energy source. |
LuaChunkIterator | A chunk iterator can be used for iterating chunks coordinates of a surface. |
LuaCircuitNetwork | A circuit network associated with a given entity, connector, and wire type. |
LuaCombinatorControlBehavior | |
LuaCommandProcessor | Custom game console commands. |
LuaConstantCombinatorControlBehavior | Control behavior for constant combinators. |
LuaContainerControlBehavior | Control behavior for container entities -- smart chests. |
LuaControl | This is an abstract base class containing the common functionality between LuaPlayer and character entities (see LuaEntity). |
LuaControlBehavior | The control behavior for an entity. |
LuaCustomChartTag | A custom tag that shows on the map view. |
LuaCustomInputPrototype | Prototype of a custom input. |
LuaCustomTable | Lazily evaluated table. |
LuaDamagePrototype | Prototype of a damage. |
LuaDeciderCombinatorControlBehavior | Control behavior for decider combinators. |
LuaDecorativePrototype | Prototype of an optimized decorative. |
LuaElectricEnergySourcePrototype | Prototype of an electric energy source. |
LuaEntity | The primary interface for interacting with entities through the Lua API. |
LuaEntityPrototype | Prototype of an entity. |
LuaEquipment | An item in one's power armour. |
LuaEquipmentGrid | An equipment grid is the inside of a power armour. |
LuaEquipmentGridPrototype | Prototype of an equipment grid. |
LuaEquipmentPrototype | Prototype of a modular equipment. |
LuaFlowStatistics | Encapsulates statistic data for different parts of the game. |
LuaFluidBox | An array of fluid boxes. |
LuaFluidBoxPrototype | A prototype of a fluidbox owned by some LuaEntityPrototype. |
LuaFluidPrototype | Prototype of a fluid. |
LuaForce | LuaForce encapsulates data local to each "force" or "faction" of the game. |
LuaGameScript | Main toplevel type, provides access to most of the API though its members. |
LuaGenericOnOffControlBehavior | An abstract base class for behaviors that support switching the entity on or off based on some condition. |
LuaGroup | Item group or subgroup. |
LuaGui | The root of the GUI. |
LuaGuiElement | An element of the custom GUI. |
LuaInserterControlBehavior | Control behavior for smart inserters. |
LuaInventory | A storage of item stacks. |
LuaItemPrototype | Prototype of an item. |
LuaItemStack | A reference to an item and count owned by some external entity. |
LuaLampControlBehavior | Control behavior for lamps. |
LuaLogisticCell | Logistic cell of a particular LuaEntity. |
LuaLogisticContainerControlBehavior | Control behavior for logistic chests. |
LuaLogisticNetwork | A single logistic network of a given force on a given surface. |
LuaLogisticPoint | Logistic point of a particular LuaEntity. |
LuaMiningDrillControlBehavior | Control behavior for mining drills. |
LuaModSettingPrototype | Prototype of a mod setting. |
LuaNoiseLayerPrototype | Prototype of a noise layer. |
LuaPermissionGroup | A permission group that defines what players in this group are allowed to do. |
LuaPermissionGroups | All permission groups. |
LuaPlayer | A player in the game. |
LuaProfiler | An object used to measure script performance. |
LuaProgrammableSpeakerControlBehavior | Control behavior for programmable speakers. |
LuaRCON | An interface to send messages to the calling RCON interface. |
LuaRailChainSignalControlBehavior | Control behavior for rail chain signals. |
LuaRailPath | A rail path. |
LuaRailSignalControlBehavior | Control behavior for rail signals. |
LuaRandomGenerator | A deterministic random generator independent from the core games random generator that can be seeded and re-seeded at will. |
LuaRecipe | A crafting recipe. |
LuaRecipePrototype | A crafting recipe prototype. |
LuaRemote | Registry of interfaces between scripts. |
LuaRendering | Allows rendering of geometric shapes, text and sprites in the game world. |
LuaRoboportControlBehavior | Control behavior for roboports. |
LuaSettings | Runtime settings can be changed through console commands and by the mod that owns the settings. |
LuaStorageTankControlBehavior | Control behavior for storage tanks. |
LuaStyle | Style of a GUI element. |
LuaSurface | A "domain" of the world. |
LuaTechnology | One research item. |
LuaTechnologyPrototype | A Technology prototype. |
LuaTile | A single "square" on the map. |
LuaTilePrototype | Prototype of a tile. |
LuaTrain | A train. |
LuaTrainStopControlBehavior | Control behavior for train stops. |
LuaTransportBeltControlBehavior | Control behavior for transport belts. |
LuaTransportLine | One line on a transport belt. |
LuaUnitGroup | A collection of units moving and attacking together. |
LuaVirtualSignalPrototype | Prototype of a virtual signal. |
LuaWallControlBehavior | Control behavior for walls. |
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 the event name.
script.on_event(defines.events.on_entity_died, function(event)
local recently_deceased_entity = event.entity
local time_of_death = event.tick
game.print("Let it be known that " .. recently_deceased_entity.name ..
" died a tragic death on tick " .. time_of_death)
end)
Here is a complete list of Factorio 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_elem_changed | Called when LuaGuiElement element value is changed (related to choose element buttons) |
on_gui_opened | Called when the player opens a GUI. |
on_gui_selection_state_changed | Called when LuaGuiElement selection state is changed (related to drop-downs) |
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_tool_inventory_changed | Called after a players tool inventory changed in some way. |
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. |
Other parts of the API:
defines
table, which contains symbolic constants used
throughout the API.global
: The global
dictionary, useful for storing data persistent across a save-load
cycle.