# game.rules — Origo Party's shared contract
The one module every slice of Origo Party reads. It holds no mutable state:
the Match component owns the live state table and publishes it as
`Rules.state`, and every other slice reads that and listens on `Rules.on`.
## Constants
`ROUNDS` (3), `START_COINS` (10), `STAR_COST` (20), `BLUE_COINS` (3),
`RED_COINS` (-3), `SHOWDOWN_SECONDS` (60), `SHOWDOWN_BONUS` (10), and
`PLAYERS` — the four seats with their colour, candy material and whether the
seat is human.
## The board
`BOARD_SIZE` (32) tiles around a superellipse `RADIUS_X` x `RADIUS_Z`.
- `tilePosition(index) -> x, y, z` — where tile `index` (1..32) sits.
- `tileFacing(index)` — the heading a pawn faces standing on it.
- `pawnPosition(index, seat)` — beside the tile, fanned by seat so four pawns
on one tile do not overlap.
- `spaceKindAt(index, round)` -> `"blue" | "red" | "green" | "shop" | "star"`.
The Star Space moves every round; `starIndexForRound(round)` names it.
- `SPACE_MATERIAL` / `SPACE_LABEL` — what each kind looks like and reads as.
## The rules
- `advance(from, spaces)` — the tile you land on, wrapping the loop.
- `resolveSpace(kind, player, rng)` -> `{ coins, stars, kind, note }`.
- `rankings(players)` — final order, stars first then coins.
- `newState(rounds)` — the shape the Match component owns.
## The bus
`Rules.on(event, fn)` returns an unsubscribe. `Rules.emit(event, payload)`.
A handler that throws is dropped and logged; it never takes the bus down.
Events: `title`, `roundStart`, `turnStart`, `roll`, `moveStep`, `arrive`,
`resolve`, `shop`, `starBought`, `roundEnd`, `showdownStart`, `showdownScore`,
`showdownEnd`, `matchEnd`, `hud`.
# OrigoMatch
Origo Party's referee and turn engine. Attaches to the scene's empty `Match`
anchor (mounted by `scenes/main.scene/entrypoint.luau` with no data) and boots
itself in `start()`.
It is the **only** writer of `Rules.state`. It publishes the live state table
(`Rules.newState()`), runs the whole match machine —
`title → round → per-turn (roll → move → resolve) → round close → COIN CLASH → ceremony`
— for the CPU brains on seats 2–4, the shop stock and buying, the Star
purchase (20 coins, taken on passing or landing on the Star Space, or bought
from the shop), and the final ranking. A round is **three laps** of the turn
order, so every seat lands nine times across the match. Every beat is written
to `Rules.state` (with `state.seq` bumped) and announced on the `Rules` bus;
no subscriber is needed for the match to advance.
## Sibling components it expects
None are required. The slices are readers:
- `OrigoBoard` — pawns, die, camera; reads `state.players[i].tile` and the
`roll` / `moveStep` / `arrive` / `resolve` events.
- `OrigoHud` — screens; reads `state.phase`, `state.round`, `state.turnSeat`,
`state.die`, `state.shop`, `state.rankings` and the `hud` events.
- `OrigoShowdown` — COIN CLASH; answers `showdownStart { seconds }` with
`showdownScore { seat, grabs }` and `showdownEnd { results }`. If no arena
answers within 1.5 s the referee simulates the grabs itself and still closes
the round, so the match never stalls on a missing slice.
- `OrigoSound` — subscribes to the bus only.
## Driving it
- **The clock is its own.** `update(dt)` advances a match clock and paces the
coroutine that is the match script, so a hot-seat turn always finishes
without input.
- **Early commit.** `Rules.emit("commit")` (payload optional: `{ seat }`)
fast-forwards the rest of the turn being played.
- **Shop choice.** `Rules.emit("shopBuy", { seat = 1, key = "shield" })` picks
an item from the sheet; without one the referee buys by heuristic when the
prompt times out. The stock is four items — **Star** (at `Rules.STAR_COST`,
the one that wins), Double Die, Shield, Lucky Charm — and `key = "star"`
buys the Star.
## Fields
| Field | What it does |
| --- | --- |
| `pace` | Clock multiplier. 1 is real time; 4 plays four times as fast. |
| `showdownSeconds` | COIN CLASH length; 0 takes `Rules.SHOWDOWN_SECONDS` (60). |
| `shopSeconds` | How long a shop sheet waits for a choice; 0 takes 8 s for the human seat, 1.4 s for a CPU. |
| `verbose` | Logs every beat to the console. |
## What it leaves in `Rules.state`
`phase` (`title` / `roundIntro` / `turn` / `rolling` / `moving` / `resolving`
/ `roundEnd` / `showdown` / `ceremony`), `round`, `rounds`, `laps` (laps per
round, 4), `lap` (the lap being played), `turnSeat`, `players` (coins, stars,
tile, items), `die`, `shop` (four items while a shop is open), `lastResolve`,
`showdownActive`, `showdownScores`, `lastShowdown`, `rankings`, `winner`
(name), `winnerSeat`, `winners` (names, more than one on a shared win), `tie`,
`message`, `seq`.
## Done when
A three-round match plays from title to ceremony with no input, ends with a
named winner, and `state.rankings` (and the `matchEnd` payload) equals
`Rules.rankings(players)` for those same players.
# OrigoSound — the party's voice
Attached by the scene entrypoint to the `Sound` anchor when play begins. It
shows nothing on screen and owns no state: it is a pure reaction to what the
match announces on the `game.rules` bus.
It starts the looping candy music bed once at `start()`, and plays one clip per
beat thereafter. Each effect gets its own short-lived temporary entity under
the `Sound` anchor so two of the same sound can overlap, and despawns itself
after six seconds.
## What plays when
| Bus event | Clip | Note |
| --- | --- | --- |
| (start) | `game.audio.party_loop` | looping music bed on the `music` channel |
| `roll` | `game.audio.dice_roll` | the die leaving the hand |
| `moveStep` | `game.audio.hop` | once per tile walked, pitch varied |
| `resolve` | `game.audio.coin_gain` / `coin_loss` | by the sign of the coin CHANGE, not the total |
| `starBought` | `game.audio.star_buy` | the star fanfare; the coin-loss cue is suppressed on that beat |
| `shop` | `game.audio.shop_chime` | the shop opening |
| `showdownStart` | `game.audio.countdown` | COIN CLASH opening |
| `showdownScore` | `game.audio.grab` | rate-limited to one per 0.09 s |
| `matchEnd` | `game.audio.win` / `lose` | win when P1 takes the match, shared wins included |
## Two details of the bus worth knowing
- `resolve` carries `coins` and `stars` as the player's totals **after** the
effect. The coin cue is picked from the difference against the total this
component last saw for that seat, so a red tile plays the loss however rich
the player is. The totals are re-baselined on `roundStart`, `turnStart` and
`showdownEnd`, because the showdown bonus is paid outside a resolve.
- `matchEnd` carries `winner` as a ranking row and `winnerSeat` beside it, not
a seat number.
## Mixing
The clips came back from the generator at very different levels — peak from
0.09 (`coin_gain`) to 1.0 (`coin_loss`) — and a source's volume is clamped to
1.0 by the mixer, so the loud ones are trimmed down rather than the quiet ones
pushed up. Each clip's figure in `TRIM` is the peak it contributes to the mix:
0.09 to 0.50, against a bed that peaks at 0.14. Every effect therefore lands
at or above the bed's loudest transient, and the master stays well under
clipping when a loud cue lands on the music.
`hop` was regenerated: its first generation peaked at 0.003, about 51 dB below
every other effect, and nothing the mixer accepts could make it audible.
## Needs
- A `game.rules` module in the world (`require("game.rules")`).
- An `AudioListener` somewhere in the scene; the camera in
`scenes/main.scene/build.luau` carries one.
- The eleven clips under `game/audio/`.
# OrigoShowdown
COIN CLASH — the showdown that closes every round of Origo Party.
Attaches to the scene's empty `Showdown` anchor (mounted by
`scenes/main.scene/entrypoint.luau` with no data) and boots itself in
`start()`. It listens on the bus for `showdownStart`, and does nothing at all
while it is idle.
On `showdownStart { seconds }` it builds the sky arena 60 units above the
board — a round cream platform cut from `game.meshes.CandyTile` slabs, a
chequered coral-and-cream barrier with a cream rail round the top, a deep-sky
band under the rim, and one coloured entry pod per seat — then flies
`PartyCamera` onto it over a second and runs the scramble for those seconds:
coins pop up out of the floor, the four toys chase the nearest one, and each
grab is reported as `Rules.emit("showdownScore", { seat, grabs })`. A cream
and coral scoreboard (P1–P4 counts and the countdown) rides the top of the
frame while it runs.
At zero it reports `showdownEnd { results, grabs, winnerSeat, winners, bonus }`
— the same counts the live counter reported, so the match's coin bonus lands
on the seat the arena says won — holds the winner for a beat, cuts the camera
back to the board and destroys the arena.
Everything it spawns is a temporary child of its own anchor, so nothing it
makes is baked into the scene and a rebuild of `build.luau` never fights it.
Reads `game.rules` (`Rules.on`, `Rules.emit`, `Rules.PLAYERS`,
`Rules.SHOWDOWN_SECONDS`, `Rules.SHOWDOWN_BONUS`); requires `juiceKit.juice`
for the coin sparkle, the pop-in and the confetti. The Match slice is the one
that fires `showdownStart` and applies the bonus; the Sound slice answers the
same events on the bus.
# OrigoBoard — the ring, the toys and the die
The board slice of **Origo Party**. It dresses the authored ring and brings it
to life, and it never writes the scene:
- **Four toy characters** (seats 1–4, pink / mint / lemon / tangerine) built
from the `CandyTile` slab and primitives: slab body with a cream belly, wider
slab head with a cream face, dark eyes and a coral smile, a party hat with a
cream brim and bobble, mitten hands, cream boots, and the little die pinned to
the chest.
- **Tile-by-tile walking** with a hop, a forward lean and a landing squash. The
walk is driven by the `moveStep` / `arrive` events, and catches up from
`Rules.state` if the bus goes quiet for a seat.
- **The fat die** (rounded box, black pips, one coral-marked face) tumbles over
the middle of the board on `roll` and settles showing the rolled value to the
camera, then bobs while it waits.
- **Tile glyphs** — `+3`, `-3`, `?`, `SHOP`, `STAR` — as cream `Text3D`
lettering lying on each slab, re-read from `Rules.spaceKindAt(i, round)` every
round so the Star Space's move is visible; the shop stall also gets a coral
`SHOP` board.
- **Coin and Star pops** off the tile that resolves, delayed until the toy has
actually landed there.
- **PartyCamera** is moved only by lerping its transform: a gentle lean toward
whichever toy is walking, a centring on the die while it rolls, a slow drift
on the title and the ceremony. It holds still while the showdown owns the
camera (`showdownStart` / `showdownEnd`).
## Attaches to
The `Pawns` anchor, mounted by `scenes/main.scene/entrypoint.luau` as
`game.board.OrigoBoard`.
## Needs
- `game.rules` — state and bus (read only; the Match slice writes it).
- `game.materials.Candy*` and `game.meshes.CandyTile` — the authored art.
- `juiceKit` — reaction layer (`coinPickup`, `levelUp`, `popIn`, `pulse`,
`vfxConfetti`).
- The scene's named tiles (`tile_1`…`tile_32`) for the glyph height, and the
`PartyCamera` entity.
Everything it spawns is a temporary child of one group entity under the anchor,
so a scene rebuild never fights it and `onDestroy` removes the lot.
# OrigoHud
Every screen the player reads in Origo Party, mounted on the scene's `Hud`
anchor when play begins. It owns four `ui` screens — the title
(`origo_title`), the in-play HUD (`origo_hud`), the corner-store sheet
(`origo_shop`) and the results ceremony (`origo_ceremony`) — and shows the one
the match's phase asks for.
It reads `Rules.state` (the Match slice owns it and is its only writer) and
subscribes to the Rules bus so a shop opens and a ceremony lands the frame they
happen. It never writes state: PLAY reports `commit` and a booster purchase
reports `shopBuy`.
Siblings: `OrigoMatch` (state and phase), `OrigoBoard` and `OrigoShowdown`
(whose screens own the arena scoreboard). The trees themselves are built by the
modules under `game/screens/`.