# 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.Ledger
Mounted once, on the scene's `mount_memory`. The city, awake.
It does three things and owns nothing else.
## 1. It keeps the city's calendar
One game day is six real minutes. It drives `game.memory`'s day and clock, announces each new hour on
the bus (`Core.events.clockTick`), says when the player crosses into a new district
(`districtEntered`), and writes the store to disk every `saveEvery` seconds.
## 2. It puts the street's stories in the world
Missions in this game are not markers on a map. They are things the player walks past, and how they
move through them is the choice.
Each entry in this component's chain table names a place, two people, what is overheard, and what
investigating it does. The chain stands its actors in the world at load. Then:
- walking **within `approach` metres** of it *is* investigating it — the dialogue plays, the act is
recorded, and a chain opens that can be picked up later;
- coming within `notice` metres and then walking away past it *is* ignoring it, and that is recorded
too, with its own weight.
Two chains ship: **Two men outside the Osprey** (South Docks, at the Osprey Diner in
`Core.landmarks`) and **Someone in the alley off Delancey** (Old Town). Each leaves a named actor with
a bond, and each opens a named chain.
## 3. It makes the city recognise the player
Anyone the player helped is marked. When the player next comes within nine metres of that same person
— which, since the chains are in different districts, means somewhere else — the person says so. The
first meeting is the recognition; the next is the introduction, and it opens a contact at the Pier
Market in Riverfront.
That is the sequence the whole game exists for: helped on day 1, recognised somewhere else later,
introduced on a later day still.
## Fields
| Field | Meaning |
|---|---|
| `saveEvery` | Seconds between writes of the city's memory to disk. Default 20. |
| `running` | Whether the calendar and the street stories are running. |
## Methods
| Method | What it does |
|---|---|
| `:status()` | What the memory is holding: day, clock, entry count, every district's standing, the chains, everyone's bond. |
| `:advanceDays(n)` | Move the city's calendar forward n days. For showing a meeting that is meant to be days later. |
## What is a slot here
The two people each chain stands are `@builtin::avatars.humanoid` — the engine's own rigged figure,
uncostumed. The polish pass replaces the mesh with generated characters; the entities are named
(`osprey_chef`, `osprey_bagman`, `alley_woman`, `alley_thug`) so it knows exactly where they go.