Engine GameEvents and entity props (renderer / TV contract)

GameRuntime.events is an append-only log of { t, type, player?, data? } (t = sim seconds). The TV reads new events each frame. Events marked headline are big moments worth a callout (banner, sfx, camera). Everything else is bookkeeping (the host roast and results also read it).

#Headline events: namespaces and data.moment

Blocks emit headline moments as <ns>.<moment>. ns is the block's callout param:

• the neon fallbacks use ring (RING OUT), overload (OVERLOAD), paint (PAINT WARS) and rush (CORE RUSH); NEON DASH (race) emits plain race.* events;
• AI-made games default to play;
• callout: '' turns them off.

Every headline event also carries data.moment. Match on data.moment, not on the full type, so the callouts work for any game.

Popups: score reasons are short neon caps strings ("RING OUT!", "OVERLOAD!", "BANKED", …); the renderer shows them as "+3 RING OUT!".

#Runtime (all games)

GameRuntime.leadChanges is the unthrottled count (balance metric). GameRuntime.scoreMultiplier is the current multiplier (2 in the finale).

#RING OUT: block arena-move (ringOut), ns ring

#OVERLOAD: block arena-move (overload), ns overload

Score reasons also: "CLEAN" (+1 every 5 s to everyone not holding a core, overloadSafePoints). With 4 players the fallback runs 2 cores at once (one per two players).

#PAINT WARS: block arena-move (paint), ns paint

Odd team sizes (2v1) auto-balance: the smaller team's tiles score big/small times more.

#CORE RUSH: blocks arena-move + collect (teamBases, stealNeedsDash, knockLoose), ns rush

Carry max 2; each carried core costs 15% speed (loadMul). 50 s "core-storm" fills the field.

#NEON DASH: block race (gateCycleSec), no ns

Score reasons are the race.* codes (the renderer translates them).

#Physics (planck.js): spec.world.physics / spec.world.props, ball-sport, arena-move crates

Physics is on when the spec has world.physics (or world.props), or a block needs it (ball-sport, arena-move crates). Players become round bodies (player vs player bumps stay in arena-move, now with spin and knockback); props are rigid bodies.

#Theme looks

theme.look ∈ neon | toybox | cosmos | retro (and the same id in theme.sfxSet); default palettes in THEME_PALETTES (@cadabra/spec). Lineup: RING OUT toybox, OVERLOAD cosmos, PAINT WARS retro, CORE RUSH cosmos, NEON DASH neon, ROCKET BALL neon, CRATE CRASH toybox.

#sfx names (FxEvent sfx) added by physics

bumper, boom (barrel), kick (ball hit / power shot), crate (crate impact / refill), goal.

#ROCKET BALL: blocks arena-move + ball-sport (goals), ns rocket

keepaway mode: "POSSESSION" points every keepAwayEverySec to whoever touched the ball last.

#CRATE CRASH: block arena-move (crates) + barrels in world.props, ns crate

#Legacy blocks (AI games can still use them)

The sneak (guards, heist-style chase), dodge (hazards, near misses, penguin-style crumble/knockout) and tug (rhythm tug of war) blocks are unchanged; their events are: <ns>.chase.start, <ns>.caught, <ns>.knockout, <ns>.crumble, <ns>.surge, <ns>.splash, <ns>.swing, plus sneak.*, dodge.*, tug.* bookkeeping (see git history for the full tables).

#Timeline hooks (opt-in params, exact kind match)

• arena-move: ringCrumbleEventKind (RING OUT 'quake': drop the next ring now), overloadEventKind (OVERLOAD 'surge': every fuse burns down to ~3.5 s).
• collect: goldenEventKind (CORE RUSH 'mega-core') and frenzyEventKind ('core-storm').
• tug: swingEventKind. dodge: the surprise and twist kinds.

#Tug timing

• Taps are judged on the beat as it was when they were sent: tug learns each phone's fastest arrival lag (a floor-biased EWMA of arrival sim ms − frame t) and moves a late tap back by up to 150 ms.
• This only happens once the phone's t has advanced at about real-time rate over 0.5 s; bots and tests that send step counts get no compensation.
• The runtime latches presses: a down+up that both arrive between two steps still reaches blocks as one step of "down", stamped with the press time.

#Entity props for renderers