# CheepCheep
One-paragraph description of what this component does and what it
attaches to. Mention any required sibling components (e.g. Model,
Transform).
## Public fields
- `exampleNumber: number` — what it controls, units, valid range.
- `exampleString: string` — what it controls.
- `exampleBool: boolean` — what it controls.
## Methods
- `:methodName(arg)` — what it does and when to call it.
## Lifecycle
- `awake()` — same-frame attach hook. What initial state this component
sets up.
- `start()` — first-frame-after-awake hook. Cross-component setup that
needs the other components on the entity to have finished `awake`.
- `update(dt)` — per-frame while the gameplay clock runs. What this
component does each tick.
- `onDestroy()` — cleanup performed on detach / entity despawn.
See `man components` for the full hook list (`onEnable`, `fixedUpdate`,
`onPropertyChanged`, etc.) and the timing details.
## Usage
```luau
entity(id).component.add("CheepCheep", { exampleNumber = 1.0 })
entity(id).component.get("CheepCheep"):methodName("foo")
```
# kart — Mu Mu's kart
The driving model, the whole K button, the surface penalties, the Lakitu
rescue and the chase camera. This is where the game's feel lives.
## What is here
| File | What it is |
|---|---|
| `game/kart.module` (`game.kart`) | The slice's API — finds the local player's kart and asks it. |
| `Kart.component` | The kart itself, on the scene's `kart` body. One instance per player. |
| `KartCamera.component` | The chase camera, in the scene's CameraRig's `behavior` slot. |
| `drive.inputMap` | A/D steer, J accelerate, K hop and drift, L item, O brake — keyboard, gamepad and touch on every control. |
## The controls
| Key | What it does |
|---|---|
| **J** | Accelerate. |
| **O** | Brake; held past a stop, reverses. |
| **A / D** | Steer left / right. |
| **K** | At a standstill, a small straight hop. While steering, a hop to the OPPOSITE side that lands into a drift the way you turned. |
| **K** held in a drift | Wheel sparks charge: blue at 1.0s, orange at 2.5s, rainbow at 4.0s. Releasing pays out 0.5s / 1.25s / 2.5s of boost for the colour that was showing. |
| **K** off a ramp lip | A trick spin in the air; landing it pays out 0.75s of boost. |
| **L** | Use the item in the slot. |
## The rules it enforces
- **Surfaces**: sand/dirt/rainbow 100%, water 75%, grass 50%, space is not
drivable at all. Any boost except the drift one cancels the penalty while
it runs.
- **Lakitu**: falling into space lifts the kart and sets it back down at the
nearest point of the racing line, then hands control back.
- **Laps**: `tracks.advance` is called only while the kart is on the racing
surface, so falling past a line in space never counts as crossing it.
## API (for the other slices)
```lua
local K = Core.system("kart")
K.player() -- the local kart entity, or nil
K.public() -- its component: item, speed, lap, charge
K.boost(seconds, "mushroom") -- fire a boost
K.jump(Core.FEATHER_LIFT) -- lift it (a feather)
K.placeOnTrack() -- put it on the line
K.teleport({ x, y, z }, yaw) -- put it down anywhere
K.setLocked(true) -- hold it (countdown, menus)
K.held() -- the item string it is carrying
```
## Who drives
Only the peer's own kart reads input. It decides that from the layer's
local-player handle, from the entry point's `player` event, or — a world with
one kart having only one candidate — from there being a single kart.
## Verified
Driving on circuit 1: J accelerates, A/D steer, O stops it; the water caps the
speed at exactly 24 m/s (75% of 32). On circuit 2: steering off the dirt onto
the grass caps it at exactly 16 m/s (50%). K with D held hops into a drift;
holding it charges to rainbow and releasing pays out the boost for the stage
reached (1.25s at orange, timed from when the drift actually started, not from
the hop). K off a ramp on circuit 3 spins a trick and landing pays out 0.75s.
Driving off the rainbow ribbon drops the kart and Lakitu sets it back on the
line. Crossing each gate in turn walks the lap counter up. The chase camera
follows from low and close behind, and none of it depends on the engine's
frame rate (the step is clamped).
# KartCamera
The camera the player races through — **placeholder** written by the plan pass
so the player's view is a chase view from the first frame.
A `cameraBehavior`: it is mounted in the camera's `behavior` slot on the
scene's `CameraRig` and resolves its subject from `Camera.follow` unless
`target` names an entity outright.
## Fields today
| Field | Meaning |
|---|---|
| `target` | Entity to trail; empty falls back to `Camera.follow`. |
| `distance` | Metres behind the kart. |
| `height` | Metres above the kart. |
| `lookAhead` | Metres in front of the kart the camera aims at. |
| `positionSmoothing` / `rotationSmoothing` | Per-second blend rates. |
## What the kart slice owns
The real feel: speed-based lookahead, a gentle roll into a drift, a wider lens
while boosting, and the fly-in down the start straight — tuned against
`design/references/01-game-in-play.png`.
# 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")`.
# kart
One-paragraph description of what this module provides and who consumes
it.
## Exports
- `M.exampleFn(arg) -> result` — what it does and when to call it.
- `M.exampleValue: type` — what value it carries.
## Usage
Replace `<identity>` with the string `asset.create` returned — this
module's source path with `/` written as `.` and each segment's type
suffix dropped, the way a module at `/source/lib/thing.module` is
`lib.thing` and one at `/source/kit.package/thing.module` is
`kit.thing`.
```luau
local M = require("<identity>")
M.exampleFn("foo")
```
## Notes
- Anything callers need to know about THIS module: required runtime
ordering, state ownership, side effects.
# game.audio — the sound slice
One looping music bed and the one-shots the game needs, all cued off the bus in
`game.core` — no slice calls another slice to make a noise.
| Clip | Cued by |
|---|---|
| `music/race` | starts at mount, loops for the whole session. |
| `sfx/boost` | the `boost` event — drift, trick, mushroom or feather. |
| `sfx/crate` | the `crate` event, and again (higher, quieter) on `lap`, and low on `finish`. |
Generated with the `audio_gen` service and promoted to `.soundClip` assets by
the importer. They are resolved on a real-time retry rather than once, because
a world that opens while the import is still running must still get its sound.
## API
```lua
local A = Core.system("audio")
A.play("boost", { pitch = 1.1 })
A.music(true) / A.music(false)
A.ready() -- which clips have landed
```
Two entities carry the sources: `MkoMusic` (Music, non-spatial, looping) and
`MkoSfx` (SoundEffect, non-spatial, used for one-shots). The scene carries the
world's one `AudioListener` — nothing here adds a second.
# tracks
The three circuits of Mario Kart OrigoZ, built from code on every scene
load — nothing is frozen into the scene, so a reload lands in the same world.
`require("game.tracks")`, then `Core.system("tracks")`.
## The circuits
| id | Circuit | Laps | What it is |
|---|---|---|---|
| `cheep` | Playa Cheep Cheep | 4 | A wobbly sand ring floating in turquoise water, with posts down both edges, twenty-two Cheep Cheep (some swimming, some leaping), palm islands in the shallows and a start gantry. |
| `mumu` | Pradera Mu Mu | 3 | A big square dirt route over a grass meadow — a wandering path with rounded corners, a shortcut cutting straight across the middle, fences, hills, fourteen cows (one in a sombrero) and two turning windmills. |
| `arcoiris` | Senda Arcoiris | 4 points | One long point-to-point rainbow ribbon through black space, never revisited: Earth huge and far off down the course, stars, clouds floating beside the road, three chained balls patrolling the last stretch, and a finish gantry ringed with heart-shaped clouds. |
Only one circuit is in the world at a time; `select` clears every circuit
tree — by name, so a hot reload of this file cannot orphan one — and builds
the one you asked for.
## API
| Call | Contract |
|---|---|
| `T.select(id)` | Build and show that circuit, set its environment (sun, ambient, sky, Earth, sea, meadow), take the others down. Idempotent: selecting what is already up does nothing. |
| `T.active()` | The active circuit's record from `Core.CIRCUITS`. |
| `T.activeCircuit()` | The internal record: `ribs`, `reach`, `gates`, `origin`, `closed`, `laps`. |
| `T.startPose(id?)` | `{ pos = {x,y,z}, yaw = radians }` — on the line, facing down the course. |
| `T.surfaceAt(pos)` | `"road"` / `"water"` / `"grass"` / `"space"`. On a loop, off the ribbon is the circuit's `out` surface; on the ribbon it is space. |
| `T.heightAt(pos)` | Y of the racing surface, or nil when there is none within reach. |
| `T.progressAt(pos)` | `{ u = 0..1, lateral, onTrack, width, y, rise }`. `u` is the distance round the racing line; `rise` is the local slope, and `rampAt` is `|rise| > 0.16`. |
| `T.rampAt(pos)` | True where the path climbs hard enough to launch off. |
| `T.nearest(pos)` | `{ pos, yaw }` — the nearest drivable point, high enough to drop back onto. Lakitu's target. |
| `T.crossed(prev, cur)` | The gate a move crossed this frame — stateless, so many karts can share it. |
| `T.advance(prev, cur)` | Crossed a gate **and** advanced the race: calls `Core.reachPoint`, which banks the lap or finishes the circuit. Returns `{ crossed, point, finished }`. The kart owns the previous position; this owns the meaning. |
| `T.crates(id)` | The `?` crate spots for the circuit, in lap order — 5 rows of 4 on a loop, 8 rows of 4 on the ribbon. |
## Environment
`sun`, `ambient` and `sky` belong to the scene and the tracks set them per
circuit; what each circuit owns (the sea, the meadow, the Earth) is spawned
by this module.
## Fields that are stand-ins for polish
`Cow`, `CowSombrero`, `CheepCheep`, `ChainChomp`, `Earth`, `Windmill`, `Palm`
and `HeartCloud` are blockouts. Each is a named entity at the right place,
size and scale, waiting for a generated model at the same transform.
# screens
One-paragraph description of what this module provides and who consumes
it.
## Exports
- `M.exampleFn(arg) -> result` — what it does and when to call it.
- `M.exampleValue: type` — what value it carries.
## Usage
Replace `<identity>` with the string `asset.create` returned — this
module's source path with `/` written as `.` and each segment's type
suffix dropped, the way a module at `/source/lib/thing.module` is
`lib.thing` and one at `/source/kit.package/thing.module` is
`kit.thing`.
```luau
local M = require("<identity>")
M.exampleFn("foo")
```
## Notes
- Anything callers need to know about THIS module: required runtime
ordering, state ownership, side effects.
# items
One-paragraph description of what this module provides and who consumes
it.
## Exports
- `M.exampleFn(arg) -> result` — what it does and when to call it.
- `M.exampleValue: type` — what value it carries.
## Usage
Replace `<identity>` with the string `asset.create` returned — this
module's source path with `/` written as `.` and each segment's type
suffix dropped, the way a module at `/source/lib/thing.module` is
`lib.thing` and one at `/source/kit.package/thing.module` is
`kit.thing`.
```luau
local M = require("<identity>")
M.exampleFn("foo")
```
## Notes
- Anything callers need to know about THIS module: required runtime
ordering, state ownership, side effects.