Getting Started

Fall of an Empire is built to be modded, and the whole thing is designed to be as painless as possible. Almost everything in the game - the traits, buildings, units, diplomatic actions and events, and even whole campaigns set in other parts of the world - is content that the game discovers and loads while it runs, rather than something baked into the executable. What that means is you can add your own content without a copy of the engine, without recompiling anything, and for the most part without touching the base game's files at all.

The three things you can make

There are really three layers you can work with, and you're free to use any mix of them.

The first is campaigns: a whole scenario, with its landscape, rivers, provinces, settlements, factions and characters. You build these visually in the World Editor, and you don't need to write a line of code to do it.

The second is gameplay content - traits, buildings, units, interactions, policies, events, cultures, religions. These are written in AngelScript, a small scripting language that reads a lot like C#. You drop a file into a folder and the game finds it.

The third is the interface: new screens, sidebars and toolbar buttons. The whole of the game's UI is a React and TypeScript app, and mods extend it the same way the base game is built, through a small published SDK. There's a page on that too, Mod Screens.

Plenty of mods only ever use one of these. A pack that swaps out a few icons is perfectly valid, and so is a total conversion that ships a new map, a hundred script files and its own management screen. It's up to you and how far down the rabbit hole you want to go.

What a mod actually is

A mod - or content pack, as it's also called here and there - is really just a folder. It lives under Mods/ in the game directory, and the game recognises it by a single file called mod.json. Everything else in the folder is optional, and only there if your particular mod needs it.

The packaged game creates that Mods/ folder for you, so there's always a known place for players to drop mods into.

mod.json

This is the one file the game insists on. At the very least it needs a stable id, a display name, a version, a kind, and a numeric loadOrder:

{
  "id": "com.yourname.lords-of-sicily",
  "name": "Lords of Sicily",
  "version": "1.0.0",
  "kind": "Mod",
  "loadOrder": 100
}

The id is permanent, so it's worth choosing carefully - other mods depend on it, save games reference it, and the Workshop tracks it, so once people are using your mod you really can't change it. A reverse-domain string like the one above works nicely. The loadOrder decides who wins when two mods touch the same thing: higher numbers load later and sit on top, with the base game loading first and each pack after it in ascending order. And kind is one of Base, Dlc or Mod - for a player mod it's Mod.

Everything beyond that is opt-in, and you add it as your mod grows to need it. A fuller descriptor might look like this:

{
  "id": "com.yourname.lords-of-sicily",
  "name": "Lords of Sicily",
  "version": "1.0.0",
  "kind": "Mod",
  "loadOrder": 100,

  "dependencies": [],
  "incompatible": [],

  "scripts": { "roots": ["Script"] },
  "content": { "roots": ["Content"] },

  "campaigns": [
    { "id": "SicilySouthernItaly827", "path": "Data/Maps" }
  ],

  "webui": {
    "localization": "WebUI/Localization/{locale}.po",
    "entries": [
      { "id": "sicily_command", "script": "WebUI/dist/index.js" }
    ],
    "styles": ["WebUI/dist/style.css"]
  }
}

Not every block is worth explaining here, because each one belongs to a system that has its own page - the campaigns block goes with the World Editor, scripts with AngelScript, webui with Mod Screens, and the rules for switching base content off live in Disabling & Overriding Content. The game reads mod.json when it loads your mod and ignores anything it doesn't recognise; if something is malformed, it shows up in the in-game Mods manager.

The tools

The game ships the modding tools in ModdingTools/:

ModdingTools/AngelScriptSDK/as.predefined is what VS Code needs for AngelScript autocomplete. It contains the C++ and UObject API exposed by the game, and VS Code can complete calls into all the game types.

The full setup is covered on the AngelScript page.

Learning from the examples

The quickest way to get a feel for any of this is to read a mod that already works. There are three complete World Editor projects published:

• foae-worldeditor-tutorial is the smallest complete example, and a good place to start if you just want to see the minimum shape of a working campaign.
• foae-worldeditor-campaign is a larger scenario that shows how a full campaign is laid out.
• foae-worldeditor-sicily is Lords of Sicily, and it's the one worth studying most closely. It's a finished, published mod that uses nearly everything in this guide - a custom map, script content, and its own WebUI screen - so if a feature exists, there's a fair chance Sicily is using it somewhere. It's also on the Steam Workshop to play.

Each of those repositories holds the World Editor source for its campaign - the project you actually open in the editor - which is the format you'll be working in yourself.

To see how the base game does something, the whole of the game's UI is open source at fall-of-an-empire-ui. It's the same code your mod screens sit alongside, so it's the best reference there is for how the SDK and bridge are meant to be used.

Where to go next

From here it depends on what you're building. If it's a scenario or a map, head to the World Editor. If it's gameplay content, start with AngelScript and then Hooking Into Game Systems. If it's a screen or a panel, that's Mod Screens. If you want to switch base content off or override it, see Disabling & Overriding Content. And when you're ready to share what you've made, Testing & Publishing covers getting it onto the Workshop.