Your First Mod

A map is a scenario: terrain, placed units, players, triggers. A mod is a portable package of changes that applies on top of a map. No terrain, nothing placed.

That difference is the whole point. One balance mod plays on every map. One map plays with or without it.

The learning path so far:

1. Your First Map.
2. Your First Win Condition.
3. Your First Custom Unit.
4. Your first mod (this page).
5. Publish and Iterate.

Twenty minutes, and it starts from the map you already have.

Step 1: build the changes on a map first#

This is the workflow, and it is not a shortcut. Make the changes on a test map, where you can see them, play them and fix them:

• Data overrides in the Data module (F7).
• Triggers in the Triggers module (F6).

A mod is exactly those two things plus any sounds and models they reference. If it works on the test map, it is ready to become a mod.

Step 2: export it#

File → Export Standalone Mod (.sosmod)…

That writes a package containing the map's data overrides, its trigger script, and its sound and model references. It does not contain the terrain, the placed units or the player roster.

The export fills in the boring fields for you, and its guesses are placeholders:

• id comes from the map name, lowercased, with other characters turned into _.
• version is 1.0.0.
• author is Forge Modder.

The trigger script is only exported when it has at least one trigger or variable, so a pure balance mod comes out with no triggers block at all.

Step 3: fix the fields the export guessed#

Open the file in a text editor. It is JSON, and it is meant to be read.

Set id, name, version, author and description properly. The id is 1 to 64 characters of lowercase letters, digits, _ and -, starting with a letter or digit, and it is what a share link will carry, so choose one you can live with.

version must be MAJOR.MINOR.PATCH. Anything else is a warning, and it breaks version ranges for anyone who depends on your mod.

This is a complete, working mod, and it is the unit from the previous page made portable:

{
  "formatVersion": 2,
  "id": "my_marksman",
  "name": "The Marksman",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "Adds a long-ranged dwarf archer, trainable at the barracks.",
  "defOverrides": {
    "units": [
      {
        "id": "myvault_marksman",
        "baseId": "dwarf_crossbowman",
        "patch": { "name": "Marksman", "range": 10, "hp": 60, "cost": { "gold": 140 } }
      }
    ],
    "buildings": [
      { "id": "dwarf_barracks", "patch": { "produces": { "$append": ["myvault_marksman"] } } }
    ]
  }
}

Nine lines of metadata and the change itself. That mod now plays on any custom map in the game.

Step 4: validate it#

Two ways, and they agree:

npx tsx tools/validate.ts my_marksman.sosmod

or paste it into /tools/validator in the browser, which needs no checkout and has a Test in Game button that launches it on a blank map.

The example above reports:

PASS my_marksman.json [Mod Package (.sosmod)] 0 error(s), 0 warning(s)

A package with no overrides, no triggers, no sounds and no models is valid and gets a warning, because it does nothing. That warning is usually the sign that the export ran before you made the change.

Step 5: play it#

A mod is applied when a custom map is launched. It is never baked into a map you save.

• From a file. The map browser and the multiplayer lobby's custom-map panel have a Mod control: Load .sosmod picks a file, Clear removes it. The choice lasts for that browser tab.
• From a link, for mods hosted on the site: /play?customMap=<map>&mod=<id>. The two sample mods work this way, for example the Ironclad balance mod on the tower defence showcase.
• From the validator, with Test in Game.

Mods only apply to custom maps. The campaign and ordinary skirmish are never modded.

The multiplayer rule, which is better than you expect#

Only the host needs the mod.

The host's game resolves the mod and its dependencies, merges everything into the map, and sends the merged map to everyone, along with a checksum and the mod's id and version. Every player's game checks that checksum before the match starts, and again at the start signal.

If anything differs, the match does not start. The message says Map integrity check failed and shows both checksums. It does not let the match begin and desync twenty minutes later, which is what the equivalent mismatch did in older engines.

Guests see a read-only Mod: name vversion line in the lobby, so nobody is playing a modified game without knowing.

What a mod may carry#

A whole package is at most 4,194,304 bytes, and a single embedded data: URI at most 262,144 bytes. Host anything bigger on a server and reference it by URL. An http:// URL is an error; it must be https://.

Two things about trigger mods specifically#

Regions travel with the script. Triggers refer to regions by id, so the export carries the regions too, with the coordinates from your test map. A mod whose triggers use regions therefore only makes sense on maps laid out the same way. When the mod is applied, a region with the same id on the target map is replaced by the mod's copy.

A balance mod has no such problem, which is why balance mods are the easy first mod and trigger mods are the second.

To bring a mod's changes back into a map you are editing, use File → Import Standalone Mod (.sosmod)…. It merges the overrides, triggers, sounds and models into the map, so mod:<key> model references keep working in the saved map, in Test Map and once published.

Sharing it#

There is no mod gallery yet. Share the .sosmod file however you share files, and players load it with Load .sosmod. Mods hosted in the game's own /mods/ folder, which today means the two samples, also work with ?mod=<id> links.

That is an honest gap rather than a hidden feature. If you want your changes in front of people today, the reliable route is to publish a map that already contains them, which is the next page.

Common first mistakes#

Where to go next#

• Mods is the full reference: the two sample mods line by line, merge order, dependencies and version ranges.
• Compatibility & Versioning explains every version number and what the game enforces about each.
• Custom Units & Models covers shipping a 3D model inside a mod.

Next: Publish and Iterate.