Tutorial:Modding tutorial/Gangsir

This is a modding tutorial for Factorio version 0.15. In this tutorial, the author will explain how Factorio works behind the scenes, how to modify Factorio, where to find documentation, and explain concepts.

Overview

Before we start the tutorial, a few things to note:

Code tinted green like this should be included into the mod this tutorial is going to create; If the reader follows along with it. The best way to do this is to copy and paste, to ensure faithful reproduction.
Whenever code is added to the mod, a Lua comment with the file name will be at the beginning of the green box. Place the code in the box into that file. Eg:
--control.lua

Code tinted purple like this should not be included into the mod, it's just for educational/example purposes, and to boost understanding.

This tutorial was created for version 0.15, so any viewers in the future should take note that some minor changes may have been made, and should look at the changelogs up to the current version.

Terminology used in modding

Before we start the tutorial, a few terms and definitions should be laid out, to ensure the reader understands.

Mod

A script or series of scripts that allow modifications to the game through the API.

Entity

An entity in Factorio is anything in the game that is not a concept, event, or tile. Examples of entities include the character, an assembling machine, a biter, etc. This can be 'machines' or free-moving objects like the character.

Character

The actual entity that the player manipulates the world through.

Player

All the data that defines a player, such as username, position in the player table, etc. All players have characters, but no characters have players within them.

Prototype

A prototype is an internal handling of entities, a bit like a template. It defines stats, what the entity actually is, etc. A prototype is used to create an entity.

Surface

A surface is a bit like a dimention. It is composed of terrain, such as grass, sand, and water, and all the entities on the surface. By defualt, there is only one surface in Factorio, referred to internally as "nauvis", or game.surfaces[1], but mods may create additional surfaces through the API.

Event

An event is a recurring...event, that is triggered internally by the game. There are several events that mods may connect functions to, such as on_entity_died, etc. More on this in the control scripting section.

Recipe

This is a data structure a bit like a prototype that defines a recipe for the internal crafting engine. A technology follows a similar setup.

More terminology may be declared and defined later in this tutorial.

Before beginning to mod

Before we can start modding Factorio, we must understand what Factorio is. You may be tempted to answer in lieu of the about page, but that is what a player would say. Since we are trying to become a modder, we need a more detailed explanation. Factorio is a game that is coded in the language C++, with an API provided by Wube (the developers of Factorio) to mod Factorio in the programming language Lua. This API allows adding scripts to the Factorio init process, to modify it without the source code of the base game being exposed, or modifying memory. This may be different than other games that offer modding, but this is a more professional and proper way of supporting modding.

To aid in the use of this API, the devs have kindly provided fairly comprehensive documentation at their API site. Get used to using this site, as it will become a frequent visit you will make while you develop mods. It contains information on factorio's classes, information on concepts, and information on events that you can hook into. You will need to check this site often, so the author reccomends bookmarking it. In addition to this site, there is also many resources to be found created by the community, such as this tutorial.

Setup

The best way to develop a mod is to develop it in a place where it can be easily tested. When the tutorial gets to making the mod, this will be explained further. Additionally, using an editor that allows ease of typing and Lua language support is reccomended. Emacs, Vim, Sublime Text, and Notepad++ are all viable candidates. This author prefers Emacs, but it does not make a difference in the mod itself.

How Factorio loads mods

The data stage

When Factorio first initializes, it initializes part of itself, then starts looking for mods. Mods are loaded by dependency, then by alphabetical order. This is very important to understand, as it can cause you problems if you neglect it and try to add inter-mod support to your mod.

Factorio has two kinds of dependencies. There are required dependencies, and optional dependencies. Required dependencies are loaded first, always. The game will fail to initialize if one of these is not present. Optional dependencies are loaded first if present, but do not have to be present. This is useful for enabling bonus features if mods are used together. Required dependencies should be used for mod libraries, and similar infrastructure.

This is the most restricted part of the Factorio init, there's not much you can do here other than declare prototypes for technologies and entities. Stuff like manipulating files, affecting the world, etc, are blocked/unavailable. In fact, any functions or changes made will be discarded, as the lua session is terminated. You also cannot mess with the data table, it will error or be ignored. When using data:extend({}), it expects a specific format, more on this later.

When running through this stage, the game looks through all mods for a file called data.lua. This file is executed, then each mod's data-updates.lua, and finally each mod's data-final-fixes.lua. All other files to be loaded will need to be required. All the files run here should contain nothing but prototype definitions. More on requiring files later.

Migrations

Migrations are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

Control

Within most mods is a file called control.lua. This file contains scripting that makes the mod actually do things, beyond simply adding entities to the game. During this stage, each mod's control.lua is run, in it's own lua instance (this means no inter-communication without special setup) which it will own for the rest of the play session. Because this is run every time a save file is created or loaded you don't need to restart the game to see changes made to the control.lua file. Simply restarting or reloading a save will re-run this stage. There are a few other caveats to this stage, reading the data life cycle page on the API site provides the best overview.

Runtime

At this stage, the mod is setup, and the save is running. Access to all tables provided by the game can be done inside of event handlers. (More on those below.)