FreeOrion: an open source 4X empire game where the content is the point

A 4X game whose design centre is the content layer

FreeOrion is a free, open source, turn-based space empire and galactic conquest game. It is inspired by the tradition of the Master of Orion games, and the README is careful to say that it does not try to be a clone or remake of that series or of any other game, and that it builds on the classic 4X model of eXplore, eXpand, eXploit and eXterminate.

The distinctive sentence comes next. By adding scripting capabilities to the game engine, the project aims to give the community an easy way to customize the game mechanics and presentation to create a living, breathing universe in a grand campaign model.

That is the whole thesis of the project. The engine is a vehicle, and the community's contribution is supposed to be the universe itself. A player who is content with the shipped empires gets a competent 4X game. A player who wants a species that plays differently, a technology tree that changes the shape of an expansion, or a scenario with its own rules writes a script rather than waits for a patch.

The repository layout backs this up. Alongside the C++ engine directories, Empire/, client/, server/, universe/, combat/, network/, UI/, parse/ and util/, there is a default/ directory that holds the shipped content, a python/ directory for the scripting, and separate godot/ and godot4/ directories that suggest work on a different client technology. The default branch is master, the project has a CI workflow that builds on pushes to it, and the site is freeorion.org.

FOCS is where the community actually works

The README's directory section is effectively the manual for modding, and the important part is the resource directory, which holds the audio, visual and textual UI content along with the python scripts.

Inside it there are four directories that matter. The scripting directory holds the FreeOrion Content Scripts, described as FOCS, which describe game content such as tech and species. The stringtables directory holds the translation indices for the various languages. The python/AI directory holds the AI for the computer controlled empires. And the resource directory itself is the install directory's default/ folder, which can be redirected in config.xml or persistent_config.xml in the configuration directory.

That last point is the mechanism that makes the whole design workable. A mod that changes how the game plays is a set of FOCS files and an AI script in a directory of your own, pointed at by a configuration file, rather than a patch to the installation. Two players can run different universes from the same executable.

The repository also has test-scripting/ and check/ directories, and the Python tooling configuration shows that the content is treated as code. The pyproject.toml sets up ruff for formatting and linting with a line length of 120 and a target version of py310, selects a broad rule set including the C9 complexity checks, the pyupgrade rules, isort and the annotation rules, and there are per-file ignores for the specific scripts that need to break the rules, such as the AI entry point and the universe generation modules. There is a pre-commit configuration as well, so the content is checked before it is committed.

For a game whose community writes most of it, treating that content as linted, typed code is the difference between a modding scene and a pile of scripts.

Configuration, data and resources live in three different places

The README documents three locations, and confusing them is the classic first mistake.

The configuration directory holds the game settings. On Linux it is $XDG_CONFIG_HOME/freeorion, which defaults to ~/.config/freeorion, and on macOS it is $HOME/Library/Application Support/FreeOrion/. On Windows it is $APPDATA\FreeOrion.

The data directory holds local user data, saved games and log files, with the same shape of paths: $XDG_DATA_HOME/freeorion on Linux, the Application Support folder on macOS and $APPDATA\FreeOrion on Windows.

The resource directory holds the audio, visual and textual UI content and the python scripts, and it is the only one of the three that lives inside the installation rather than in the user's home. It is the install directory's default/ folder, and it can be redirected through config.xml or persistent_config.xml in the configuration directory.

The distinction between the configuration and the data directory is the one worth internalising, because it is what lets you have two different universes with the same settings, or a shared configuration with separate saved games. The redirection of the resource directory is what lets you keep your content outside the installation entirely, which matters for a mod that you want to survive a reinstall.

The two files with different purposes, config.xml and persistent_config.xml, are a common pattern in games: one for settings the game owns and one for settings the user owns, so an upgrade cannot silently overwrite a preference.

Installing from six distributions, a DMG, an installer or a Flatpak

The install section covers the platforms separately, and the Linux story is the richest.

On Windows you execute the native installer binary and follow the on-screen instructions. On macOS you open the downloaded DMG file and copy the contained FreeOrion application to your Applications folder by drag and drop. On Linux and other from-source installations the README points at the Build Instructions in BUILD.md.

For distributions that package the stable release, the commands are one line each.

apt-get install freeorion
dnf install freeorion
emerge games-strategy/freeorion
xbps-install freeorion
pacman -S freeorion
zypper in freeorion

Those cover Debian and Ubuntu, Fedora, Gentoo, Void, Arch and openSUSE, and the project notes that you can also install them with a graphical package manager by searching for FreeOrion. There is a Flatpak on Flathub as well, installed by following the Flathub setup instructions.

The distribution packages are described as providing the stable release, which matters if you are chasing a bug: a packaged build is a stable build, and the newest content is not in it.

The weekly releases are a separate channel with a separate host. Stable releases are native installer binaries for Windows and Mac OSX, or source releases for Linux and other UNIX-ish platforms from GitHub. The weekly releases, which are in-development releases intended for enthusiasts and testers who want to track or contribute to the development, are native installer binaries for Windows and Mac OSX from SourceForge.

Requirements that are a floor rather than a wish

The requirements section is short and specific. FreeOrion requires an OpenGL 2.1 capable graphic card and a display with a suggested minimum resolution of at least 1280x800.

That OpenGL 2.1 figure is the interesting one. It is an old requirement, and it reflects a decision to keep the renderer conservative so the game runs on old hardware and in environments where a modern GL context is awkward. The cost is that the game's visual ceiling is set by that constraint, and any modern features from the newer graphics pipeline are not available.

The operating system support is stated with the same precision. Recent releases require at least Windows 8.1 or later, macOS 10.12 or later, or any reasonably recent Linux distribution on x86 compatible processors, with Ubuntu 20.04 or 22.10 given as examples. Other operating systems and architectures have reported to be working by users, but are not actively supported by the project.

That last sentence is a useful boundary to hold on to. An ARM Linux machine or an unusual platform may well run the game, and the community has reported as much, but nobody is fixing what breaks there. For a game with a scripting layer and community content, running on an unsupported platform usually means running an old content set, because the newer content assumes the current engine.

The releases themselves are the stable 0.5.1 series, with 0.5.1 on 2025-02-07, 0.5.1.1 on 2025-06-22 and 0.5.1.2 on 2026-02-26.

Three licences and a couple of bundled third parties

The licence section is the most careful part of the README, and it splits the project into three categories.

The FreeOrion source code is licensed under the terms of GPL v2. The game assets are licensed under the terms of CC-BY-SA-3.0. The game content scripts are licensed under the terms of both GPL v2 and CC-BY-SA-3.0.

The split follows what each category is. Code is software, so it gets a software licence with its copyleft obligations. Artwork is a creative work, so it gets a Creative Commons licence that requires attribution and share-alike. The content scripts sit in between, because they are both code and the definition of game content, so they carry both sets of terms.

The practical consequence for a player who writes content is that a mod is a Creative Commons share-alike work, and redistributing it carries the attribution and share-alike requirements. The consequence for someone who wants to reuse the engine is that the code is GPL v2, and the code that ships with the game, such as the AI in the default/python/AI directory, is the part covered by both terms.

The README also flags the third party material bundled in the tree, because the licences differ. The GiGi library is in the GG/ directory, the Roboto font is in default/data/fonts/ and DejaVuSans is there as well. The accompanying licence file has the details.

There is a separate reference to default/COPYING for the full terms, and the note that additional bundled projects or assets may be under different terms than the project itself is the reason to read it rather than assume the GPL covers everything you find in the tree.

Building it, and the toolchain the project is moving towards

The repository is set up for a from-source build with CMake, and the README points at BUILD.md rather than duplicating the steps, which is the right call for a project with this many platform combinations.

The top level gives the shape. CMakeLists.txt is the build entry point, with a cmake/ directory of modules, and the source is split into the engine directories, Empire/ for the empire and government model, universe/ for universe generation and the object graph, combat/ for the combat system, network/ for the multiplayer layer, client/ and server/ for the two sides, UI/ for the interface, parse/ for parsing, and util/ for shared helpers. The default/ directory holds the shipped content, packaging/ holds the platform packaging, and snap/ is there for the Snap package.

Two directories point at where the project is going. godot/ and godot4/ suggest a client built on the Godot engine, and msvc2026/ suggests support for a newer Visual Studio than the 2022 that the project used before. Neither is described in the README beyond their presence, so it is fair to say that the project has an in-progress Godot client and a Visual Studio 2026 configuration, and not much more than that.

The Python tooling is where the content is kept honest. The pyproject.toml configures ruff for format and lint with pyrefly and ty for type checking, and the exclusion list shows which directories are not Python at all, while the source list names the directories that are, namely default/python, default/python/AI, default/python/universe_generation, default/python/charting, default/scripting, test-scripting and check. The mccabe complexity limit is set to 10.

The project is not archived and the last push was on 2026-10-18, so the work continues even in the months between stable releases, and the ChangeLog.md in the repository is where the detail lives.

Editorial conclusion

FreeOrion fits a player who wants a 4X game they can extend with their own species, technology and campaign scenarios, and a modder who would rather write content in a scripting language than patch a closed engine. It does not fit someone looking for a polished commercial release cadence, since the stable builds arrive roughly every six months while the interesting work lands in the weekly in-development builds, and it does not fit a platform outside the supported list. Verify three things before you commit: that your machine has an OpenGL 2.1 capable card and a display of at least 1280x800, which is the suggested minimum rather than a hard requirement, whether you want the stable release or a weekly build, since the stable installers are on GitHub and the weekly ones are on SourceForge, and what the licensing means for the content you write, because the scripts you author sit under both GPL v2 and CC-BY-SA-3.0 rather than one or the other.

Frequently asked questions

Official sources

1. freeorion/freeorion on GitHub
2. Issues
3. Project website
4. README
5. Releases