Design — The Economy

High-level design for the town’s economic layer: how goods are priced, what drives demand, where gold comes from and goes, and how the outside world reaches in. Answers to ../GAME_DESIGN.md §3 (the core loop) and §5 (the economic front), and builds on politics.md (taxes feed the town treasury, the Chamberlain holds the dials). Design doc — the model and its rules, not an implementation plan.

The concrete goods graph, recipes, and starting prices live in ../../design/production_notes.md (8 workshops, 6 extraction buildings + 4 wild gathering spots, raw → intermediate → final, with cost-plus starting values). That document is the data; this one is the model those numbers feed.

Modelled on The Guild 2’s town economy: a single local market with dynamic, supply-and-demand prices — trimmed to one town (no multi-city trade), with the outside world represented abstractly through Kingdom Events rather than real caravans.

1. What the economy is

The economy is one of the three sandbox dominance fronts (GDD §5) and the engine of the core loop gather → produce → sell → reinvest (GDD §3). It is a real market, not a frozen price list: a good’s price moves with how oversupplied or starved the town is for it. That movement is the whole game — profit comes from serving scarcity, and a market you flood collapses your own margins.

There is one town and one market (matching the single-tier City of politics.md). The Guild 2’s multiple cities are deliberately dropped — one market is easier to balance and the multi-city layer never added much. The outside world (the Crown, wars, famines) reaches in as modifiers, not as a second place to trade (§6).

Balancing is the headline concern of this whole system. Every number below is a tunable knob, by design — in a sandbox with no win condition, a smoothly-running, non-degenerate economy is the product. The model is kept small precisely so it is all knobs.

2. The price model — floor × scarcity

A good’s price is built from exactly two things: a floor and a scarcity multiplier.

   price = base_value  ×  scarcity_multiplier
           └─ floor ─┘     └─ 1 … cap ─┘

• base_value = the guaranteed price floor. Data-driven (per item, in the DB), fully tunable. It is the bare minimum a unit ever sells for — you can always convert product to gold, the only question is how profitable it is. This is the floor’s only job now; The Guild 2’s other use of base price (selling from your shop’s own storefront inventory) is dropped — all sales go to the central market.

• The scarcity multiplier runs from 1 up to a cap (e.g. ~10×, TBD):

  • Glutted (lots of stock vs what demand wants) → multiplier → 1 → you get exactly the floor. A flooded market bottoms out at the floor, never below.

  • Scarce (stock near zero vs demand) → multiplier climbs toward the cap → the scarcity premium.

  • So a good’s price always lives in [base_value, base_value × cap].

Worked example: a sword with base_value 200 sits at 200 when the market is flooded with swords, and spikes toward ~2000 when a starved town has almost none.

Why this drives the game

• Profit = the scarcity premium, not the floor. The production_notes cost-plus numbers become the floors, so a normal supply chain selling at the floor makes thin-to-no profit. Real money is made by finding the underserved good and selling into its multiplier — until you (or a rival) oversupply it and the multiplier collapses back to 1.

• Profitability is emergent and per-good. Your inputs are bought at their floating prices too, so a product genuinely loses money when its raw materials spike — the “unprofitable if your raws are expensive” case. Whether any given product line is worth running is a live, moment-to-moment judgement, not a fixed fact.

• It is all knobs. Per-item floors, the cap, and the shape of the glut→scarcity curve are every lever balancing needs.

Open (balancing): the exact cap (one global value? per-category?) and the curve shape between empty and glutted (how fast scarcity bites). Not pinned here.

3. Demand — abstract per-good pools

A price can only move if there is a demand side to push against. Demand is not a consumer-agent simulation; it is an abstract pool per good, fed from two sides and drained by consumption. Stock-vs-demand is what sets the scarcity multiplier (§2).

Internal demand — a few town demographic drivers

The town is a small set of demographic counters, and every good’s demand is a simple formula over them. Starting mapping (tunable):

The whole demand side is therefore driven by a handful of numbers — total pop, male, female, guard count (+ a wealthy segment for luxuries). Simple inputs, emergent variety. A nice cross-system coupling falls out for free: guard count is a politics number (the Sheriff commands the city guards, politics.md §2), so a militarising town raises its own weapon and armour demand.

These demographic counters are abstract town stats for now, not derived from real citizen entities. How they grow and shrink is later balancing — and a shrinking town (fewer people, less demand) is part of the tailspin risk (§8).

External demand — the Crown pulls too

The same pools are also fed from outside: a Kingdom Event (§6) can stack demand onto a good — the export case, where the Crown drains weapons or food off the local market. So a good’s demand at any moment is:

internal demographic demand + active external (Crown) demand.

The town consumes from within; the Crown consumes from without; both push the same number up and spike scarcity. An export event is just extra demand stacked on the pool.

Workshop input demand

A workshop buying another’s intermediate good (e.g. a baker buying flour) feeds the same pools — producers and consumers compete over the same buyers. This is the economic-warfare hook: oversupplying an input crashes its price for everyone; cornering it starves rivals downstream.

4. The money supply — faucets, drains, and slow inflation

The marketplace is symmetric — both faucet and drain

The marketplace holds unlimited gold (UnlimitedGoldComponent, see §7). This is not a bug to fix — it is the mechanism that injects gold into the world. And it cuts both ways:

• Sell product to the market → it pays from thin air → gold created (faucet).
• Buy materials from the market → your gold vanishes into its reserve → gold destroyed (drain).

So net gold entering the world is not “every sale” — it is the town’s trade balance. A dynasty that buys as many inputs as it sells products is gold-neutral; net gold only grows when the town as a whole net-sells.

Faucets and drains

The bottom three are not true sinks — they recirculate through the politics town treasury (politics.md §6): tax in, salary out. That treasury is the one pool that can leak (insolvency is the politics balancing risk).

Stance: accept slow inflation, don’t engineer a closed economy

We do not chase a strict closed loop where sinks exactly soak the faucet. Instead: accept slow, mild inflation as normal, and use the sinks (construction, upgrades, licences, buying inputs, the sales tax) as brakes that keep it slow. Reasons:

• A slowly growing money supply is fine — even good — in a sandbox where the dynasty is meant to accumulate wealth and build ever-bigger holdings.

• A perfectly closed economy is a balancing nightmare and fights the “pure sandbox, no win condition” design (GDD §1/§6).

• Prices are already bounded by the floor and the scarcity cap (§2), so even with more gold around you cannot extract infinite value per item.

Inflation is a thing to watch (via the knobs), not a thing to eliminate.

5. Taxes & the town treasury

Two taxes feed the politics town treasury (politics.md §6) — think Australia’s split of income tax and GST:

• Daily profit tax — taxes a dynasty’s profit each day. (Already in code as the hardcoded CitySystem::TAX_RATE = 0.10; §7.)

• Per-transaction sales tax — skims a % off every market transaction. This is the Chamberlain’s dial (“Set Sales Tax”, politics.md §2).

The per-transaction sales tax is the piece that makes the treasury work, and it earns its keep three ways:

1. It is the treasury’s main faucet — directly funding the salaries and embezzle pool the politics design needs, answering the “how does the treasury stay solvent” gap.

2. It is a gentle inflation brake — because it skims newly-created faucet gold off market sales before it fully reaches the seller (§4).

3. It is a contested, economy-wide lever — a high sales tax fattens the treasury (salaries, city projects, embezzle) but squeezes every producer’s margin toward the floor. The Chamberlain’s setting is a genuine knob dynasties fight over.

Whether the per-transaction sales tax replaces or supplements the daily profit tax is a balancing/implementation call left open (§8) — both concepts now exist and the doc keeps them distinct.

6. The outside world — Kingdom Events (the Crown)

There is no second town to trade with (§1). Instead, a virtual outside world — the Crown — reaches into the single local market through Kingdom Events: an event applies temporary modifiers to the demand/supply pools for a number of days. This is the thematic payoff of the title — Guilds of the Crown — and a cheap, rich source of dynamism with no logistics simulation**.

Examples:

• A Kingdom at war → weapon/armour demand spikes (the demand driver lifts, or the Crown drains N weapons/day off the market — the export case, §3) → scarcity → weapons suddenly very profitable.

• A famine → food is exported to the Crown (supply yanked off the market) → food scarcity → food suddenly very profitable.

Kingdom Events are the home for two things parked elsewhere:

• The Crown tariff — a temporary, externally-imposed surcharge the Crown slaps on goods it is currently moving across the border (the tariff event effect). This is distinct from the Chamberlain’s standing tariff dial (politics.md §2) — the town’s own set-and-hold trade duty. Two separate things sharing one per-good surcharge hook: one event-set, one seat-set (see crown.md §2/§7).

• The tailspin escape hatch (§8) — specifically the crisis import: the Crown/City injecting supply of a critical resource to restart a seized market (the supply+ relief valve). Note this is one of §8’s two valves — the other, the City permanently owning some raw production (a structural supply floor), is not a Crown event and stays an economy/production concern (§8).

Both external shocks and city stabilization just push on the same supply/demand pools (§3). Mechanically simple — likely a single screen listing active events and their modifiers. “Nothing too crazy.”

Now designed in design/crown.md: the Crown as an environmental force; an event = a timed bundle of pool-modifiers (the four effects demand+ / supply− / supply+ / tariff); two triggers (an ambient weighted timer + a reactive relief valve that is the City controller’s call); one read-only panel; real Crown diplomacy parked. This economy doc still owns the hooks (the §3 pools events push on); crown.md owns the events, the scheduler, and the relief-valve trigger.

7. ⚠ Tensions with current code

• Prices are static today. The whole §2 model is unbuilt. Each item has a DB base_value (gold per unit) and stack_limit (the “full sack” that triggers a sale and sets quantity), read by BuildingUtils::ReadItemSaleData; a sale is literally quantity × base_value (SellStepSystem). There is no scarcity multiplier, no demand pool, no price movement. The design re-roles base_value from the price to the floor and adds the multiplier on top.

• The marketplace is a passive, infinite sink. MarketplaceSystem emplaces InventoryComponent + UnlimitedGoldComponent on the market object and has no Update logic — it never adjusts a price or tracks a demand pool. It is the symmetric faucet/drain of §4, but with no scarcity behaviour yet.

• Market buying of inputs is only half-built. The loop today is gather → produce → sell to the market; sourcing inputs from the market (a BuyStep mirroring SellStep) is listed as future work, not built. The §4 drain side and §3 workshop-input demand both depend on it.

• No town treasury, two taxes greenfield. As flagged in politics.md §7: TAX_RATE is a hardcoded constant and collected tax accumulates into no treasury balance. Both the §5 daily-tax-as-dial and the new per-transaction sales tax need a real city gold balance and a tax hook on every transaction.

• Town demographics don’t exist. The §3 drivers (total/male/female/wealthy population, guard count) are not modelled as town stats today. Guard count has a toehold (CityRole::Guard); the rest is greenfield.

• No Kingdom / Crown. The §6 outside world (events, external demand/supply modifiers) does not exist in any form.

• Item representation may not fit (re-examine). Items are ItemStack (StringId + int qty) and gold is itself an item (items::currency::gold); price lives only as the DB base_value. A dynamic market needs somewhere to hang floors, live prices, demand pools, and per-good modifiers — base_value alone won’t carry it. The item/inventory representation should be re-examined against this cleaner design before building the market (→ todo/TODO_FUTURE_WORK.md).

8. Open questions & held notes (next pass)

• The scarcity cap & curve (§2) — global vs per-category cap; how fast scarcity bites between glutted and empty. Pure balancing.

• Per-item floors (§2) — production_notes cost-plus values are the starting floors, tunable so the economy runs smoothly.

• Sales tax vs daily tax (§5) — replace, or supplement? Plus the rates themselves.

• Demographic model (§3) — what the town’s population counters actually are, and how they grow/shrink. The wealthy luxury driver in particular is unspecified.

• The tailspin / hard-lock risk (held note → CHALLENGES). The Guild-2 death spiral: raw supply dries up (a dynasty monopolizes a resource and either can’t afford to run it or deliberately withholds), and with limited AI the whole economy seizes. Two safety valves: (1) the City permanently owns some raw-resource production (a structural supply floor — not a Crown event, stays an economy/production concern, still pure balancing here), and (2) the crisis import — resources flagged “critical” city-/Crown-imported during extreme scarcity to restart flow, as a real city secures grain. Valve (2) is now designed as the Kingdom-Events relief valve (crown.md §4): a supply+ injection on a critical good pinned at the scarcity cap, fired reactively as the City controller’s call; its trigger numbers remain balancing.

• Item-system re-examination (held note → TODO). Whether the current ItemStack/base_value representation still fits once the dynamic market, floors, and demand pools need a home (§7).

• Market-buy (BuyStep) (§7) — the input-purchasing half of the loop, needed before workshop-input demand and the §4 drain are real.

• Kingdom Events content (§6) — the event roster, cadence/weights, and screen; the mechanism is now designed (crown.md), but the concrete event list and balancing numbers stay open there (crown.md §9).

• Reinvestment sinks (§4) — final tuning of construction / upgrade / licence costs as the inflation brakes.