A town simulation in pale isometric line art, implemented with Ritmo ECS and PixiJs 3D
/**
* Saving and loading a town, as Effect programs. A save is a versioned file
* (the world as the simulation snapshots it, with a title and when it was
* saved) in one of two slots: the mayor's own, and the autosave the page
* writes every few minutes of game time. Loading reads, checks, and
* restores it, failing with what went wrong: nothing saved, a file that
* cannot be read, a version this game does not know, or a world the
* simulation refuses. Where the files live (the browser's storage, or a map
* in a test) and the world they come from are services.
*/
import { Clock, Context, Effect, Schema } from "effect"
import { goodIds, TOWN_RANK, TRADE_LOAD } from "../game/content/index.ts"
export const SAVE_FORMAT = "inkline-town/save"
/**
* 2: the charter's towns. 3: neighbourhoods and their dangers (desirability, crews, risks, wear, ruins,
* winters). 4: parks and patrols. 5: the grudge over taxes, and where each piece of news happened.
* 6: how much of each good may be traded at a collection. 7: the mayor's guide. 8: terms that follow one
* another, the town's rank, and upgraded buildings.
* 10: fixed-step Clock values and runtime snapshot format 2. 11: runtime snapshot format 3 (Ritmo 0.13).
* Version 4 to 10 saves are carried forward (see `carry`); older ones cannot be loaded.
*/
export const SAVE_VERSION = 11
/**
* Fills in what a save from an earlier version lacks, so a town in progress
* survives an update: from 10, the runtime's snapshot format 3, which
* changed only how state machines are saved, and the town has none; from 4, the mood's grudge (none yet) and the news's
* places (unknown); from 5, trade at full loads, as it was; from 6, the
* guide from its start (it puts away at once what the town has already
* done); from 7, its first term, and its rank: a town that was complete
* (or governed on after) is a town, any other a hamlet that rises as its
* goals hold. A complete town waiting on its mayor carries on playing;
* from 8, its water as never fished, its upgrades as the first, its finer
* homes as rebuilt already, and no furniture anywhere yet, at its first price.
* Anything else is left to the world's own validation.
*/
const carry = (version: number, world: unknown): unknown | null => {
if (version < 4 || version > 10 || typeof world !== "object" || world === null) return null
const w = world as { version?: number; scopes?: Record<string, unknown>; resources?: Record<string, unknown>; entities?: Array<{ components?: Record<string, unknown> }> }
const r = w.resources
if (!r || typeof r !== "object") return null
// Town never used entity scopes before this format. Its old clock counted
// the same 60 Hz steps under `tick`; preserve that count exactly.
if (w.version === 1) { w.version = 2; w.scopes = {} }
// Format 3 saves a state machine with its fields; the town has no machines, so a format 2 world is the same.
if (w.version === 2) w.version = 3
const time = r["Town/Time"]
if (typeof time === "object" && time !== null && "tick" in time && typeof time.tick === "number") {
r["Town/Time"] = { step: time.tick, hz: 60, dt: time.tick > 0 ? 1 / 60 : 0 }
}
if (version === 9 || version === 10) return w
// From 8, water that was never fished, and an upgraded building upgraded once.
for (const e of Array.isArray(w.entities) ? w.entities : []) {
const water = e.components?.["Town/Water"]
if (water && typeof water === "object" && !("fished" in water)) e.components!["Town/Water"] = { fished: -1_000_000 }
const upgraded = e.components?.["Town/Upgraded"]
if (upgraded && typeof upgraded === "object" && !("level" in upgraded)) e.components!["Town/Upgraded"] = { level: 1 }
}
// From 8 too, furniture: none of it anywhere, at its first price, stores and markets that take it, homes and the census without it.
const furnish = (o: unknown, furniture = 0) => (o && typeof o === "object" && !("furniture" in o) ? { ...o, furniture } : o)
for (const e of Array.isArray(w.entities) ? w.entities : []) {
const c = e.components
if (!c) continue
for (const [name, field] of [["Town/Site", "owed"], ["Town/Works", "owed"], ["Town/Inventory", "stock"], ["Town/Roam", "basket"]] as const) {
const v = c[name] as Record<string, unknown> | undefined
if (v && typeof v === "object") c[name] = { ...v, [field]: furnish(v[field]) }
}
if (c["Town/House"]) c["Town/House"] = furnish(c["Town/House"])
// Homes rose for nothing before 9: a finer home has had its rebuilding, and rises back into it for nothing if it steps down.
const tier = (c["Town/House"] as { tier?: unknown } | undefined)?.tier
if ((tier === 2 || tier === 3) && !("Town/Rebuilt" in c)) c["Town/Rebuilt"] = { tier }
const inventory = c["Town/Inventory"] as { accepts?: Array<string> } | undefined, kind = (c["Town/Building"] as { kind?: string } | undefined)?.kind
if (inventory && Array.isArray(inventory.accepts) && !inventory.accepts.includes("furniture")
&& (kind === "market" || goodIds.every((g) => g === "furniture" || inventory.accepts!.includes(g))))
inventory.accepts = [...inventory.accepts, "furniture"]
}
if (r["Town/Census"]) r["Town/Census"] = furnish(r["Town/Census"])
const market = r["Town/Market"] as { prices?: unknown } | undefined
if (market && typeof market === "object") r["Town/Market"] = { ...market, prices: furnish(market.prices, 100) }
const loads = (r["Town/Policy"] as { loads?: Record<string, unknown> } | undefined)?.loads
if (loads && typeof loads === "object" && !("furniture" in loads)) loads.furniture = TRADE_LOAD
if (version === 8) return w
const fate = r["Town/Fate"] as Record<string, unknown> | undefined
if (fate && typeof fate === "object" && !("rank" in fate)) {
const { governing, won, ...rest } = fate
const complete = rest.state === "won" || governing === true || (typeof won === "number" && won >= 0)
r["Town/Fate"] = {
...rest,
state: rest.state === "won" ? "playing" : rest.state,
reason: rest.state === "won" ? "" : rest.reason,
term: 1,
began: 0,
rank: complete ? TOWN_RANK : 0,
goalSince: -1
}
}
if (version === 7) return w
if (!("Town/Guide" in r)) r["Town/Guide"] = { done: [], off: false }
if (version === 6) return w
const policy = r["Town/Policy"]
if (policy && typeof policy === "object" && !("loads" in policy)) r["Town/Policy"] = { ...policy, loads: Object.fromEntries(goodIds.map((g) => [g, TRADE_LOAD])) }
if (version === 5) return w
const mood = r["Town/Mood"]
if (mood && typeof mood === "object" && !("grudge" in mood)) r["Town/Mood"] = { ...mood, grudge: 0, memory: 0 }
const chronicle = r["Town/Chronicle"] as { lines?: Array<Record<string, unknown>> } | undefined
if (chronicle && Array.isArray(chronicle.lines)) r["Town/Chronicle"] = { ...chronicle, lines: chronicle.lines.map((l) => ({ at: null, ...l })) }
return w
}
export type Slot = "manual" | "auto"
export const slots: ReadonlyArray<Slot> = ["manual", "auto"]
const keyOf = (slot: Slot) => `inkline-town/save/${slot}`
/** Where the first charter version kept its one save: the world alone, no envelope. */
const LEGACY_KEY = "town/save/charter"
/** A save file. */
export const SaveFile = Schema.Struct({
format: Schema.Literal(SAVE_FORMAT),
version: Schema.Int,
slot: Schema.Literals(["manual", "auto"]),
/** When it was saved, in milliseconds since the epoch. */
savedAt: Schema.Int,
/** What it is, in a line: "medium, fair land · year 2 · 23 min in". */
title: Schema.String,
world: Schema.Unknown
})
export type SaveFile = typeof SaveFile.Type
const decodeFile = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown))
const decodeEnvelope = Schema.decodeUnknownEffect(SaveFile)
// ── What can go wrong ─────────────────────────────────────────────────────
export class NothingSaved extends Schema.TaggedError<NothingSaved>()("NothingSaved", { slot: Schema.String }) {}
export class Unreadable extends Schema.TaggedError<Unreadable>()("Unreadable", { slot: Schema.String, reason: Schema.String }) {}
export class WrongVersion extends Schema.TaggedError<WrongVersion>()("WrongVersion", { slot: Schema.String, version: Schema.Number }) {}
export class Rejected extends Schema.TaggedError<Rejected>()("Rejected", { slot: Schema.String, reason: Schema.String }) {}
export class StorageFailed extends Schema.TaggedError<StorageFailed>()("StorageFailed", { slot: Schema.String, reason: Schema.String }) {}
/** The world refused to be saved: a value its schema could not encode. */
export class Unsaveable extends Schema.TaggedError<Unsaveable>()("Unsaveable", { slot: Schema.String, reason: Schema.String }) {}
export type LoadError = NothingSaved | Unreadable | WrongVersion | Rejected | StorageFailed
/** What to tell the mayor. */
export const describe = (error: LoadError | StorageFailed | Unsaveable): string => {
switch (error._tag) {
case "NothingSaved":
return error.slot === "auto" ? "No autosave yet" : "Nothing saved yet"
case "Unreadable":
return "The save could not be read"
case "WrongVersion":
return error.version < SAVE_VERSION ? "That save is from an older version of the game" : "That save is from a newer version of the game"
case "Rejected":
return `The save does not fit this game: ${error.reason}`
case "StorageFailed":
return `Could not save: ${error.reason}`
case "Unsaveable":
return `Could not save the town: ${error.reason}`
}
}
// ── Services ──────────────────────────────────────────────────────────────
/** Where save files are kept, by key. */
export class Storage extends Context.Service<Storage, {
readonly get: (key: string) => string | null
readonly set: (key: string, value: string) => void
}>()("inkline-town/Storage") {}
/** The town being saved and loaded. */
export class World extends Context.Service<World, {
/** The world as plain data, or why it could not be saved (Ritmo's `runtime.snapshot()` result). */
readonly snapshot: () => { readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly error: unknown }
/** Restores a world, or says why it will not. */
readonly restore: (world: unknown) => string | null
/** The town in a line, for a save's title. */
readonly title: () => string
}>()("inkline-town/World") {}
/** The browser's storage (which can throw: full, or blocked). */
export const browserStorage = (store: globalThis.Storage): Storage["Service"] => ({
get: (key) => store.getItem(key),
set: (key, value) => store.setItem(key, value)
})
/** Storage in a map, for tests and for running headless. */
export const memoryStorage = (files = new Map<string, string>()): Storage["Service"] & { readonly files: Map<string, string> } => ({
files,
get: (key) => files.get(key) ?? null,
set: (key, value) => {
files.set(key, value)
}
})
// ── Saving and loading ────────────────────────────────────────────────────
/** The town as a save file, written nowhere: what a slot keeps, and what a shared town carries. */
export const fileOf = (slot: Slot) =>
Effect.gen(function* () {
const world = yield* World
const snapshot = world.snapshot()
if (!snapshot.ok) return yield* new Unsaveable({ slot, reason: JSON.stringify(snapshot.error) })
const file: SaveFile = {
format: SAVE_FORMAT,
version: SAVE_VERSION,
slot,
savedAt: yield* Clock.currentTimeMillis,
title: world.title(),
world: snapshot.value
}
return file
})
/** Writes the town to a slot. */
export const save = (slot: Slot) =>
Effect.gen(function* () {
const storage = yield* Storage
const file = yield* fileOf(slot)
yield* Effect.try({
try: () => storage.set(keyOf(slot), JSON.stringify(file)),
catch: (cause) => new StorageFailed({ slot, reason: cause instanceof Error ? cause.message : String(cause) })
})
return file
})
/** Reads a slot's file, checked, without loading it. A save from before files had envelopes reads as the manual slot. */
export const read = (slot: Slot) =>
Effect.gen(function* () {
const storage = yield* Storage
const raw = yield* Effect.try({
try: () => storage.get(keyOf(slot)) ?? (slot === "manual" ? storage.get(LEGACY_KEY) : null),
catch: (cause) => new StorageFailed({ slot, reason: cause instanceof Error ? cause.message : String(cause) })
})
if (raw === null) return yield* new NothingSaved({ slot })
const parsed = yield* decodeFile(raw).pipe(Effect.mapError((e) => new Unreadable({ slot, reason: e.message })))
// The first charter saves were the world alone.
if (typeof parsed === "object" && parsed !== null && "entities" in parsed && !("format" in parsed)) {
return { format: SAVE_FORMAT, version: SAVE_VERSION, slot, savedAt: 0, title: "an earlier save", world: carry(9, parsed) ?? parsed } satisfies SaveFile
}
const version = (parsed as { version?: unknown } | null)?.version
if (typeof version === "number" && version !== SAVE_VERSION) {
const carried = carry(version, (parsed as { world?: unknown }).world)
if (carried === null) return yield* new WrongVersion({ slot, version })
const file = yield* decodeEnvelope({ ...(parsed as object), version: SAVE_VERSION, world: carried }).pipe(Effect.mapError((e) => new Unreadable({ slot, reason: e.message })))
return file
}
return yield* decodeEnvelope(parsed).pipe(Effect.mapError((e) => new Unreadable({ slot, reason: e.message })))
})
/** Loads a slot into the world. */
export const load = (slot: Slot) =>
Effect.gen(function* () {
const file = yield* read(slot)
const world = yield* World
const refused = world.restore(file.world)
if (refused !== null) return yield* new Rejected({ slot, reason: refused })
return file
})
/** The slot saved last that can still be read (the mayor's own save, or the autosave), without loading it; `null` when there is none. */
export const latest = Effect.gen(function* () {
const files = yield* Effect.forEach(slots, (slot) => read(slot).pipe(Effect.option))
return files.flatMap((f) => (f._tag === "Some" ? [f.value] : [])).sort((a, b) => b.savedAt - a.savedAt)[0] ?? null
})
/** Loads whichever slot was saved last: the mayor's own save, or the autosave. */
export const loadLatest = Effect.gen(function* () {
const newest = yield* latest
return yield* load(newest?.slot ?? "manual")
})
/**
* Loads a save file handed over as text (a shared town), checked and
* carried forward as a load from a slot is, without touching the slots.
*/
export const loadText = (text: string) =>
load("manual").pipe(Effect.provideService(Storage, memoryStorage(new Map([[keyOf("manual"), text]]))))