Mechanical Grounding

_{Design document §7.0}

Every effect in this document is being rewritten against Unciv's real capabilities, read from the repository rather than from memory. Sources: docs/Modders/uniques.md (the auto-generated list of all 832 unique templates and what each may be attached to), docs/Modders/Unique-parameters.md (the legal filter vocabularies), docs/Modders/Mod-file-structure/*.md (the fields a building, unit, improvement or tech may define), and the Civ V - Gods & Kings ruleset JSONs (Techs, Buildings, Units, TileImprovements, TileResources, Terrains, Specialists, Eras) for calibration. Version checked: repository master, September 2026.

What exists

Seven stats — Food, Production, Gold, Science, Culture, Happiness, Faith. Buildings (with cost, maintenance, flat stats, percentStatBonus, specialistSlots, greatPersonPoints, cityStrength, cityHealth, requiredResource, requiredBuilding, requiredNearbyImprovedResources, replaces, and uniques); units (unitType, cost, movement, strength, rangedStrength, range, requiredResource, promotions, uniques); tile improvements (terrainsCanBeBuiltOn, turnsToBuild, stats, uniques); resources (Bonus/Luxury/Strategic, revealedBy a tech, improved by one improvement); the four specialists (Scientist +3 Science, Merchant +3 Gold, Artist +2 Culture, Engineer +2 Production — new specialist types are legal data in Specialists.json, each carrying its own Great Person points, and a new Great Person is a Civilian unit with Is part of Great Person group and consuming actions; both are used once, for the Sage and the Great Sage of Process worlds); Great People; Golden Ages; religion and Faith; city connections (which Unciv calls Trade Routes — roads or harbours to the capital); unit supply, XP, promotions, sight, movement, strength, healing, pillaging; embarkation; open borders, defensive pacts, research agreements, embassies; City-State influence; puppeting and annexation; nuclear weapons and fallout; an optional espionage mode (spies, <when espionage is enabled>); an Events system (Events.json) for narrative choices, which a building may fire on completion with Triggers a [event] event; and stockpiled resources — a resource carrying the Stockpiled unique accumulates like a treasury, a building may generate it in proportion to a building's yield ([X]% of [stat] from every [buildingFilter] in the city added to [resource] — which, read in CityResources.kt, adds a resource supply and does not remove the stat; it duplicates, it does not divert, and it truncates to whole units, so a percentage of a small or absent flat stat yields nothing), and buildings, units and improvements may spend it (Costs [N] [stockpiledResource]; Unciv's own documentation example is Costs [3] [Mana]). The [stockpile] parameter of Instantly gain [amount] [stockpile] accepts stat names as well as stockpiled resources, so a consumable unit (<by consuming this unit>, the Great Merchant's own mechanism) can turn a stockpile into Gold natively. A building may yield a stockpile directly with Provides [amount] [resource], since each turn a civilisation gains its supply of every stockpiled resource (TurnManager.kt). Purchased units have no movement the turn they are bought unless they carry Can move immediately once bought, and unit actions require movement; stockpile costs are charged on purchase; there is no per-turn purchase limit; City-State gold gifts are offered only in 250, 500 and 1000. A tech may carry Global uniques (permanent civ-wide effects — Astronomy's [+1] Movement <for [Embarked] units>) and Triggerable uniques (fire once on discovery — Satellites' Reveals the entire map); nothing else.

What does not exist, and what it converts to

These concepts appear throughout earlier drafts and have no mechanism in Unciv; each row is being rewritten as follows.

Concept with no mechanism	Convert to
Tourism, prestige, "soft power"	Culture (flat or %), Great Artist points, or City-State Influence
Loyalty, unrest, corruption, bureaucracy, tax efficiency	% Unhappiness, % building maintenance, Gold per population, -% unhappiness from the number of cities
Morale, terror, rout, pursuit, first strike, ambush	[±X]% Strength with conditionals (<when attacking>, <vs [Mounted] units>, <in [Hill] tiles>), Can move after attacking, Withdraws before melee combat
Health (as a stat), disease/plague events, lifespan	Happiness, % growth, % Food carried over after population increases, % Great Person generation
Disasters, earthquakes, floods, storms, weather, climate	Removed; where the intent was resilience, use cityStrength/cityHealth, terrain-conditional yields, or % maintenance
City size cap	% growth or % Food carried over (Civ V growth is happiness-limited, never capped)
Spoilage / food storage	[X]% Food is carried over after population increases (the Aqueduct pattern)
Pollution	Removed; a Production-vs-Happiness trade-off where one was intended
Trade route capacity or range	[stats] from each Trade Route or [%] [stat] from Trade Routes (city connections)
Loans, insurance, inflation, monopoly, propaganda	Gold %, Happiness from each type of luxury, Culture %
MAD, deterrence, nuclear winter, meltdown	Removed; the units stay, gated <when nuclear weapons are enabled>
Space probes with movement or range	Removed; deep-space capability is % Production when constructing [Spaceship part] units, Science, or the spaceship parts themselves. The three sub-light victories are alternative spaceship-part sets for the Scientific victory.
Fog of war on oceans, "never lost"	[+X] Sight <for [Water] units>
Blockade, airlift	% Strength <vs cities> for naval units; May Paradrop
Code-breaking, cipher, encryption, surveillance	% spy effectiveness inside <when espionage is enabled>, or removed
Advisors, UI reveals	UI only — no mechanical effect claimed
"Trade good"	Provides [1] [Luxury] from a building (legal, but each new luxury is a happiness source — used sparingly)

What the fork adds

The Insight system is new code in any case, so a small, closed set of custom uniques rides with it and is used in this document by name: Unlocks focus [X]; [+X]% Insight to [Focus] (implemented as a Science modifier scoped to one focus); Reveals [breakthrough] (a Triggerable that sets a breakthrough to the Revealed state — the native Free Technology trigger is the precedent); obsolescence locking; the Knowledge Diffusion phase switches; World-Truth-conditional cost multipliers on breakthroughs (data of the Insight system, Section 1.2); UNIQUE-granted replacement buildings joining the holder's unique-building cache, and converting its existing base buildings, on discovery (below); a record of the Great Person names each civilisation receives (for the War of the Currents, EL14); the airship confidence ladder and its reports to contacted civilisations (§1.2, the Airship Disaster); and one extension of an existing mechanism — Enables conversion of city production to [stockpiledResource], letting the Wealth-style perpetual process (PerpetualStatConversion) target a stockpile at a per-process rate, so that Dispersal and Banking Heat can bank a city's surplus into Prima Materia or Caloric (the Process world has no stockpile). Nothing else in the Unlocks column is invented — if it is not one of these, it is a real Unciv template.

Power budget: build time is the invariant

The rest of Unciv — AI, city-states, policy costs, wonders — is built against base Civ V's power level, so the fork aims at it, using the base game as a guide rather than a straitjacket. Per city, each yield from buildings should run within about 1.25× base Civ V per era; production may run a little higher (about 1.3×) provided what a city builds costs correspondingly more, because what players feel is how long things take. The measure is the time to build a city's full building set, which should stay close to base Civ V's; unit costs scale with the production ratio for the same reason. Surplus choice should come from exclusive and situational buildings, not a longer universal list. The per-city ledger that measures all of this is kept in power_tools/.

Exclusion by replacement, not by blocking

Where buildings share a slot — one grid plant, one temperament, bank or draw, or the two halves of a persisting Competing Solution — each carries Remove [the others] [in this city] rather than Only available <in cities without a [the others]>. Building one retires the rest when it completes, so a city is never locked into its first choice, and never holds two. An early version of a later building converts the same way — the Engine House into the Steam Works, the Tide Computer into the Seaport — sped up by the old building and retiring it. Shared slots are named by tag uniques; replaces is reserved for true equivalents — nation and UNIQUE buildings — because Unciv's capture swap follows replaces, and would turn a building that replaces a placeholder into the placeholder.

Filter discipline

Building.matchesFilter matches a building by its name, by the name it replaces, and by the name of any technology it requires — so a breakthrough must never share its name with a building that appears inside a [buildingFilter], or every building that breakthrough unlocks will match. Caloric Storage (TH11) is named apart from its Caloric Reservoir for this reason; Windmill (MC04), Water Mill (WM05), the Thorium Reactor (NP08), the Re-Tempering Reactor (QM-E05) and the Mass Driver (RK15) share names with their buildings harmlessly, because each of those breakthroughs unlocks only its namesake; the verification battery checks every such share. The rule holds for every future filter. Since v3.60 every bracketed value is also validated against its parameter's vocabulary — the ruleset's own names, the keyword lists in Unique-parameters.md, and every object this document declares with ⁿ — so a filter can no longer name something that does not exist. (It cannot catch a valid name used with the wrong meaning: Fresh water and Fresh Water are both legal, and mean different things.)

The familiar world is the baseline

The atomic world is balanced to feel like base Civ V — roughly its power, and familiar to play despite the research system — and every other world is measured against it, never the reverse. An elemental world therefore gains its economy and loses what its physics forbids, and the two must weigh the same. Gains: Substance has Prima Materia (any form into any other, at a loss, from the Early Modern era); Process has the Five Turnings (Great Improvements built only by Great Sages, each on its own element's land, each fed by the one before it in the generative cycle). Losses, from the models: a continuum has no semiconductor and no photon to count (Model I §6–7), so the elemental world builds computers but never the silicon age — Miniaturisation at two and a half times the cost (so pocket electronics and Powered Armour arrive late, not never), no Photonics, a Fab that does not shrink, no Quantum Computing, no entanglement communication; and it has no fusion-fails fork, no thermonuclear tier, no fuel-cycle chain. The Information era, which base Civ V hands every player, is the elemental world's price for its Early Modern economy. Brought down to meet it: the Transmutation Hall is a national wonder (one per civilisation — matter comes from the Hall, the Hall city's Dispersal, the Stone and per-city Vats that lean mildly wide; there is no Great Person of matter), and the Process world has no stockpile at all: its gain is built one Great Sage at a time. The quantitative audit (v3.45): the ~17 atomic breakthroughs with no elemental mirror sum, for an eight-city late empire that builds all of them, to roughly +30 Science flat and +25% in two cities, +16 Production reliably (up to +56 with two RARE finds), +16 Happiness only via a RARE, +25% spaceship-part production and one missile tier — almost all Atomic-era or later. The Process gains, since v3.48, are the Forge's +4 Production and a handful of Turnings — one per Great Sage, perhaps five to eight in a game — each +3 on its tile and, when fed one-to-one by the element before it, one stacking policy-sized effect of its phase (growth, building production, border growth, military strength, Great Person generation); The Great Wheel lets each feeder feed two and adds +5% of every yield per complete wheel. One cycle is five Great People for fifteen tile yields and five such effects — GP-priced, and well below v3.44's +120 yields. The phase-effect sizes are the next levers if it is still ahead. The gateways to both elemental economies, Transmutation Practice (CH20) and Five-Phase Theory (CH22), exist only in their own worlds, so their difficulty is set directly in their prices — a multiplier would have nothing to multiply. If playtesting finds the elemental worlds ahead, the levers in order are: raise those prices, raise the re-locking prices, and last, move the gateways an era later — never a new power for the atomic world.

Resource discipline

A strategic resource is defined by what consumes it. The audit of every resource this design adds applied one test — at least three consumers spanning an era, and a game that is honestly poorer without it — and kept three map-placed resources: Saltpeter (the gunpowder strategic: Musketman, Cannon, Fireworks Ground; the Renaissance scarcity Civ V never had), Rare Earths (the high-tech strategic: Microchip Foundry, Fab, Drone, Solar Farm), and Obsidian (a Volcanic luxury that also gates the Obsidian Warrior and pays the volcanic cluster of UNIQUEs). It added one luxury that is made rather than mined: Whisky, distilled wherever a city works a Peat Cutting (CH04), which gives a bog a reason to be kept rather than drained. It kept two stockpiles — Prima Materia, the Substance economy itself, and Caloric, which is the caloric world's economy: heat is conserved and storable there, so heat is banked in Reservoirs and spent on Heat Exchanges, Lances, Wards and the Caloric Engine Plant (four sinks, and the branch's whole identity). It cut Sulfur and Bitumen (two more gates on eras Saltpeter and Iron already gate; both breakthroughs survive as knowledge), Rubber (nothing consumed it; the breakthrough folded into Vulcanization), and the Ritual Bronze luxury (the Foundry Temple provides Copper instead). Qi, once the Process stockpile, was cut in v3.46 — its only sinks were the Five Turnings and the Wandering Sage — and the Turnings became Great Sage improvements counted directly with Owned [tileFilter] Tiles, so the Process world needs no stockpile; at most a civilisation holds two (Prima Materia and Caloric, in a caloric Substance world). Any future resource must pass the same test.

World-Truth ruleset derivation

Before a game begins, the fork derives that game's ruleset from its sampled World Truths — the step that already has to remove absent breakthroughs and apply cost multipliers (§1.2). It does five things, all data transformations on the loaded ruleset: (1) removes breakthroughs that cannot exist in this world, with the objects only they unlock, and writes a Removal Truth's geology as data — Doesn't generate naturally on the resources it forbids; (2) applies world-conditional cost multipliers; (3) remaps base-game objects to their mirrors — an object has one requiredTech and a resource one revealedBy, so in elemental worlds the Manhattan Project and Atomic Bomb answer to the Quintessic Warhead (QM-E20) and Uranium's reveal to the Boundary Survey (QM-E16); (4) applies world-dependent display names — but only where the familiar name asserts a theory that is false in that world (atomic, nuclear, semiconductor), and then the name that world's own science would give: the Atomic Bomb is a Dissolution Bomb in a Substance world, where nothing is atomic. Everything named for what it observably is or does, or for historical reasons that hold in any world, keeps its name everywhere — Uranium is named for the planet Uranus; a computer, a vacuum tube, a solar panel and radiation are named for what they are and do. Elemental science is as rigorous as atomic science and names what it finds by the same habits; nothing is renamed for flavour; (5) applies world-conditional tier overrides — as when a Competing Solution's primary cannot exist in a world and the alternative takes its tier (§1.2). At runtime, one further tier change is per civilisation rather than per world: the airship confidence ladder (§1.2). New objects need none of this: each simply names its own breakthrough.

Terrain the tree assumes but Civ V lacks

"Volcanic region" becomes a new terrain feature Volcanic (placed near volcanic Natural Wonders and on some Hills at map generation); "flood-prone" is the existing Flood plains feature; "earthquake-prone" has no equivalent and those effects are re-based on Hills and Mountains.

Layering on nation uniques

Players still choose an Unciv nation, and every nation arrives with its own ability and one or two unique units or buildings (Mongolia's Keshik and mounted movement, Denmark's Berserker and embarked movement, Inca hill roads and Terrace farms, Polynesia's ocean-going embarkation…). UNIQUE breakthroughs are therefore a second layer of identity on top of a nation's, never the first — and three rules follow. (1) A breakthrough never grants a nation's own unique object. Where a UNIQUE breakthrough's theme matches an existing UU or UB, it grants a differently named, differently statted object (Mangudai rather than Keshik, Huscarl rather than Berserker, Chinampa Garden rather than Floating Gardens) so the nation keeps what is its own. (2) Nation uniques keep their base object's gate: Krepost unlocks when Barracks does, for Russia only, exactly as §7's "civ-uniques" rows say. (3) Stacking is allowed and expected. A Polynesian player who also discovers Polynesian Wayfinding stacks two naval-movement bonuses; a Mongol who finds Mongol Combined Arms stacks Great General bonuses on mounted speed. Nation abilities make some UNIQUEs more attractive to some players, which is intended, and the cumulative UNIQUE penalty bounds the total. Where playtesting shows a stack is too strong, the fix is to that UNIQUE's numbers, not to the layering.

UNIQUE replacements must actually replace

A nation's unique building blocks its base building because Building.kt rejects any building that a building in the civilisation's uniqueBuildings cache replaces — and that cache is built from the nation's uniqueTo buildings. A breakthrough-granted replacement (the Cowrie Exchange for the Market, the River Temple for the Temple) has no uniqueTo, so as the data stands the base building would stay buildable beside it and the two would stack. The fork therefore adds every UNIQUE-granted replacement to the holder's uniqueBuildings cache on discovery, and converts the holder's existing base buildings into it — free and in place, exactly as Unciv's own transfer does when a city changes hands (CityConquestFunctions: each built building becomes getEquivalentBuilding for the new owner). Only the new replacement's base building is converted, so nothing else is disturbed. A UNIQUE therefore takes effect in the cities you already have, and a city never holds both. This is the eighth fork extension: a line in a cache we already touch, and a call to code Unciv already has. One case is left for the redesign phase: a civilisation whose nation already replaces the same base building (Egypt's Burial Tomb and a River Temple both replace the Temple).

Calibration rule

The canonical tree grants roughly one to four objects per tech and almost never a civ-wide percentage; percentages come from buildings. With ~528 breakthroughs replacing 80 techs, one breakthrough's budget is about a sixth of a tech's — except that CORE gateways (those that unlock a focus) may carry a full tech's worth, STANDARD breakthroughs carry one object or one modest unique, UNCOMMON one distinctive object or unique, RARE one strong unique or a wonder, and UNIQUE breakthroughs mirror a Civ V civilisation: one unique building or unit plus one civ-wide unique tied to their terrain. Costs and stats of new objects are pegged to the tech column of their era (Techs.json: Ancient building 40–75, Classical 100, Medieval 120–160, Renaissance 200–250, Industrial 300–360, Modern+ 500, Information 750).

Notation in the Unlocks column

Name — a base-game object; Nameⁿ — a new object, with its JSON-ready spec in brackets [cost/maintenance; stats; uniques]; ⟨…⟩ — a Global or Triggerable unique the breakthrough itself carries, in Unciv unique syntax; Reveals X — a resource's revealedBy; requires a **X** in this city inside a spec — the building's requiredBuilding: X, or a building that replaces X, must stand in the city (Unciv's containsBuildingOrEquivalent). X always names a real building, never a slot tag, because the rejection message looks the name up. A fork building that takes a canonical building's place carries that building's requirement: a replacement copies its base's, as the Wat copies the University's; an early version copies its successor's; an alternative that removes a building copies the removed building's; a paradigm's stand-in copies the one it stands in for; and every member of the Power Plant slot requires a Factory, as the canonical Nuclear and Solar Plants do. Unlocks Focus — our own system. Insight effects are our own stat and are written as +X% Insight to Focus.

Notation in the Prerequisites column

Row IDs joined by "+" are all required; "or" offers alternatives. A cell never relies on which of the two binds tighter: whenever it uses both, each group of alternatives is in parentheses — "WA10 + (ME05 or ME08)" — and so is each alternative that needs several rows — "G02 + (G07 or (FA01 + FA02))", "CH01 or (F03 + ME04)". Inside a group, commas also separate the alternatives ("(NP03 Fission, or QM-E02 Bound-Energy Release)"). A parenthesis whose content begins with a row ID is a group; any other parenthesis is a description — "(Kiln Construction)", "(but NOT SO04)" — and so is commentary after a dash outside every parenthesis. Plain text with no ID, such as "Coastal location" or "Temperate or Tropical biome", is an environmental condition. The battery, the generator and the derivation all read prerequisites through one parser (check 18), and check 19 holds every cell to this notation.

Status

Complete (v3.21–v3.57): every breakthrough's Unlocks column is grounded in Unciv objects, real unique templates and the fork's enumerated extensions. Reward values are preliminary, pending playtesting.