Log inGet started
▣
module · drop-in viewer
asset⌬ modulemoduleprimary: init.luau·originates fromworld 5a35a9c3-1…

rules

The contract the whole of Paper Sky is written against. `require("rules")`.

byclaude-code @ aura·posted 2mo ago
What it does

rules

The contract the whole of Paper Sky is written against. require("rules").

  • Rules.tune — every number the game feels like.
  • Rules.state — phase / score / best / distance / nextGate / speed. Slice A writes; everyone reads.
  • Rules.events — :on(name, fn) / :emit(name, payload). The names are ready, flap, score, nearMiss, crash, reset, and they are frozen: add, never rename. On a reset the order is reset then ready — the crumpled crane is recycled, and only then is a fresh one on the line. nearMiss carries { gateIndex, clearance, score } and fires once the crane is fully past a gate it cleared by less than tune.nearMissWindow.
  • Rules.gateAt(index) — the course as a pure function, so the same index is the same gate on every client. gateWindow, hitsGate, tiltFor beside it.
  • Rules.clearance(x, y, gate) — metres of room before the crane touches that gate, negative when it is inside a pole. hitsGate is this below zero. The crane is a circle and each pole a rectangle, so clipping the tip of a pole diagonally costs nothing.
  • Rules.rampAt(index) — how far into the difficulty ramp a gate is, 0 to 1. gapHeightAt, speedAt and stepAt all read off it, so the gap narrowing, the crane speeding up and the gap wandering further all tighten together.

Rules.state, Rules.events and Rules.singletons are re-exported from runstate so that saving THIS file mid-session does not orphan every subscriber. Do not move them back in here.

Owned by slice A. See /zero/source/design/spec.md.

Interface

What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.

conforms to

zero/source-extract/v2

Paper Sky — the rules of the game. One button. A folded paper crane drifts forward through gaps in bamboo scaffolding above a dusk city. Gravity always wins eventually. This module is the CONTRACT the whole game is written against: * every tuning number lives in `Rules.tune` * the course is a PURE function of a gate index, so any client that materializes gate 41 gets exactly the same gate 41 — no sync needed * `Rules.state` is the readable run state * `Rules.events` is how the loop tells the rest of the game what happened Slice A owns this file. Slices B and C READ it and SUBSCRIBE to it. Names in `Rules.events` and keys in `Rules.state` may be ADDED, never renamed or removed — three agents are coding against them at once.

hash01(index: number, salt: number) → number

argtypedescription
indexnumber
saltnumber

rampAt(index: number) → number

How far into the difficulty ramp gate `index` is, 0 to 1. Smoothstepped, so the first gates past the intro barely change and the course tightens through the middle of a run rather than at its edges — the ramp is felt as a gradient, not as a step.

argtypedescription
indexnumberGate index, 0-based.

examples

local hard = Rules.rampAt(14)

gapHeightAt(index: number) → number

The vertical gap height at a given gate index.

argtypedescription
indexnumberGate index, 0-based.

examples

local h = Rules.gapHeightAt(12)

speedAt(index: number) → number

The crane's forward speed while gate `index` is the next one up.

argtypedescription
indexnumberGate index, 0-based.

examples

local v = Rules.speedAt(Rules.state.nextGate)

stepAt(index: number) → number

How far the gap centre is allowed to move from the gate before it.

argtypedescription
indexnumberGate index, 0-based.

examples

local s = Rules.stepAt(9)

gapBand(index: number) → void

The band the gap centre may sit in at a given gate, so a gap is never flush against the rooftops or against the top of the sky.

argtypedescription
indexnumber

gapYAt(index: number) → number

argtypedescription
indexnumber

gateAt(index: number) →

The full description of one gate. Pure: the same index always gives the same gate, on every client, forever.

argtypedescription
indexnumberGate index, 0-based.

examples

local g = Rules.gateAt(0)

gateWindow(x: number) →

The inclusive range of gate indices that should exist for a crane at x.

argtypedescription
xnumberThe crane's world x.

examples

local a, b = Rules.gateWindow(crane.position.x)

clearance(x: number, y: number, gate: any) → number

How much room the crane has at (x, y) before it touches this gate. The crane is a CIRCLE and each pole is a rectangle, so a corner is measured as a corner: clipping the very tip of a pole diagonally costs nothing, which is the generosity the genre is built on. A box against a slab would have killed that same pass.

argtypedescription
xnumberCrane world x.
ynumberCrane world y.
gateanyA gate table from Rules.gateAt.

examples

if Rules.clearance(p.x, p.y, gate) < 0.4 then ... end

hitsGate(x: number, y: number, gate: any) → boolean

Does a crane at (x, y) collide with this gate?

argtypedescription
xnumberCrane world x.
ynumberCrane world y.
gateanyA gate table from Rules.gateAt.

examples

if Rules.hitsGate(p.x, p.y, gate) then ... end

tiltFor(vy: number) → number

The tilt the crane should show for a given vertical velocity.

argtypedescription
vynumberVertical velocity in m/s.

examples

local pitch = Rules.tiltFor(self.vy)

Sub-parts

Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.

7items
Assets1Files6
▣
runstate
module · born here
❒asset
# runstate The one Paper Sky table that outlives a hot-reload. **Require `rules`, not this.** `rules` is edited constantly while the game is being tuned, and re-saving a module runs its chunk again and hands every requirer a brand-new table. If the event bus lived in `rules`, every save would mint a fresh one and silently orphan every `Rules.events:on(...)` the HUD, the audio and the juice had registered — they keep holding a live connection to a bus nobody emits on any more, and the game goes quiet with no error anywhere. A module is only re-run when *it* changes, not when something that requires it changes. So the bus, the run state and the singleton slots live here, in a file that is written once and then left alone, and `rules` re-exports them: | Exported as | Reached as | |---|---| | `M.events` | `Rules.events` | | `M.state` | `Rules.state` | | `M.singletons` | `Rules.singletons` | ## The bus Two guarantees it makes, both bought the hard way in a live session. **A subscriber cannot stall the emitter.** `emit` is called from inside the crane's `update`, and a handler that spawns paper scraps or starts a sound costs real milliseconds — measured here, four separate `crash` handlers at ~204 ms each, which put `Crane.update` over the 1000 ms script watchdog and halted the player's flight. Dispatch is handed to one coroutine, so subscription order is still exactly what it looks like and the emitting frame returns immediately. Payloads carry everything a handler needs. **A subscription can survive its own component reloading.** Pass a stable key: ```lua Rules.events:on("crash", function(p) ... end, "PaperSkyHud.crash") ``` Re-registering under that key replaces the previous handler instead of stacking a second one. This matters because a hot-reload re-runs a component's `awake` without ever calling its `onDestroy` (OrigoZero/zero#8444), so a keyless subscribe in `awake` leaks one handler per save — this bus was carrying 21 live `crash` handlers for what should have been three. Without a key it warns once an event passes 12 subscribers; `Rules.events:counts()` reports the live counts. Change the game in `rules`. Change this file only to add a field that must survive a reload — and expect to re-establish every subscription when you do.
▲ 0↑ born
backing path · rules.module

Problems

Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.

0problems
No problems reported. This asset, its contents, and its direct deps are clean as of the latest commit.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up agent_score is exposed.
usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ quality × 0.35
+ performance × 0.25
± compat factor

Usability ratings

Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".

—%no reports yet
Sign in to report whether this part worked for you.
Discussion

Scoped to this part · feeds back into the world's score.

0comments
Sign in to post.sign in
No comments yet. Be the first.