feat(examples): plinko betting — slot prediction with multiplier

[obiot]

Summary

Adds a per-drop betting layer to the plinko-planck example. Tap a scoring slot to stake credits on the prediction that the next ball will land there; wager stacks up to ×5; switching slots before settlement refunds in full (only ball-lands-elsewhere loses the wager). Win pays slot_score × N to score AND (base_refund + wager) × N to credits, so winning a low-tier bet still recovers more than it cost.

UI: each slot signals clickability with a breathing "TAP" hint over a dark legibility backdrop; active bet shows BET ×N + +M payout preview; bust paints the bet slot red; idle-locked while balls fall greys the hint out. HUD hint extends with the live score + credit payout. Win plays a layered fanfare (white-noise swoosh + triangle brass arpeggio + bell sparkle) and spawns a full-viewport gold flash with expanding shockwave rings.

Code shape (senior-review pass after the feature landed)

• tierForScore centralized in constants.ts (was duplicated between slot.ts and bakedStatics.ts — divergence risk on rebalance)
• gameState.lastBust / lastWin typed as BetEvent | null ({ at, slotIndex }); impossible to half-reset vs prior parallel fields
• gameState.activeBalls integer counter ticked in Ball.onActivateEvent / onDeactivateEvent; hasActiveBalls() is now O(1) instead of O(N×slots) per frame
• findWorld(node) helper extracted to entities/util.ts; replaces three identical ancestor-walks
• Slot.collect() decomposed into settleBet / playLandingAudio / spawnLandingEffects / spawnScoreFly / spawnCreditFly, each taking a frozen BetOutcome
• Slot.update() reduced to a computeLabelState projection + applyLabelState applier; state-machine separated from Text-mutation
• WinFlash extracted to its own file
• All "feel" timing constants co-located in constants.ts
• placeBetClick returns number | null (the new wager); call site drops ?? 1 fallback and non-null assertion

Also: HUD subtitle → // www.melonjs.org.

Test plan

• Open the plinko-planck example
• Tap a slot — BET ×2 appears with breathing outline, credits decrement, click cue plays
• Tap the same slot again — multiplier climbs (×3, ×4, ×5), capped at ×6 display
• Tap a different slot — prior wager refunded, new bet opens at ×2
• Drop a ball into the bet slot — fanfare + gold flash + score + credits both multiplied
• Drop a ball into a non-bet slot — bust flash on the bet slot, wager is lost
• While balls are falling — TAP hints are greyed, slot clicks are no-ops
• Run out of credits — TAP hints fade away entirely

[Copilot]

Pull request overview

Adds a per-drop betting mechanic to the plinko-planck example, extending the existing score/credit loop with slot prediction wagers, win/bust feedback, and supporting refactors to keep the example maintainable and performant.

Changes:

• Introduces bet state + wager click handling in shared gameState, plus HUD and slot UI/FX to reflect active bets and outcomes.
• Refactors slot landing handling into smaller helpers, centralizes tierForScore, and extracts shared findWorld utility.
• Improves runtime checks by switching “active balls” detection to an O(1) counter and adds new win/bust audio + a full-viewport win flash effect.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/examples/src/examples/plinko-planck/gameState.ts	Adds betting state/events, wager constants, active-ball counter, and placeBetClick helper.
packages/examples/src/examples/plinko-planck/entities/winFlash.ts	New full-viewport win celebration renderable.
packages/examples/src/examples/plinko-planck/entities/util.ts	New findWorld helper to replace repeated ancestor-walks.
packages/examples/src/examples/plinko-planck/entities/slot.ts	Implements bet interactions/labels and refactors landing settlement into smaller helpers with win/bust visuals.
packages/examples/src/examples/plinko-planck/entities/hud.ts	Updates HUD hinting to include bet status and payout previews; uses new active-ball logic.
packages/examples/src/examples/plinko-planck/entities/dropZone.ts	Uses findWorld and new hasActiveBalls() signature for restart gating.
packages/examples/src/examples/plinko-planck/entities/ball.ts	Maintains gameState.activeBalls and simplifies hasActiveBalls() to O(1).
packages/examples/src/examples/plinko-planck/entities/bakedStatics.ts	Uses centralized tierForScore for baked slot rendering.
packages/examples/src/examples/plinko-planck/constants.ts	Centralizes tierForScore and co-locates new timing “feel” constants.
packages/examples/src/examples/plinko-planck/audio.ts	Adds bet click, bust, and win fanfare cues.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.