# pondahai/train_sim architecture

> Architecture diagram of the GitHub repository pondahai/train_sim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pondahai/train_sim
- Repository: https://github.com/pondahai/train_sim

## Overview

##### Project type and purpose
- This is a desktop-based full-stack application written in Python. It actually contains two “front-ends”:
- A real-time 3D train simulator (`main.py`) built with Pygame and PyOpenGL.
- A graphical scene editor (`scene_editor.py`) built with PyQt5 that reads/writes the same `scene.txt`.
- Core purpose: allow users to define 3D track layouts and environment in a text file, simulate/train driving in first-person, and edit scenes via GUI.

##### File structure
Top-level files (no subdirectories):
- main.py – simulation entry point, orchestrates modules and event loop
- scene_editor.py – PyQt5 GUI for editing the scene file, 2D/3D previews
- renderer.py – OpenGL drawing of 3D scene, HUD, skybox/skydome
- minimap_renderer.py – 2D minimap baking (simulator) and dynamic drawing (editor)
- scene_parser.py – parses `scene.txt`, constructs objects/tracks/branches/imports
- tram.py – physics & control logic for the train
- track.py – track geometry, vertex generation, vbranch support
- camera.py – first-person/fly-around camera control
- texture_loader.py – loads and caches textures (with alpha testing support)
- README.md – detailed description, usage, dependencies

##### README for additional insights
- External dependencies: Pygame, PyOpenGL, NumPy, Numba, PyQt5, Pillow.
- Data inputs: `scene.txt` (scene definition), `textures/` folder.
- Two modes share many core modules (parser, renderer, camera, minimap_renderer, texture_loader).

1. Simulator Application (main.py)
2. Scene Editor Application (scene_editor.py)
3. Core Library Modules (shared)
– Scene Parser
– Track Geometry
– Train Physics (Tram)
– Camera Controller
– Renderer (3D)
– Minimap Renderer (2D)
– Texture Loader
4. Data & Config
– scene.txt (scene definition)
– textures/ (PNG assets, skybox images)
– editor_settings.json (editor-only persistent settings)
5. External Libraries
– Pygame, PyOpenGL, NumPy, Numba (simulation & rendering)
– PyQt5 (editor GUI)
– Pillow (image I/O for minimap/editor)
6. Operating System / File System

- Simulator App → reads scene.txt via Scene Parser → constructs scene graph (Tracks + Objects)
- Texture Loader ← scene graph requests textures → caches and returns OpenGL textures
- Simulator main loop uses Train Physics + Camera Controller → updates positions & view matrix
- Renderer (3D) ← scene graph + camera matrix + textures → draws frame
- Minimap Renderer (2D) ← scene graph + train position → overlays HUD
- Scene Editor → uses Scene Parser to populate UI table & 2D/3D preview
- Editor’s 2D Minimap Renderer ← same module as simulator’s but dynamic
- Editor’s 3D Preview ← main renderer with fly-camera controlled by PyQt5 events
- Editor → writes back scene.txt and editor_settings.json

c. Architectural patterns & principles
- Modular separation of concerns: parsing, geometry, physics, rendering, UI
- Shared core library between two applications (DRY principle)
- MVC-style in editor:
- Model = scene data (via parser)
- View = table widget, 2D minimap, 3D preview
- Controller = PyQt5 event handlers
- Real-time game loop in simulator:
- Input → Update (physics, camera) → Render (3D + HUD)
- Resource caching layer in Texture Loader

d. Key technologies & frameworks
- Python 3.x
- Pygame + PyOpenGL for simulation window & rendering
- PyQt5 for scene editor GUI
- NumPy/Numba for performance in geometry/physics calculations
- Pillow for image loading in minimap/editor

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Applications
    subgraph "Applications"
        direction TB
        SimulatorApp["Simulator Application\n(main.py)"]:::app
        EditorApp["Scene Editor Application\n(scene_editor.py)"]:::app
    end

    %% Core Modules
    subgraph "Core Library Modules"
        direction TB
        SceneParser["Scene Parser\n(scene_parser.py)"]:::core
        TrackGeometry["Track Geometry\n(track.py)"]:::core
        TrainPhysics["Train Physics\n(tram.py)"]:::core
        CameraController["Camera Controller\n(camera.py)"]:::core
        Renderer3D["3D Renderer\n(renderer.py)"]:::core
        MinimapRenderer["2D Minimap Renderer\n(minimap_renderer.py)"]:::core
        TextureLoader["Texture Loader\n(texture_loader.py)"]:::core
    end

    %% Data & Config
    subgraph "Data & Config"
        direction TB
        SceneFile["scene.txt"]:::data
        Textures["textures/"]:::data
        EditorSettings["editor_settings.json"]:::data
        README["README.md"]:::data
    end

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        PyGameOpenGL["Pygame + PyOpenGL\n(Rendering)"]:::ext
        NumPyNumba["NumPy + Numba\n(Calculations)"]:::ext
        PyQt5["PyQt5\n(GUI)"]:::ext
        Pillow["Pillow\n(Image I/O)"]:::ext
    end

    %% Relationships: Simulator
    SimulatorApp -->|"parse scene.txt"| SceneParser
    SceneParser -->|"scene graph"| TrackGeometry
    SceneParser --> TrackGeometry
    SceneParser --> TrainPhysics
    SceneParser --> CameraController
    SceneParser --> Renderer3D
    SceneParser --> MinimapRenderer
    SceneParser --> TextureLoader

    SimulatorApp -->|"physics update"| TrainPhysics
    SimulatorApp -->|"camera update"| CameraController
    SimulatorApp -->|"render frame"| Renderer3D
    SimulatorApp -->|"draw HUD"| MinimapRenderer

    TrainPhysics --> NumPyNumba
    TrackGeometry --> NumPyNumba
    CameraController --> NumPyNumba
    Renderer3D --> PyGameOpenGL
    MinimapRenderer --> Pillow
    TextureLoader --> PyGameOpenGL

    TextureLoader -->|"load/cache textures"| Textures
    Renderer3D -->|"use textures"| TextureLoader

    %% Relationships: Editor
    EditorApp -->|"load scene.txt"| SceneParser
    SceneParser -->|"model data"| EditorApp
    EditorApp -->|"2D preview"| MinimapRenderer
    EditorApp -->|"3D preview"| Renderer3D
    EditorApp -->|"save scene"| SceneFile
    EditorApp -->|"save settings"| EditorSettings
    EditorApp --> PyQt5

    %% Data & Docs
    EditorApp --> README

    %% Click Events
    click SimulatorApp "https://github.com/pondahai/train_sim/blob/main/main.py"
    click EditorApp "https://github.com/pondahai/train_sim/blob/main/scene_editor.py"
    click SceneParser "https://github.com/pondahai/train_sim/blob/main/scene_parser.py"
    click TrackGeometry "https://github.com/pondahai/train_sim/blob/main/track.py"
    click TrainPhysics "https://github.com/pondahai/train_sim/blob/main/tram.py"
    click CameraController "https://github.com/pondahai/train_sim/blob/main/camera.py"
    click Renderer3D "https://github.com/pondahai/train_sim/blob/main/renderer.py"
    click MinimapRenderer "https://github.com/pondahai/train_sim/blob/main/minimap_renderer.py"
    click TextureLoader "https://github.com/pondahai/train_sim/blob/main/texture_loader.py"
    click README "https://github.com/pondahai/train_sim/blob/main/README.md"

    %% Styles
    classDef app fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
    classDef ext fill:#D3D3D3,stroke:#333,stroke-width:1px
```
