# fardinfaruqi/tron-lightcycle-game--two-player architecture

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

- Interactive diagram: https://gitdiagram.com/fardinfaruqi/tron-lightcycle-game--two-player
- Repository: https://github.com/fardinfaruqi/tron-lightcycle-game--two-player

## Overview

1. **Repository shape**
   - This is primarily a **Python, turtle-based, two-player arcade game**.
   - The core game lives in `Tron_Lightcycle.py` plus the `classes/` package.
   - `screenshots/` is documentation-only, and `deployment/index.html` suggests there is also a **static web deployment/landing artifact** separate from the Python runtime.

2. **Runtime boundary**
   - The actual game runtime is a **local Python process** using the standard-library `turtle` graphics module.
   - There are no third-party runtime dependencies called out in the README.
   - The game is therefore architected as a **single-process, event-driven desktop game**, not a client-server app.

3. **Entry point**
   - `Tron_Lightcycle.py` is the startup file.
   - Its role is to create the main game object, wire up the turtle window, and hand control to the game loop.
   - This is the main architectural root from which all other subsystems are composed.

4. **Main orchestrator**
   - `classes/game.py` is the central coordination layer.
   - It owns the high-level flow: initialize subsystems, start a round, advance frames, check collisions, update state, and trigger rendering.
   - In diagram terms, this is the hub that connects input, simulation, collision logic, UI, and game state.

5. **Core domain model**
   - `classes/player.py` represents each lightcycle: position, heading, color, movement, and trail history.
   - `classes/arena.py` defines the play field and its boundaries.
   - Together they form the core simulation model: where the players are, how they move, and what counts as “inside” the arena.

6. **Game state management**
   - `classes/game_state.py` tracks session-level state such as whether the match is running, over, who won, and the current frame count.
   - The README indicates it also controls **timing-related rules** like trail sampling and self-collision grace frames.
   - This creates a clear separation between transient per-frame motion and match lifecycle state.

7. **Collision and rules enforcement**
   - `classes/collision_detector.py` is the physics/rules boundary.
   - It checks wall collisions, self-collisions, and collisions with the opponent’s trail.
   - The README implies the detector uses a **collision radius** and likely applies a **grace period** before self-collision becomes active, which helps keep early movement fair.

8. **Input subsystem**
   - `classes/input_handler.py` isolates keyboard binding from gameplay logic.
   - Player A uses WASD; Player B uses arrow keys.
   - This subsystem feeds direction changes into the players, while preventing illegal 180° reversals as part of the control rules.

9. **Rendering / UI subsystem**
   - `classes/ui_renderer.py` handles all on-screen presentation: splash screen, HUD, and end-game results.
   - The actual movement/trail drawing is likely split between the player/arena rendering and this UI layer, but the key architectural point is that **text and match messaging are centralized here**.
   - That keeps presentation concerns separate from simulation.

10. **Configuration boundary**
    - `classes/constants.py` centralizes tunables such as arena size, step size, frame delay, trail thickness, sampling interval, collision radius, and grace frames.
    - This file acts as the project’s configuration contract and is the main place to adjust difficulty, speed, and visual feel without changing the architecture.

11. **Per-frame data flow**
    - The high-level flow is: **keyboard input → player direction updates → player movement → trail accumulation → collision checks → game state update → rendering**.
    - The game loop advances continuously at roughly 75 FPS, so the simulation and UI are synchronized through frame-based updates rather than discrete turns.

12. **Boundaries and extension points**
    - The architecture is intentionally modular: input, simulation, collision, rendering, and state are separated into distinct classes.
    - That makes it straightforward to add AI, sound, power-ups, or additional modes by extending the orchestrator and introducing new subsystems rather than rewriting the core loop.

13. **Deployment artifact**
    - `deployment/index.html` is structurally separate from the Python source tree, so it should be treated as a **delivery/deployment surface**, not part of the game engine itself.
    - If you are drawing an architecture diagram, keep the Python game runtime and any web deployment wrapper as two distinct boundaries.

14. **What to emphasize in a diagram**
    - Draw the game loop as the central control path.
    - Show `Game` as the orchestrator connecting `InputHandler`, `Player`, `CollisionDetector`, `Arena`, `GameState`, and `UIRenderer`.
    - Treat `constants.py` as shared configuration input to multiple subsystems, and treat `deployment/index.html` as a separate packaging/deployment layer.

Main entry points: [`classes/game.py`](https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/game.py) (Game), [`classes/collision_detector.py`](https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/collision_detector.py) (Collision Detector), [`classes/ui_renderer.py`](https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/ui_renderer.py) (UI Renderer), [`classes/player.py`](https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/player.py) (Player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Python Runtime"]
  node_entry["Tron Lightcycle<br/>entrypoint<br/>[Tron_Lightcycle.py]"]
  node_game["Game<br/>orchestrator<br/>[game.py]"]
  node_input["Input Handler<br/>keyboard input<br/>[input_handler.py]"]
  node_player["Player<br/>lightcycle model<br/>[player.py]"]
  node_arena["Arena<br/>playfield model<br/>[arena.py]"]
  node_collision["Collision Detector<br/>rules engine"]
  node_state["Game State<br/>match state<br/>[game_state.py]"]
  node_ui["UI Renderer<br/>presentation<br/>[ui_renderer.py]"]
  node_constants["Constants<br/>config<br/>[constants.py]"]
  node_turtle(("Turtle<br/>stdlib graphics"))
end

subgraph group_delivery["Deployment"]
  node_deployment["Index Page<br/>static delivery<br/>[index.html]"]
end

node_entry -->|"starts"| node_game
node_game -->|"binds"| node_input
node_game -->|"moves"| node_player
node_game -->|"uses"| node_arena
node_game -->|"checks"| node_collision
node_game -->|"updates"| node_state
node_game -->|"renders"| node_ui
node_game -->|"reads"| node_constants
node_input -->|"steers"| node_player
node_collision -->|"inspects"| node_player
node_collision -->|"bounds"| node_arena
node_collision -->|"ends round"| node_state
node_ui -->|"displays"| node_state
node_ui -->|"styles"| node_constants
node_player -->|"moves by"| node_constants
node_arena -->|"sizes by"| node_constants
node_deployment -.->|"packages"| node_entry
node_entry -->|"runs on"| node_turtle
node_ui -->|"draws with"| node_turtle

click node_entry "https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/Tron_Lightcycle.py"
click node_game "https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/game.py"
click node_input "https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/input_handler.py"
click node_player "https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/player.py"
click node_arena "https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/arena.py"
click node_collision "https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/collision_detector.py"
click node_state "https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/game_state.py"
click node_ui "https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/ui_renderer.py"
click node_constants "https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/constants.py"
click node_deployment "https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/deployment/index.html"

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_entry,node_game,node_input,node_player,node_arena,node_collision,node_state,node_ui,node_constants,node_turtle toneBlue
class node_deployment toneAmber
```

## Components

### Python Runtime

Single-process turtle-based game loop and simulation

- [Tron Lightcycle](https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/Tron_Lightcycle.py): entrypoint · Bootstraps the turtle window and starts the game · `Tron_Lightcycle.py`
- [Game](https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/game.py): orchestrator · Central coordinator for rounds, frames, and subsystem flow · `classes/game.py`
- [Input Handler](https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/input_handler.py): keyboard input · Binds controls and translates key presses into direction changes · `classes/input_handler.py`
- [Player](https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/player.py): lightcycle model · Represents a cycle's position, heading, color, movement, and trail · `classes/player.py`
- [Arena](https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/arena.py): playfield model · Defines the arena bounds and playable space · `classes/arena.py`
- [Collision Detector](https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/collision_detector.py): rules engine · Checks wall, self, and opponent trail collisions · `classes/collision_detector.py`
- [Game State](https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/game_state.py): match state · Tracks running state, winner, frame count, and timing rules · `classes/game_state.py`
- [UI Renderer](https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/ui_renderer.py): presentation · Renders splash, HUD, and end-game messages · `classes/ui_renderer.py`
- [Constants](https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/classes/constants.py): config · Shared tunables for size, speed, collision, and timing · `classes/constants.py`
- **Turtle**: stdlib graphics · Standard-library drawing and windowing runtime

### Deployment

Static web delivery artifact

- [Index Page](https://github.com/fardinfaruqi/tron-lightcycle-game--two-player/blob/main/deployment/index.html): static delivery · Separate web deployment or landing artifact · `deployment/index.html`

## Connections

- Tron Lightcycle → Game: starts · Creates the main game object and hands off control
- Game → Input Handler: binds · Initializes keyboard controls and routes direction changes
- Game → Player: moves · Advances each cycle and updates trails
- Game → Arena: uses · Applies playfield boundaries and space rules
- Game → Collision Detector: checks · Runs collision detection each frame
- Game → Game State: updates · Manages round lifecycle and win state
- Game → UI Renderer: renders · Triggers screen updates and match messaging
- Game → Constants: reads · Uses shared tunables for frame and gameplay behavior
- Input Handler → Player: steers · Feeds validated direction changes into players
- Collision Detector → Player: inspects · Examines player position and trail data
- Collision Detector → Arena: bounds · Uses arena limits for wall checks
- Collision Detector → Game State: ends round · Flags match outcome when a collision occurs
- UI Renderer → Game State: displays · Reads match status for splash, HUD, and results
- UI Renderer → Constants: styles · Uses tunables for presentation sizing and timing
- Player → Constants: moves by · Uses step and trail settings while advancing
- Arena → Constants: sizes by · Uses configuration for playfield dimensions
- Index Page → Tron Lightcycle: packages · Separate delivery surface for the game artifact
- Tron Lightcycle → Turtle: runs on · Uses the standard-library turtle graphics runtime
- UI Renderer → Turtle: draws with · Renders presentation through turtle
