# RCWeb Stack Fall

**Stack Fall** (`app/stack-fall`) is the shared-screen display for a physics balancing game built around the RCWeb asymmetric app pattern. The large screen shows three independent lanes, a QR code for phone controllers, the global drop countdown, and the live towers as they wobble, collide, and settle.

Open the display on a TV, projector, laptop, or large monitor, then let players scan the QR code to join with `stack-fall-c`. The display is the single source of truth for the round: it chooses each drop shape, runs the timer, owns the Box2D physics world, decides when pieces have balanced, and eliminates players when a piece falls below the floor.

![icon](pwa-512x512.png "Stack Fall Display Icon")

## The Game

Stack Fall is a modern block-stacking challenge inspired by tower games and falling-block puzzles. Each lane starts with only a floor. Every drop cycle gives all lanes the same Tetris-style shape, so active players and open stacks face the same physical problem at the same time.

During the five-second aiming window, each lane has one piece at the top of the screen. A connected player can move their piece with the phone slider or optional phone tilt. If a lane has no player, or the player is not touching the slider, the piece drifts left and right on its own. When the countdown reaches zero, all active pieces release together and fall onto their lane's floor or existing stack.

A piece can tip, lean, slide, or hang over an edge and the player can continue as long as it remains above the floor. A player is out only when a block or tower piece drops below the floor. Open stacks keep playing without a controller so the screen remains alive while players join.

## How To Play

Open `/stack-fall/?r=<room>` on the shared screen. Players scan the QR code to open `/stack-fall-c/?r=<room>` on their phones. Up to **3 players** can join, one per lane.

Each round runs in repeated synchronized drops:

- The display picks one shared shape for the next drop.
- Every non-eliminated lane receives that same shape at the top of the screen.
- Players have **5 seconds** to aim.
- All pieces release at the same time.
- Settled pieces count as balanced.
- A player is eliminated when any of their pieces falls below the floor.

When all active players have lost, the display starts a short reset countdown and then begins a new game with the same connected players.

## Display Layout

The display is designed for shared landscape screens while still functioning in portrait. The visual style uses a black OLED-friendly background with saturated RGB lane colors and neon HUD accents. The main playfield keeps the falling pieces clear of player status text and the QR code. The **Stack Fall** title sits at the top left, while the bottom panel is reserved for lane info, connection status, and the QR code. The global countdown number and progress bar sit at the top center so the drop timer is visible without covering the pieces being aimed.

## Powered By RCWeb

Stack Fall uses RCWeb's room-based WebSocket layer through `comms.js`. The display publishes a QR code with the room already embedded, then receives controller intents through `rc.sendFunctionCall`.

The display intentionally keeps communication event-based. Controllers send updates only when the slider, touch state, name, reset request, or tilt value changes. The countdown is maintained locally from timestamps in snapshots, avoiding constant WebSocket traffic.

## Implementation Notes

- Physics uses the shared Box2DWeb JavaScript library at `/assets/lib/box2dweb-2.1.0-b/package/box2d.js`.
- Falling pieces are compound Box2D bodies made from square fixtures, allowing I, O, T, L, J, S, and Z style shapes to tumble as single rigid pieces.
- The display isolates collisions by lane so stacks do not interfere with neighboring towers.
- `stack-fall` targets the controller app `stack-fall-c` with tailored snapshots for each joined player.
- The QR code is created with `rc.buildQRCodePanel()` to match other RCWeb apps.