Tutorial:Mod structure

Mods are expected to have a certain structure in order to be loaded by the game. This page aims to explain that file structure and what each file is used for.

Mod folder and file structure

The mod must either be in a folder, or in a folder inside a zip file. The mod folder (no zip file) must either be named in the pattern of {mod-name}_{version-number} or just {mod-name}, for example test-mod-thing. The mod zip must be named in the pattern of {mod-name}_{version-number}, for example test-mod-thing_0.0.1. When using a zip file for the mod, the folder inside the zip file does not have any naming restrictions; only the zip file itself must be named with the {mod-name}_{version-number} pattern. The mod name and its version number are defined in the info.json file.

Files

Inside the mod folder, the game automatically reads the following files during load:

• info.json — The only mandatory file. The info.json identifies the mod, defines its version and other general properties.
• changelog.txt — Version history of the mod, to be shown in the mod browser. The changelog file must follow the strict formatting requirements.
• thumbnail.png — Thumbnail to be shown on the mod portal and in the mod browser in-game. Ideally a 144x144px image file.
• settings.lua — This and the next two files are used to set up mod configuration options.
• settings-updates.lua
• settings-final-fixes.lua
• data.lua — This and the next two files are used to define prototypes.
• data-updates.lua — The load order of the three data*.lua files is explained on Data lifecycle.
• data-final-fixes.lua
• control.lua — This file is used for runtime scripting. Runtime scripting is documented on lua-api.factorio.com.

Subfolders

Furthermore, the following folders inside the mod folder are recognized by the game:

• locale — Can contain up to one subfolder per language, identified with the language code, for example en for English. The subfolder then has to contain at least one *.cfg file which defines the translations for that language.
• scenarios — Custom scenarios can be placed in subfolders of this folder.
• campaigns — Custom campaigns can be placed in subfolders of this folder.
• tutorials — Custom tutorials scenarios can be placed in subfolders of this folder.
• migrations — Migration files are placed in this folder. They are a way to handle prototype changes and mod data structure changes between mod versions or game versions.

Example

Here is an example directory structure for a mod titled my-armor-mod with a version number of 0.3.6:

my-armor-mod_0.3.6.zip
|- aFolderName/
  |- control.lua
  |- data.lua
  |- info.json
  |- thumbnail.png

info.json

The info.json file identifies the mod and defines its version. If the game encounters a problem when parsing the file, the error message can be found in the log file. A minimal info.json file can look like this:

   {
     "name": "test-mod-thing",
     "version": "0.0.1",
     "title": "My best test mod",
     "author": "A very great tester",
     "factorio_version": "1.1",
     "dependencies": ["? optional-mod"]
   }

The info.json file supports the following fields:

name

Type: string

Mandatory field. The internal name of mod. The game accepts anything as a mod name, however the mod portal restricts mod names to only consist of alphanumeric characters, dashes and underscores. Note that the mod folder or mod zip file name has to contain the mod name, where the restrictions of the file system apply.

The game accepts mod names with a maximum length of 100 characters. The mod portal only accepts mods with names that are longer than 3 characters and shorter than 50 characters.

version

Type: string

Mandatory field. Defines the version of the mod in the format "number.number.number" for "Major.Middle.Minor", for example "0.6.4". Each number can range from 0 to 65535.

title

Type: string

Mandatory field. The display name of the mod, so it is not recommended to use someUgly_pRoGrAmMeR-name here. Can be overwritten with a locale entry in the mod-name category, using the internal mod name as the key.

The game will reject a title field that is longer than 100 characters. However, this can be worked around by using the locale entry. The mod portal does not restrict mod title length.

author

Type: string

Mandatory field. The author of the mod. This field does not have restrictions, it can also be a list of authors etc. The mod portal ignores this field, it will simply display the uploader's name as the author.

contact

Type: string

Optional field. How the mod author can be contacted, for example an email address.

homepage

Type: string

Optional field. Where the mod can be found on the internet. Note that the in-game mod browser shows the mod portal link additionally to this field. Please don't put "None" here, it makes the field on the mod portal website look ugly. Just leave the field empty if the mod doesn't have a website/forum thread/discord.

description

Type: string

Optional field. A short description of what your mod does. This is all that people get to see in-game. Can be overwritten with a locale entry in the mod-description category, using the internal mod name as the key.

factorio_version

Type: string

Default: "0.12"

Optional field in the format "major.minor". The Factorio version that this mod supports. This can only be one Factorio version, not multiple. However, it includes all .sub versions. While the field is optional, usually mods are developed for versions higher than the default 0.12, so the field has to be added anyway.

Adding a sub part, e.g. "0.18.27" will make the mod portal reject the mod and the game act weirdly. That means this shouldn't be done; use only the major and minor components "major.minor", for example "1.0".

Mods with the factorio_version "0.18" can also be loaded in 1.0 and the mod portal will return them when queried for factorio_version 1.0 mods.

dependencies

Type: array of #Dependency

Default: ["base"]

Optional field. Mods that this mod depends on or is incompatible with. If this mod depends on another, the other mod will load first, see Data lifecycle. An empty array allows to work around the default and have no dependencies at all.

Example:

"dependencies": ["mod-a", "? mod-c > 0.4.3", "! mod-g"]

Dependency

Each dependency is a string that consists of up to three parts: "<prefix> internal-mod-name <equality-operator version>", for example "? some-mod-everyone-loves >= 4.2.0".

The equality operator (<, <=, =, >= or >) combined with the version allows to define dependencies that require certain mod versions, but it is not required. Incompatibility does not support versions; if incompatibility is used, version is ignored. If a version is used for an optional dependency, the mod is considered incompatible (and disabled) if the dependency is present but does not fulfill the version requirement.

The possible prefixes are:

• ! for incompatibility
• ? for an optional dependency.
• (?) for a hidden optional dependency
• ~ for a dependency that does not affect load order
• no prefix for a hard requirement for the other mod.

See also

• Modding tutorial overview
• Prototype documentation
• Runtime API documentation