Making mods

A mod is a folder with a mod.json file and the files it changes or adds: texts, pictures, music, cards, commanders, bases, missions or events. You write mods in a text editor; you need no programming and no game engine. Players put the folder in the game's mods folder and switch it on in main menu → Mods.

This guide explains every file a mod can have, with all the values the game understands.

Contents: Quick start · What a mod can do · Where mods go · mod.json · Texts in several languages · Ids · Translations · Pictures · Music · Cards · Commanders · Bases · Changing the game's cards · Decks · Missions · Expedition events · Other texts · Testing and fixing a mod · Sharing a mod · The game's ids

Quick start

1. Download the example mod (on the website: https://soldivided.eu/modding.html; in the game's source: docs/modding/example_mod/). It has three cards, a token, a commander, a base, a ready deck, a mission, an Expedition event, a card back, pictures and a changed text.
2. Copy its folder, rename the folder (for example my_mod) and change "id" in mod.json to the same name.
3. Change the files (any text editor; save as UTF-8). Delete the files you do not need.
4. Put the folder in the game's mods folder: in the game, Mods → Open the folder.
5. In the game, Mods: tick your mod. The game asks to restart; changes to mods always need a restart.
6. Open Mods again and click your mod: under Skipped the game lists everything it could not read, with the reason. Fix it, restart, look again.

What a mod can do

• One mod can have any of these together. If it has anything from the ⛔ rows, the whole mod is offline only.
• Online play is off while an offline-only mod is on: the online buttons are grey and say which mod blocks them. The server plays every online battle itself with the game's own cards, and the other player would not see your pictures or backs anyway.
• Changes the rules: battles played while such a mod is on count as modded in the statistics.
• The campaign's rewards and enemies never use a mod's new cards. The tutorial always uses the game's own cards.

Where mods go

Mods → Open the folder in the game opens the right one. Each mod is one folder in it:

mods/
  my_mod/
    mod.json
    icon.png
    cards.json
    card_art/
      plasma_lancer.jpg
    translations/
      bg.csv

mod.json

Every mod needs it. Only id is required.

{
  "id": "my_mod",
  "name": {"en": "The Red Guard", "bg": "Червената гвардия"},
  "author": "Your name",
  "version": "1.0",
  "description": {"en": "What it does, in a sentence or two.", "bg": "Какво прави."},
  "replace_battle_music": false,
  "language_name": "Español"
}

icon.png next to mod.json (square, 128×128 is plenty) is the mod's picture in the Mods screen.

Texts in several languages

Every text in a mod's files (names, descriptions, briefings…) can be:

• one text for every language: "name": "Plasma Lancer"
• a text per language: "name": {"en": "Plasma Lancer", "bg": "Плазмен копиеносец", "zh_CN": "等离子枪兵"}

The game's languages are en (English), bg (Bulgarian) and zh_CN (Simplified Chinese). A language your text does not have shows the first one you wrote.

Ids

• Your cards, tokens, commanders, bases, decks, missions and events get your mod's id in front: plasma_lancer in the mod red_guard becomes red_guard_plasma_lancer. That is how two mods can both have a card called lancer.
• Inside your own mod, use the short id ("summon": "guard_drone"). The long one works too.
• To use something of the game (a card in a deck, a commander for an enemy), use its own id: mars_stormtrooper, mercer, fortified_bunker. See The game's ids.
• An id the game already has is not allowed: a mod called mars with a card stormtrooper would be mars_stormtrooper, a card of the game, so that card is skipped. To change a card of the game, use card_changes.json.
• A mod's card backs and backgrounds are mod_<mod id>_<file name>: card_backs/red.jpg in my_mod is mod_my_mod_red.

Translations — translations/<locale>.csv

A CSV file with two columns, key and text. The first line is the header:

key,text
UI_TAGLINE,The war for the Solar System
CARD_MARS_STORMTROOPER_NAME,Storm Trooper
UI_QUIT,"Quit, for now"

• The file name is the language: en.csv, bg.csv, zh_CN.csv, es.csv, de.csv, pt_BR.csv, …
• Fixing a language the game has (en, bg, zh_CN): put in only the keys you change, even one. Every other text stays the game's. Players of that language see your texts after the restart, without choosing anything.
• A new language (es, de, …): it becomes a choice in Settings → Display → Language once the file has at least 200 texts. "language_name" in mod.json is its name in the list. The player picks it there; a key you have not translated shows in English.
• Two mods with the same key: the one lower in the Mods list wins.
• All the keys with the Bulgarian and English texts are in the translation template (columns key,bg,en,text). The game also reads a text column, so you can fill in that column and use the file as it is.
• A text with a comma or a quote goes in quotes, and a quote inside is doubled: "He said ""no""".
• A new line inside a text: \n.
• %s and %d are filled in by the game (a name, a number); %% is a percent sign. Keep the same ones in the same order.
• Save as UTF-8 (with or without BOM). Windows line ends are fine.

Pictures

• PNG, JPG or WEBP. Keep the files reasonably small (a card picture as JPG is about 150 KB).
• <id> is the short id of your card (card_art/plasma_lancer.jpg) or the id of the game's card, commander or base (card_art/mars_stormtrooper.jpg), whose picture it then replaces.
• A card of your mod without a picture is drawn with a simple outline of the kind set in its art field (see Cards).
• A file that is not a readable picture is listed under Skipped and left out.

Music

• OGG Vorbis is best; MP3 works too.
• With "replace_battle_music": true in mod.json only your battle tracks play.
• Tracks are played in a loop, so make the end fit the start.

Cards — cards.json

{"cards": [
  {"id": "guard_drone", "token": true, "faction": "mars", "kind": "unit", "type": "ground",
   "subtype": "drone", "cost": 1, "attack": 1, "health": 1, "art": "drone",
   "name": {"en": "Guard Drone", "bg": "Охранителен дрон"}},
  {"id": "plasma_lancer", "faction": "mars", "kind": "unit", "type": "ground", "subtype": "infantry",
   "cost": 3, "attack": 3, "health": 2, "keywords": {"assault": 1},
   "abilities": [{"trigger": "on_play", "target": "enemy_ground", "effects": [{"damage": 1}]}],
   "name": {"en": "Plasma Lancer", "bg": "Плазмен копиеносец"},
   "flavor": {"en": "\"Closer. Always closer.\""}},
  {"id": "drone_nest", "faction": "mars", "kind": "unit", "type": "ground", "subtype": "station",
   "cost": 4, "attack": 0, "health": 5, "no_attack": true,
   "abilities": [{"trigger": "turn_start", "target": "none", "effects": [{"summon": "guard_drone"}]}],
   "name": {"en": "Drone Nest"}},
  {"id": "red_banner", "faction": "mars", "kind": "tactic", "cost": 2,
   "abilities": [{"trigger": "on_play", "target": "all_friendly_units",
                  "effects": [{"buff": {"attack": 1, "this_turn": true}}]}],
   "name": {"en": "Red Banner"}}
]}

The card's rules text is written by the game from its keywords and abilities, in every language: you do not write it.

Keywords

Abilities

{"trigger": "on_play", "target": "enemy_unit", "combo": false, "effects": [{"damage": 2}, {"draw": 1}]}

All the effects of one ability go to its target. To do two things to two different targets (deal damage to a unit and draw a card yourself), write two abilities.

"combo": true — the ability works only if you already played another card this turn.

If the player must pick a target and there is none, a tactic cannot be played (a unit can, without the ability).

Commanders — commanders.json

{"commanders": [
  {"id": "colonel_reza", "factions": ["mars", "earth"],
   "bonuses": ["infantry_atk_1", "drone_hp_1"],
   "power": {"trigger": "on_play", "target": "friendly_unit", "effects": [{"buff": {"keyword": "shield"}}]},
   "power_cost": 2,
   "name": {"en": "Colonel Nadia Reza"}, "bio": {"en": "A few lines about her."},
   "bonus_texts": {"drone_hp_1": {"en": "Your drones have +1 health.", "bg": "Дроновете ти имат +1 живот."}}}
]}

Bonuses (commanders and bases)

A bonus is written as an id: <who>_<what>_<number>.

<who> is all, ground, ships, infantry (infantry, engineers, androids), machine (ground units that are not infantry), tank, mech, artillery, fighter, drone, token, cheap (cost 1–2), big (cost 6+), tactic (cost only), any other subtype (cruiser), or a keyword (units that have it: camo_atk_1).

Special bonuses: base_hp_plus_N, base_defense_plus_N, turn_heal_base_N (your base heals N each turn), air_damage_plus_N (your ships deal N more to the base), tactic_damage_plus_N, regen_plus_N, first_tactic_draw (your first tactic each turn draws a card), base_heal_double.

The game has texts for the bonuses its own commanders and bases use (for example ground_assault_1, ships_cost_minus_1, infantry_hp_1, drone_atk_1, base_hp_plus_3); for any other bonus give its text in bonus_texts, or it shows as its id.

Bases — bases.json

{"bases": [{"id": "red_bastion", "faction": "mars", "health": 28, "defense": 6,
            "defense_type": "armor", "ability": "drone_atk_1",
            "name": {"en": "Red Bastion"},
            "bonus_texts": {"drone_atk_1": {"en": "Your drones have +1 attack."}}}]}

Changing the game's cards — card_changes.json

{"mars_stormtrooper": {"cost": 2, "attack": 4, "health": 3,
                       "name": {"en": "Storm Trooper Mk II"}},
 "mars_phobos_recruit": {"abilities": [{"trigger": "on_play", "target": "player", "effects": [{"draw": 1}]}]},
 "col_ceres_militia": {"keywords": {"taunt": 1, "shield": 1}}}

• The key is the id of a card or token of the game. Give only what you change: cost, attack, health, keywords, abilities, no_attack, name, flavor.
• keywords and abilities replace the card's whole list: write all you want it to have.
• The changes count everywhere: campaign (its rewards and enemies too), Expedition, against the AI, two players at one computer, missions. Not in the tutorial.
• Every changed card has a purple MOD mark; the Mods screen lists the cards a mod changes.
• If two mods change the same card, the one lower in the Mods list wins.

Decks — decks.json

{"decks": [{"id": "starter", "commander": "colonel_reza", "base": "red_bastion",
            "card_back": "mod_red_guard_back_red_guard", "name": {"en": "Red Guard"},
            "cards": {"plasma_lancer": 2, "drone_nest": 2, "mars_stormtrooper": 2}}]}

• A legal deck: exactly 40 cards, at most 2 of each, only cards of the commander's factions and neutral ones, no tokens. A deck that breaks a rule is still listed but cannot be played; its problems show in the deck builder.
• cards is {"id": copies} or a list of ids (["plasma_lancer", "plasma_lancer", …]).
• card_back is optional: a back of the game (back_sol, back_mars, back_earth, back_belt, back_lunar, back_laurel, back_navigator, back_ring_station, back_singularity, back_torch_drive) or of a mod (mod_<mod id>_<file name>).
• Decks are for your mod's own cards (so players can try them at once) and for your missions' enemies. To share a deck of the game's cards, use its deck code (Decks → Deck code): no mod needed, and it works online.

Missions — scenarios.json

A battle like a campaign mission. Players find it in the campaign, in the Mods tab next to the acts (at its planet on the map), and in the Mods screen. It gives no rewards; its stars are kept apart from the campaign's.

{"scenarios": [
  {"id": "landing", "planet": "mars",
   "title": {"en": "Landing"}, "briefing": {"en": "Destroy the outpost."},
   "tip": {"en": "Its base has armor: use many small units."},
   "after_win": {"en": "The outpost is ours."}, "after_loss": {"en": "We fall back."},
   "enemy": {"commander": "col_cmd_rook", "base": "base_hidden_asteroid", "ai": 0},
   "enemy_deck": "col_starter", "enemy_base": [20, 4],
   "enemy_units": ["col_ceres_militia", "col_belt_miner"],
   "arena": "base_hidden_asteroid", "turns": 10, "life": 50},
  {"id": "hold_out", "planet": "ceres", "after": "landing",
   "title": {"en": "Hold out"}, "briefing": {"en": "Hold out for 7 turns."},
   "enemy": {"commander": "earth_cmd_hale", "base": "base_ganymede_lab", "ai": 2},
   "survive": 7, "turns": 7, "life": 40}
]}

• The player plays with any deck they choose.
• A chain of missions: give each mission after the first an after. The map draws the route between them, the next one opens when the one before is won, and a win offers Next mission. Missions without after are open from the start, so a mod can have a chain and some single missions together.
• Each mod numbers its missions from 1. With two or more mods with missions on, the Mods tab has a list to show one mod at a time.

Expedition events — events.json

An event that can come up on the Expedition's map, with exactly two choices.

{"events": [{"id": "drone_cache", "title": {"en": "Drone cache"},
  "text": {"en": "A sealed military cache floats in the debris."},
  "choices": [
    {"text": {"en": "Guess the password"}, "chance": 0.5,
     "win": {"card": "high"}, "lose": {"life": -4},
     "win_text": {"en": "It opens."}, "lose_text": {"en": "It defends itself."}},
    {"text": {"en": "Sell the beacon"}, "effects": {"credits": 25}}]}]}

• A choice has effects (certain), or chance (0–1) with win and lose (risky), or nothing ({"text": …}: leave).
• win_text and lose_text are optional lines after a risky choice.

Other texts — texts.json

Any text of the game or of your mod by its key, in several languages at once:

{"UI_TAGLINE": {"en": "The war for the Solar System — now with the Red Guard",
                "bg": "Войната за Слънчевата система — вече с Червената гвардия"}}

The same as a line in each language's CSV; use whichever is easier.

Testing and fixing a mod

• Restart after every change to a mod's files (the game reads mods when it starts).
• Mods screen: a mod that cannot be loaded at all is red, with the reason (usually its mod.json). Under Skipped is everything the game had to leave out of a mod that loaded, and why: an unknown keyword, a deck with a card it cannot find, a picture it cannot read, … The rest of the mod still works.
• Common mistakes: a comma missing or one too many in a JSON file (paste it into any JSON checker); a text in quotes where a number is needed ("cost": "3" works, "cost": "three" does not); a short id where the game's long id is needed or the other way round; a file saved in another encoding than UTF-8.
• A value of the wrong kind is listed under Skipped and the default is used.
• Try a mod with a fresh deck in a battle against the AI: hover the cards to read the rules text the game wrote for them.
• Switching a mod off: decks with its cards stay but cannot be played until it is on again, an Expedition run loses its cards, and its pictures, music and texts are gone after the restart. A player's progress is not lost.

Sharing a mod

• Zip the mod's folder (the folder itself, not only the files in it) and share the zip: players unzip it into their mods folder.
• Do not include files of the game (its pictures, music or texts) — only your own work or work you may share. Say who made what in description.
• Mods that only change texts, backgrounds and music can be used online; everything else is for single player and two players at one computer.

The game's ids

• Cards: every card of the game, with its id, is in https://soldivided.eu/cards/cards.json ("id"), and on the card gallery: https://soldivided.eu/cards.html.
• Commanders: mercer, valez, vex, mbele, mars_cmd_drakos, mars_cmd_sato, mars_cmd_okafor, mars_cmd_lindqvist, col_cmd_rook, col_cmd_tamsin, col_cmd_ivanov, col_cmd_noor, earth_cmd_hale, earth_cmd_varma, earth_cmd_moreau, earth_cmd_chen, earth_cmd_kowalski, earth_cmd_adeyemi, corp_cmd_sterling, corp_cmd_kane, corp_cmd_voss, corp_cmd_lin, corp_cmd_brandt, corp_cmd_unit7.
• Bases: fortified_bunker, base_olympus_citadel, base_valles_dome, base_phobos_outpost, base_derelict_cruiser, comm_relay, europa_ice_mines, saturn_ring_station, base_ceres_port, base_pallas_refinery, base_hidden_asteroid, base_comet_station, orbital_station, lunar_shipyard, base_luna_command, base_geneva_spire, base_l5_fortress, base_neptune_watch, base_corp_arcology, base_venus_platform, base_mercury_mine, base_titan_harbor, base_ganymede_lab, base_tycho_station.
• Ready decks: mars_starter, col_starter, earth_starter, corp_starter.
• Texts: every key is in the translation template. A card's name is CARD_<ID>_NAME and its flavor CARD_<ID>_FLAVOR; a commander's name CMD_<ID>_NAME; a base's name BASE_<ID>_NAME (ids in capitals).