Joel Purra: Developer and more


Factorio 0.12 Factorio 0.18
A concept of a factory for the trailer in 0.12 A concept of a factory for the trailer in 0.18

Screenshots of factory concepts for the Factorio 1.0 launch trailer, showcasing the evolution of the game. The Factorio blog covers the process in detail.

factorio-save-upgrader

Tool to upgrade old Factorio game save files to the newest version. Bring on the map nostalgia!

Use this tool at your own risk. Backup your saves first.
The save file format in Factorio is pretty stable. Each Factorio “major” version supports loading save games from one or more previous save file formats. The game will tell you if your save file is too old, otherwise you don’t need to do anything.

The stepwise load/upgrade concept:

Loading
1.1   1.0   0.18   0.17   0.16
❌ --> ❌ --> ❌ --> ✅ ... ❓ ...
                    |
Upgrading           |
1.1   1.0   0.18    |
✅ <-- ✅ <-- ✅ <----
  • First factorio-save-upgrader loads (a copy of) the save in the most recent Factorio version possible, then upgrades it stepwise to the most recent version available. After shutting down the last instance the map is fully upgraded, and the modified file is put in the output directory.
  • Leaves up-to-date save files alone. Output is written with the same filename but to a different directory. Does not overwrite existing files.
  • Can upgrade all save files in the ./saves directory at once, or one by one.
  • Does not require the full game to be installed. Save file can be transferred to a separate computer where upgrades are performed.
  • Built using Factorio Docker (factoriotools/factorio-docker), originally intented for running dedicated game servers.

Version compatibility

Not all Factorio versions have (working) Docker images. Check the issues for this tool as well as issues for Factorio Docker for possible solutions.

Here is a table of last known status (although it is presumably constantly outdated) for the available Factorio Docker image versions. Major game versions can also load some older save file formats. For example, Factorio 0.17 also supports upgrading from 0.16 and 0.15.

Version Running Upgrading from
1.1
1.0
0.18
0.17
0.16
0.15
0.14
0.13
0.12

Older versions are not supported, unless someone publishes a compatible Docker image.

Limitations

  • Factorio has evolved over the years. For example some recipes, such as oil processing, have changed so your factory may not run very well without manual fixes.
  • Only upgrading vanilla Factorio has been tested. For this reason, upgrading save files with mods are not officially supported by this tool.
  • Replay support is untested. Presumably doesn’t upgrade replays, since they are more tightly coupled to the version used for recording. Loading the map may still work, but replaying is not possible.
  • The save preview (screenshot) is lost during automated upgrades. When saving using the full game it is regenerated.
  • This tool doesn’t inspect the savegame.zip files to try to figure out which upgrades might be necessary. Instead it brute-forces the solution by testing the save file against several major versions of Factorio until loading succeeds. The save file is then upgraded step-by-step through each subsequent major version.
  • This tool doesn’t detect when the save file has been successfully upgraded. Instead it waits for 60 seconds (by default) during each step, and then assumes everything went well. Upgrading a large/complex map on a slow machine may take even longer, potentially interrupting the process prematurely. Upgrading a small/simple map on a reasonably fast machine only takes seconds though, so the extra wait may seem unneccessary. Adjust to your liking; see usage.

Requirements

  • Creating backups of your save files before attempting to upgrade them. You don’t want to lose your precious factory, do you?
  • A Unix/Linux system with common programs such as bash, sed, find, sort, mktemp, realpath.
  • Docker to run the Factorio Docker images.
    • Does not require root access if your user belongs to the docker group.
    • Similar tools, like Podman, should also work.

Installation

There’s no real installation step. Just download the code somewhere and execute it in your terminal.

# NOTE: clone the git repository.
git clone https://github.com/joelpurra/factorio-save-upgrader.git

cd factorio-save-upgrader

# NOTE: either run directly from this directory...
./factorio-save-upgrader

# NOTE: ...or optionally symlink to your $PATH for ease of use.
ln --symbolic "${PWD}/factorio-save-upgrader" ~/bin/

factorio-save-upgrader

Usage

Only successfully upgraded files are put in the output directory.

factorio-save-upgrader <output directory> <input directory or file(s)>

Examples assume loading saves from Factorio’s default user data directory location on a Linux system.

Basic examples

Simple backup

You can do better.

cp --recursive ~/.factorio/saves ~/factorio-saves-backup-$(date +%F)

Upgrade all saves to another directory

Afterwards, manually copy the upgraded save files from ~/factorio-upgraded-saves to ~/.factorio/saves.

mkdir --parents ~/factorio-upgraded-saves

factorio-save-upgrader ~/factorio-upgraded-saves ~/.factorio/saves

Advanced examples

Use one or more environment variables to change some settings; see the source code for details.

Show verbose output

FACTORIO_SAVE_UPGRADER_DEBUG_LEVEL='1' factorio-save-upgrader ~/factorio-upgraded-saves ~/.factorio/saves

Shorter map upgrade timeout

A shorter timeout can speed things up if you have many save files, but if your map is too complex or your machine too slow it might fail.

You can also increase the timeout, and connect to the game server to verify that the upgrade worked. Start Factorio and connect to address localhost from the multiplayer menu.

FACTORIO_TIMEOUT='15s' factorio-save-upgrader ~/factorio-upgraded-saves ~/.factorio/saves

Limit Factorio versions

Ensure versions are listed in descending order, with a single space between.

FACTORIO_VERSIONS='0.13 0.12' factorio-save-upgrader ~/factorio-upgraded-saves ~/.factorio/saves

Updating the Factorio Docker images

Because this tool executes images in a loop, it doesn’t spend time checking if there are any updated images on Docker Hub. You should perform updates manually if you haven’t in a couple of weeks.

Advanced users may use custom images; see the source code for details.

Pull updates for all local Factorio images

docker image ls --format ':' --filter 'reference=factoriotools/factorio' | xargs --max-lines=1 docker pull

Delete all local Factorio images to force re-download

This tool does not keep data in images or persistent volumes. Be more careful if you use the images for anything else, such as actually running a game server.

docker image rm $(docker image ls --format ':' --filter 'reference=factoriotools/factorio')

factorio-save-upgrader Copyright © 2022 Joel Purra. Released under GNU General Public License version 3.0 (GPL-3.0). Your donations are appreciated!