Skip to content

A town simulation in pale isometric line art, implemented with Ritmo ECS and PixiJs 3D

25.9 KB
Raw Blame
/**
 * The mayor's guide: a tutorial told through the ticker, one step at a
 * time, written for someone who has never played a town-builder. Each step
 * is one thing to do (`action`) and one reason for it (`why`), and names the
 * buildings it asks for (`asks`) so the ticker can turn them into chips that
 * place them. A step shows while it applies (`when`) and is put away for good
 * once the town has done it (`done`), whether or not it was ever shown, so a
 * mayor who already knows the game is not told what they did. The list is in
 * order of priority, not of chapters: a request from the crown with a
 * deadline goes ahead of a chain that takes minutes to build.
 *
 * Most steps are a course (`course`), taught in order, chapter by chapter,
 * and counted ("step 3 of 8"). Founding: homes, a road to the water, a
 * fishery, a look at what it needs, a lumberjack, a sawmill, the term's goal,
 * and ten homes. Growing citizens: a quarry, cloth, faith, bread, the first
 * citizens, the goals again. Governing: the ranks, up to a city. The course always has
 * something to say, so the guide never falls silent on a mayor who does not
 * know what comes next; a step whose buildings the town cannot build yet
 * says what opens them (`lockedNote`), and the course goes on to one it can.
 *
 * The course never asks for a building before the town needs it: a
 * building's upkeep starts the day it stands. A step with a `need` waits for
 * it (planks running low, stone running low), the course goes on past it,
 * and the card says what comes next and when (`upcoming`: "next: a
 * lumberjack and a sawmill, once planks fall below 25 (31 now)").
 *
 * Around the course, steps come when the town needs them: each waits for a
 * sign (stone running low, the woods thinning, a fire risk rising), goes
 * ahead of the course once Founding is done, and after one is done the guide
 * keeps quiet about such signs for `GUIDE_QUIET` seconds. An urgent step (the
 * crown's request, winter, a fire, the sick, a building falling apart) does
 * not wait for the quiet. A sign once shown stays until it is done or put
 * away, so the ticker does not hop between steps.
 *
 * A step that asks for a building is done when the building stands, not when
 * it is laid; in between, `waiting` says what is happening (carriers bringing
 * planks to the site), so the mayor knows they did the right thing.
 *
 * The texts are written once for mouse and touch. In them:
 * - a building's name (in `asks`) becomes a chip that starts placing one;
 * - `[homes]`, `[road]`, `[select]`, `[build]`, `[town]`, `[speed]`,
 *   `[pause]`, and `[view:fire]` (any map view) become chips that pick that
 *   tool, open that panel, or show that view; on a keyboard they carry the key;
 * - `{tap|click}` reads "tap" on a touch screen and "click" with a mouse.
 */
import { kinds, type Amounts, type KindId } from "../content/index.ts"

/** What the guide reads of the town. */
export interface GuideFacts {
  /** Homes laid, built or not; and built. */
  readonly homes: number
  readonly builtHomes: number
  readonly residents: number
  /** Citizens, and homes that hold them (citizens' homes and townhouses). */
  readonly citizens: number
  readonly finerHomes: number
  /** Kinds of building placed (sites too), and standing. */
  readonly placed: ReadonlySet<KindId>
  readonly standing: ReadonlySet<KindId>
  readonly stock: Amounts
  readonly sick: number
  readonly burning: number
  /** It is winter now, or the next one is this many seconds away (`null`: none before the term ends). */
  readonly winter: boolean
  readonly winterIn: number | null
  /** A building that wants mending. */
  readonly worn: boolean
  /** A settlers' home with every citizens' need met, on a street too poor for citizens. */
  readonly poorStreet: boolean
  readonly crown: { readonly open: boolean; readonly met: number }
  /** Coins a minute, and approval. */
  readonly net: number
  readonly approval: number
  /** The town buys or sells something; a tax rate is off the usual. */
  readonly trading: boolean
  /** The town buys tools from traders. */
  readonly buysTools: boolean
  readonly taxed: boolean
  /** The most of any one good in store. */
  readonly most: number
  /** The page: the town panel is open; a home is selected; a building (not the town hall) is selected. */
  readonly sawTown: boolean
  readonly sawHome: boolean
  readonly sawBuilding: boolean
  /** A road comes within two cells of water, close enough for a fishery on it. */
  readonly roadToWater: boolean
  /** The town's rank: 0 hamlet, 1 village, 2 town, 3 city. */
  readonly rank: number
  /** Kinds of building upgraded where they stand (a market hall, a church). */
  readonly upgraded: ReadonlySet<KindId>
  /** Coins in the treasury. */
  readonly coins: number
  /** Built homes no food walker reaches (the town hall's or a market's). */
  readonly unreached: number
  /** A home whose risk of fire, sickness, or theft is rising. */
  readonly risk: { readonly fire: boolean; readonly health: boolean; readonly order: boolean }
  /** A lumberjack with few trees left in reach. */
  readonly fewTrees: boolean
}

/** Seconds of the town's time the guide keeps quiet after a step, before the next that is not urgent. */
export const GUIDE_QUIET = 45

/** Where a step's "show me where" goes: a place on the land, or a building of a kind. */
export type GuideFocus = "hall" | "water" | "trees" | "stone" | "ore" | "worn" | "poorStreet" | { readonly kind: KindId }

export const chapters = ["Founding", "Keeping it standing", "Growing citizens", "Governing"] as const
export type Chapter = (typeof chapters)[number]

export interface GuideStep {
  readonly id: string
  readonly chapter: Chapter
  /** What to do, in one sentence. */
  readonly action: string
  /** Why, in a sentence or two. */
  readonly why: string
  /** When the step is done, in a few words: shown under it, so the mayor knows what closes it. */
  readonly goal: string
  /** The buildings the step asks for: their names in the text become chips to place one. */
  readonly asks?: ReadonlyArray<KindId>
  readonly focus: GuideFocus | null
  readonly when: (f: GuideFacts) => boolean
  /** Part of the course, taught in this order chapter by chapter, without the quiet. */
  readonly course?: boolean
  /** A course step that waits until the town needs it (the course goes on past it meanwhile); and, while it waits, what for. */
  readonly need?: (f: GuideFacts) => boolean
  readonly soon?: (f: GuideFacts) => string
  /** It cannot wait for the guide's quiet (and goes ahead of the step shown). */
  readonly urgent?: (f: GuideFacts) => boolean
  readonly done: (f: GuideFacts) => boolean
  /** Once the mayor has done their part and the town is at work on it: what is happening (`null`: not yet). */
  readonly waiting?: (f: GuideFacts) => string | null
}

/** Every one of these buildings stands (built, not only laid). */
const has = (f: GuideFacts, ...kinds: ReadonlyArray<KindId>) => kinds.every((k) => f.standing.has(k))

/** Planks and stone low enough that a lumberjack and a sawmill, or a quarry, are worth their upkeep. */
export const PLANKS_LOW = 25
export const STONE_LOW = 8

/** What a site needs while it waits: planks, mostly, carried from the store. */
const siteNote = (f: GuideFacts) =>
  f.stock.planks === 0
    ? "The store has no planks left, so the site waits: sell something in the [town] panel, or buy planks there."
    : "It is a building site for now: carriers bring its planks and stone from the store, then builders put it up. [speed] makes time run faster."

/** The step's buildings are laid but not all standing yet. */
const rising = (...kinds: ReadonlyArray<KindId>) => (f: GuideFacts) =>
  kinds.some((k) => f.placed.has(k) && !f.standing.has(k)) ? siteNote(f) : null

export const guideSteps: ReadonlyArray<GuideStep> = [
  // ── The opening, in order ──
  {
    id: "homes",
    chapter: "Founding",
    course: true,
    action: "Pick [homes] and drag along the grey road around the town hall{, then tap Build|}.",
    why: "Settlers move into homes that touch a road, and every home pays taxes: the town's income.",
    goal: "a home stands",
    focus: "hall",
    when: () => true,
    done: (f) => f.builtHomes > 0,
    waiting: (f) =>
      f.homes > 0
        ? f.stock.planks === 0
          ? "The homes wait for planks, and the store has none."
          : "Builders are carrying planks from the store to the new homes, and settlers move in once one stands. [speed] makes time run faster."
        : null
  },
  {
    id: "road",
    chapter: "Founding",
    course: true,
    action: "Pick [road] and drag a road from the town hall's road towards the water.",
    why: "Every building needs a road touching the middle of one of its sides, or nobody can reach it. The fishery comes next, and it needs water nearby.",
    goal: "a road comes within two cells of water",
    focus: "water",
    when: () => true,
    done: (f) => f.roadToWater || has(f, "fishery") || has(f, "bakery")
  },
  {
    id: "fishery",
    chapter: "Founding",
    course: true,
    action: "{Tap|Click} fishery, then place it on that road, with water no more than two cells away.",
    why: "Settlers eat fish. The town starts with a little, and fish rots in store.",
    goal: "a fishery stands",
    asks: ["fishery"],
    focus: "water",
    when: () => true,
    done: (f) => has(f, "fishery") || has(f, "bakery"),
    waiting: rising("fishery")
  },
  {
    id: "look",
    chapter: "Founding",
    course: true,
    action: "Pick [select] and {tap|click} the fishery to open its panel.",
    why: "A building needs workers from homes within 15 road cells; its panel says how many it has, and what holds it back. The jobs counter at the top adds them all up.",
    goal: "you open a building's panel",
    focus: { kind: "fishery" },
    when: (f) => f.standing.has("fishery"),
    done: (f) => f.sawBuilding
  },
  {
    id: "lumberjack",
    chapter: "Founding",
    course: true,
    action: "Build a lumberjack on a road beside the trees.",
    why: "Planks are running low, and every home and building costs some. Wood is where planks start.",
    goal: "a lumberjack stands",
    asks: ["lumberjack"],
    focus: "trees",
    when: () => true,
    need: (f) => f.stock.planks < PLANKS_LOW || f.placed.has("lumberjack"),
    soon: (f) => `a lumberjack and a sawmill, once planks fall below ${PLANKS_LOW} (${f.stock.planks} now)`,
    done: (f) => has(f, "lumberjack"),
    waiting: rising("lumberjack")
  },
  {
    id: "sawmill",
    chapter: "Founding",
    course: true,
    action: "Build a sawmill on a road near the lumberjack.",
    why: "Goods come in chains: the lumberjack fells wood, and the sawmill saws it into planks. Carriers walk the goods between them along the roads.",
    goal: "a sawmill stands",
    asks: ["sawmill"],
    focus: { kind: "lumberjack" },
    when: () => true,
    need: (f) => f.stock.planks < PLANKS_LOW || f.placed.has("lumberjack") || f.placed.has("sawmill"),
    soon: (f) => `a sawmill, once planks fall below ${PLANKS_LOW} (${f.stock.planks} now)`,
    done: (f) => has(f, "sawmill"),
    waiting: rising("sawmill")
  },
  {
    id: "term",
    chapter: "Founding",
    course: true,
    action: "Open the [town] panel and read the goals at its top.",
    why: "Meeting them raises the town from hamlet to village, town, and city, each with a reward from the crown. [pause] stops the clock whenever you need to think.",
    goal: "you open the town panel",
    focus: null,
    when: () => true,
    done: (f) => f.sawTown
  },
  {
    id: "grow",
    chapter: "Founding",
    course: true,
    action: "Lay more roads and homes until ten homes stand.",
    why: "More people pay more taxes, and unlock new buildings in [build]. The guide asks for a building only once the town needs it.",
    goal: "10 homes stand",
    focus: "hall",
    when: () => true,
    done: (f) => f.builtHomes >= 10,
    waiting: (f) => (f.homes >= 10 && f.builtHomes < 10 ? "Ten homes are laid: builders are putting them up." : null)
  },

  // ── The course goes on: citizens ──
  {
    id: "quarry",
    chapter: "Growing citizens",
    course: true,
    action: "Build a quarry on a road beside the pale rocks.",
    why: "Stone is running low, and the workshops citizens need cost some. The dark rocks are ore, for later.",
    goal: "a quarry stands",
    asks: ["quarry"],
    focus: "stone",
    when: () => true,
    need: (f) => f.stock.stone < STONE_LOW || f.placed.has("quarry"),
    soon: (f) => `a quarry, once stone falls below ${STONE_LOW} (${f.stock.stone} now)`,
    done: (f) => has(f, "quarry"),
    waiting: rising("quarry")
  },
  {
    id: "cloth",
    chapter: "Growing citizens",
    course: true,
    action: "Build a sheep farm and a weaver, on roads near each other.",
    why: "A home becomes a citizens' home with bread, cloth, and faith. The sheep farm shears wool, and the weaver weaves it into cloth.",
    goal: "a sheep farm and a weaver stand",
    asks: ["sheep", "weaver"],
    focus: "hall",
    when: () => true,
    done: (f) => has(f, "sheep", "weaver"),
    waiting: rising("sheep", "weaver")
  },
  {
    id: "chapel",
    chapter: "Growing citizens",
    course: true,
    action: "Build a chapel on a road among the homes.",
    why: "Faith is the second need. The chapel's walker brings it to the homes it passes, and the chapel makes its street nicer to live on.",
    goal: "a chapel stands",
    asks: ["chapel"],
    focus: "hall",
    when: () => true,
    done: (f) => has(f, "chapel"),
    waiting: rising("chapel")
  },
  {
    id: "wheat",
    chapter: "Growing citizens",
    course: true,
    action: "Build a farm and a mill.",
    why: "Bread is the third need, and the longest chain: the farm grows wheat, and the mill grinds it into flour.",
    goal: "a farm and a mill stand",
    asks: ["farm", "mill"],
    focus: "hall",
    when: () => true,
    done: (f) => has(f, "farm", "mill"),
    waiting: rising("farm", "mill")
  },
  {
    id: "bakery",
    chapter: "Growing citizens",
    course: true,
    action: "Build a bakery near the mill.",
    why: "It bakes the mill's flour into bread. Even a settlers' cottage with bread on the table pays half again.",
    goal: "a bakery stands",
    asks: ["bakery"],
    focus: { kind: "mill" },
    when: (f) => has(f, "farm", "mill"),
    done: (f) => has(f, "bakery"),
    waiting: rising("bakery")
  },
  {
    id: "citizens",
    chapter: "Growing citizens",
    course: true,
    action: "Pick [select] and {tap|click} a home to see what it still lacks to hold citizens.",
    why: "With bread, cloth, faith, and a street of desirability 5, a home rises once the store pays its planks and stone. Its panel lists what is missing.",
    goal: "the first home holds citizens",
    focus: "hall",
    when: () => true,
    done: (f) => f.finerHomes > 0
  },
  {
    id: "goals",
    chapter: "Growing citizens",
    course: true,
    action: "Open the [town] panel to see how close the goals are.",
    why: "The first citizens have moved in, and each rank asks for a bigger share of them.",
    goal: "you open the town panel",
    focus: null,
    when: (f) => f.finerHomes > 0,
    done: (f) => f.sawTown
  },
  {
    id: "ranks",
    chapter: "Governing",
    course: true,
    action: "Meet every goal in the [town] panel to raise the town's rank.",
    why: "Hold them for two minutes and the town rises, up to a city. The town rank opens upgrades for the market and the chapel. The guide speaks up when something needs you.",
    goal: "the town is a city",
    focus: null,
    when: () => true,
    done: (f) => f.rank >= 3
  },

  // ── Around the course, when the town needs them ──
  {
    id: "crown",
    chapter: "Governing",
    action: "Send the crown what it asks for, with the send button on its request at the top.",
    why: "It pays coins. An unanswered request is a fine, and three missed in a row end your term.",
    goal: "the goods are sent",
    focus: null,
    when: (f) => f.crown.open,
    urgent: () => true,
    done: (f) => f.crown.met > 0
  },
  {
    id: "winter",
    chapter: "Keeping it standing",
    action: "Build a granary or a smokehouse before winter comes.",
    why: "In winter fishing slows, homes eat more, and fish rots in store. A granary keeps it five times as long, and smoked fish keeps all winter.",
    goal: "a granary or a smokehouse stands",
    asks: ["granary", "smokehouse"],
    focus: "hall",
    when: (f) => f.residents >= 20 && (f.winter || (f.winterIn !== null && f.winterIn <= 120)),
    urgent: () => true,
    done: (f) => has(f, "granary") || has(f, "smokehouse"),
    waiting: rising("granary", "smokehouse")
  },
  {
    id: "tools",
    chapter: "Growing citizens",
    action: "In the [town] panel, under goods and trade, set tools to buy.",
    why: "Workshops use up tools, and only a smithy makes new ones, which opens at 10 citizens.",
    goal: "the town buys tools, or a smithy stands",
    focus: null,
    when: (f) => f.residents >= 15 && f.citizens < 10 && f.stock.tools <= 3 && !has(f, "smithy"),
    done: (f) => f.buysTools || has(f, "smithy")
  },
  {
    id: "forester",
    chapter: "Founding",
    action: "Build a forester next to the lumberjack.",
    why: "The lumberjack is running out of trees, and a forester plants new ones for it.",
    goal: "a forester stands",
    asks: ["forester"],
    focus: { kind: "lumberjack" },
    when: (f) => f.fewTrees,
    done: (f) => has(f, "forester"),
    waiting: rising("forester")
  },
  {
    id: "firewatch",
    chapter: "Keeping it standing",
    action: "Build a fire watch on a road among the homes.",
    why: "Wooden cottages catch fire, and a fire spreads to the neighbours. Its watchman keeps the risk down, and its firefighters put fires out. [view:fire] shows the risk.",
    goal: "a fire watch stands",
    asks: ["firewatch"],
    focus: "hall",
    when: (f) => f.risk.fire || f.burning > 0,
    urgent: (f) => f.burning > 0,
    done: (f) => has(f, "firewatch"),
    waiting: rising("firewatch")
  },
  {
    id: "builder",
    chapter: "Keeping it standing",
    action: "Build a builder's yard near the worn buildings.",
    why: "A run-down building works at half pace and can fall down. Its builder mends what it passes, with planks and stone. [view:condition] shows their state.",
    goal: "a builder's yard stands",
    asks: ["builder"],
    focus: "worn",
    when: (f) => f.worn,
    urgent: () => true,
    done: (f) => has(f, "builder"),
    waiting: rising("builder")
  },
  {
    id: "market",
    chapter: "Keeping it standing",
    action: "Build a market among the homes furthest from the town hall.",
    why: "Some homes are beyond the town hall's walker, which only reaches 20 road cells, and get no food. A market's walker carries it further.",
    goal: "a market stands",
    asks: ["market"],
    focus: "hall",
    when: (f) => f.unreached >= 2,
    done: (f) => has(f, "market"),
    waiting: rising("market")
  },
  {
    id: "markethall",
    chapter: "Keeping it standing",
    action: "{Tap|Click} the market (the gold arrow over it) and begin its market hall from its panel.",
    why: "Some homes are beyond every food walker. A market hall's walker goes further and more often, without a second market's upkeep.",
    goal: "a market hall stands",
    focus: { kind: "market" },
    when: (f) => f.rank >= 2 && has(f, "market") && f.unreached >= 2,
    done: (f) => f.upgraded.has("market")
  },
  {
    id: "street",
    chapter: "Growing citizens",
    action: "Raise this home's street to desirability 5: add a chapel, a market, or a park nearby, and keep workshops away.",
    why: "It has bread, cloth, and faith, but citizens only live on a decent street. [view:appeal] shows desirability.",
    goal: "a home on a fine street holds citizens",
    asks: ["chapel", "market"],
    focus: "poorStreet",
    when: (f) => f.poorStreet,
    done: (f) => f.finerHomes > 0
  },
  {
    id: "carpenter",
    chapter: "Growing citizens",
    action: "Build a carpenter: it makes furniture from planks.",
    why: "Burghers live in townhouses, and a townhouse wants furniture: two pieces to rise to one, and a fresh piece from the market now and then to stay one. Townhouses pay the most and hold the most people.",
    goal: "a carpenter stands",
    asks: ["carpenter"],
    focus: "hall",
    when: (f) => f.citizens >= 60 && f.finerHomes >= 8,
    done: (f) => has(f, "carpenter"),
    waiting: rising("carpenter")
  },
  {
    id: "healer",
    chapter: "Keeping it standing",
    action: "Build a healer on a road among the homes.",
    why: "Sickness is spreading, and a sick home holds half as many people. The healer's physician calls on homes and cures them. [view:health] shows the risk.",
    goal: "a healer stands",
    asks: ["healer"],
    focus: "hall",
    when: (f) => f.residents >= 30 && (f.sick > 0 || f.risk.health),
    urgent: (f) => f.sick > 0,
    done: (f) => has(f, "healer") || has(f, "hospital"),
    waiting: rising("healer")
  },
  {
    id: "watchhouse",
    chapter: "Keeping it standing",
    action: "Build a watch house on a road among the homes.",
    why: "Poor streets, half-empty homes, and low approval breed thieves. Its constable walks the streets and keeps order. [view:order] shows the risk.",
    goal: "a watch house stands",
    asks: ["watchhouse"],
    focus: "hall",
    when: (f) => f.residents >= 40 && f.risk.order,
    done: (f) => has(f, "watchhouse"),
    waiting: rising("watchhouse")
  },
  {
    id: "trade",
    chapter: "Governing",
    action: "In the [town] panel, under goods and trade, sell a good that piles up, or buy one that runs short.",
    why: "The town trades nothing until you tell it to, and spare goods are coins waiting to be made.",
    goal: "the town sells or buys something",
    focus: null,
    when: (f) => f.residents >= 20 && (f.net < 0 || f.most >= 80),
    done: (f) => f.trading
  },
  {
    id: "taxes",
    chapter: "Governing",
    action: "Raise taxes a little in the [town] panel.",
    why: "The town is content but losing coins, and approval can carry higher taxes. Above 125% leaves a grudge that lasts.",
    goal: "a tax rate is changed",
    focus: null,
    when: (f) => f.approval >= 30 && f.net < 0,
    done: (f) => f.taxed
  },
  {
    id: "smithy",
    chapter: "Governing",
    action: "Build a mine beside the dark, rust-veined rocks, and a smithy.",
    why: "Tools are running low, and every workshop uses them up. The mine digs ore, and the smithy forges it into tools.",
    goal: "a mine and a smithy stand",
    asks: ["mine", "smithy"],
    focus: "ore",
    when: (f) => f.citizens >= 10 && f.stock.tools <= 5,
    done: (f) => has(f, "mine", "smithy"),
    waiting: rising("mine", "smithy")
  }
]

/** The course, in order. */
export const courseSteps: ReadonlyArray<GuideStep> = guideSteps.filter((s) => s.course)

/** Where a course step stands in its chapter ("step 3 of 8"), or `null` for a step not in the course or alone in its chapter. */
export const courseCount = (step: GuideStep): { readonly at: number; readonly of: number } | null => {
  if (!step.course) return null
  const chapter = courseSteps.filter((s) => s.chapter === step.chapter)
  return chapter.length > 1 ? { at: chapter.indexOf(step) + 1, of: chapter.length } : null
}

/** When the town cannot build what a step asks for yet: what opens it, and what to do meanwhile (`null`: it can). */
export const lockedNote = (step: GuideStep, f: GuideFacts): string | null => {
  for (const id of step.asks ?? []) {
    const kind = kinds[id]
    if (kind.unlock.residents > f.residents)
      return `The ${kind.title.toLowerCase()} opens at ${kind.unlock.residents} residents (${f.residents} now): lay more [homes] and keep them fed.`
    if (kind.unlock.citizens > f.citizens) return `The ${kind.title.toLowerCase()} opens at ${kind.unlock.citizens} citizens (${f.citizens} now).`
  }
  // Not yet laid, and the treasury cannot pay for the cheapest of them.
  const unpaid = (step.asks ?? []).filter((id) => !f.placed.has(id)).map((id) => kinds[id])
  const cheapest = unpaid.sort((a, b) => a.cost.coins - b.cost.coins)[0]
  if (cheapest && f.coins < cheapest.cost.coins)
    return `Save up: the ${cheapest.title.toLowerCase()} costs ${cheapest.cost.coins} coins (${f.coins} now). Homes pay taxes every minute.`
  return null
}

/** The next course step that waits for the town to need it: what it is, and when it comes (`null`: none waiting). */
export const upcoming = (f: GuideFacts, done: ReadonlySet<string>): string | null => {
  const step = courseSteps.find((s) => !done.has(s.id) && !s.done(f) && s.when(f) && s.need && !s.need(f) && s.soon)
  return step ? `Next: ${step.soon!(f)}.` : null
}

/** The steps the town has now done that the guide has not yet put away. */
export const guideDone = (f: GuideFacts, done: ReadonlySet<string>): Array<string> =>
  guideSteps.filter((s) => !done.has(s.id) && s.done(f)).map((s) => s.id)

/**
 * The step to show now, if any: an urgent one first; then the course while
 * the town is being founded; then a sign already shown (`shown`), until it is
 * done or put away; then, unless the guide is keeping `quiet`, a new sign;
 * and otherwise the course: its next step, or when the town cannot build
 * that yet, a later building it can (else the step, saying what opens it).
 */
export const guideStep = (f: GuideFacts, done: ReadonlySet<string>, pace: { readonly shown?: string | null; readonly quiet?: boolean } = {}): GuideStep | null => {
  const open = (s: GuideStep) => !done.has(s.id) && !s.done(f)
  const urgent = guideSteps.find((s) => open(s) && s.when(f) && s.urgent?.(f))
  if (urgent) return urgent
  const course = courseSteps.filter((s) => open(s) && s.when(f) && (s.need?.(f) ?? true))
  // A step the town cannot build yet gives way to a later building it can; else it shows, saying what opens it.
  const first = course[0] ?? null
  const next = first && lockedNote(first, f) !== null ? (course.find((s) => s.asks && lockedNote(s, f) === null) ?? first) : first
  if (next?.chapter === "Founding") return next
  const shown = guideSteps.find((s) => s.id === pace.shown && !s.course && open(s) && (!s.urgent || s.when(f)))
  if (shown) return shown
  const sign = pace.quiet ? undefined : guideSteps.find((s) => !s.course && open(s) && s.when(f))
  return sign ?? next
}