How ghost0t/b8ll8ard0 works
1. This is a TypeScript browser game and simulator for billiards/snooker/three-cushion, built around a single-page client that renders in WebGL and runs the full game loop in the browser. The checked-in dist/ folder contains the deployed static artifacts, while src/ is the authoritative source.
2. The top-level architecture is split into four main layers: model for physics and table state, controller for game state transitions and rule enforcement, view for rendering/UI, and events for the user/game event pipeline. A container layer wires these pieces together for browser startup and configuration.
3. The physics core lives in src/model/physics and handles ball motion, ball-ball collisions, cushion rebounds, pocketing, and spin/throw behavior. The README’s equations match this layer closely, so the architecture centers on a numerically simulated cue-sport engine rather than a simple animation.
4. The controller layer orchestrates gameplay modes. It includes initialization, aiming, shot execution, ball placement, end-of-turn handling, replay playback, spectating, and “watch aim/shot” flows. This layer is where raw input and physics results become match progression.
5. Rule-specific logic is isolated in src/controller/rules for eight-ball, nine-ball, snooker, and three-cushion. The rule factory and shared scoring/utilities keep mode-specific constraints separate from the generic shot/physics pipeline.
6. Input and interaction are event-driven. src/events defines typed events for aim, hit, start, break, concede, rerack, chat, watch, notifications, scoring, and replay recording. This acts as the boundary between DOM/device input and controller logic, and also as the basis for replay serialization.
7. The replay and record path is a notable data flow: player actions are turned into event records, encoded, and later replayed by the controller. This supports break recording, shared replay links, and regression tests around historical bugs.
8. The view layer is a WebGL/DOM hybrid. src/view contains table/ball/cue meshes, camera systems, particle effects, HUD/menu/chat/notifications, and sound playback. It receives state from the controller and model, but does not own game rules or physics.
9. The repository includes a diagram/analysis subsystem under src/diagram and src/diagrams.ts. These pages and plots are used to inspect physics behavior, validate equations, and visualize things like cushion rebounds, roll, throw, and real-position calculations. They are part of the product, not just documentation.
10. Networking is split into client-side session/messaging and bot play support. src/network/client handles multiplayer session state, score reporting, rematch, and message relay integration; src/network/bot implements automated opponents and strategy selection. The README indicates two-player online mode relies on an external nchan-based message server.
11. Static assets are first-class architectural inputs: HTML entry points, CSS bundles, sounds, and 3D models live under dist/. The app loads GLTF/BIN assets for tables and backgrounds, plus audio cues for collisions, shots, pots, and success states.
12. The build/deployment boundary is a browser bundle produced with Webpack/TypeScript tooling and validated with Jest. GitHub Actions, GitHub Pages, Vercel, Render, and a public worker-hosted demo are all deployment targets, but they all consume the same static client build.
13. The test suite mirrors the architecture and is a strong indicator of boundaries: separate tests exist for model physics, rules, controller flows, events, network, view widgets, diagrams, and server/session behavior. That test partitioning reflects the intended subsystem seams for the diagram.
Main entry points: view.ts View · controller.ts Controller · physics.ts Physics · container.ts Container
Components 24
Core game
Physics, rules, controller, and events that drive a browser match.
- Container · Bootstraps the browser client and wires together model, controller, view, and events.
src/container/container.ts - Browser startup · Browser-specific container setup and configuration entry.
src/container/browsercontainer.ts - Controller · Coordinates initialization, aiming, turns, replay, spectating, and mode transitions.
src/controller/controller.ts - Shot flow · Executes shots and advances play from input to physics outcome.
src/controller/playshot.ts - Turn end · Handles end-of-turn resolution and match progression.
src/controller/end.ts - Replay · Encodes, records, and replays event history for playback and regression cases.
src/controller/replay.ts - Rules · Shared rule interfaces and mode-specific constraint handling.
src/controller/rules/rules.ts - Rule factory · Selects the active rule implementation for the current game mode.
src/controller/rules/rulefactory.ts - Physics · Numerical cue-sport simulation for motion, collisions, cushions, pockets, and spin.
src/model/physics/physics.ts - Table · Represents table geometry and playing state used by physics and rules.
src/model/table.ts - Ball model · Ball state and outcome data structures shared across simulation and gameplay.
src/model/ball.ts - Event types · Typed event definitions that separate user actions from controller logic.
src/events/eventtype.ts - Recorder · Captures game events for replay, sharing, and historical playback.
src/events/recorder.ts
Presentation
WebGL/DOM rendering, HUD, sound, and interactive UI.
- View · WebGL/DOM presentation layer for table, balls, cues, HUD, menus, notifications, and sound.
src/view/view.ts - Table mesh · Table and cloth geometry rendering for the 3D scene.
src/view/tablemesh.ts - Ball mesh · Ball rendering, materials, and appearance helpers.
src/view/ballmesh.ts - Camera · Camera systems for match view and top-down viewing.
src/view/camera.ts - HUD · Heads-up display, menus, chat, notifications, and interaction widgets.
src/view/hud.ts - Sound · Sound playback for collisions, shots, pots, and success states.
src/view/sound.ts
Integration
Browser startup, networking, bots, and shared utilities.
- Client net · Client-side multiplayer session, score reporting, rematch, and message relay integration.
src/network/client/session.ts - Bot play · Automated opponent and strategy selection for bot-driven matches.
src/network/bot/botstrategy.ts - Utilities · Cross-cutting helpers for replay encoding, GLTF loading, rack/respot logic, and browser utilities.
src/utils/utils.ts
Analysis
Diagram and physics inspection tools.
- Diagrams · Wires interactive physics diagrams and plots for inspection and validation.
src/diagram/diagramcontainer.ts - Graph plots · Plot and graph helpers used by the diagram subsystem.
src/diagram/graph.ts
Connections 26
- Browser startup → Container: configures · Browser-specific setup feeds the shared application container.
- Container → Controller: wires · Startup wiring connects the controller to the app shell.
- Container → View: wires · The container instantiates the rendering and UI layer.
- Container → Physics: wires · Physics engine is part of the core runtime assembled at startup.
- Container → Client net: wires · Multiplayer session support is injected into the browser client.
- Controller → Shot flow: uses · Core game flow delegates shot execution to specialized turn logic.
- Controller → Turn end: uses · Turn resolution and progression are handled by end-of-turn logic.
- Controller → Replay: uses · Replay and record playback are part of the controller's orchestration.
- Controller → Rules: applies · Controller consults rules to enforce mode-specific behavior.
- Rule factory → Rules: selects · Factory chooses the active rule implementation.
- Rules → Physics: constrains · Rules consume simulation outcomes and shape legal progression.
- Physics → Table: simulates · Simulation operates on table geometry and state.
- Physics → Ball model: updates · Ball state is advanced by the physics core.
- Physics → Utilities: uses · Shared math and replay helpers support the simulation.
- Event types → Controller: drives · Typed events are the boundary into controller logic.
- Recorder → Replay: feeds · Recorded events become replay input and stored history.
- View → Table mesh: renders · View composes the 3D table scene.
- View → Ball mesh: renders · View composes the ball visuals and materials.
- View → Camera: uses · Scene rendering depends on camera control systems.
- View → HUD: uses · User interface overlays are part of the view layer.
- View → Sound: uses · Audio cues are triggered from the presentation layer.
- Client net → Recorder: shares · Session and replay paths both rely on event history semantics.
- Bot play → Controller: simulates · Automated play produces controller-facing actions.
- Diagrams → Graph plots: uses · Diagram pages build on graph and plotting helpers.
- Diagrams → Physics: inspects · Analysis tools visualize and validate physics behavior.
- Utilities → View: supports · Shared helpers back rendering, DOM, and asset loading.