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, three 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:
LuaBootstrap Entry point for registering event handlers.
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.
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.
LuaGroup Item group or subgroup.
LuaGui The root of the GUI.
LuaGuiElement An element of the custom GUI.
LuaInventory A storage of item stacks.
LuaItemPrototype Prototype of an item.
LuaItemStack An item and a count.
LuaLogisticCell Logistic cell of a particular LuaEntity.
LuaLogisticNetwork A single logistic network of a given force on a given surface.
LuaPlayer A player in the game.
LuaRecipe A crafting recipe.
LuaRemote Registry of interfaces between scripts.
LuaStyle Style of a GUI element.
LuaSurface A "domain" of the world.
LuaTechnology One research item.
LuaTile A single "square" on the map.
LuaTrain A train.
LuaTransportLine One line on a transport belt.
LuaUnitGroup A collection of units moving and attacking together.


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 ipairs(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:
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_entity_died Called when an entity dies.
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_click Called when LuaGuiElement is clicked.
on_marked_for_deconstruction Called when an entity is marked for deconstruction with the Deconstruction planner or via script.
on_picked_up_item Called when a player picks up an item.
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_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_mined_item Called when the player mines something.
on_player_rotated_entity Called when the player rotates an entity (including some non-obvious rotations such as with the stone furnace, but not the solar-panel).
on_preplayer_mined_item Called when the player starts mining something.
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_mined Called when a robot mines an entity.
on_robot_pre_mined Called before a robot mines an entity.
on_rocket_launched Called when the rocket is launched.
on_sector_scanned Called when the radar finishes scanning a sector.
on_train_changed_state Called when a train changes state (started to stopped and vice versa)
on_trigger_created_entity Called when an entity with a trigger prototype (such as capsules) create an entity AND that trigger prototype defined trigger_createdentity="true".

Other types

The API will expect and provide certain types of information -- such as positions or crafting ingredients in a specific format. You can read about these types here.