# tailuge/billiards architecture

> Architecture diagram of the GitHub repository tailuge/billiards, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tailuge/billiards
- Repository: https://github.com/tailuge/billiards

## Overview

##### Main System Components

Frontend Layer:
- WebGL/Three.js Rendering Engine
- User Interface (HUD, Menu, Sliders)
- Sound System
- Camera Controls

Core Game Layer:
- Physics Engine
- Game Rules Engine
- Event System
- Controller System

Backend Layer:
- A "Network Services" section showing:
- WebSocket Server
- Lobby System
- Game State Management

##### Component Relationships

a) Data Flow:
- User Input → Controller → Physics Engine → View
- Physics Engine → Event System → Network Layer
- WebSocket Server ↔ Client Connections

b) Key Subsystems:
- Ball Mechanics
- Collision Detection
- Cushion Physics
- Spin Effects

##### Architectural Patterns

Patterns:

- MVC Pattern:
- Model: /src/model (physics, table, balls)
- View: /src/view (rendering, UI)
- Controller: /src/controller (game rules, input)

- Event-Driven Architecture:
- Event flow between components
- EventHistory system

##### Technical Details

Elements:

- Technologies:
- TypeScript
- WebGL/Three.js
- WebSocket
- Node.js

- External Interfaces:
- Browser WebGL Context
- WebSocket Connections
- Sound System

##### Specific Implementation Notes

Create sections showing:

- Physics Implementation:
- Collision Detection
- Ball Motion Equations
- Cushion Interactions

- Multiplayer Features:
- Game State Synchronization
- Player Communication
- Lobby Management

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Frontend
        View["WebGL/Three.js Rendering Engine"]
        UI["User Interface Components"]
        Sound["Sound System"]
        Camera["Camera Controls"]
        Assets["Asset Management"]
    end

    subgraph Core
        subgraph Physics
            PhysicsEngine["Physics Engine"]
            BallMech["Ball Mechanics"]
            Collision["Collision Detection"]
            Cushion["Cushion Physics"]
            Table["Table Physics"]
        end

        subgraph GameLogic
            Rules["Game Rules Engine"]
            Controller["Controller System"]
            Events["Event System"]
            
            subgraph GameVariants
                Nineball["Nine Ball"]
                Snooker["Snooker"]
                ThreeCushion["Three Cushion"]
                FourteenOne["Fourteen One"]
            end
        end
    end

    subgraph Network
        WSServer["WebSocket Server"]
        Lobby["Lobby System"]
        GameState["Game State Management"]
        NetClient["Network Client"]
    end

    %% Relationships
    Controller --> PhysicsEngine
    PhysicsEngine --> View
    PhysicsEngine --> Events
    Events --> NetClient
    NetClient --> WSServer
    WSServer --> Lobby
    Lobby --> GameState
    Controller --> Rules
    Rules --> GameVariants
    PhysicsEngine --> BallMech
    PhysicsEngine --> Collision
    PhysicsEngine --> Cushion
    PhysicsEngine --> Table

    %% Styling
    classDef frontend fill:#a8d1f0
    classDef physics fill:#90EE90
    classDef gamelogic fill:#98FB98
    classDef network fill:#FFA07A
    
    class View,UI,Sound,Camera,Assets frontend
    class PhysicsEngine,BallMech,Collision,Cushion,Table physics
    class Rules,Controller,Events,Nineball,Snooker,ThreeCushion,FourteenOne gamelogic
    class WSServer,Lobby,GameState,NetClient network

    %% Click Events
    click View "https://github.com/tailuge/billiards/blob/master/src/view/view.ts"
    click UI "https://github.com/tailuge/billiards/blob/master/src/view/hud.ts"
    click Sound "https://github.com/tailuge/billiards/blob/master/src/view/sound.ts"
    click Camera "https://github.com/tailuge/billiards/blob/master/src/view/camera.ts"
    click Assets "https://github.com/tailuge/billiards/blob/master/src/view/assets.ts"
    click PhysicsEngine "https://github.com/tailuge/billiards/blob/master/src/model/physics/physics.ts"
    click BallMech "https://github.com/tailuge/billiards/blob/master/src/model/ball.ts"
    click Collision "https://github.com/tailuge/billiards/blob/master/src/model/physics/collision.ts"
    click Cushion "https://github.com/tailuge/billiards/blob/master/src/model/physics/cushion.ts"
    click Table "https://github.com/tailuge/billiards/blob/master/src/model/table.ts"
    click Rules "https://github.com/tailuge/billiards/blob/master/src/controller/rules/rules.ts"
    click Controller "https://github.com/tailuge/billiards/blob/master/src/controller/controller.ts"
    click Events "https://github.com/tailuge/billiards/blob/master/src/events/eventhistory.ts"
    click WSServer "https://github.com/tailuge/billiards/blob/master/src/network/server/socketserver.ts"
    click Lobby "https://github.com/tailuge/billiards/blob/master/src/network/server/lobby.ts"
    click GameState "https://github.com/tailuge/billiards/blob/master/src/network/server/tables.ts"
    click NetClient "https://github.com/tailuge/billiards/blob/master/src/network/client/socketconnection.ts"
    click Nineball "https://github.com/tailuge/billiards/blob/master/src/controller/rules/nineball.ts"
    click Snooker "https://github.com/tailuge/billiards/blob/master/src/controller/rules/snooker.ts"
    click ThreeCushion "https://github.com/tailuge/billiards/blob/master/src/controller/rules/threecushion.ts"
    click FourteenOne "https://github.com/tailuge/billiards/blob/master/src/controller/rules/fourteenone.ts"
```
