# ghost0t/b8ll8ard0 architecture

> Architecture diagram of the GitHub repository ghost0t/b8ll8ard0, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ghost0t/b8ll8ard0
- Repository: https://github.com/ghost0t/b8ll8ard0

## Overview

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: [`src/view/view.ts`](https://github.com/ghost0t/b8ll8ard0/blob/main/src/view/view.ts) (View), [`src/controller/controller.ts`](https://github.com/ghost0t/b8ll8ard0/blob/main/src/controller/controller.ts) (Controller), [`src/model/physics/physics.ts`](https://github.com/ghost0t/b8ll8ard0/blob/main/src/model/physics/physics.ts) (Physics), [`src/container/container.ts`](https://github.com/ghost0t/b8ll8ard0/blob/main/src/container/container.ts) (Container)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core game"]
  node_container["Container<br/>browser wiring<br/>[container.ts]"]
  node_browsercontainer["Browser startup<br/>startup wiring"]
  node_controller["Controller<br/>game flow<br/>[controller.ts]"]
  node_playshot["Shot flow<br/>turn execution<br/>[playshot.ts]"]
  node_end["Turn end<br/>state transition<br/>[end.ts]"]
  node_replay["Replay<br/>record/playback<br/>[replay.ts]"]
  node_rules{{"Rules<br/>rule system<br/>[rules.ts]"}}
  node_rulefactory["Rule factory<br/>mode dispatch<br/>[rulefactory.ts]"]
  node_physics["Physics<br/>simulation engine<br/>[physics.ts]"]
  node_table["Table<br/>state model<br/>[table.ts]"]
  node_ball["Ball model<br/>state model<br/>[ball.ts]"]
  node_eventtype["Event types<br/>event schema<br/>[eventtype.ts]"]
  node_recorder["Recorder<br/>event log<br/>[recorder.ts]"]
end

subgraph group_presentation["Presentation"]
  node_view["View<br/>rendering<br/>[view.ts]"]
  node_tablemesh["Table mesh<br/>3D render<br/>[tablemesh.ts]"]
  node_ballmesh["Ball mesh<br/>3D render<br/>[ballmesh.ts]"]
  node_camera["Camera<br/>scene control<br/>[camera.ts]"]
  node_hud["HUD<br/>ui overlay<br/>[hud.ts]"]
  node_sound["Sound<br/>audio<br/>[sound.ts]"]
end

subgraph group_integration["Integration"]
  node_networkclient["Client net<br/>session/network<br/>[session.ts]"]
  node_bot["Bot play<br/>automation<br/>[botstrategy.ts]"]
  node_utils["Utilities<br/>shared helpers<br/>[utils.ts]"]
end

subgraph group_analysis["Analysis"]
  node_diagramcontainer["Diagrams<br/>analysis app"]
  node_graph["Graph plots<br/>analysis views<br/>[graph.ts]"]
end

node_browsercontainer -->|"configures"| node_container
node_container -->|"wires"| node_controller
node_container -->|"wires"| node_view
node_container -->|"wires"| node_physics
node_container -->|"wires"| node_networkclient
node_controller -->|"uses"| node_playshot
node_controller -->|"uses"| node_end
node_controller -->|"uses"| node_replay
node_controller -->|"applies"| node_rules
node_rulefactory -->|"selects"| node_rules
node_rules -->|"constrains"| node_physics
node_physics -->|"simulates"| node_table
node_physics -->|"updates"| node_ball
node_physics -->|"uses"| node_utils
node_eventtype -->|"drives"| node_controller
node_recorder -->|"feeds"| node_replay
node_view -->|"renders"| node_tablemesh
node_view -->|"renders"| node_ballmesh
node_view -->|"uses"| node_camera
node_view -->|"uses"| node_hud
node_view -->|"uses"| node_sound
node_networkclient -.->|"shares"| node_recorder
node_bot -->|"simulates"| node_controller
node_diagramcontainer -->|"uses"| node_graph
node_diagramcontainer -->|"inspects"| node_physics
node_utils -.->|"supports"| node_view

click node_container "https://github.com/ghost0t/b8ll8ard0/blob/main/src/container/container.ts"
click node_browsercontainer "https://github.com/ghost0t/b8ll8ard0/blob/main/src/container/browsercontainer.ts"
click node_controller "https://github.com/ghost0t/b8ll8ard0/blob/main/src/controller/controller.ts"
click node_playshot "https://github.com/ghost0t/b8ll8ard0/blob/main/src/controller/playshot.ts"
click node_end "https://github.com/ghost0t/b8ll8ard0/blob/main/src/controller/end.ts"
click node_replay "https://github.com/ghost0t/b8ll8ard0/blob/main/src/controller/replay.ts"
click node_rules "https://github.com/ghost0t/b8ll8ard0/blob/main/src/controller/rules/rules.ts"
click node_rulefactory "https://github.com/ghost0t/b8ll8ard0/blob/main/src/controller/rules/rulefactory.ts"
click node_physics "https://github.com/ghost0t/b8ll8ard0/blob/main/src/model/physics/physics.ts"
click node_table "https://github.com/ghost0t/b8ll8ard0/blob/main/src/model/table.ts"
click node_ball "https://github.com/ghost0t/b8ll8ard0/blob/main/src/model/ball.ts"
click node_eventtype "https://github.com/ghost0t/b8ll8ard0/blob/main/src/events/eventtype.ts"
click node_recorder "https://github.com/ghost0t/b8ll8ard0/blob/main/src/events/recorder.ts"
click node_view "https://github.com/ghost0t/b8ll8ard0/blob/main/src/view/view.ts"
click node_tablemesh "https://github.com/ghost0t/b8ll8ard0/blob/main/src/view/tablemesh.ts"
click node_ballmesh "https://github.com/ghost0t/b8ll8ard0/blob/main/src/view/ballmesh.ts"
click node_camera "https://github.com/ghost0t/b8ll8ard0/blob/main/src/view/camera.ts"
click node_hud "https://github.com/ghost0t/b8ll8ard0/blob/main/src/view/hud.ts"
click node_sound "https://github.com/ghost0t/b8ll8ard0/blob/main/src/view/sound.ts"
click node_networkclient "https://github.com/ghost0t/b8ll8ard0/blob/main/src/network/client/session.ts"
click node_bot "https://github.com/ghost0t/b8ll8ard0/blob/main/src/network/bot/botstrategy.ts"
click node_utils "https://github.com/ghost0t/b8ll8ard0/blob/main/src/utils/utils.ts"
click node_diagramcontainer "https://github.com/ghost0t/b8ll8ard0/blob/main/src/diagram/diagramcontainer.ts"
click node_graph "https://github.com/ghost0t/b8ll8ard0/blob/main/src/diagram/graph.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_container,node_browsercontainer,node_controller,node_playshot,node_end,node_replay,node_rules,node_rulefactory,node_physics,node_table,node_ball,node_eventtype,node_recorder toneBlue
class node_view,node_tablemesh,node_ballmesh,node_camera,node_hud,node_sound toneAmber
class node_networkclient,node_bot,node_utils toneMint
class node_diagramcontainer,node_graph toneRose
```

## Components

### Core game

Physics, rules, controller, and events that drive a browser match.

- [Container](https://github.com/ghost0t/b8ll8ard0/blob/main/src/container/container.ts): browser wiring · Bootstraps the browser client and wires together model, controller, view, and events. · `src/container/container.ts`
- [Browser startup](https://github.com/ghost0t/b8ll8ard0/blob/main/src/container/browsercontainer.ts): startup wiring · Browser-specific container setup and configuration entry. · `src/container/browsercontainer.ts`
- [Controller](https://github.com/ghost0t/b8ll8ard0/blob/main/src/controller/controller.ts): game flow · Coordinates initialization, aiming, turns, replay, spectating, and mode transitions. · `src/controller/controller.ts`
- [Shot flow](https://github.com/ghost0t/b8ll8ard0/blob/main/src/controller/playshot.ts): turn execution · Executes shots and advances play from input to physics outcome. · `src/controller/playshot.ts`
- [Turn end](https://github.com/ghost0t/b8ll8ard0/blob/main/src/controller/end.ts): state transition · Handles end-of-turn resolution and match progression. · `src/controller/end.ts`
- [Replay](https://github.com/ghost0t/b8ll8ard0/blob/main/src/controller/replay.ts): record/playback · Encodes, records, and replays event history for playback and regression cases. · `src/controller/replay.ts`
- [Rules](https://github.com/ghost0t/b8ll8ard0/blob/main/src/controller/rules/rules.ts): rule system · Shared rule interfaces and mode-specific constraint handling. · `src/controller/rules/rules.ts`
- [Rule factory](https://github.com/ghost0t/b8ll8ard0/blob/main/src/controller/rules/rulefactory.ts): mode dispatch · Selects the active rule implementation for the current game mode. · `src/controller/rules/rulefactory.ts`
- [Physics](https://github.com/ghost0t/b8ll8ard0/blob/main/src/model/physics/physics.ts): simulation engine · Numerical cue-sport simulation for motion, collisions, cushions, pockets, and spin. · `src/model/physics/physics.ts`
- [Table](https://github.com/ghost0t/b8ll8ard0/blob/main/src/model/table.ts): state model · Represents table geometry and playing state used by physics and rules. · `src/model/table.ts`
- [Ball model](https://github.com/ghost0t/b8ll8ard0/blob/main/src/model/ball.ts): state model · Ball state and outcome data structures shared across simulation and gameplay. · `src/model/ball.ts`
- [Event types](https://github.com/ghost0t/b8ll8ard0/blob/main/src/events/eventtype.ts): event schema · Typed event definitions that separate user actions from controller logic. · `src/events/eventtype.ts`
- [Recorder](https://github.com/ghost0t/b8ll8ard0/blob/main/src/events/recorder.ts): event log · Captures game events for replay, sharing, and historical playback. · `src/events/recorder.ts`

### Presentation

WebGL/DOM rendering, HUD, sound, and interactive UI.

- [View](https://github.com/ghost0t/b8ll8ard0/blob/main/src/view/view.ts): rendering · WebGL/DOM presentation layer for table, balls, cues, HUD, menus, notifications, and sound. · `src/view/view.ts`
- [Table mesh](https://github.com/ghost0t/b8ll8ard0/blob/main/src/view/tablemesh.ts): 3D render · Table and cloth geometry rendering for the 3D scene. · `src/view/tablemesh.ts`
- [Ball mesh](https://github.com/ghost0t/b8ll8ard0/blob/main/src/view/ballmesh.ts): 3D render · Ball rendering, materials, and appearance helpers. · `src/view/ballmesh.ts`
- [Camera](https://github.com/ghost0t/b8ll8ard0/blob/main/src/view/camera.ts): scene control · Camera systems for match view and top-down viewing. · `src/view/camera.ts`
- [HUD](https://github.com/ghost0t/b8ll8ard0/blob/main/src/view/hud.ts): ui overlay · Heads-up display, menus, chat, notifications, and interaction widgets. · `src/view/hud.ts`
- [Sound](https://github.com/ghost0t/b8ll8ard0/blob/main/src/view/sound.ts): audio · Sound playback for collisions, shots, pots, and success states. · `src/view/sound.ts`

### Integration

Browser startup, networking, bots, and shared utilities.

- [Client net](https://github.com/ghost0t/b8ll8ard0/blob/main/src/network/client/session.ts): session/network · Client-side multiplayer session, score reporting, rematch, and message relay integration. · `src/network/client/session.ts`
- [Bot play](https://github.com/ghost0t/b8ll8ard0/blob/main/src/network/bot/botstrategy.ts): automation · Automated opponent and strategy selection for bot-driven matches. · `src/network/bot/botstrategy.ts`
- [Utilities](https://github.com/ghost0t/b8ll8ard0/blob/main/src/utils/utils.ts): shared helpers · 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](https://github.com/ghost0t/b8ll8ard0/blob/main/src/diagram/diagramcontainer.ts): analysis app · Wires interactive physics diagrams and plots for inspection and validation. · `src/diagram/diagramcontainer.ts`
- [Graph plots](https://github.com/ghost0t/b8ll8ard0/blob/main/src/diagram/graph.ts): analysis views · Plot and graph helpers used by the diagram subsystem. · `src/diagram/graph.ts`

## Connections

- 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.
