Downloads

Both also come with the game, in Primacy_Data\StreamingAssets\ModKit\, and the Mods window opens them for you.

Making mods for Primacy

A mod is a folder of plain text files: spreadsheets (CSV) you can edit in Excel or any text editor, a few JSON files, PNG pictures and small Lua scripts. There is nothing to install and nothing to compile. You put the folder in your mods folder, switch it on in the game's Mods window, and the game uses it from its next start. When it works, you publish it to the Steam Workshop from the same window.

What a mod can change: every country's start figures, cities (rename, change, remove, add), country names, flags and colours, brand-new countries, who owns each province, province names, tech nodes, Situation Room events, Government policies, new starts (scenarios), icons, fonts, translations, and rules written in Lua. What it cannot change: province shapes, rivers, coasts, terrain, the satellite picture, the tutorial, and game code (.dll files cannot be loaded).

Your first mod, step by step#

1. Start the game. On the main menu click Mods.
2. Click Example mod. The game copies a working example into your mods folder (Documents\My Games\Primacy\Mods\example-mod). It appears in the list, switched off.
3. Click Open mods folder. Copy the folder example-mod and rename the copy, for example my-first-mod.
4. Open my-first-mod\mod.json in a text editor (Notepad works). Change "id" to "my-first-mod" and "name" to a name you like. The id must be unique: two mods with the same id cannot run together.
5. Make one change. For example open tables\countries.csv and change Poland's unemployment: POL,=0.08, means "set it to 8%".
6. Back in the game, close the Mods window and open it again (it reads the folder again). Switch your mod on and click Apply & restart (hold the button). The game restarts its session with your mod.
7. Open Mods again. Your mod's row says Running and how many values it changed. If something is wrong it says how many problems its files have; click Mods log to see each one with its file and line.
8. Start a new game as Poland and look at unemployment. That is a mod.

Where everything is#

Finding ids and names#

Every key a mod file uses comes from a file in the reference folder. Open them in Excel (Data → From Text/CSV, choose UTF-8) or a text editor and search with Ctrl+F.

Tools: the Mods window, the console, the log#

The Mods window (main menu → Mods)

• The list: every installed mod with its picture, version, tags and whether it changes gameplay. Its state line says Running (and how many values it changed), "On after a restart", "Off", "Cannot run: …" with the reason, or the first error in its mod.json.
• The switch turns a mod on or off. Up / Down set the order (the top mod applies first, a lower mod wins over it).
• Publish (local mods) uploads to the Workshop; Page (Workshop mods) opens its Workshop page.
• Language: English and every language an installed mod offers.
• Example mod, Modding guide, Reference files, Mods log, Open mods folder, Open Workshop.
• Apply & restart (hold): the game's session starts again with the new list. It is only active when your list differs from what runs now.

The console (press the ` key, left of 1)

The mods log

14:02:11      Running, in this order: Example mod (example-mod v1.0), My mod (my-mod v0.1); language en
14:02:12 ERROR my-mod: cities/cities.csv line 4: no key "POL.lods" in cities (write "new:POL.lods" to add it)
14:02:12 warn  conflict countries POL unemployment: set by example-mod, my-mod; my-mod wins
14:02:12      my-mod: 12 values changed, 1 problems
14:02:12      Applied in 640 ms
14:30:05      [my-mod] January 2026: Poland's debt is 61%

mod.json#

Every mod folder needs a mod.json at its top. Without it the folder is not a mod.

{
  "id": "polish-golden-age",
  "name": "Polish Golden Age",
  "version": "2.0",
  "game": "0.1+",
  "description": "Poland's rise: a richer start, the Amber Coast and new events.",
  "tags": ["Scenario", "Countries", "Events"],
  "gameplay": true,
  "loadAfter": ["real-balance-2025"],
  "needs": [],
  "dlc": []
}

Other files at the top of a mod

• preview.png (or .jpg): the mod's picture in the Mods window and on the Workshop. 512×512 or 1024×1024, under 1 MB.
• workshop.txt: written by the game when you first publish; it holds your Workshop item number. Keep it: it makes your next upload update the same Workshop page.

The folder

my-mod/
  mod.json                 required
  preview.png              optional picture
  tables/countries.csv     country start figures          → Country figures
  cities/cities.csv        cities                          → Cities
  map/countries.csv        country names, new countries    → Country names
  map/owners.csv           who owns which province         → Who owns the land
  map/provinces.csv        province names                  → Province names
  tech/nodes.csv           tech nodes                      → Tech tree
  events/*.json            Situation Room events           → Events
  policies/*.json          Government policies             → Policies
  scenario/start.json      a start of its own              → Scenarios
  military/equipment.csv   weapons each country has        → Equipment
  military/weapon-types.csv each weapon type's stats, new types → Weapon types
  military/air-stats.csv   aircraft numbers by role and generation → Aircraft numbers
  military/naval-stats.csv warship numbers by hull class   → Warship numbers
  military/air-bases.csv   airfields for squadrons         → Air bases
  military/naval-bases.csv naval bases                     → Naval bases and navies
  military/navies.csv      ships by class per navy         → Naval bases and navies
  transport/airports.csv   civil airports                  → Airports and seaports
  transport/seaports.csv   seaports                        → Airports and seaports
  diplomacy/organisations.csv the UN, NATO, the IMF... and new ones → Organisations
  diplomacy/*.csv           trade deals, sanctions, treaties, disputes, bases... → Diplomacy
  military/warheads.csv    nuclear stockpiles          → Diplomacy and warheads
  military/navies.csv      (see above)
  scripts/*.lua            rules in Lua                    → Lua scripts
  pictures/flags/POL.png   a country's flag                → Flags and icons
  pictures/icons/<key>.png an icon                         → Flags and icons
  fonts/*.ttf, *.otf       letters the game lacks          → Fonts
  lang/<code>/language.json + *.csv   a translation       → Translations

Every part is optional except mod.json. A file in a folder the game knows but with a name it does not (for example tables/countrys.csv) is reported in the log, so a typo is found at once.

CSV and JSON rules#

How tables change values#

A table file does not replace the game's table: it lists only the rows and columns you change. The first column is the key (a country code, a city key, a node id…); the other columns are any of that table's columns, in any order, as few as you like.

• Remove a row (cities only): put remove in the second cell: UKR.pripyat,remove.
• Add a row (cities only): start the key with new: and fill every needed column: new:POL.amber-port,Amber Port,54.40,18.20,120000,no,3.
• * and + only work on numbers; text can only be set.
• A wrong line is reported and skipped; the rest of the file still applies.

Order, conflicts, restarts and saves#

When a mod applies

Once, while the game starts (before the map, borders, cities and names are built). Changing the mod list or the language therefore needs Apply & restart; a running game never mixes two mod lists. modsreload in the console does the same after you edited files.

Order

Mods apply from the top of the list to the bottom, moved only as far as each one's loadAfter needs. A later mod's = wins over an earlier one; * and + stack: VAT 23% with mod A =0.25 then mod B *0.8 gives 20%.

Conflicts

A value two mods both set with = is a conflict. It is not an error: the lower mod wins, and the Mods window and the log say which value, which mods and who won.

Saves

• A save remembers its mods and their order.
• A save loads only with the same gameplay mods in the same order. Otherwise the game shows which mods it needs, offers Subscribe to all (Workshop mods) and Use this save's mods (switches your list and loads the save).
• Looks-only mods ("gameplay": false) can be added or removed at any time.
• A newer version of the same mod is allowed: Workshop mods update themselves. Keep your updates compatible with saves made with older versions.

Country figures#

Every number of every country at the start of a game: people, health, schools, safety, the economy, the budget and the forces. The key column is iso3, the country code (see lists\countries.csv). A country you change gets these values from day one; the economy, the forces and everything else are built from them.

iso3,population,unemployment,health.beds,militarySpending
POL,*1.05,=0.04,,
HUN,,,+0.5,
ISR,,,,=0.06

Cities#

Rename a city, change its population, make it the capital, set how developed it looks, remove it, or add a new one anywhere on land. The game builds everything else from the list: buildings and night lights, map labels, offices and homes; the city's owner is the province it stands in.

key,name,lat,lon,population,capital,level
RUS.saint-petersburg,=Leningrad,,,,,
RUS.volgograd,=Stalingrad,,,*1.5,,=5
POL.lodz,remove
new:POL.amber-port,Amber Port,54.40,18.20,120000,no,3

• Removed city: its buildings and label go; its people stay in the province's figures. A stadium, holy site, station or airport it had serves the nearest city of the same country.
• New city: needs name, lat, lon and population. Its people come from its province (the province's total stays the same). Buildings grow by themselves.
• Adding or removing cities needs a new game (saves remember cities by their place in the list). Renames also work with old saves.
• A name with letters the game's fonts lack (Москва, 東京) works: the letters come from a fallback font.

Country names and new countries#

iso3,name,short,adjective,flag,colour
RUS,Union of Soviet Socialist Republics,Soviet Union,Soviet,flags/SOV.png,#a8322f
KUR,Kurdistan,Kurdistan,Kurdish,flags/KUR.png,#c8a040

• A renamed country keeps all its figures; the game's own data still finds it by its old name.
• A new country starts with nothing: give it land in map/owners.csv. It builds its economy from the provinces it gets, like a state born from a revolt.
• Rows apply before owners.csv, so a new country can receive land in the same mod.

Who owns the land#

from,to
UKR,RUS          # every province of Ukraine to Russia
BLR,RUS
IRQ-2201,KUR     # one province to the new country Kurdistan

• from: a country code (every province it owns now) or a province id (one province). Province ids are in map\provinces.csv (column id, with its name and owner).
• to: a country code, including a new country made in map/countries.csv.
• Moves run top to bottom, before day 1, with the same annexation wars use: people, farms, industry and cities go with the land.
• A country left with no land stays in the game (it can come back), like one that lost a war.
• Province shapes never change: you can only give whole provinces.

Province names#

id,name
RUS-2155,=Leningrad Oblast

The id comes from map\provinces.csv in the reference. Only the name can change; the owner column there is for information (owners change in map/owners.csv). Renames work with old saves.

Tech tree#

id,name,cost,year,weight,odds
comp.net.mobile-broadband,,*0.9,,,
enrg.fusion.compact-q1,=Compact fusion,,=2040,,

Finding the id: open tech\nodes.csv in the reference and search the node's name as the tech tree shows it. The first column is the id. The columns field, branch and era tell you where it sits (for example "Compute & AI", "comp.net", "The Digital Age").

Situation Room events#

Any number of .json files in events/. Each has "add" (new events), "change" (the game's or another mod's events), or both.

How events are picked

Each month the game weighs every event that may happen to a country: its weight formula gives a number (0 = cannot happen now). One event is picked with chances in proportion to the weights (an "Opportunity" counts ×1.25). An event does not come back to the same country before its cooldown (months); the player does not get two events of the same family within 75 days. Typical weights: 0.02 (rare) to 0.5 (likely).

{
  "add": [ {
    "id": "pga.vistula_boom",
    "family": "Economy", "tone": "Opportunity", "scope": "Player", "place": "BigCity", "other": "None",
    "countries": ["POL"],
    "cooldown": 48, "days": 7, "big": false, "chainOnly": false,
    "weight": "0.04 + ramp(gdpPerHead, 15000, 40000) * 0.06 * (atWar ? 0.5 : 1)",
    "title": "Factories flock to the Vistula",
    "text": "Three carmakers want to build near {place}. They ask for {money:0.2} in tax breaks.",
    "facts": [ ["Jobs", "{num:900-4000}"], ["Asked for", "{money:0.2}"] ],
    "voices": [ ["Economy minister", "Say yes before Hungary does."], ["Finance minister", "Every factory wants a gift."] ],
    "choices": [
      { "name": "Tax breaks", "about": "Pay to win them", "fx": "cost:0.2 gdp+0.3@24 mood:Business+3@12",
        "riskP": 0.2, "riskText": "One carmaker takes the money and leaves.", "riskFx": "ap-3@6",
        "echoP": 0.5, "echoMonths": 12, "echoEvent": "pga.vistula_second_wave", "echoText": "A second wave of investors calls." },
      { "name": "Let them come", "about": "No money from the state", "fx": "gdp+0.1@24", "hold": false, "notes": ["Slower"] }
    ],
    "none": "mood:Business-2@6",
    "noneText": "Nobody decided. The carmakers went to Hungary.",
    "worldNews": "{country} lands three car factories."
  } ],
  "change": {
    "volcano": { "off": true },
    "hostages_abroad": { "weightMul": 0.5, "cooldown": 60 },
    "quake": { "title": "The ground shakes in {place}", "days": 5 }
  }
}

Every field of an added event

Every field of a choice

Changing an existing event ("change")

Text templates#

Effect words#

Effects are short words separated by spaces: cost:0.2 gdp+0.3@24 mood:Business+3@12. @n at the end means "for n months" (the effect fades over that time); without it, it is immediate or permanent. All numbers use a dot for decimals.

Chance formulas#

A formula is a text in quotes. It is worked out for each country each month; the result is the event's weight (0 or less = it cannot happen).

"0.03"                                        always the same
"atWar ? 0.2 : 0"                             only at war
"ramp(unemployment, 0.06, 0.15) * 0.4"        grows with joblessness
"0.05 + (approval < 35) * 0.1"               likelier when unpopular
"coastal && month >= 6 && month <= 9 ? 0.1 : 0" summer, on the coast

Values a formula can read (the country being weighed)

Government policies#

Change the game's policies, or add new sliders. A new policy appears in its ministry in the Government window, is signed like any other, waits, then phases in. Ids: policies\ids.txt.

{
  "change": {
    "incb": { "max": 60, "wait": 2, "name": "Income tax (flat)", "about": "One rate for every worker." }
  },
  "add": [ {
    "id": "pga.amber_fund",
    "ministry": "Industry",
    "name": "Amber Coast fund",
    "about": "State money that makes the coast attractive to investors.",
    "examples": "Like Ireland's 1990s grants",
    "unit": "%", "min": 0, "max": 2, "step": 0.1, "default": 0,
    "wait": 3, "ramp": 12, "stage1": "Parliament", "stage2": "Money flows",
    "levers": [ { "stat": "InvestmentAttractiveness", "perUnit": 1.5 },
                { "stat": "Corruption", "perUnit": 0.5 } ],
    "forecast": "gdp .02 .05 bal -.03 -.01",
    "upBetter": ["Investors come to the coast"], "upWorse": ["Costs the budget"],
    "downBetter": ["Saves money"], "downWorse": ["Fewer new firms"],
    "whoUp": "Business +", "whoDown": "Business -"
  } ]
}

Changing a policy

min, max, step (slider range), wait (months until it starts), ramp (months until full effect), name, about, examples.

Every field of a new policy

Scenarios#

A scenario is a start of its own. Combine it with map/countries.csv and map/owners.csv for a different world on day one. It shows on the nation pick's GAME SETUP strip. If two running mods have one, the game merges them setting by setting: a setting a mod leaves out keeps what a mod above it gave (a scenario without year keeps another mod's year), a setting both give is the lower mod's (shown as a conflict), and their wars add up.

{
  "name": "The Soviet Union returns",
  "description": "Russia has taken back the Soviet republics. Poland and Finland stand alone.",
  "keepGameWars": false,
  "wars": [ {
    "attacker": "RUS", "defender": "POL", "since": "2024-12-20",
    "held": [ [ [23.5,52.1], [24.2,52.1], [24.2,51.6], [23.5,51.6] ] ],
    "fronts": [ { "name": "Brest", "lon": 23.7, "lat": 52.1,
                  "attackerGroup": "Western group", "attackerDivisions": 6, "attackerArtillery": 1,
                  "defenderGroup": "Eastern command", "defenderDivisions": 4, "defenderArtillery": 1 } ]
  } ]
}

An earlier start needs only the year (and usually no wars of today):

{ "name": "Cold War, 1985", "description": "The world of 1985.", "keepGameWars": false, "year": 1985 }

Wars start with the "Start with wars" option on GAME SETUP; off means a world at peace.

Armies and squadrons#

A country's forces at the start are built from its figures and its equipment, so you change them in two files:

A brand-new country made by a mod has no row in tables/countries.csv, so it starts with no forces of its own; it raises them in play like any country. Squadrons only form at air bases inside the country's land on day one.

Equipment#

Every country's weapons at the start: how many of each type it has in service, in storage and on order. Armies, squadrons and fleets take their weapons from this list.

key,country,type,active,stored,ordered
POL.k2-black-panther,,,*1.5,,
UKR.t-64bv,remove
new:POL.leopard-2a7v,POL,Leopard 2A7V,120,0,0

Weapon types: stats and new types#

Every tank, armoured vehicle, gun, air-defence system, aircraft, helicopter, drone and warship in the game is a weapon type: 4,512 of them, from the T-55 to designs of the 2060s. This file changes what each type can do, and adds new types of your own: a new bomber, fighter, tank or frigate.

key,name,category,generation,rating1,rating2,rating3,cost,year,maker,school,model,family,builtBy
su-57,,,=5,,=15,,,,,,,,
tu-160,=Tu-160 White Swan,,,,*1.5,,,,,,,,
leopard-2a7v,,,,=12,,,=18,,,,,,
new:tu-260,Tu-260 Storm,bomber,5.2,20,30,10,450,2031,RUS,RUS,Bomber,Tu-260,RUS
new:pzl-hawk,PZL Hawk,multirole,4.4,5,10,0,70,2029,POL,EURO,Fighter,Hawk,POL

The first three lines change the game's own types (Su-57 one generation step up and better weapons; the Tu-160 renamed and its weapons rating half again higher; the Leopard 2A7V better protected and dearer). The last two add new aircraft that Russia and Poland can build from the first day.

What the three ratings do

All three also count together as the type's worth: 1 + (rating1 + rating2 + rating3) / 300. An army's fighting power is multiplied by its equipment's worth (three ratings of +30 = 30% stronger), and the AI compares types by it.

How a type's generation becomes real numbers

• Aircraft: a squadron flies with the numbers of its role at its aircraft's generation from military/air-stats.csv, taken between the two nearest rows (generation 4.6 = 60% of the way from the Gen 4.5 row to the Gen 5 row). Then rating2 and rating3 above. The role comes from the category: fighter → fighter; multirole → fighter or strike; attack → strike; bomber → bomber; male_drone, ucav → drone.
• Ships: a ship has the numbers of its hull class from military/naval-stats.csv at its generation rounded (4.6 → 5). The hull comes from the category: cv carrier, lhd assault ship, lpd landing ship, cg cruiser, ddg destroyer, ffg frigate, corvette corvette, ssn/ssgn attack submarine, ssk/midget diesel submarine, ssbn missile submarine, mcm minesweeper.
• Armies: an army's generation is the average of its equipment's. Each step of generation over its country's starting level makes it markedly stronger, and its worth (above) multiplies that.

Giving your new type to countries

1. Add the type here with new: (name, category, generation, ratings, cost, year at least).
2. Put it in service: add rows to military/equipment.csv using its name as the type:

   key,country,type,active,stored,ordered
   new:RUS.tu-260,RUS,Tu-260 Storm,16,0,8

   Squadrons, armies and fleets take it from their country's stock at the start (newest first).
3. Let countries build it: write their codes in builtBy. Others can then buy it from them on the arms market.

New types come after the game's 4,512 and cannot be removed (rows of this file cannot be removed at all: set a type's equipment rows to 0 instead). A save that holds a mod's type needs that mod to be on: without it, those holdings are dropped on loading and the log says how many.

Aircraft numbers#

How far, how fast and how hard every kind of aircraft flies and fights, by role and generation: 30 rows, fighter.1 (a Gen 2 fighter) to drone.6. The roles are fighter, strike (strike fighters and attack aircraft), bomber, helicopter (attack helicopters) and drone (MALE and combat drones). Generation 1 .. 6 = Gen 2, 3, 4, 4.5, 5, 6.

key,radius,speed,stealth,radar,missileRange,missiles
fighter.5,*1.2,,=0.7,,,
fighter.6,,=1300,,=260,=200,=8
bomber.4,=4000,,,,,

Changes count for every country. A squadron flying a mix of types averages the numbers of their generations, then applies their weapons and range ratings (Weapon types).

Warship numbers#

Every hull class's numbers, as a ship of the 1990s-2000s (generation 4) has them: 11 rows, carrier, assault, landing, cruiser, destroyer, frigate, corvette, attackSub, dieselSub, missileSub, minesweeper. Older and newer ships are worked out from this row: generation 1 has a quarter of the missiles, 55% of the radar and sonar range and a quarter of the anti-ship missile reach; generation 6 has 1.3 times the missiles and sensors and 2.6 times the anti-ship reach; submarines get quieter with each generation.

key,max,hp,antiShip,antiShipKm,radar
destroyer,=32,*1.5,=16,,
frigate,,,,=250,*1.2

Each ship then uses its own type's endurance rating (Weapon types), and its generation from its type.

Air bases#

key,name,kind,lat,lon,runway,country
POL.lask-air-base,=Lask 32nd Tactical Air Base,,,,=3200,
new:POL.amber-coast-air-base,Amber Coast Air Base,military,54.45,18.30,2800,POL
POL.copernicus-wroclaw-airport,remove

Squadrons are placed at the start at the bases each country holds; a country with aircraft but no base has nowhere to fly from. Air bases and civil airports are separate lists: this one is for military flying, airports are for passengers and the economy.

Naval bases and navies#

# military/naval-bases.csv
key,name,country,fleet,role,dockyard,lat,lon
new:POL.hel-naval-base,Hel Naval Base,POL,Baltic,Secondary,no,54.60,18.80

# military/navies.csv
iso3,carriers,destroyers,frigates,corvettes,attackSubs,fastAttack,tech
POL,,=2,*2,,=2,,

Ships are spread over the navy's bases by their roles; a navy with no base uses a fallback port.

Airports and seaports#

# transport/airports.csv
key,name,lat,lon,country,runways,passengers,military,iata
POL.warsaw-chopin-airport,=Warsaw Okecie,,,,,*1.2,,
new:POL.amber-coast-airport,Amber Coast Airport,54.38,18.47,POL,2,4.5,no,AMB

# transport/seaports.csv
id,name,depth,containers,bulk,oil,lng
gdansk,,=18,*1.5,,,

Organisations#

The international organisations of the start: the UN and its Security Council, NATO, the EU, the IMF, the WTO, OPEC+, BRICS and the rest (27 rows, keys in diplomacy\organisations.csv of the reference). Change their members and rules, remove them, or found new ones.

key,name,kinds,voting,members,suspended,mutual,vetoes
NATO,,,,+UKR GEO,,,
EU,,,,-HUN,,,
IMF,remove
new:WARSAW,Warsaw Pact,defence arms,consensus,RUS POL CZE SVK HUN ROU BGR,,yes,
new:COMECON,Council for Mutual Economic Assistance,trade money,consensus,RUS POL CZE SVK HUN ROU BGR CUB VNM MNG,,no,

• The game's own keep their own rules. The UN needs two thirds; the Security Council's resolutions need 9 votes and no veto; the IMF lends to members deep in debt; OPEC+ cuts and raises oil output; NATO and the EU need every member. Your changes to members, name, kinds and voting still apply.
• A new organisation works by its columns. A defence organisation with mutual yes is an alliance; a trade one lowers tariffs between members; a money one can vote loans.
• Removing one removes what it does. Without the UN there are no General Assembly votes and no UN sanctions; without the Security Council no resolutions or UN peacekeepers; without the IMF no bailouts; without NATO no NATO battlegroups on the eastern flank.
• Trade agreements between countries (free trade deals) and defence treaties between two countries are not in this table.

The diplomacy of the start#

Besides the organisations, eight more files hold the world's diplomacy on day one. Each is the game's own list row by row (see diplomacy\ in the reference): change a row, remove it (key,remove), or add one (new:key,...). Codes are 3-letter country codes; a sender or treaty party may also be an organisation (EU, UN, NATO). List columns take +codes and -codes.

Warheads

military/warheads.csv: the nine nuclear states' stockpiles on day one: key,tactical,strategic,deployedTactical,deployedStrategic,perYear,cap,shownLow,shownHigh. The Soviet Union of 1985: RUS,=29000,=10200,=8000,=9900,=1500,=40000,=33000,=45000.

A start before 2024

A scenario with a year also trims what did not exist yet, by itself: weapons and drones of later years, named warships commissioned later, modern coastal missile batteries, SAMs and aircraft beyond the year's generation, space missions, launch sites, observatories and satellites of later years, and NATO's eastern battlegroups (2017). Wars in scenario/start.json take real dates of that year ("since": "1980-09-22"), and scripts see the shown year (date().year is 1986 in a 1985 world).

Flags and icons#

• pictures/flags/POL.png: replaces a country's flag, named by its code. PNG or JPG, 3:2 (e.g. 300×200).
• pictures/icons/<key>.png: replaces an icon. Keys are in pictures\icons.txt (e.g. hud.economy.png). Draw it white on a transparent background, square, 128×128: the game colours it like its own icons.
• At most 4096×4096. A mod with only pictures should be "gameplay": false, so players can add it to old saves.

Fonts#

The game's fonts cover the letters of its own text. Letters they lack (a Cyrillic city name, a Chinese translation) come from a fallback font, looked for in this order: .ttf / .otf files in your mod's fonts/ folder, then the fonts Windows has (Arial for Latin, Greek and Cyrillic; Microsoft YaHei, Yu Gothic, Malgun Gothic for Chinese, Japanese, Korean; Nirmala and Leelawadee for Indian scripts and Thai). The map labels copy the letters they need into their own atlas. Ship a font only if Windows' fonts do not have your letters, and only fonts you may share.

Translations#

my-translation/
  mod.json                 "gameplay": false, "tags": ["Translation"]
  lang/de/language.json    { "name": "Deutsch" }
  lang/de/menu.csv
  lang/de/events.csv       (any number of .csv files)

# lang/de/menu.csv
source,text
New game,Neues Spiel
Load game,Spiel laden
"Mods apply from top to bottom. Any mod turns achievements off.","Mods gelten von oben nach unten. Jeder Mod schaltet Erfolge ab."

• The folder name is the language code you choose (de, pl, pt-br); language.json gives the name players pick in the Mods window.
• source is the English text exactly as the game has it, capitals and punctuation included; text is yours. Put a cell with a comma in double quotes. \n is a line break.
• The full list of the game's texts: lang\en\seen.csv in the reference (windows, buttons, hover explanations, events, policies). Copy it, fill the second column, and remove rows you do not translate.
• Window captions show in capitals, but you translate them as written in the list.
• Players pick the language in the Mods window; it applies after Apply & restart.
• Texts the game builds with numbers inside ("12 provinces") stay English for now; everything fixed is translated.

Lua scripts: how they run#

• Every .lua file in your mod's scripts/ folder runs once when the game starts (after the mods applied). Files run in name order; they share one set of global variables per mod. Each mod has its own: mods cannot see each other's variables.
• That first run should only set things up: define functions and register handlers with on(event, function). The game calls a handler when its event happens (a new month, a war…), never every frame.
• Global variables keep their values between calls for the whole session. They are not saved: after loading a save, scripts start fresh. Work out what you need from the game (country(), date()) rather than counting in variables when it must survive a load.
• Scripts read the game and ask it to do things through the functions below; they cannot reach anything else (no files, no internet, no other programs).

-- scripts/rules.lua
local warned = false                      -- a variable of this file

on("new_month", function(e)               -- runs every new month
  local pl = country("POL")               -- a table of Poland's figures
  if pl.debtShare > 0.6 and not warned then
    message("Poland's debt", string.format("Debt is %.0f%% of GDP.", pl.debtShare * 100))
    warned = true
  end
end)

The Lua language (what scripts can use)#

Primacy runs standard Lua syntax with the parts below. If you know any Lua (Roblox, WoW, Garry's Mod), this is the same.

nil                    nothing
true, false
42, 3.5, 1e6           numbers (all decimal)
"text", 'text', [[long
text]]
{ 1, 2, 3 }            a list (index from 1)
{ name = "POL", n = 5 } a table with fields
function(x) return x end

local x = 1          -- this file / this block only
count = 0            -- global (this mod's scripts)
local a, b = 1, 2
t.name = "Poland"    -- set a field
t["name"]            -- read a field
#t                   -- length of a list or text

+ - * / % ^          arithmetic (% remainder, ^ power)
..                   join texts: "a" .. 1
== ~= < > <= >=    compare (~= is "not equal")
and or not           logic
x = x or 0           default value

if a then ... elseif b then ... else ... end
while cond do ... end
repeat ... until cond
for i = 1, 10 do ... end        -- 1..10
for i = 10, 1, -1 do ... end    -- step
for i, v in ipairs(list) do ... end
for k, v in pairs(tbl) do ... end
break
return value

local function add(a, b) return a + b end
local sq = function(x) return x * x end
local t = { n = 2 }
function t:twice(x) return self.n * x end
print(t:twice(21))   -- 42
-- a function can return several values:
local function mm(a, b) return a, b end

math.floor math.ceil math.abs math.sqrt
math.min math.max math.random math.huge math.pi
string.len string.upper string.lower
string.sub(s, i, j)  string.rep(s, n)
string.find(s, part)
string.format("%s %d %.1f %%", "a", 5, 2.25)
table.insert(t, v)   table.insert(t, pos, v)
table.remove(t)      table.concat(t, ", ")
type(v) tostring(v) tonumber(s)
pairs ipairs next error assert print

Game events#

Register a handler: on("new_year", function(e) ... end). The handler gets one argument, e, a table with the event's details (read them as e.year, e.attacker…). You may register several handlers for the same event; they run in the order registered.

Every function a script can call#

Countries are always named by their code (a text like "POL"); codes are in lists\countries.csv. A new country made by a mod uses the code you gave it.

country(code) → table or nil

The country's figures right now. Returns nil if there is no such country (check it: local c = country("XYZ") if not c then return end).

local de = country("DEU")
print(de.name, de.gdp, de.unemployment * 100 .. "%")

countries() → list of codes

Every country that holds land now. Loop over it with ipairs:

for _, code in ipairs(countries()) do
  local c = country(code)
  if c.debtShare > 1.2 then log(c.name .. " owes more than its GDP") end
end

player() → code

The player's country code (nil before the player picked one).

date() → table

date().year, date().month, date().day: the game's date.

at_war(a, b) → true/false

Whether two countries are at war with each other: if at_war("RUS", "UKR") then ... end.

wars() → list

Every war: a list of tables { a = code, b = code }.

for _, w in ipairs(wars()) do log(w.a .. " fights " .. w.b) end

province(id) → table or nil

{ id, name, owner } of a province (ids in map\provinces.csv): province("UKR-1234").owner.

provinces(code) → list of ids

Every province a country holds now.

city(name [, code]) → table or nil

The first city with that name (in that country, if you give a code): { name, country, population, lat, lon, capital }. city("Gdansk", "POL").population.

fire_event(id, code) → true/false

Opens a Situation Room event for a country now: the game's (ids in events\ids.txt) or your own (give it "chainOnly": true if it should only ever come from your script). Returns false when it cannot happen there.

message(title [, text])

Shows a card to the player and keeps it in Messages, with your mod's name on it.

sign_policy(id, value) → true, false or a reason

The player's government signs a policy change (ids and ranges in policies\ids.txt). It waits and phases in like one the player signs. Returns a text saying why when it cannot be signed now ("The economy is not running yet.").

declare_war(a, b) → true/false

Country a declares war on country b, with diplomacy's normal rules and consequences.

make_peace(a, b) → true/false

Ends the war between a and b; each keeps the ground it holds. False when they are not at war.

add_sanction(sender, target, packages), lift_sanction(sender, target [, packages])

Imposes or lifts sanctions: packages are any of travel arms tech finance energy full ("arms tech"). Without packages, lift_sanction lifts them all.

sign_treaty(kind, a, b [, years]), end_treaty(kind, a, b) → true/false

Signs or ends an agreement: Alliance, FreeTrade, NonAggression, Guarantee, Basing, VisaFree, Research... (the treaty kinds of the Talks tab).

join_org(org, code), leave_org(org, code) → true/false

Takes a country into an organisation, or out of it at once (join_org("NATO", "POL")). Keys as in diplomacy/organisations.csv.

add_opinion(a, b, value, text [, years])

What a thinks of b: a grievance (below 0) or a friendship (-100..100), with its reason, fading over the years given (10 if none).

give_province(id, code) → true/false

Hands a province (ids: map\provinces.csv) to a country, with its people, cities and industry, like a ceded one.

launch_mission(code, kind, world [, name]) → true or the reason it cannot

Orders a space mission the way the game plans any: launch_mission("RUS", "Outpost", "earth", "Mir"). Kinds: Flyby, Orbiter, Entry, Lander, Rover, Aerial, Sample, CrewFlyby, Crewed, Outpost, Solar, Telescope, Impactor, Relay. Real missions with their own dates go in space/missions.csv (the game's list, row by row; a new row's dates are in the scenario's years).

log(text) and print(...)

Write a line to the mods log (Mods log in the Mods window; mods log in the console), with your mod's id in front. Use them to see what your script does.

on(event, function)

Registers a handler (see Game events). Unknown event names are an error.

Worked examples#

A yearly report on the richest countries

on("new_year", function(e)
  local list = {}
  for _, code in ipairs(countries()) do
    table.insert(list, country(code))
  end
  -- find the top three by GDP (simple selection)
  for n = 1, 3 do
    local best, bestI = nil, 0
    for i, c in ipairs(list) do
      if not best or c.gdp > best.gdp then best, bestI = c, i end
    end
    if best then
      log(string.format("%d. %s: $%.0f B", n, best.name, best.gdp / 1e9))
      table.remove(list, bestI)
    end
  end
end)

Rally when the player is attacked

on("war_declared", function(e)
  if e.defender == player() then
    local me = country(player())
    message("The nation rallies", me.name .. " is attacked by " .. country(e.attacker).name .. ".")
    fire_event("pga.rally_round_the_flag", player())
  end
end)

A crisis that grows with debt, once

local fired = {}
on("new_month", function(e)
  for _, code in ipairs(countries()) do
    local c = country(code)
    if c.debtShare > 1.5 and not fired[code] then
      fired[code] = true
      fire_event("pga.debt_crisis", code)
    end
  end
end)

A war that starts in 2027

on("new_month", function(e)
  if e.year == 2027 and e.month == 3 and not at_war("CHN", "TWN") then
    declare_war("CHN", "TWN")
  end
end)

Limits and errors#

• Each call (the first run, each handler call) may take up to 200,000 steps. A script that runs longer is stopped with "the script ran too long", and the game goes on. Loop over countries freely; avoid loops in loops over thousands of things.
• Calls may nest 120 deep (recursion). Deeper is stopped.
• An error stops only that call. It goes to the mods log with the file and line: rules.lua:12: a number is needed, not nil. The handler stays registered and runs again next time.
• Common errors: "cannot index nil 'c'" (a function returned nil: check it), "cannot call nil 'contry'" (a typo in a function name), "'end' expected to close 'if'" (a missing end), "cannot compare nil with number" (a field that does not exist).

Publish on the Workshop#

1. In the Mods window, find your local mod and click Publish (it says Update after the first time).
2. Title (from mod.json's name), description, what changed in this version, and who can see it: Only me (test first), Friends, Link only, Everyone.
3. Hold Publish. The upload shows its progress. The first time, Steam may ask you to accept the Workshop agreement on the item's page: until you do, the item stays hidden.
4. The game writes workshop.txt into your folder; keep it so later uploads update the same page.
5. The tags come from mod.json's tags (only the Workshop's tags are sent), and "Space DLC" when the mod lists the Space pack.

Players subscribe on Steam; the game shows the mod in their Mods window, switched off, after Steam downloads it.

Every error message, and what to do#

Rules and limits#

• Changing the mod list or the language restarts the game's session.
• Any mod switches achievements off.
• Mods cannot unlock DLC.
• Nothing changes the world at once mid-game: mod policies phase in; scripts act through the game's own systems (events, policies, diplomacy).
• No code: .dll files are never loaded. Lua does that job.
• Not moddable: province shapes, rivers, coasts, terrain, the satellite picture and adding new tech nodes. The tutorial only starts with no mods running (it teaches the game as it ships).
• Do not publish other people's work (art, fonts, music) without their permission, or real-world hate content.

Questions#

My mod does nothing.

Is it switched on and did you Apply & restart? Open the Mods window: does its row say Running and "N values changed"? If 0 values: open the mods log, every skipped line is there with its reason.

Excel changed my file.

Excel may turn codes into dates or use semicolons. Save as "CSV UTF-8" and check the file in Notepad. Or edit CSVs in a text editor.

Where do I see what a value is now?

Reference files writes every table as the running game has it, your mods included. Compare with the shipped reference (unmodded).

Can my mod change another mod?

Yes: list it in loadAfter (so yours applies after) and change the same rows; needs if yours cannot work without it.

How do I test quickly?

Edit your files, then type modsreload in the console: the session restarts with the files as they are now.

Can a script remember something across saves?

No: scripts start fresh after a load. Work it out from the game's state (the date, a country's figures) each time.

Does my mod slow the game?

Tables apply once at start (a city mod adds about half a second). Scripts run only on their events, with a step limit.