How pondahai/train_sim works
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