SOVL Modding Guide

Open the editor

How to build a custom faction, get it into the game, and put it on the Steam Workshop.

A mod adds a faction: its units, their stats and points, the rules they carry, and your own art. Units are assembled from the game's existing catalog of 274 unit properties, plus properties you define yourself out of the effects listed further down.

Getting started

1. Build the faction

Open the mod editor. Everything runs in your browser and your work is kept in the browser's own storage, so you can close the tab and come back to it.

Start at Mod & Faction and fill in a mod id — lower case, no spaces. It is the name of your mod's folder and the prefix on everything inside it, so pick it before you build much.

Then, roughly in this order:

  1. Images — drop in your PNGs. Include one named preview.png; the Workshop needs it.
  2. Sections — how many units of each kind an army may take. Commanders and BattleLine come as standard and cannot be removed.
  3. Units — a unit per entry, with stats, points, art and properties.
  4. Properties — only if the built-in ones do not cover what you want.

The bar along the bottom lists what is still wrong. A mod with problems will not load, so clear it before you export.

2. Get it into the game

Press Export mod.zip. Unzip it into the game's mods folder, so that the folder holding manifest.json sits directly inside mods:

%USERPROFILE%\AppData\LocalLow\DalenStudios\SOVL\mods\
└── yourmodid\
    ├── manifest.json
    ├── preview.png
    ├── factions\
    │   └── yourfaction.json
    └── images\
        └── *.png

The quickest way there is Mods → Open folder in the game, which opens that exact directory.

The game cannot import a .zip for you yet — see What is not in yet. Unzip it by hand for now.

3. Load it

In the game: Mods, then turn modding on. Your mod appears in the list.

Reload picks up changes without restarting, so the loop while you are working is: edit in the browser, export, unzip over the old folder, Reload.

Build a list in the army editor, then play it in a custom game against the AI. That is the only place mods run for now.

4. Publish to the Workshop

Select your mod in the Mods panel and press Publish. The first publish creates a new Workshop item; after that the same button updates it, because the item's id is written into workshop.json in your mod folder. Keep that file — delete it and your next publish makes a duplicate item instead.

Publishing needs all of:

Subscribers get it automatically. Subscribing or unsubscribing while the game is running works too; the game notices and reloads at the main menu, never mid-battle.

Everything in the mod folder is uploaded, so delete any stray files first — backups, source art, notes.

5. Update your Workshop item

Publish again from the same mod folder. As long as workshop.json is still in it, the game updates your existing item instead of making a new one. The loop:

  1. In the editor, Open mod folder and pick your installed mod folder (or Open mod.zip with your last export). The editor remembers its workshop.json and puts it back in the next export.
  2. Make your changes and Export mod.zip.
  3. Extract the zip over your mod folder, replacing the files, then Reload in the Mods panel and check it loads.
  4. Publish.

Lost workshop.json? Publishing makes a second item. Delete the old one from your Workshop page so subscribers are not left with two.

Starting from someone else's mod — Workshop downloads live in steamapps\workshop\content\1870300\<item id> in your Steam library. Open that folder in the editor, then change the mod id before you export, so your version installs beside the original instead of clashing with it. You can only publish updates to items you made.

Common surprises

The questions that came up most on Discord.

What is not in yet

An honest list of the edges. Some of these are coming, some are deliberate.

Where mods can be played

Custom game against the AI only. Mod factions show up in the army list editor and in a custom game against the AI, and nowhere else — not multiplayer, ranked, campaign, or grand strategy.

Multiplayer is the one most likely to change. It needs both players to be able to prove they have the same version of the same mod, and that does not exist yet; without it, two players could silently fight different battles. Campaign and grand strategy tie factions to hardcoded progression, which is a much larger job.

Achievements and leaderboards are switched off for the rest of the session once a mod is used in a battle. Restart the game to get them back.

Rules you cannot author

Content you cannot add

Rough edges

The editor in detail

The buttons along the top

Open mod folder Load a mod you already have installed, to keep editing it, or one you subscribed to on the Workshop. Point it at the folder containing manifest.json, or the folder just above it. Firefox cannot pick folders — use Open mod.zip there.
Open mod.zip Load a mod from a zip: one the editor exported, or a mod folder someone zipped and sent you. Anything the game loads opens here, hand-written JSON included.
Start over Throws away the current draft. There is no undo.
Export mod.zip Downloads the whole mod. A browser can only hand you one file at a time and a mod is many, so a zip is the only way out.

Mod & Faction

Mod id names your folder and prefixes every id inside it, which is what keeps two mods from colliding when a player installs both. Lower case, no spaces.

Display name, author and version are what players see in the Mods panel and on the Workshop.

The faction's slug names its file; its display name is what appears in the faction picker.

Material template decides how your models take faction colouring — pick whichever existing faction looks closest to yours. Faction image is the banner in the faction picker.

Colours are indices into the game's shared 64-colour palette (0–63), used as the faction's default primary, secondary and icon colours.

Images

PNG only, up to 2048px square and 4 MB each. Names must be unique; they are how everything else refers to them.

One must be named preview.png — it is the Workshop thumbnail, and is not usable as unit art.

Draw art top-down. The battlefield camera looks down, and a model has to read well facing any direction; front-facing art looks wrong on the table.

Sections

A section is a row in the army builder — Commanders, BattleLine, and whatever else you add. For each army size (Warband 500pts, Battalion 1000, Legion 1500, Border Patrol 650, Unrestricted) you set the minimum and maximum number of units an army may take from that section. A minimum of 0 makes the section optional.

Commanders and BattleLine are required and cannot be deleted.

Units

Kind is regiment (a block of models) or character (a single commander).

Regiments additionally set models per regiment per army size — tick an army size and give the minimum and maximum model count. An unticked size does not ban the unit: it can be taken there at any size from 1 to 100 models. To keep a unit out of an army size, limit its section in that size instead.

Characters instead get a retinue: which regiments the commander may join, or which mounts it may ride (tick as a mount). Tick fights alone for a commander that needs no retinue.

Properties

The rules a unit carries. Built-in properties and ones you defined both appear in the list, and the built-in ones show their description once selected.

SelectorWhat it does
builtin The unit always has this property, at no extra cost.
optional The player may buy it when building a list, for extra points.
pickOne The player chooses one from a set, each with its own cost.
spellList, enchantments, banners Opens the game's existing spell, magic item or banner selection for this unit.

Model graphics

The sprites drawn per model on the battlefield. Add several sprites and one is picked at random per model, which is what stops a regiment looking like a photocopy. Up to 8.

The first card is the unit's default look. To change the look when the player picks an option — a flamer, a great weapon — add another card and set Only with to that option. Only options the unit can buy (optional or pickOne) are offered there.

Steeds are what make a unit cavalry: add steed sprites and the sprites above ride on top of them. Draw steeds long and narrow — they render wider than they are tall.

Scale multiplies the model's size; 1.85 is what the built-in units use.

Rider offset appears once you add steeds. Positive moves the rider towards the rear — which is what a chariot wants, since the driver does not stand in the middle of it.

Mirror some models flips a random half of them horizontally for variety. Only tick it for symmetrical art; anything with a shield on one arm will look wrong mirrored.

Custom properties

Only worth writing when nothing among the built-in 274 fits.

Id must start with yourmodid:. Applies to decides whether the rule works on each Model individually or on the Unit as a whole.

A property holds up to 8 effects:

Effect
statModifierChange a stat.
movementAdd to movement, or replace it outright.
toHit, damageSaveShift the rolls to hit, or to save.
combatScore Add to the combat result that decides who wins a round.
doubleWoundsDouble the wounds caused.
extraRankAttacksAttack from an extra rank.
rangedAttackBonusModify a ranged attack.
disciplineChange discipline tests.
regenerationRecover wounds.
deploymentChange how the unit deploys.
ignoreDifficultTerrain, ignoreImpassableTerrain Move through terrain.

Each effect has a When, which is what makes a rule interesting rather than a flat bonus:

charging, inCombat, firstRound, flankOrRear, melee, ranged, monstrousTarget, withCommander, targetUnitType, and allOf / anyOf to combine them (nested up to 4 deep).

Leave When empty and the effect is always on.

Collected from decides who the effect lands on — ownerUnit (the unit carrying the property) or opponent (whoever it is fighting). Aura extends it to the unit a commander has joined.

Abilities

Tick Activated ability on a property to turn it from a passive rule into something the player triggers in the strategic phase — your own Warcry, Reposition, Regrowth or Fireball. A unit can use one ability per turn (its commander one more) and still move afterwards. The AI uses them too: attacks when it shoots, buffs and debuffs once units are in combat.

What it does:

Give it an icon (a small square PNG) for the button. Mods with abilities need this version of the game or newer; the editor marks them as such, and an older game says so instead of loading the ability as an always-on rule.

Limits

Units per faction60
Sections per faction12
Custom properties per faction40
Effects per property8
Condition nesting depth4
Model sprite variants8
Stats0–20
Points cost1–2000
ImagesPNG, 2048px square, 4 MB
preview.png1 MB