Design — The Crown & Kingdom Events

High-level design for the outside world: the off-screen sovereign — the Crown — and the Kingdom Events through which it reaches into the town’s single market. Answers to ../GAME_DESIGN.md §3 (the core loop’s dynamic market) and completes the hooks economy.md §6 registered but left undesigned. Design doc — the model and its rules, not an implementation plan.

There is one town and one market (economy.md §1) — no second city to trade with, no caravans, no logistics simulation. The rest of the kingdom exists abstractly, as the Crown: a force that reaches into the local market and bends it. This is the thematic payoff of the title — Guilds of the Crown** — bought cheaply.

The Crown is three things at once, and the design only makes sense if all three are held in mind:

1. A bit of flavour — named, announced events (“The Crown marches to war”) that make the world feel alive and connected to something larger.

2. A bit of chaos — timed swings in what’s profitable, so the market never settles into a solved steady state. The “what should I make this month” churn.

3. A bit of sanctioned “cheat” — when the market seizes, the Crown/City can inject supply to restart it. Honest about why it exists (a safety net), but mechanically it is just the City being a responsible controller (§4).

The Crown is an environmental force, not a negotiating party. You do not petition it, curry its favour, or sign charters with it as a played system. It happens to the town; you read it and react. (Real Crown diplomacy is deliberately parked — see §6.)

1. The mechanism — an event is a timed bundle of pool-modifiers

The market already has the machinery this pillar needs. economy.md §3 defines per-good demand/supply pools, and §2 the scarcity multiplier that moves price as stock runs against demand. A Kingdom Event adds no new market machinery — it is a named, timed, announced bundle of modifiers on those same pools.

   A KINGDOM EVENT  =  announce-text  +  [ one or more effects ]  +  duration
                                          └─ each pushes on a §3 pool ─┘

That is the whole pillar. An event cannot do anything the dynamic market cannot already express; it just turns a knob the market already has, for a while, with a name on it. Adding an event is a data row (§2) — the pool system already opts in, exactly as crime kinds and memory kinds are rows readers opt into.

2. The event atom — a data row

Crimes (crime.md §5) and memory kinds (memory.md §4) are data-driven tables, not hardcoded lists; events follow the same discipline. Each event is a row:

  event kind → [ effect rows ] · duration · weight · announce-text

An event bundles several effects

An event carries a list of effect-rows under one announce-text. A single “war” is then a real event — weapon demand up and food drained as armies consume it — not one isolated knob-turn. Costs nothing structurally (a 1-to-many); buys a lot of texture.

The four effect kinds — and only four

Every effect is one of exactly the four pushes economy.md already defined. An event never reaches outside this set:

Each effect row is { effect · target (good / category) · magnitude }. target can be a single good (bread) or a whole category (weapons). All magnitudes, durations, and weights are balancing knobs — the model is kept this small precisely so it is all knobs.

Room to grow. This is deliberately the minimum that works. Obvious later expansions — chained/sequential events, region flavour, events that touch demographics or politics rather than only market pools, player-influenceable events — all slot on top of this atom without changing it. Not now.

3. What fires events — two triggers, one atom

Events are produced by two different mechanisms wearing the same “event” clothing. Keeping them separate is what lets the random roller stay dumb and the safety net stay reliable.

Ambient events — a weighted timer

A scheduler fires on a jittered timer (every N days ± noise — balancing): it rolls the weighted event table (§2 weight) and activates one. This is the flavour and chaos — the ambient war/famine/trade-boom churn that keeps “what’s profitable” moving. The roller is stateless about market health: it never looks at whether anything has seized; it just turns the wheel. That is what keeps it trivial to reason about and balance.

The relief valve — a reactive trigger, off the table

The crisis import (§4) is not on the random table. It fires because the market seized, never by dice — a safety net that depended on luck would not be a safety net. It reuses the event atom (a supply+ injection) purely as convenient packaging; its trigger is a state check, not the scheduler.

So: both emit the same atom; only the trigger differs — a weighted roll for ambient events, a state condition for the relief valve.

4. The relief valve — crisis import

economy.md §8 holds the tailspin death-spiral as a known balancing risk and floats two safety valves. They are different in kind and split cleanly:

• The permanent supply floor — the City owns some raw-resource production outright, so a critical raw can never be 100% monopolised. This is structural and always-on, runs through the normal controller layer (a city-owned building, GDD §2), and is not a Crown event. It stays an economy.md / production.md concern. crown.md does not own it.

• Crisis import — when a critical good seizes anyway, supply is injected to restart flow. This is the relief valve, and crown.md owns it.

What “seized” means

Kept crude on purpose — it is a safety net, not a simulation:

A good flagged critical (production.md §4 — anything a recipe consumes) whose scarcity multiplier sits pinned at the cap (economy.md §2) for N consecutive days → the market is seized for that good. Fire a supply+ injection of it for a duration, then re-check. N, the injection volume, and the duration are balancing knobs.

It is the City controller’s call, not a blind if

The pinned-critical state is the signal; the City controller decides whether to import — exactly the memory.md pattern (the state is the signal; the controller decides what to do). The City is just another controller (GDD §2) acting on its Agenda, so the relief valve is not a special-cased economy hack bolted outside the model — it is the City AI doing its job of keeping the town’s economy alive. The “cheat” framing is honest about the intent (the City has a bottomless treasury and uses it to stabilise); mechanically it is symmetric with everything else.

5. Presentation — one read-only panel

economy.md §6 called for “a single screen listing active events and their modifiers. Nothing too crazy.” Confirmed, and read-only:

• A Crown / Kingdom Events panel lists every currently-active event, each showing: the announce-text, the affected good(s), the effect(s) in plain terms (“Weapons demand +40%”, “Food −20/day”), and days remaining.

• No interaction. You do not act on events — the Crown is not a negotiating party (intro, §6). The panel is pure situational awareness: what is the Crown doing to my market right now, and how long do I have to exploit or survive it.

• The relief valve shows here too while active, so a critical good suddenly loosening is visible — no invisible hand yanking the market without the player understanding why.

6. Deliberately parked

The same “earn complexity on a proven base” discipline the social layer used (relationships.md §6): design the shape, ship the minimum.

• Crown diplomacy as a played system — petitions, royal favour/reputation, charters negotiated with the Crown, royal demands you accept or refuse. The Crown stays an environmental force; making it a party is a whole future layer, cousin to the parked inter-dynasty diplomacy (relationships.md §6, rival-ai.md §7).

• Chained / scripted event arcs — a war that escalates over several events, with memory of what came before. The atom (§2) supports it later; not seeded now.

• Events touching non-market systems — events that shift demographics, force a political event, or trigger crime. Kept to market pools only for 1.0.

• Player-influenceable events — bribing the Crown to lift a tariff, lobbying for a war. Needs the diplomacy layer above.

7. Already in code / what it reuses

The pillar is greenfield — there is no Crown, event, or scheduler concept in the code today. But it is the thinnest pillar by far, because it owns almost no machinery of its own — it is a content layer plus a scheduler on top of the dynamic market:

• The demand/supply pools (economy.md §3) — every effect is a push on these. They do not exist yet (the market is static-price today, economy.md §7) — which is why this pillar sequences after the dynamic market.

• The scarcity multiplier (economy.md §2) — the relief valve’s “pinned at cap” trigger reads it.

• The critical flag (production.md §4) — the relief valve only watches critical goods.

• The controller layer (GDD §2, controllers.md) — the City is a controller; the crisis import is its Agenda call (§4).

• The per-good surcharge hook — the tariff effect (§2) and the Chamberlain’s standing tariff dial (politics.md §2) write the same hook from two sources (one event-set, one seat-set), mirroring how demand pools take both internal and Crown pushes.

• A timed-modifier substrate — events expire after duration; if the market’s pool modifiers already carry expiry, events reuse it; otherwise this is the one small new piece (a tick that retires lapsed events).

What is genuinely new is small: the event roster (data), the ambient scheduler (a weighted timer), the relief-valve trigger (a state check the City controller acts on), and the one panel.

8. ⚠ Tensions with current code

• The whole market substrate is greenfield. Pools, scarcity multiplier, and the BuyStep drain are all unbuilt (economy.md §7). There is nothing to push on until they exist — this pillar cannot ship before the dynamic market.

• No Crown / event concept anywhere. No scheduler, no event component, no panel.

• The critical flag is not modelled — production.md §4 defines it conceptually (anything a recipe consumes) but no code marks goods critical yet; the relief valve needs it.

• The City-as-controller layer is unbuilt (GDD §2 tension) — the relief valve being “the City’s Agenda call” assumes a City controller that does not exist yet; until it does, the import would be a plain reactive system (acceptable interim).

• Tariff hook shared with politics. The tariff effect and the Chamberlain dial (politics.md §2) must write one shared per-good surcharge; if that hook is built for only one of them first, the other must reuse it, not fork.

9. Open questions (next pass)

• The ambient cadence & weights (§3) — how often events fire, the jitter, and the per-event weights. Pure balancing.

• The seeded event roster (§2) — the concrete starting list (war, famine, trade boom, blight…), each event’s effects/magnitudes/durations. Content + balancing, kept open like the crime roster.

• The relief-valve trigger numbers (§4) — N consecutive pinned days, injection volume, import duration, re-check cadence. Balancing — and the tuning risk that it must keep the market healthy without feeling like the AI rigs the game or yanks the rug (→ CHALLENGES).

• Tariff overlap (§7/§8) — the Crown tariff effect and the Chamberlain dial are two separate things sharing one hook; revisit whether they overlap too much in implementation/balance and should be reconciled.

• Timed-modifier home (§7) — whether event expiry reuses the market’s pool- modifier expiry or needs its own retirement tick.