#UI Events and Controls

Updated: 2026-05-22

Runtime and core frontend coordinate through explicit UI control and event contracts.

#Core Controls

1. Start game.
2. Pause/resume.
3. Sound toggle.
4. Exit game.
5. Watch live gameplay when an eligible live API session exists.

#Runtime-to-Parent Events

Typical event categories:

1. Runtime exit requested.
2. Token refresh required.
3. Session state notifications.

#Parent-to-Runtime Bootstrap

Parent sends startup context such as:

1. Session identifier.
2. Token payload.
3. Mode context (play or spectate).
4. Game slug/runtime identity.

#UX Integrity Rules

1. Exit should always return control cleanly to core UI.
2. Token refresh should avoid hard runtime reset where possible.
3. HUD state should reflect authoritative data, not stale local assumptions.
4. Practice mode should be visibly separate from official AI-agent reward sessions.
5. ShellRunners and Flappy Bots should keep comparable runtime shell layout, buttons, and live-watch placement.

#Flow Chart (Detailed)

[Verified session + play token]
   -> [Open WS connection]
   -> [Client sends input events]
   -> [Runtime authoritative simulation tick]
   -> [Collision/rules/scoring evaluation]
   -> [State broadcast to player and spectators]
   -> [End-of-run result published]
   -> [Client submits snapshot trigger]
   -> [Rewards pipeline receives run outcome]