# game.core
**The shared vocabulary of THE CITY REMEMBERS.** Every build slice reads it; no slice writes it.
It answers the questions five agents building at once would otherwise each answer differently: where
the districts are, how big a block is, what the clock says, what a reputation score is worth, how
much heat is a star, which colours the references were drawn in, and the names of the scene entities
each slice attaches its component to.
It holds **no behaviour**. Rules live here (a pure function from position to district, from score to
band, from heat to stars); systems live in the slices.
## What is in it
| Field | What it settles |
|---|---|
| `city` | 9 × 9 grid of 80 m blocks on a 100 m pitch, 20 m streets, origin at block (4, 4), ground 1400 m. |
| `districts` | The six districts in the ledger's own order, each with the grid test that claims a cell and its character, height range, density and police presence. |
| `landmarks` | The named places the city must contain (station, hospital, precinct, bank, dealer, market, hotel, diner) with the grid cell each sits in. |
| `clock` | One game day is 24 real minutes. Day 1 begins at 07:20, when the player steps off the train. |
| `reputation` | One score per district, −100 … +100, labelled in the ledger's six bands: RESPECTED, CAUTIOUS, NEUTRAL, SKEPTICAL, WARY, HOSTILE. |
| `wanted` | Heat in points, five star thresholds, decay and the cooldown before heat falls. |
| `money`, `health`, `xp` | Starting money 0, health, regen, hospital fee, and the rank ladder from NOBODY upward. |
| `memory` | The fifteen memory kinds with each one's reputation weight, witness radius and ticker pattern, plus the bond thresholds that turn a stranger into an ally or a foe. |
| `palette`, `ui` | Every colour in the references, so five slices produce one city. |
| `ids` | The scene's named entities and the six mounts each slice attaches to. |
| `camera`, `arrival` | The gameplay camera's setting, and where the player arrives. |
## Functions
```lua
local Core = require("game.core")
Core.districtAt(x, z) -- -> "oldTown" the district a world position is in
Core.districtName("oldTown") -- -> "Old Town"
Core.cellOf(x, z) -- -> i, j the grid cell a position falls in
Core.blockCentre(i, j) -- -> x, z world centre of a cell
Core.clockOf(elapsed) -- -> { day, label, phase, ... }
Core.dayStamp(5) -- -> "DAY 5"
Core.reputationLabel(70) -- -> { label = "RESPECTED", colour = "teal" }
Core.wantedStars(140) -- -> 3
Core.rankName(500) -- -> "SOMEBODY"
Core.memoryShape() -- -> the shape one stored memory has
```
## The mounts
A slice attaches its component to its own mount and to no other one. The mounts are entities the
scene build places; adding a component to one is an `entityOps.addComponents` call and does not
involve writing the scene file.
```
mount_city the city's geometry and atmosphere
mount_life pedestrians, traffic, the police
mount_memory the memory ledger and reputation
mount_player the player, vehicles, the arrival
mount_ui every screen
mount_world weather and ambience
```
## The memory contract
`game.core` defines what a memory *is*; `game.memory` (the memory slice) is what stores one. Any
slice that wants the city to remember something calls:
```lua
require("game.memory").record({
kind = "helped",
district = Core.districtAt(x, z),
subject = npcId,
subjectName = "the man from the alley",
text = "Helped a stranger out of a bad alley.",
x = x, z = z,
})
```
and the memory slice dates it, weights it, files it, moves that district's reputation, gives it to
whoever saw it, and draws it in the ledger.
# game.memory
**THE CITY REMEMBERS.** The city's memory of the player: every act that mattered, dated against the
city's own calendar, attributed to a district, given to whoever was standing there to see it, and
kept.
This module is the store and the rules. The `Ledger` component (`game.memory.Ledger`) is what drives
it, and every other slice reaches the city's memory **only** through `record`.
## The contract
Taken from `design/spec.md` section 6, and not negotiable:
- `record` **never throws and never blocks.** A caller passing rubbish gets it logged and dropped.
- Every entry carries the city's day and clock, a unique id, and a district.
- A record moves that district's reputation by the kind's own weight, clamped to the band, and
announces itself on the bus.
- Everyone inside the kind's witness radius keeps the memory too — which is what lets a stranger
recognise the player somewhere else on a later day.
- The whole thing survives a reload.
## The one call
```lua
local Memory = require("game.memory")
Memory.record({
kind = "helped", -- a key of Core.memory.kinds
district = "oldTown", -- omitted, Core.districtAt(x, z) decides
subject = npcId, -- optional
subjectName = "the man from the alley",
text = "Helped a stranger out of a bad alley.", -- optional
x = x, z = z,
})
```
## API
| Function | What it answers |
|---|---|
| `record(event)` | Write one act into the city's memory. Returns the stored entry, or nil. |
| `entries(opts)` | The ledger, newest first. `opts`: `district`, `kind`, `subject`, `sinceDay`, `limit`. |
| `count()` | How many things the city remembers. |
| `reputation(district)` | One district's standing, −100 … 100. |
| `reputationAll()` | Every district's standing, in ledger order. |
| `adjust(district, delta)` | Move a district directly. Returns the new score. |
| `remember(who)` | Everything one person remembers: `bond`, `standing`, `met`, their entries. |
| `everyone()` | Every person the city holds a memory of. |
| `witnesses(x, z, radius)` | Who is close enough to see something happen there. |
| `introduce(person)` | Make somebody the city can remember. Returns the stored record. |
| `adopt(list)` | Publish an external crowd (the life slice's pedestrians) as witnesses. |
| `forgetActor(id)` | Take somebody out of the witness pool. |
| `crowd()` | Everybody currently able to witness, from both sources merged. |
| `setClock(day, minute)` / `clock()` / `stamp()` | The city's calendar. The `Ledger` component drives it. |
| `setChain(chain)` / `chain(id)` / `unlocked()` | The story chains the street has opened. |
| `save()` / `load()` / `reset()` / `ready()` | Durability. Stored at `/zero/source/local/city-memory.json`. |
## Bonds
A person's `bond` is the sum of the weights of everything they hold against the player. It reads as
a standing, from `Core.memory.bond`: `ally` at +60, `friend` at +30, `enemy` at −35,
`nemesis` at −70, and "a stranger" in between.
## The witnesses
`witnesses` merges two sources: the people this module introduced, and the crowd the **life** slice
publishes through `adopt`. Neither slice has to be finished for the other to work — a run with no
crowd simply has no witnesses, and the memory still records.