# core
The shared contract of **Mario Kart OrigoZ**. Every slice reads its rules
here, so no slice hard-codes a number that belongs to the game.
`require("game.core")` from anywhere in this world.
## What it holds
| Field | What it is |
|---|---|
| `TITLE`, `PROMPT`, `ART` | The game's name, the *pulsa J para jugar* prompt, and the art-direction sentence — word for word from the reference pass, reused by every prompt. |
| `CIRCUITS` | The three circuits: id, name, laps, layout (`ring` / `square` / `ribbon`), racing surface, what lies beyond the edges, and half-width. |
| `KART` | How a kart feels: max speed, acceleration, braking, turn rates, hop and gravity, drift multipliers, trick spin. |
| `SURFACE` | What each surface does to you: `road` 100%, `water` 75%, `grass` 50%, `space` falls. |
| `SPARK` | The drift charge table: blue at 1.0s (0.5s boost), orange at 2.5s (1.25s), rainbow at 4.0s (2.5s). |
| `BOOST` | Trick 0.75s, mushroom 2.0s, feather 2.0s. |
| `ITEMS` | Crate respawn (8s) and the mushroom / feather odds. |
| `RESCUE` | How Lakitu puts you back: drop height, lift speed, lift duration. |
| `PHASE`, `flow`, `race` | The flow state machine and the live race clock. |
| `records` | The best time on each circuit, kept in `runtime_data.world` — shared and durable. |
## API
- `M.circuits()`, `M.circuit(id)`, `M.circuitIndex(id)`
- `M.register(name, api)` / `M.system(name)` — how slices reach each other
- `M.on(name, fn)` / `M.emit(name, payload)` — the slices' event bus
(`phase`, `circuit`, `lap`, `crate`, `boost`, `rescue`, `finish`)
- `M.setPhase(p)`, `M.selectCircuit(id)`, `M.openControls()`, `M.beginRace()`,
`M.startRace()`, `M.tick(dt)`, `M.reachPoint(total)`, `M.finishRace()`
- `M.records.get(id)` / `M.records.set(id, ms)` / `M.records.all()`
- `M.formatTime(ms)` → `"00:45.678"`, `M.countdownLabel(seconds)`
- `M.clamp`, `M.lerp`, `M.approach`
## Who reads what
- **kart** — `KART`, `SURFACE`, `SPARK`, `BOOST`, `RESCUE`, `race`.
- **tracks** — `CIRCUITS`, `SURFACE`, `reachPoint`, `PHASE`.
- **items** — `ITEMS`, `BOOST`, `FEATHER_LIFT`, `emit("crate")`.
- **screens** — `flow`, `race`, `records`, `formatTime`, `PHASE`.
- **audio** — `on("phase")`, `on("boost")`, `on("crate")`, `on("finish")`.
# items — the ? crates and the two things they hold
Every lap of every circuit has rows of floating **?** crates on the racing line.
Drive through one and the kart is armed with a **Mushroom** or a **Feather**;
**L** uses it. Crates go dark for 8 seconds and come back.
| File | What it is |
|---|---|
| `game/items.module` (`game.items`) | The slice's read-back surface. |
| `Items.component` | One instance, spawned by the module. Owns arming the crates, the roll, and both items. |
| `ItemCrate.component` | One per crate: spins, bobs, watches for the local kart, and respawns. |
## Where the crates are
`tracks.crates(id)` gives the positions — rows of four along the racing line, 5
rows on a loop and 8 on the ribbon — and the slice re-arms them whenever the
circuit changes.
## The rules
- A kart already holding something does not take a second crate.
- **Mushroom** — `Core.BOOST.mushroom` (2 s) of boost, source `"mushroom"`.
- **Feather** — `Core.FEATHER_LIFT` of lift, then, the moment the kart is back
on the ground, 2 s of boost with source `"feather"`.
- Both are boosts other than the drift one, so they cancel the off-track speed
penalty while they run.
## API
```lua
local I = Core.system("items")
I.arm("cheep") -- arm this circuit's crate rows
I.use() -- use what the local kart is holding
I.held() -- what that is: "", "mushroom" or "feather"
I.count() -- how many crates are armed
```