A town simulation in pale isometric line art, implemented with Ritmo ECS and PixiJs 3D
/**
* What the view layer trades with every UI and renderer, as plain data: no
* page, no Three.js. A UI (the page in `ui/dom`, or any other) and the map
* input write the `Interaction`; the view's systems read the world and it,
* move the selection and drags on, and fill in what is `Shown`: a
* `TownView` for the UI and a `SceneView` for the renderer. Player actions
* go to the simulation as edits (`game/edits.ts`). None of it is saved.
*/
import type { Amounts, CharterValue, GoodId, GroundId, KindId, PropId, Tier, WinterId } from "../game/content/index.ts"
import type { Point } from "../game/world/iso.ts"
import type { Status } from "../game/schema.ts"
import type { IconName } from "./icons.ts"
/** How a line of a panel reads: fine, worth a look, wrong, or an aside. */
export type Tone = "ok" | "warn" | "bad" | "dim"
/**
* A line of a building's or home's description: an icon, what it is about,
* its value, and (when something is wrong, or worth knowing) a note
* underneath saying why and what to do. `goods` are shown as icon chips.
*/
export interface Line {
readonly icon: IconName | GoodId
readonly label: string
readonly value?: string | undefined
readonly note?: string | undefined
readonly tone?: Tone | undefined
readonly goods?: ReadonlyArray<{ readonly good: GoodId; readonly count: number }> | undefined
/** What to do about it, under the note: and, when it is to build something, what (the panel offers to place it). */
readonly fix?: { readonly text: string; readonly build?: KindId | undefined } | undefined
}
/**
* A box of a panel's rows under a heading (`help` sits behind an ⓘ). Every
* row reads the same way: what, then a short value; a note under it only
* when there is something to do about it, or a line of context.
*/
export interface Group {
readonly title: string
readonly icon: IconName
readonly help?: string | undefined
readonly lines: ReadonlyArray<Line>
}
/** Something that needs looking at now, and where (when it is somewhere). */
export interface Alert {
/** A next step to take, something going wrong, or something that costs the town now. */
readonly tone: "hint" | "warn" | "bad"
readonly text: string
readonly at: Point | null
/** The footprint there, cells a side, for the outline. */
readonly size: number
/** The entity to select on the way there, if there is one. */
readonly id: number | null
/** Buildings the line names, by kind: where one of each stands, so its chip goes there rather than placing another. */
readonly places?: Partial<Record<KindId, { readonly at: Point; readonly size: number; readonly id: number }>>
}
export type Tool = "select" | "road" | "pave" | "home" | "bulldoze" | "place" | "ground" | "prop" | "upgrade"
/** What the map shows over the town: nothing, or one of its views, cell by cell. */
export const viewIds = ["none", "appeal", "workers", "fire", "health", "order", "condition"] as const
export type View = (typeof viewIds)[number]
/** What the pointer did, in grid coordinates. */
export type Gesture =
| { readonly type: "press"; readonly at: Point }
| { readonly type: "release"; readonly at: Point; readonly panned: boolean; readonly hit?: number | null }
export type Look = "hover" | "picked" | "blocked" | "reach"
/** What the town shows besides its entities: ghosts, the road being dragged, outlines. */
export interface Preview {
/** Outlines on the floor: `size` cells a side from (x, y). */
plots: Array<{ readonly x: number; readonly y: number; readonly size: number; readonly look: Look }>
/** Ghost buildings and homes, at their footprints' top cells. */
ghosts: Array<{ readonly what: KindId | "home"; readonly cell: Point }>
/** Road cells about to be laid. */
roads: Array<Point>
/** Road cells a thing being placed would reach: a service's walkers, or the commute its workers (or a home's residents) make. */
range: Array<Point>
/** What `range` shows, for the tooltip. */
rangeNote: string | null
/** Park cells about to be laid or furnished, as they will look. */
parks: Array<{ readonly x: number; readonly y: number; readonly ground: GroundId; readonly prop: PropId | "none" }>
/** The entity under the pointer. */
hover: number | null
/** Bulldozing: the hovered thing is tinted. */
danger: boolean
tooltip: string | null
/** A road, pave, home, or park stroke being dragged: how much it lays and what it costs. */
stroke: string | null
}
export const emptyPreview = (): Preview => ({ plots: [], ghosts: [], roads: [], range: [], rangeNote: null, parks: [], hover: null, danger: false, tooltip: null, stroke: null })
/** The side panel: the build menu, the town's numbers and taxes, a building, or a home. */
export type Panel =
| { readonly type: "build" }
| { readonly type: "town" }
| {
readonly type: "building"
readonly id: number
readonly cell: Point
readonly kind: KindId
readonly status: Status
/** Why it is not working, when it is not. */
readonly problem: string | null
/** How it is, as a row of its own above the rest: working, or what keeps it from it and what to do. */
readonly state: Line
/** Whether it can be paused (not the town hall, not a site), and whether it is. */
readonly pausable: boolean
readonly paused: boolean
/** What pulling it down costs and gives back: "pull down: −25 coins · 2 planks back". */
readonly salvage: string
readonly groups: ReadonlyArray<Group>
/** What it is called and what it is for, at its level of upgrades (a market hall, not a market). */
readonly title: string
readonly blurb: string
/** Upgrades it has had (see `Kind.upgrade`), and whether it has had any. */
readonly level: number
readonly upgraded: boolean
/**
* The upgrade it could have next (`null`: none, or one under way): what it becomes, what it costs
* now and carried in, what changes, and what keeps it from it now (the rank; coins short).
*/
readonly upgrade: {
readonly title: string
readonly blurb: string
readonly price: string
/** Why the town needs it now, when it does (the gold arrow over it); `null`: it can wait. */
readonly needed: string | null
/** Coins now, and the materials carriers bring. */
readonly cost: { readonly coins: number; readonly materials: Partial<Record<GoodId, number>> }
readonly changes: ReadonlyArray<string>
readonly blocked: string | null
readonly short: string | null
} | null
/** An upgrade under way: what it is to become, the share of its materials in, and what is still owed. */
readonly works: { readonly title: string; readonly share: number; readonly left: string } | null
}
| {
readonly type: "house"
readonly id: number
readonly cell: Point
readonly tier: Tier
/** Whether it can be closed (standing, not on fire), and whether it is: a closed home stands empty and costs nothing. */
readonly closable: boolean
readonly closed: boolean
readonly salvage: string
/** How it is, in a word or two for the header ("4 residents", "hungry"), and whether that is trouble. */
readonly summary: string
readonly trouble: boolean
readonly groups: ReadonlyArray<Group>
}
| {
readonly type: "park"
readonly id: number
readonly cell: Point
/** Cells, and the desirability it gives out to how far. */
readonly cells: number
readonly value: number
readonly reach: number
readonly lines: ReadonlyArray<Line>
}
| {
readonly type: "ruin"
readonly id: number
readonly cell: Point
readonly cause: "burnt" | "collapsed" | "derelict"
readonly lines: ReadonlyArray<Line>
}
/** The town's numbers for the top bar and the panels. */
export interface Stats {
readonly coins: number
readonly taxes: number
/** What the same homes would pay a minute with every need met: taxes left on the table when it is more. */
readonly suppliedTaxes: number
/** Taxes a minute at each step of a tier's rate, once the homes settle at it; empty while the tier has no homes. */
readonly taxOutlook: Readonly<Record<"settlers" | "citizens", ReadonlyArray<{ readonly rate: number; readonly taxes: number }>>>
readonly trade: number
readonly upkeep: number
readonly admin: number
/** Coins a minute: taxes and trade less upkeep and administration. */
readonly net: number
readonly homes: number
/** Homes with each need met. */
readonly needs: { readonly food: number; readonly bread: number; readonly cloth: number; readonly faith: number; readonly furniture: number }
/** Homes that are townhouses (the ones that keep furniture). */
readonly townhouses: number
readonly policy: {
readonly settlers: number
readonly citizens: number
readonly sells: ReadonlyArray<GoodId>
readonly buys: ReadonlyArray<GoodId>
readonly reserve: number
readonly loads: Amounts
}
readonly stock: Amounts
/** Each good's price with traders, in percent of the usual. */
readonly prices: Amounts
readonly settlers: number
/** Citizens in citizens' homes and townhouses; of them, `burghers` in townhouses. */
readonly citizens: number
readonly burghers: number
readonly jobs: number
readonly employed: number
/** Workplaces short of workers, to step through from the jobs counter. */
readonly shortStaffed: ReadonlyArray<{ readonly id: number; readonly title: string; readonly cell: Point; readonly size: number; readonly assigned: number; readonly needed: number; readonly nobodyNear: boolean }>
readonly charter: CharterValue
/** Minutes since the town was founded (see `fate.began` for this term's). */
readonly minute: number
readonly season: {
readonly year: number
readonly winter: boolean
readonly left: number
/** This winter's severity, while it lasts; and the next one the almanac foresees, and the one after. */
readonly severity: WinterId | null
readonly coming: WinterId | null
readonly after: WinterId | null
}
readonly mood: {
readonly approval: number
readonly target: number
readonly parts: ReadonlyArray<{ readonly label: string; readonly value: number }>
}
/** The crown's open request, if any: seconds left to answer it. */
readonly crown: {
readonly open: boolean
readonly good: GoodId
readonly amount: number
readonly left: number
readonly reward: number
readonly met: number
readonly missed: number
/** Missed in a row, and how many in a row the crown puts up with. */
readonly streak: number
readonly patience: number
/** Seconds until the next request. */
readonly next: number
}
readonly fate: {
readonly state: "playing" | "lost" | "over"
readonly reason: string
/** Minute (since the founding) the term ended. */
readonly at: number
/** Which term this is, from 1, and the minute (since the founding) it began. */
readonly term: number
readonly began: number
/** The rank the town has reached (see `ranks`), and the next one, or `null` at the top. */
readonly rank: number
readonly rankTitle: string
readonly nextTitle: string | null
/** This term's score, once it has ended. */
readonly score: number
/** Seconds left before each danger ends the term, or `null` when it is not threatening. */
readonly bankrupt: number | null
readonly revolt: number | null
/** Seconds the next rank's goals have to hold still, or `null` when they are not all met. */
readonly rises: number | null
readonly peak: number
}
/** The next rank's goals (see `goalsOf`): what each asks (`target`, in its own unit), how the town stands, and whether it is met. */
readonly goals: ReadonlyArray<{ readonly id: string; readonly target: number; readonly text: string; readonly value: string; readonly met: boolean }>
readonly larder: number
/**
* Each good over the last minute: made, used (eaten, worked up, built
* with, rotted, sent away), and bought less sold; and how much the town
* holds outside storage now (workshops, markets, baskets, crates). A
* rolling minute, reckoned again every ten seconds; `null` for the
* first half minute.
*/
readonly flow: {
readonly made: Amounts
readonly used: Amounts
readonly traded: Amounts
readonly elsewhere: Amounts
/** The treasury over the same minute: taxes and other income, upkeep and spending, and trade. */
readonly coins: { readonly made: number; readonly used: number; readonly traded: number }
} | null
/** Food the town ate, and food that rotted in store, over the last minute. */
readonly eaten: number
readonly rotted: number
/** Homes sick, and homes and buildings on fire, right now. */
readonly sick: number
readonly burning: number
readonly history: ReadonlyArray<{
readonly tick: number
readonly coins: number
readonly residents: number
readonly citizens: number
readonly approval: number
readonly net: number
}>
readonly chronicle: ReadonlyArray<{ readonly tick: number; readonly text: string; readonly alarm: boolean; readonly at: Point | null }>
/** What needs looking at right now, a line each: workshops waiting, workplaces no one can reach, food running out. */
readonly alerts: ReadonlyArray<Alert>
/**
* The upgrades the town could make, one for each kind and level (a market to a market hall; the town
* hall to a guildhall, or a guildhall to a city hall): what it becomes, what it costs now and carried
* in, what changes, what keeps it from it (the rank), and how many buildings are ready for it and under way.
*/
readonly upgrades: ReadonlyArray<{
readonly kind: KindId
readonly level: number
readonly from: string
readonly to: string
readonly blurb: string
readonly coins: number
readonly materials: Partial<Record<GoodId, number>>
readonly price: string
readonly changes: ReadonlyArray<string>
readonly blocked: string | null
readonly ready: number
readonly underway: number
}>
/** The mayor's guide: the step to take now (if any, and the guide is on), and how far along it is. */
readonly guide: {
readonly step:
| (Omit<Alert, "tone"> & {
readonly key: string
readonly chapter: string
readonly goal: string
/** Why the step matters, in a sentence or two (`text` is what to do). */
readonly why: string
/** The mayor has done their part, and the town is at work on it: what is happening (`null`: not yet). */
readonly waiting: string | null
/** The town cannot build what it asks for yet: what opens it (`null`: it can). */
readonly locked: string | null
/** The next step that waits for the town to need it, and when it comes ("Next: a quarry, once stone falls below 8"). */
readonly next: string | null
/** The buildings it asks for: only these become chips that place one. */
readonly asks: ReadonlyArray<KindId>
/** The building it points at, when that stands (`id`): its name goes there rather than placing another. */
readonly near: KindId | null
/** Where it stands in the opening ("step 3 of 8"), or `null` after it. */
readonly count: { readonly at: number; readonly of: number } | null
})
| null
readonly done: number
readonly total: number
readonly off: boolean
}
}
/** A map view's legend: what each colour means. */
export interface Legend {
readonly title: string
readonly keys: ReadonlyArray<{ readonly color: number; readonly label: string }>
readonly note: string
}
/** A map view's cell: a colour washed over it, and whether it is outlined. */
export interface OverlayCell {
readonly x: number
readonly y: number
readonly size: number
readonly color: number
readonly alpha: number
/** Outlined, for what the view is about (a workplace and its homes). */
readonly ring?: boolean
}
/** What the mayor tells the guide: put a step away, or turn the guide off or on (see `Guide`). */
export type GuideAction = { readonly type: "skip"; readonly id: string } | { readonly type: "off" | "on" }
/**
* What the player is doing with the map. The UI sets the tool, the menu, the
* speed, and the map view; the map input sets the pointer and queues
* gestures; the view's systems turn gestures into a selection, drags, and
* edits.
*/
export interface Interaction {
tool: Tool
/** The kind being placed with the `place` tool, and the kind whose buildings the `upgrade` tool upgrades. */
placing: KindId | null
upgrading?: KindId | null
/** The ground laid with the `ground` tool, and the furnishing set with the `prop` tool. */
ground: GroundId
prop: PropId
/** Which side panel the toolbar opened, when nothing is selected. */
menu: "build" | "town" | null
/** The pointer on the grid, or `null` off the canvas. */
pointer: Point | null
/** Camera-ray entity hit. Undefined allows grid-only headless interaction. */
pointerHit?: number | null
/** Where a road, a row of homes, or a patch of park being dragged started. */
dragFrom: Point | null
/** The stroke from `dragFrom` is held for a tap to confirm (touch), or let go here it would be dropped (off the map). */
stroke?: "held" | "cancel" | null
selected: number | null
gestures: Array<Gesture>
/** What the mayor told the guide since the last frame. */
guide: Array<GuideAction>
/** Steps of the simulation a fixed step: 0 (paused), 1, 2, or 4. */
speed: number
/** The new-town dialog is open: the town waits. */
founding: boolean
/** The map view shown over the town. */
view: View
/** A place the page points at (from the ticker): outlined until `until`, in milliseconds of the wall clock. */
flash: { readonly cell: Point; readonly size: number; readonly until: number } | null
}
/** What the UI shows, filled in by the view once a frame. */
export interface TownView {
panel: Panel | null
stats: Stats | null
legend: Legend | null
/** What the pointer is over, or what the stroke being dragged lays and costs. */
tooltip: string | null
stroke: string | null
/** Messages for the player since the last frame: the UI takes them. */
toasts: Array<string>
}
/** What the renderer draws besides the world's entities, filled in by the view once a frame. */
export interface SceneView {
preview: Preview
/** The map view's cells (rebuilt as the town changes, `key` says when). */
overlay: { readonly key: string; readonly cells: ReadonlyArray<OverlayCell> }
/** The view's colour for each building and home, washed over the model itself so it reads from above. */
tints: ReadonlyMap<number, number>
/** The buildings whose upgrade the town needs now, with why (the gold arrow over each). */
wanted: ReadonlyMap<number, string>
/** How fast the town's people move about: the speed, or 0 while the town waits. */
pace: number
}
/** Everything the view shows, in two parts: the UI's and the renderer's. */
export interface Shown {
readonly town: TownView
readonly scene: SceneView
}
/** The map before anything is clicked. */
export const blankInteraction = (): Interaction => ({
tool: "select", placing: null, upgrading: null, ground: "lawn", prop: "lamp", menu: null, pointer: null, dragFrom: null, selected: null, gestures: [], guide: [],
speed: 1, founding: false, view: "none", flash: null
})
/** Nothing shown yet. */
export const blankShown = (): Shown => ({
town: { panel: null, stats: null, legend: null, tooltip: null, stroke: null, toasts: [] },
scene: { preview: emptyPreview(), overlay: { key: "", cells: [] }, tints: new Map(), wanted: new Map(), pace: 1 }
})