Factorio API Docs

https://lua-api.factorio.com/stable/
Admin
Factorio API Docs is the reference documentation for creating Factorio mods using Lua, covering the...
Tokens:2,545,474
Snippets:44,314
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Recipe ID Examples

Source: https://lua-api.factorio.com/stable/prototype-api.json

Examples of valid RecipeID strings.

```lua
"electronic-circuit"
```

```lua
"kovarex-enrichment-process"
```

--------------------------------

### Module Category Example

Source: https://lua-api.factorio.com/stable/prototype-api.json

Examples of valid ModuleCategoryID strings.

```lua
"productivity"
```

```lua
"efficiency"
```

--------------------------------

### Lamp Prototype Configuration

Source: https://lua-api.factorio.com/stable/prototype-api.json

Example configuration for a 'small-lamp' prototype. This includes settings for energy usage, light intensity, color, and visual appearance when on and off.

```lua
{
  type = "lamp",
  name = "small-lamp",
  icon = "__base__/graphics/icons/small-lamp.png",
  flags = {"placeable-neutral", "player-creation"},
  fast_replaceable_group = "lamp",
  minable = {mining_time = 0.1, result = "small-lamp"},
  max_health = 100,
  corpse = "lamp-remnants",
  dying_explosion = "lamp-explosion",
  collision_box = {{-0.15, -0.15}, {0.15, 0.15}},
  selection_box = {{-0.5, -0.5}, {0.5, 0.5}},
  damaged_trigger_effect = hit_effects.entity(),
  impact_category = "glass",
  open_sound = {filename = "__base__/sound/open-close/electric-small-open.ogg", volume = 0.7},
  close_sound = {filename = "__base__/sound/open-close/electric-small-close.ogg", volume = 0.7},
  energy_source =
  {
    type = "electric",
    usage_priority = "lamp"
  },
  energy_usage_per_tick = "5kW",
  darkness_for_all_lamps_on = 0.5,
  darkness_for_all_lamps_off = 0.3,
  light = {intensity = 0.9, size = 40, color = {1, 1, 0.75}},
  light_when_colored = {intensity = 0, size = 6, color = {1, 1, 0.75}},
  glow_size = 6,
  glow_color_intensity = 1,
  glow_render_mode = "multiplicative",
  picture_off =
  {
    layers =
    {
      {
        filename = "__base__/graphics/entity/small-lamp/lamp.png",
        priority = "high"
      }
    }
  }
}
```

--------------------------------

### Get Starting Area Radius

Source: https://lua-api.factorio.com/stable/runtime-api.json

Returns the radius of the starting area for the surface. This is typically where players begin.

```lua
game.surfaces[1].get_starting_area_radius()
```

--------------------------------

### FluidBox Configuration Example

Source: https://lua-api.factorio.com/stable/types/FluidBox.html

This example demonstrates how to configure a fluid box with volume, pipe covers, connections, production type, and filter.

```lua
fluid_box =
{
  volume = 200,
  pipe_covers = pipecoverspictures(),
  pipe_connections =
  {
    {flow_direction = "input-output", direction = defines.direction.west, position = {-1, 0.5}},
    {flow_direction = "input-output", direction = defines.direction.east, position = {1, 0.5}}
  },
  production_type = "input-output",
  filter = "water"
}

```

--------------------------------

### get_starting_area_radius

Source: https://lua-api.factorio.com/stable/classes/LuaSurface.html

Gets the starting area radius of this surface.

```APIDOC
## get_starting_area_radius()

### Description
Gets the starting area radius of this surface.

### Return values
* **double** - The starting area radius.

### Method
Not applicable (Lua function call)
```

--------------------------------

### from

Source: https://lua-api.factorio.com/stable/classes/LuaRenderObject.html

Gets or sets the starting point for a line render object.

```APIDOC
## from

### Description
Where this line is drawn from.

### Type
Read|Write ScriptRenderTarget

### Notes
_Can only be used if this is Line_
```

--------------------------------

### Energy Specification Examples

Source: https://lua-api.factorio.com/stable/types/Energy.html

Examples demonstrating how to specify energy values for buffer capacity and input flow limits. It also shows equivalent power consumption representations.

```lua
buffer_capacity = "5MJ"
input_flow_limit = "300W"
-- the following two lines result in the same power consumption:
energy_usage = "60W"
energy_usage = "1J" -- not recommended, Watt is convention for power
```

--------------------------------

### get_rail_segment_stop

Source: https://lua-api.factorio.com/stable/classes/LuaEntity.html

Gets the train stop at the start or end of the rail segment this rail is in.

```APIDOC
## get_rail_segment_stop

### Description
Get train stop at the start/end of the rail segment this rail is in.

### Parameters
- **direction** (defines.direction): The direction to check (start or end).

### Returns
- LuaEntity?: The train stop entity, or nil.
```

--------------------------------

### Factorio Electronic Circuit Recipe Example

Source: https://lua-api.factorio.com/stable/auxiliary/item-weight.html

Illustrates the ingredients and their weights for the electronic circuit recipe, and the recipe's product count. This is used to calculate the initial recipe weight and product count for the item's weight determination.

```lua
-- electronic circuit recipe ingredients and weights
ingredients = {
    {type = "item", name = "iron-plate", amount = 1},  -- weight of 1000
    {type = "item", name = "copper-cable", amount = 3}  -- weight of 250
}
-- the recipe's weight is thus: 1 * 1000 + 3 * 250 = 1750

-- electronic circuit recipe products
results = { {type="item", name="electronic-circuit", amount=1} }
-- the recipe's product count is thus 1
```

--------------------------------

### get_rail_segment_signal

Source: https://lua-api.factorio.com/stable/classes/LuaEntity.html

Gets the rail signal at the start or end of the rail segment this rail is in.

```APIDOC
## get_rail_segment_signal

### Description
Get the rail signal at the start/end of the rail segment this rail is in.

### Parameters
- **direction** (defines.direction): The direction to check (start or end).
- **in_else_out** (boolean): True to get the incoming signal, false for the outgoing signal.

### Returns
- LuaEntity?: The rail signal entity, or nil.
```

--------------------------------

### Mod Path Example

Source: https://lua-api.factorio.com/stable/prototype-api.json

Demonstrates how to reference files within the base mod or other active mods using the `__<mod-name>__` placeholder.

```lua
filename = "__base__/graphics/entity/accumulator/accumulator.png"
```

```lua
filename = "__a-mod__/animations/assembler.png"
```

--------------------------------

### Example Recipe Ingredients

Source: https://lua-api.factorio.com/stable/classes/LuaRecipePrototype.html

Demonstrates the structure of the 'ingredients' attribute for a recipe. This shows how to represent fluid and item ingredients with their types, names, and amounts.

```Lua
-- The ingredients of "advanced-oil-processing" would look like this
{{type="fluid", name="crude-oil", amount=100}, {type="fluid", name="water", amount=50}}
```

--------------------------------

### get_starting_area_radius

Source: https://lua-api.factorio.com/stable/runtime-api.json

Gets the radius of the starting area for this surface. This defines the initial safe zone for players.

```APIDOC
## get_starting_area_radius

### Description
Gets the starting area radius of this surface.

### Method
(Not specified, likely a getter)

### Endpoint
(Not applicable, Lua API method)

### Parameters
None

### Response
#### Success Response
- **return_value** (double) - The radius of the starting area.
```

--------------------------------

### AmbientSound Prototype Example

Source: https://lua-api.factorio.com/stable/prototypes/AmbientSound.html

This example shows how to define an ambient sound prototype, including its name, track type, and sound file with volume.

```lua
{
  type = "ambient-sound",
  name = "world-ambience-4",
  track_type = "interlude",
  sound =
  {
    filename = "__base__/sound/ambient/world-ambience-4.ogg",
    volume = 1.2
  }
}
```

--------------------------------

### get_bar

Source: https://lua-api.factorio.com/stable/runtime-api.json

Get the current bar. This is the index at which the red area starts. Only usable if this inventory supports having a bar.

```APIDOC
## get_bar

### Description
Get the current bar. This is the index at which the red area starts.

Only useable if this inventory supports having a bar.

### Response
#### Success Response
- **uint32** - The current bar index.
```

--------------------------------

### dash_offset

Source: https://lua-api.factorio.com/stable/classes/LuaRenderObject.html

Gets or sets the starting offset for the dashes of a line render object. Cannot exceed dash_length + gap_length.

```APIDOC
## dash_offset

### Description
Starting offset to apply to dashes of this line. Cannot be greater than dash_length + gap_length.

### Type
Read|Write double

### Notes
_Can only be used if this is Line_
```

--------------------------------

### Example Products for Advanced Oil Processing

Source: https://lua-api.factorio.com/stable/classes/LuaRecipe.html

Demonstrates the structure of the products array for a specific recipe.

```lua
-- The products of "advanced-oil-processing" would look like this:
{{type="fluid", name="heavy-oil", amount=25}, {type="fluid", name="light-oil", amount=45}, {type="fluid", name="petroleum-gas", amount=55}}
```

--------------------------------

### Retrieve Prototype Properties

Source: https://lua-api.factorio.com/stable/prototype-api.json

Retrieve specific properties from existing prototypes using `data.raw`. This example gets the max health of the wooden chest.

```lua
-- get the max health of the wooden chest
local health = data.raw["container"]["wooden-chest"].max_health
```

--------------------------------

### Retrieving Prototype Data

Source: https://lua-api.factorio.com/stable/types/Data.html

Use `data.raw` to retrieve specific properties of existing prototypes. This example shows how to get the maximum health of a wooden chest.

```lua
-- get the max health of the wooden chest
local health = data.raw["container"]["wooden-chest"].max_health

```

--------------------------------

### Example Changelog Format

Source: https://lua-api.factorio.com/stable/auxiliary/changelog-format.html

This example demonstrates the standard structure for a changelog, including version numbers, dates, and categorized entries for features, balancing, and bug fixes. It serves as a template for creating new changelog entries.

```plaintext
---------------------------------------------------------------------------------------------------
Version: 1.1.60
Date: 06. 06. 2022
  Features:
    - This is an entry in the "Features" category.
    - This is another entry in the "Features" category.
    - This general section is the 1.1.60 version section.
  Balancing:
    - This is a multiline entry in the "Balancing" category.
      There is some extra text here because it is needed for the example.
      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
  Bugfixes:
    - Fixed that canceling syncing mods with a save would exit the GUI.
    - Fixed a desync when fast-replacing burner generators.
---------------------------------------------------------------------------------------------------
Version: 1.1.59
Date: 06. 05. 2022
  Bugfixes:
    - This general section is the 1.1.59 version section.
    - This is an entry in the "Bugfixes" category.
    - Fixed grenade shadows.
---------------------------------------------------------------------------------------------------
Version: 0.1.0
Date: 24. 12. 2012
  Major Features:
    - Initial release.
    - This general section is the 0.1.0 version section.


```

--------------------------------

### Color Initialization Examples

Source: https://lua-api.factorio.com/stable/types/Color.html

Demonstrates various ways to initialize a Color struct, including named properties, default values, and array notation. Useful for setting colors for entities, UI elements, or visual effects.

```lua
color = {r=1, g=0, b=0, a=1} -- red, full opacity
color = {r=1} -- the same red, omitting default values
color = {1, 0, 0, 1} -- also the same red
color = {0, 0, 1} -- blue
color = {r=0, g=0.5, b=0, a=0.5} -- half transparency green
color = {} -- full opacity black
```

--------------------------------

### Filter Fluid Prototypes by Heat Capacity

Source: https://lua-api.factorio.com/stable/classes/LuaPrototypes.html

Get fluid prototypes that have a specific heat capacity. This example filters for fluids with a heat capacity exactly equal to 100.

```lua
local prototypes = prototypes.get_fluid_filtered{{filter="heat-capacity", comparison="=", value=100}}
```

--------------------------------

### Get Player Name and Print

Source: https://lua-api.factorio.com/stable/classes.html

This example demonstrates how to retrieve a player's name and display it in the game console using LuaGameScript::get_player and LuaPlayer::print. Ensure you have access to the game instance.

```lua
local first_player = game.get_player(1)
first_player.print(first_player.name)
```

--------------------------------

### Shortcut Prototype Example

Source: https://lua-api.factorio.com/stable/prototypes/ShortcutPrototype.html

Defines a shortcut for spawning a deconstruction planner. The 'order' property is used to position this shortcut within the quick panel when using a controller. This example demonstrates setting various properties like type, name, action, localized name, and associated control input.

```lua
{
  type = "shortcut",
  name = "give-deconstruction-planner",
  order = "b[blueprints]-i[deconstruction-planner]",
  action = "spawn-item",
  localised_name = {"shortcut.make-deconstruction-planner"},
  associated_control_input = "give-deconstruction-planner",
  technology_to_unlock = "construction-robotics",
  item_to_spawn = "deconstruction-planner",
  style = "red",
  icon = "__base__/graphics/icons/shortcut-toolbar/mip/new-deconstruction-planner-x56.png",
  icon_size = 56,
  small_icon = "__base__/graphics/icons/shortcut-toolbar/mip/new-deconstruction-planner-x24.png",
  small_icon_size = 24
}
```

--------------------------------

### Basic Recipe Example

Source: https://lua-api.factorio.com/stable/prototypes/RecipePrototype.html

Defines a simple smelting recipe for iron plates. Use this for straightforward crafting processes.

```lua
{
  type = "recipe",
  name = "iron-plate",
  category = "smelting",
  energy_required = 3.5,
  ingredients = {{type = "item", name = "iron-ore", amount = 1}},
  results = {{type = "item", name = "iron-plate", amount = 1}}
}
```

--------------------------------

### FluidID Example: Lubricant

Source: https://lua-api.factorio.com/stable/types/FluidID.html

This is an example of a FluidID for lubricant.

```lua
"lubricant"
```

--------------------------------

### Add Market Offer Example

Source: https://lua-api.factorio.com/stable/classes/LuaEntity.html

Demonstrates how to add a market offer for a single item. The offer specifies what the player gives and what they receive in return.

```lua
-- Adds market offer, 1 copper ore for 10 iron ore
market.add_market_item{price={{name = "iron-ore", count = 10}}, offer={type="give-item", item="copper-ore"}}
```

--------------------------------

### FluidID Example: Water

Source: https://lua-api.factorio.com/stable/types/FluidID.html

This is an example of a FluidID for water.

```lua
"water"
```

--------------------------------

### Example RecipeID for Special Process

Source: https://lua-api.factorio.com/stable/types/RecipeID.html

This example shows a RecipeID for a specific in-game process, demonstrating the naming convention for unique recipes.

```string
"kovarex-enrichment-process"
```

--------------------------------

### AmmoCategoryID Example

Source: https://lua-api.factorio.com/stable/types/AmmoCategoryID.html

This is an example of a string value for AmmoCategoryID.

```string
"bullet"
```

```string
"melee"
```

--------------------------------

### Example EquipmentGridID

Source: https://lua-api.factorio.com/stable/types/EquipmentGridID.html

These are examples of valid EquipmentGridID strings. They are used to reference specific equipment grid configurations.

```string
"small-equipment-grid"
```

```string
"spidertron-equipment-grid"
```

--------------------------------

### Example Ingredients for Advanced Oil Processing

Source: https://lua-api.factorio.com/stable/classes/LuaRecipe.html

Demonstrates the structure of the ingredients array for a specific recipe.

```lua
-- The ingredients of "advanced-oil-processing" would look like this:
{{type="fluid", name="crude-oil", amount=100}, {type="fluid", name="water", amount=50}}
```

--------------------------------

### LuaForce::create_space_platform

Source: https://lua-api.factorio.com/stable/runtime-api.json

Creates a new space platform on this force, orbiting a specified planet and requiring a starter pack. The platform name is optional and will be random if not provided.

```APIDOC
## LuaForce::create_space_platform

### Description
Creates a new space platform on this force, orbiting a specified planet and requiring a starter pack. The platform name is optional and will be random if not provided.

### Method
(Not specified, likely a Lua function call)

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **name** (string) - Optional - The platform name. If not provided, a random name will be used.
- **planet** (SpaceLocationID) - Required - The planet that the platform will orbit.
- **starter_pack** (ItemWithQualityID) - Required - The starter pack required to build the platform.

### Request Example
```lua
-- Creates a space platform named "MyPlatform" orbiting planet "PlanetA" with a basic starter pack.
game.player.force.create_space_platform("MyPlatform", "PlanetA", {{name="iron-plate", count=100}})

-- Creates a space platform with a random name orbiting planet "PlanetB" with a different starter pack.
game.player.force.create_space_platform(nil, "PlanetB", {{name="steel-plate", count=50}})
```

### Response
#### Success Response (200)
- **Return Value** (LuaSpacePlatform) - The created space platform object, or nil if creation failed.

#### Response Example
- None
```
Tokens:
Raw