Factorio API


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:

This will print the first player's username, making use of the LuaGameScript::players array to gain access to players' information, and LuaPlayer::print to display a string in the player's game console.
local first_player = game.players[1]

You can browse the overview of Factorio classes or view the documentation for a particular class in the list below:

LuaAccumulatorControlBehavior Control behavior for accumulators.
LuaArithmeticCombinatorControlBehavior Control behavior for arithmetic combinators.
LuaBootstrap Entry point for registering event handlers.
LuaBurner A reference to the burner energy source owned by a specfic 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.
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.
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 a virtual signal.
LuaEquipmentPrototype Prototype of a modular equipment.
LuaFlowStatistics Encapsulates statistic data for different parts of the game.
LuaFluidBox An array of fluid boxes.
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.
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.
LuaProgrammableSpeakerControlBehavior Control behavior for programmable speakers.
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.
LuaRoboportControlBehavior Control behavior for roboports.
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

  for _, player in pairs(game.players) do
    player.print("Let it be known that " .. recently_deceased_entity.name ..
                 " died a tragic death on tick " .. time_of_death)

Here is a complete list of Factorio events:

All events Every event contains at least the name and tick attributes.
on_biter_base_built Called when a biter migration builds a base.
on_built_entity Called when player builds something.
on_canceled_deconstruction Called when the deconstruction of an entity is canceled.
on_chunk_generated Called when a chunk is generated.
on_difficulty_settings_changed Called when the map difficulty settings are changed.
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_force_created Called when a new force is created using game.create_force()
on_forces_merging Called when two forces are merged using game.merge_forces().
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_elem_changed Called when LuaGuiElement element value is changed (related to choose element buttons)
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_marked_for_deconstruction Called when an entity is marked for deconstruction with the Deconstruction planner or via script.
on_market_item_purchased Called after a player purchases some offer from a Market entity.
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_built_tile Called after a player builds tiles.
on_player_changed_force Called after a player changes forces.
on_player_changed_surface Called after a player changes surfaces.
on_player_crafted_item Called when the player crafts an item (upon 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_died Called after a player dies.
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_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_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_placed_equipment Called after the player puts equipment in an equipment grid
on_player_quickbar_inventory_changed Called after a players quickbar inventory changed in some way.
on_player_removed_equipment Called after the player removes equipment from an equipment grid
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_tool_inventory_changed Called after a players tool inventory changed in some way.
on_pre_entity_settings_pasted Called before entity copy-paste is done.
on_pre_player_died Called before a players dies.
on_pre_surface_deleted Called just before a surface is deleted.
on_preplayer_mined_item Called when the player finishes mining an entity, before the entity is removed from map.
on_put_item Called when players uses 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_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_launched Called when the rocket is launched.
on_runtime_mod_setting_changed Called when a runtime mod setting is changed by a player.
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_created Called when a surface is created.
on_surface_deleted Called after a surface is deleted.
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_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".


Other parts of the API: