Design — Production & buildings

High-level design for the production layer: what a building is, the few archetypes there are, how goods are made along a specialized chain, how a building levels and is built, and the rules that keep the economy from seizing up. This is the model the controller layer drives (controllers.md — managers post the tasks), the market prices (economy.md — goods are sold into it), and the guilds gate (../GAME_DESIGN.md §5 — a licence to practice). Design doc — the model and its rules, not an implementation plan.

This doc is the truth; the data follows it. ../../design/production_notes.md (the long list of workshops, recipes, and prices) is throwaway scratch data — a quick fill made before this design existed. Where it disagrees with this doc, it is wrong and gets remapped or discarded. Treat it as an appendix of candidate numbers, not a specification.

The shortest version: a building is a chassis that posts tasks; its repertoire of task families gives it flavour. Production is the core family — make goods by transforming inputs, along a chain of specialized shops that must trade with each other — and three structural rules guarantee that chain can never deadlock.

1. What a building is — a chassis plus a repertoire

The trap to avoid is “every building is a production workshop with no character.” A building is more general than production and more specific than a blob:

A building is a manager-seated site that posts tasks into the task substrate. What makes one building feel different from another is its task repertoire — the specific set of task families it can post.

• Production is one family — transform inputs into goods you sell. It is the majority of what most workshops do, and the family designed in depth here.

• Services are other families — yield gold directly (serve a customer, treat a patient), or apply a special effect (lead a prayer → a buff; pickpocket → steal + bank a crime memory, memory.md). Services are a first-class extension point: the chassis is built to carry them, but each actual service (tavern, church, hospital, criminal den) is designed with its own pillar (crime, and a future town-services pass), not here.

A smith and a carpenter share roughly the same production repertoire, so they should feel similar — that is correct, not a lack of flavour. A tavern or a hospital feels different because its repertoire is different. Everything a building does is still a task (../GAME_DESIGN.md §2) — services are just building-specific task kinds, posted by the same seated manager.

Production isn’t privileged in the engine — it is simply the task family whose output is goods you sell. The economy (economy.md) only cares that something produces sellable goods or gold; services feed it through a different door.

2. The building taxonomy — three archetypes

There are exactly three kinds of building. Everything else is a configuration or repertoire of one of them.

The workshop is the chassis from §1; the gathering spot is the one archetype that breaks the manager rule (it is just there, free to all); the house is special enough (it does four unrelated jobs) to stand on its own rather than be “a workshop that only has services.”

3. The production chain — hard specialization

Production is a specialized, split chain: distinct buildings own distinct steps, and a shop genuinely cannot make everything it needs. The carpenter does not make his own nails — the smith makes nails, and the carpenter buys them. There is no self-supply fallback; cross-production between shops is the normal state, not an exception.

This is a deliberate choice. A vertically integrated shop (raw → final under one roof) would be simple but would flatten the inter-shop economy the controller layer exists to orchestrate. Hard specialization is what gives orders (controller → controller, controllers.md §3) and the Trademaster’s routing real work: the dynasty is a supply chain you (or the AI) coordinate — mine → smeltery → smith → market.

The price of hard specialization is the risk of a soft-lock — a shop idle because nobody supplies its input, cascading into a seized economy. §4 is how that is prevented.

4. Three stacked soft-lock guards

Specialization is made safe by three complementary rules. Together they guarantee a shop can always obtain its inputs and always earn, so the chain cannot deadlock.

1. L1 is raws-only — the guaranteed income floor. A level-1 recipe never consumes another shop’s product; it converts raw materials only. So every shop — freshly built, isolated, or cut off from the supply web — always has a raw → good → income path. Cross-shop dependencies (consuming an intermediate) begin at L2. (An L1 output may still be sold as a cross-product — iron ingot from ore+coal is raws-only L1 and the basic others buy; what L1 may not do is consume another shop’s product.)

2. Production inputs are “critical” — the market never runs dry. Every resource that appears as an input in a production recipe is, by definition, flagged critical, and the City guarantees a baseline supply of critical goods on the market (economy.md §8 — the City-owned supply floor / critical-import valve). So a shop blocked on nails can always buy them. This also gives “critical” a rule instead of a hand-picked list: critical = anything consumed by a recipe.

3. Cross-products are cheap — the web stays liquid. Anything one shop depends on another to supply is kept low-tier and easy to make (L1, occasionally L2). A web of cheap shared basics is one the City can realistically backstop and shops can cheaply trade; a web of expensive deep dependencies is exactly what soft-locks.

The fallback for a blocked shop is the market, backstopped by the City — never self-sufficiency. Specialization stays hard; the safety net is purchasability, not self-supply.

Balancing edge (held): the City’s critical-supply guarantee must be a last-resort floor, not a cheap firehose — likely priced at a premium — or it quietly becomes an infinite cheap source that flattens real production. The guarantee of availability is the anti-soft-lock promise; the price is the knob that keeps trade worthwhile. (See CHALLENGES; this is the economy-tailspin risk, one level down.)

5. Leveling — two interacting axes

How capable a workshop is comes from two separate axes that both must be satisfied:

• Building level — climbed by upgrading (§6). Each level grants:

  1. more worker slots — capacity is headcount; more workers = more labour in parallel = more throughput;

  2. new recipes — the tier gate (L1 raws-only floor → L2 → L3 specialized finals);

  3. (idea, not solid) a level modifier to unlock — see “paid upgrades” below. - Guild licence — the separate permission axis (../GAME_DESIGN.md §5, designed in the guilds pillar): permission to practice the craft at all (gates building and upgrading it) + bonus modifiers, levelled by material contribution.

You need both: the licence says may you practice this trade; the level says how far up it you have climbed.

Worker slots are filled by dynasty family labour (free, floating across the dynasty’s buildings) and hired workers (waged) — per dynasty.md and the employment model; production does not redesign that here.

No inventory cap — a deliberate non-feature. Buildings (and inventories generally) hold unlimited goods. Guild 2’s per-stack holding limit is intentionally rejected: it is fiddly micro the player dislikes, and — more importantly — a stock cap punishes the AI hardest (it cannot babysit overflowing inventory the way a human can), which would break the player↔AI symmetry the whole design rests on (../GAME_DESIGN.md §2). This supersedes the stack_limit concept in the current item/DB code.

Paid upgrades (idea, not solid). Guild 2-style purchasable per-building modifiers bought for money. Recorded as an open idea — it overlaps the GDD §5 guild “document” buffs (purchasable timed bonuses); both are just entries in the modifier system, so whether shop-upgrades and guild-documents are one mechanism or two is a guilds-pillar question.

6. The building lifecycle — plot → build → upgrade

A building comes into being and climbs along one path:

  empty land plot ──buy──► construct (timer) ──► Workshop L1 ──upgrade──► L2 ──► L3

Each step costs money + time — and nothing else. Construction and upgrading do not consume materials. This is deliberate: a material cost bites hardest exactly when the player is poorest and least established (early game), and it would tangle construction into the production logistics web right when expansion should feel clean. Building stays a pure gold sink, which is also what economy.md wants (sinks = build / upgrade / licence / buy).

The one extra gate is the guild licence rank: you cannot upgrade a craft’s workshop past the level your licence rank allows — coupling the building ladder to the guild ladder (../GAME_DESIGN.md §5). The precise rank mechanics belong to the guilds pillar; here it is a hook, not a full design.

(The plot → construct mechanic largely exists in code already — ConstructingBuildingComponent + BuildingUpgradeSystem transform a bought plot into a building at L1 — see §9.)

7. The House — a special archetype

The house is not a workshop with services; it does four distinct jobs and so stands on its own:

• Residence. Characters sleep there. Dynasty members live in the house; simple hired workers live in worker cottages — a housing variant for non-dynasty labour.

• Depot. The house has its own inventory and is a delivery target: the Marshal orders swords to the house, and a guard draws them from it. This is where non-shop positions keep and stage goods.

• Muster point. Where idle dynasty workers wait when they have no task — notably guards, who are essentially always dynasty workers.

• Service repertoire. House-specific service tasks — e.g. spy (a guard shadows a target and banks crime memory, memory.md, if he witnesses something). The house is, in effect, “a workshop that is all services, plus home and warehouse.”

This resolves a question the controller pass parked: non-shop positions like the Marshal presumably operate from some building (an HQ / house equivalent) (controllers.md §9). The house is that HQ — the Marshal works out of it; orders deliver there.

Open (parked to a second pass): whether a dynasty has one house or several. Not decided here.

8. Building state — presence, health, destruction

• Characters go into a building to work — they vanish inside a workshop or house while working; at a gathering spot they stand around it. Mostly presentation, but flagged with one possible mechanical edge: “inside” may mean off-map / not interceptable, which could matter for the crime/combat pillar (can you attack a guard who is home, or a worker mid-craft?). A flag, not a decision.

• Buildings have health and can be destroyed. A building carries a destructible HP state and is a legitimate target of the force front (attack rival buildings, ../GAME_DESIGN.md §5). The attack that deals the damage, and what a destroyed building leaves behind (rubble / reverts to plot / sunk investment), are crime & conflict pillar questions — recorded here, designed there.

9. ⚠ Tensions with current code

Recorded as a map of what will change — not as a constraint on the design (the design leads; see the project’s design-is-truth stance).

• Buildings are “owned ⇒ produce,” with one blind brain. Today WorkshopSystem walks every owned workshop and posts a fixed Hire/Craft/Sell/Gather ladder; there is no manager, no repertoire, no service families, no order-driven trade. The chassis + repertoire model (§1) and the controller layer it implies are greenfield (controllers.md §8).

• The chain is not specialized or guarded. No notion of “cross-product,” no L1-raws-only rule, no “critical input” flag, no City supply floor — and the scratch recipes in production_notes.md violate the L1 rule (intermediates appear at L1). The recipe DAG must be remapped under §4. The dynamic market and the City valve those guards lean on are themselves greenfield (economy.md §7).

• Extraction is inert. Extraction buildings have output data (ExtractionProductionComponent) but no controller drives them — they produce nothing today. Under §2 they are just inputless workshops; they need the same manager/controller as any workshop.

• Levels exist; the two-axis gate does not. BuildingComponent carries level / maxLevel and BuildingUpgradeSystem upgrades buildings, and the plot → construct path exists (ConstructingBuildingComponent). But recipe-tier-by-level, capacity (worker slots) by level, and the guild-licence permission/rank gate are unbuilt (the licence layer does not exist at all — guilds pillar).

• stack_limit contradicts “no inventory cap.” The DB/item code carries a stack_limit; §5 deletes the concept. This is the production answer to the economy TODO’s item/inventory re-examination.

• No building health / destruction. Buildings cannot currently be damaged or destroyed (§8); greenfield, tied to the crime pillar.

• Gathering exists but is hardwired. GatheringSpotComponent models the commons, but the only consumer is the blind WorkshopSystem gather-at-random step; the unowned-commons role (§2) is fine, its use is part of the controller rework.

10. Open questions & held notes (next pass)

• The concrete recipe DAG. The actual workshops, recipes, tiers, and prices — remapped under the §4 rules — is concrete data, the successor to production_notes.md. A balancing job, not architecture.

• Service families in depth (§1). Each real service (tavern, church, hospital, criminal den) — its tasks, gold/effect outputs — is designed with its pillar (crime; a future town-services pass), not here.

• One house or many (§7). Parked to a second pass.

• Paid upgrade modifiers (§5). Whether they exist, and whether they are the same mechanism as guild “documents” — a guilds-pillar question.

• City critical-supply pricing (§4). The premium/last-resort tuning that keeps the supply floor from flattening trade — balancing, owned jointly with economy.md.

• Building destruction outcome (§8). What a destroyed building leaves behind — a crime/loss-pillar question.

• “Inside the building” mechanics (§8). Whether working characters are off-map / un-interceptable — a crime/combat-pillar question.

• Worker cottages (§7). The housing variant for hired labour — its own rules (capacity? one per worker?) are sketched, not designed.