Factorio API Docs

1.1.56 <>

Machine-readable format

The API documentation is available in a machine-readable JSON format. It allows for the creation of developer tools that provide code completion and related functionality. This page documents the structure of this format.

The current api_version that these docs reflect is 2, which was introduced with Factorio 1.1.54. See Changelog.

General notes

Some general notes that apply to the format in general:

  • If a member would be null, it is omitted from the JSON instead.
  • Descriptions are generally empty ("") instead of null if they could exist on any given member, but just happen to be empty (ex. an empty attribute description).
  • Inversely, descriptions are null (and thus omitted) if they don't exist at all (ex. the return_description for a method without a return value).
  • Every list is sorted alphabetically by name. To replicate the order seen on the website, it can be sorted by the order property of its members.
  • Text (descriptions, examples, etc.) is formatted as Markdown, which includes links, inline code, and code blocks.
  • All text can contain Markdown links. They are either a hyperlink (starting with https://), a relative link (linking to another API page relative to the current one), or an internal link (referring to any member of the API).

Top level members

The format has some top level members indicating the context of the format. These are:

  • application :: string: The application this documentation is for. Will always be "factorio".
  • stage :: string: Indicates the stage this documentation is for. Will always be "runtime" (as opposed to "data"; see the data lifecycle for more detail).
  • application_version :: string: The version of the game that this documentation is for. An example would be "1.1.30".
  • api_version :: number: The version of the machine-readable format itself. It is incremented every time the format changes. The version this documentation reflects is stated at the top.

Then, there are several top level members that contain the API documentation itself, organized by their various types. These are:

  • classes :: array[Class]: The list of classes (LuaObjects) the API provides. Equivalent to the classes page.
  • events :: array[Event]: The list of events that the API provides. Equivalent to the events page.
  • defines :: array[Define]: The list of defines that the game uses. Equivalent to the defines page.
  • builtin_types :: array[BuiltinType]: The list of types that are built into Lua itself. Equivalent to the built-in types page.
  • concepts :: array[Concept]: The list of concepts of various types that the API uses. Equivalent to the concepts page.
  • global_objects :: array[GlobalObject]: The list of objects that the game provides as global variables to serve as entry points to the API.

Top level types

Class

  • name :: string: The name of the class.
  • order :: number: The order of the class as shown in the html.
  • description :: string: The text description of the class.
  • notes :: array[string] (optional): A list of strings containing additional information about the class.
  • examples :: array[string] (optional): A list of strings containing example code and explanations.
  • methods :: array[Method]: The methods that are part of the class.
  • attributes :: array[Attribute]: The attributes that are part of the class.
  • operators :: array[Operator]: A list of operators on the class. They are called call, index, or length and have the format of either a Method or an Attribute.
  • base_classes :: array[string] (optional): A list of the names of the classes that his class inherits from.

Event

  • name :: string: The name of the event.
  • order :: number: The order of the event as shown in the html.
  • description :: string: The text description of the event.
  • notes :: array[string] (optional): A list of strings containing additional information about the event.
  • examples :: array[string] (optional): A list of strings containing example code and explanations.
  • data :: array[Parameter]: The event-specific information that is provided.

Define

Defines can be recursive in nature, meaning one Define can have multiple sub-Defines that have the same structure. These are singled out as subkeys instead of values.

  • name :: string: The name of the define.
  • order :: number: The order of the define as shown in the html.
  • description :: string: The text description of the define.
  • values :: array[BasicMember] (optional): The members of the define.
  • subkeys :: array[Define] (optional): A list of sub-defines.

BuiltinType

  • name :: string: The name of the builtin type.
  • order :: number: The order of the builtin type as shown in the html.
  • description :: string: The text description of the builtin type.

Concept

  • name :: string: The name of the concept.
  • order :: number: The order of the concept as shown in the html.
  • description :: string: The text description of the concept.
  • notes :: array[string] (optional): A list of strings containing additional information about the concept.
  • examples :: array[string] (optional): A list of strings containing example code and explanations.
  • category :: string: The category of the concept.

Depending on category, there might be additional members:

  • table: A simple collection of parameters.
    • parameters :: array[Parameter]: The parameters present in the table.
    • variant_parameter_groups :: array[ParameterGroup] (optional): The optional parameters that depend on one of the main parameters.
    • variant_parameter_description :: string (optional): The text description of the optional parameter groups.
  • table_or_array: A collection of parameters that optionally drops the explicit keys.
    • parameters :: array[Parameter]: The parameters present in the table.parameter groups.
  • enum: A collection of strings.
    • options :: array[BasicMember]: The members of the enum.
  • flag: A collection of flags with special format in the API.
    • options :: array[BasicMember]: The different flag options.
  • union: A list of ways to specify a certain concept within the API.
    • options :: array[Spec]: A list of specification options. Each Spec is a table:
      • type :: Type: The type of the specification option.
      • order :: number: The order of the option as shown in the html.
      • description :: string: The text description of the option.
  • filter: An event or prototype filter.
    • parameters :: array[Parameter]: The always-present parameters for the filter.
    • variant_parameter_groups :: array[ParameterGroup] (optional): The optional filter parameters that depend on the specific filter parameter used.
    • variant_parameter_description :: string (optional): The text description of the optional filter groups.
  • struct: A class-like collection of attributes.
    • attributes :: array[Attribute]: A list of attributes with the same properties as class attributes.
  • concept: A text-based explanation of a particular format. No additional members.

GlobalObject

  • name :: string: The global variable name of the object.
  • order :: number: The order of the global object as shown in the html.
  • description :: string: The text description of the global object.
  • type :: string: The class name of the global object.

Common structures

Several data structures are used in different parts of the format, which is why they are documented separately to avoid repetition.

BasicMember

  • name :: string: The name of the member.
  • order :: number: The order of the member as shown in the html.
  • description :: string: The text description of the member.

EventRaised

  • name :: string: The name of the event being raised.
  • order :: number: The order of the member as shown in the html.
  • description :: string: The text description of the raised event.
  • timeframe :: string: The timeframe during which the event is raised. One of "instantly", "current_tick", or "future_tick".
  • optional :: boolean: Whether the event is always raised, or only dependant on a certain condition.

Type

A type is either a string, in which case that string is the simple type. Otherwise, a type is a table:

  • complex_type :: string: A string denoting the kind of complex type.

Depending on complex_type, there are members:

  • variant:
    • options :: array[Type]: A list of all compatible types for this type.
  • array:
    • value :: Type: The type of the elements of the array.
  • dictionary or LuaCustomTable:
    • key :: Type: The type of the keys of the dictionary or LuaCustomTable.
    • value :: Type: The type of the values of the dictionary or LuaCustomTable.
  • function:
    • parameters :: array[Type]: The types of the function arguments.
  • LuaLazyLoadedValue:
    • value :: Type: The type of the LuaLazyLoadedValue.
  • table:
    • parameters :: array[Parameter]: The parameters present in the table.
    • variant_parameter_groups :: array[ParameterGroup] (optional): The optional parameters that depend on one of the main parameters.
    • variant_parameter_description :: string (optional): The text description of the optional parameter groups.

Parameter

  • name :: string: The name of the parameter.
  • order :: number: The order of the parameter as shown in the html.
  • description :: string: The text description of the parameter.
  • type :: Type: The type of the parameter.
  • optional :: boolean: Whether the type is optional or not.

ParameterGroup

  • name :: string: The name of the parameter group.
  • order :: number: The order of the parameter group as shown in the html.
  • description :: string: The text description of the parameter group.
  • parameters :: array[Parameter]: The parameters that the group adds.

Method

  • name :: string: The name of the method.
  • order :: number: The order of the method as shown in the html.
  • description :: string: The text description of the method.
  • notes :: array[string] (optional): A list of strings containing additional information about the method.
  • examples :: array[string] (optional): A list of strings containing example code and explanations.
  • raises :: array[EventRaised] (optional): A list of events that this method might raise when called.
  • subclasses :: array[string] (optional): A list of strings specifying the sub-type (of the class) that the method applies to.
  • parameters :: array[Parameter]: The parameters of the method. How to interpret them depends on the takes_table member.
  • variant_parameter_groups :: array[ParameterGroup] (optional): The optional parameters that depend on one of the main parameters. Only applies if takes_table is true.
  • variant_parameter_description :: string (optional): The text description of the optional parameter groups.
  • variadic_type :: Type (optional): The type of the variadic arguments of the method, if it accepts any.
  • variadic_description :: string (optional): The description of the variadic arguments of the method, if it accepts any.
  • takes_table :: boolean: Whether the method takes a single table with named parameters or a sequence of unnamed parameters.
  • table_is_optional :: boolean (optional): If takes_table is true, whether that whole table is optional or not.
  • return_values :: array[Parameter]: The return values of this method, which can contain zero, one, or multiple values. Note that these have the same structure as parameters, but do not specify a name.

Attribute

  • name :: string: The name of the attribute.
  • order :: number: The order of the attribute as shown in the html.
  • description :: string: The text description of the attribute.
  • notes :: array[string] (optional): A list of strings containing additional information about the attribute.
  • examples :: array[string] (optional): A list of strings containing example code and explanations.
  • raises :: array[EventRaised] (optional): A list of events that this attribute might raise when written to.
  • subclasses :: array[string] (optional): A list of strings specifying the sub-type (of the class) that the attribute applies to.
  • type :: Type: The type of the attribute.
  • read :: boolean: Whether the attribute can be read from.
  • write :: boolean: Whether the attribute can be written to.

Basic types

string

A string, which can be an identifier for something, or a description-like text formatted in Markdown.

number

A number, which could either be an integer or a floating point number, as JSON doesn't distinguish between those two.

boolean

A boolean value, which is either true or false.

Changelog

  • Changes for version 2 introduced with Factorio 1.1.54:

    • Replaced return_type and return_description fields on methods with the return_values-array.
    • Added raises field to methods and attributes.
    • Removed see_also field from classes, events, concepts, methods and attributes.
  • Changes for version 1 introduced with Factorio 1.1.35:

    • First release
|<

Classes

Events

Concepts

Defines

Builtin types

>|