How nortonv/bridge-simulation works
Projekt típusa és célja (amit a diagramnak tükröznie kell)
Ez egy lokális (desktop) Python/Pygame alkalmazás, ami egy 2D hídépítő editor + valós idejű statikai (FEM) szimulátor. Nincs klasszikus “backend/frontend” vagy hálózati komponens; a “rendszer” főleg moduláris game-loop + domain modell + solver + UI + audio + perzisztencia.
A következő top-level modulok természetes architekturális komponensek:
• Entry / App bootstrap
• src/main.py
• Core / Game state & world
• src/core/game_state.py
• src/core/grid.py
• src/core/constants.py
• src/core/material_manager.py
• src/core/serializer.py
• Domain entities (a “model”)
• src/entities/bridge.py
• src/entities/beam.py
• src/entities/agent.py (Ixchel karakter)
• Solver / Physics
• src/solvers/static_solver.py
• UI (editor + overlays + property menu + rendering)
• src/ui/editor.py
• src/ui/renderers.py
• src/ui/graph_overlay.py
• src/ui/property_menu.py
• src/ui/toolbar.py
• Audio
• src/audio/audio_manager.py + src/audio/assets/*
• Shared utilities
• src/utils/math_utils.py
• src/utils/render_utils.py
• Externalized data
• saves/*.json (bridge mentések)
• requirements.txt (pygame, numpy)
Fő futási ciklus (Game loop) – központi gerinc
Rajzold ki középre a Pygame loop-ot (implicit a main.py-ban), és bontsd 4 lépésre:
Render + Audio (képernyő + hang)
Ezt érdemes egy “App Runtime” dobozként ábrázolni, benne a loop-pal.
Build Mode vs Simulation Mode (két fő workflow)
A README alapján két domináns állapot van (SPACE vált):
• Build Mode:
• UI Editor (node/beam létrehozás, törlés, mozgatás, ív eszköz)
• Bridge modell módosul
• (Opcionális) “smart connection”: kereszteződésnél darabolás → ez tipikusan bridge.py/beam.py logika
• Simulation Mode:
• Agent (Ixchel) mozog → terhelési pont változik
• Solver fut → eredmények (N, M, U, ratio, buckling) visszaíródnak a modelbe vagy egy “results” struktúrába
• UI overlay nézetek (forces/material/stress) és feliratok ezekből renderelnek
A diagramon külön jelöld két “mode” dobozzal és nyilakkal, hogy ugyanazt a Bridge modellt használják, csak más műveletekkel.
Kapcsolatok és adatáramlás (nyilak, direction, “mi kitől függ”)
A legfontosabb kapcsolatok, amiket a diagramon kötelező megmutatni:
Core state mint Single Source of Truth
• main.py → tart egy GameState-et (core/game_state.py)
• GameState tartalmazza / hivatkozza:
• Bridge (entities/bridge.py) + benne Beams/Nodes (beam, implicit node struktúra)
• Agent (entities/agent.py)
• MaterialManager (core/material_manager.py) + globális beállítások (hőmérséklet, stb.)
• UI állapotok (aktuális tool, view mode, label mode, distortion factor)
Nyilak:
• UI/* → (events) → GameState / Bridge módosítás
• Solver/static_solver.py ← (Bridge geometry + materials + loads + temperatures) ← GameState
• Solver/static_solver.py → (displacements/forces/moments/ratios) → GameState/Bridge (vagy solver result cache)
• UI/renderers.py, UI/graph_overlay.py ← (Bridge + solver results + view flags) ← GameState
Perzisztencia (Save/Load)
• UI/editor.py (Ctrl+S / Ctrl+L) → core/serializer.py
• serializer.py ↔ saves/*.json
• serializer.py → Bridge rekonstruálása → GameState frissítése
Audio események
• UI/editor.py és/vagy GameState események (beam_place/break, step, theme) → audio/audio_manager.py → Pygame mixer + assets
Utils mint “leaf dependency”
• utils/math_utils.py és utils/render_utils.py tipikusan “alul” vannak:
• Solver és Entities használják a math_utils-t
• UI renderers használják a render_utils-t
Nyilak itt lefelé mutassanak (mindenki függ tőlük, ők senkitől).
Fontos architekturális minták/principles, amiket érdemes kiemelni a diagramon
• Layering (nem tökéletesen tiszta, de jól ábrázolható):
• UI / Presentation (src/ui)
• Domain Model (src/entities)
• Simulation/Computation (src/solvers)
• Application State/Services (src/core, src/audio)
• Utilities (src/utils)
• Single state object: a GameState a központi aggregator.
• Functional-ish solver: a static_solver egy elkülönített számítási pipeline (NumPy).
• Event-driven input: Pygame input → tool logika → model mutations.
Mit írj rá a diagramra technológiaként
• Python 3.8+
• Pygame: main loop, input, windowing, rendering, audio backend
• NumPy: globális merevségi mátrix / lineáris algebra (FEM)
• JSON: mentések (saves/*.json)
Javasolt 2 nézetet készíteni; mindkettő legyen részletes.
Dobozok és alcsoportok:
• App Runtime (main.py + Pygame loop)
• Core
• GameState
• Grid
• MaterialManager
• Serializer
• Entities
• Bridge
• Beam
• Agent
• Solver
• StaticSolver (FEM)
• UI
• Editor (tools)
• Renderers (bridge + deformation)
• PropertyMenu
• Toolbar
• GraphOverlay (distortion slider)
• Audio
• AudioManager + assets
• Utils
• math_utils
• render_utils
• Data
• saves/*.json
Nyilak (irányhelyes dependency):
• UI → Core/GameState
• Core/GameState → Entities
• Solver ↔ (Core/GameState + Entities) (input on one side, results on the other)
• UI/Renderers → Core/GameState (+ solver results)
• Serializer ↔ JSON files
• UI/Editor → AudioManager
• Solver → NumPy (külső dependency jelölés)
(2) “Runtime sequence / dataflow” (dinamikus működés)
Egy tipikus frame folyamatábra vagy szekvencia:
• Pygame event pump
• Editor tool interprets (Build: add/move/delete/arc; Sim: agent step)
• Update Bridge/Agent in GameState
• If sim_mode: call StaticSolver.solve(bridge, materials, loads, temps) -> results
• Update overlays (force view / stress ratio / labels)
• Render frame
• Trigger audio events (step, place, break)
A principal szintű “legpontosabb” diagramhoz legyenek következetes konvenciók:
• UI: kék
• Core/services: lila
• Entities/model: zöld
• Solver: narancs
• IO/Data (JSON, assets): szürke
• External libs (Pygame, NumPy): vastag keret vagy külön “External” sáv
• Nyíl típusok:
• Teljes vonal: code dependency / import
• Szaggatott: runtime dataflow / call
• Vastag nyíl: nagy adat (pl. “Solver results: U, N, M, ratios”)
• Címkézd az adatot a nyilakon:
• “geometry (nodes/beams)”
• “materials (E, rho, strength, thickness, hollow_ratio)”
• “loads (self-weight, agent point load), temperatures (T0, Tsim)”
• “results (displacements, axial forces, moments, stress/buckling ratios)”
• Mode állapot jelölése:
• GameState-ben legyen egy “BuildMode/SimMode flag” felirat, és UI/solver nyilak feltételesek (“only when sim_mode”).
Gyakori hiba ennél a projektnél (és hogyan kerüld)
• Ne rajzolj “backend”-et vagy hálózati API-t: ez single-process desktop app.
• Ne egy dobozba tedd a “physics”-et: különítsd el a Solver-t (stat_solver) az Entities-től (Bridge/Beam), különben nem látszik a FEM pipeline.
• A Save/Load legyen explicit: serializer.py + saves/*.json külön komponens, mert a felhasználói workflow része.