The prototype 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 4
, which was introduced with Factorio 1.1.89
. See Changelog.
Some notes that apply to the format in general:
null
, it is omitted from the JSON instead.""
) instead of null
if they could exist on any given member, but just happen to be empty (ex. an empty attribute description).order
property of its members.All text can contain Markdown-type links. There are two broad categories for these: hyperlinks that link to any external website, and internal links that refer to another part of this documentation. All of them will have a title that should be displayed as the link's text.
https://
, and are followed by the URL. Example: [Factorio](https://factorio.com)
.runtime:
or prototype:
, indicating the stage that is linked to. The two stages are separate namespaces, as there would be naming conflicts otherwise. So this first part indicates whether to look for the API member among classes, events, etc., or among prototypes and types.LuaGuiElement
or on_player_created
for runtime:
, and RecipePrototype
or EnergySource
for prototype:
.runtime:
, and 'prototypes', 'types' for prototype:
.::<name>
, where name is the name of a class method or attribute, or a prototype/type property. It is invalid for any other member type.Examples:
[LuaGuiElement](runtime:LuaGuiElement)
links to the LuaGuiElement
class.[results](prototype:RecipePrototype::results)
links to the results
property of the RecipePrototype
prototype.[concepts](runtime:concepts)
links to the Concepts overview page.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 "prototype"
(as opposed to "runtime"
; 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.90"
.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:
prototypes
:: array[Prototype]: The list of prototypes that can be created. Equivalent to the prototypes page.types
:: array[Type]: The list of types (concepts) that the format uses. Equivalent to the types page.name
:: string: The name of the prototype.order
:: number: The order of the prototype as shown in the HTML.description
:: string: The text description of the prototype.lists
:: array[string] (optional): A list of Markdown lists to provide additional information. Usually contained in a spoiler tag.examples
:: array[string] (optional): A list of code-only examples about the prototype.images
:: array[Image] (optional): A list of illustrative images shown next to the prototype.parent
:: string (optional): The name of the prototype's parent, if any.abstract
:: boolean: Whether the prototype is abstract, and thus can't be created directly.typename
:: string (optional): The type name of the prototype, like "boiler"
. null
for abstract prototypes.instance_limit
:: number (optional): The maximum number of instances of this prototype that can be created, if any.deprecated
:: boolean: Whether the prototype is deprecated and shouldn't be used anymore.properties
:: array[Property]: The list of properties that the prototype has. May be an empty array.custom_properties
:: CustomProperties (optional): A special set of properties that the user can add an arbitrary number of. Specifies the type of the key and value of the custom property.name
:: string: The name of the type.order
:: number: The order of the type as shown in the HTML.description
:: string: The text description of the type.lists
:: array[string] (optional): A list of Markdown lists to provide additional information. Usually contained in a spoiler tag.examples
:: array[string] (optional): A list of code-only examples about the type.images
:: array[Image] (optional): A list of illustrative images shown next to the type.parent
:: string (optional): The name of the type's parent, if any.abstract
:: boolean: Whether the type is abstract, and thus can't be created directly.inline
:: boolean: Whether the type is inlined inside another property's description.type
:: Type: The type of the type/concept (Yes, this naming is confusing). Either a proper Type, or the string "builtin"
, indicating a fundamental type like string
or number
.properties
:: array[Property] (optional): The list of properties that the type has, if its type includes a struct. null
otherwise.Several data structures are used in different parts of the format, which is why they are documented separately to avoid repetition.
name
:: string: The name of the property.order
:: number: The order of the property as shown in the HTML.description
:: string: The text description of the property.lists
:: array[string] (optional): A list of Markdown lists to provide additional information. Usually contained in a spoiler tag.examples
:: array[string] (optional): A list of code-only examples about the property.images
:: array[Image] (optional): A list of illustrative images shown next to the property.alt_name
:: string (optional): An alternative name for the property. Either this or name
can be used to refer to the property.override
:: boolean: Whether the property overrides a property of the same name in one of its parents.type
:: Type: The type of the property.optional
:: boolean: Whether the property is optional and can be omitted. If so, it falls back to a default value.default
:: union[string, Literal] (optional): The default value of the property. Either a textual description or a literal value.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 additional members:
array
:value
:: Type: The type of the elements of the array.dictionary
:tuple
:values
:: array[Type]: The types of the members of this tuple in order.union
:literal
:type
:struct
: Special type with no additional members. The properties
themselves are listed on the API member that uses this type.A literal has the same format as a Type that is complex and of type literal
.
Example: {"complex_type": "literal", "value": 2}
filename
:: string: The name of the image file to display. These files are placed into the /static/images/
directory.caption
:: string (optional): The explanatory text to show attached to the image.description
:: string: The text description of the property.lists
:: array[string] (optional): A list of Markdown lists to provide additional information. Usually contained in a spoiler tag.examples
:: array[string] (optional): A list of code-only examples about the property.images
:: array[Image] (optional): A list of illustrative images shown next to the property.key_type
:: Type: The type of the key of the custom property.value_type
:: Type: The type of the value of the custom property.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
.