How openchanter/ecosystems works
This is a single-process desktop simulation/game written in C#/.NET using a Raylib port (Vinculum) for 3D rendering + input + windowing. It simulates an ecosystem (fox/rabbit/bush + fluids like water) on a procedurally generated island, provides debug/UI menus, and can log simulation data that is later visualized by a separate Python plotting script.
So the “system” is not microservices; it’s best represented as:
• a runtime in-process architecture (game loop, simulation, rendering, input, UI, logging),
• plus an offline analysis pipeline (logs → Python/pandas/matplotlib).
What the file tree implies about architecture (map files → components)
Top-level C# sources indicate a compact codebase where major subsystems are split by domain:
• Program.cs
Likely entry point + main loop orchestration (spawning organisms, island generation, calling update/render). README explicitly says spawning is modified here.
• Engine.cs
Likely the core engine loop / orchestration layer: update ticks, timing, camera movement, input handling, scene management, rendering calls.
• Organism.cs
Entity + behavior: organism traits, stats (hydration/food), evolution, pathing targets (debug mentions pathing target), interactions (predation/herbivory).
• Fluid.cs
Fluid model (water) and hydration sources / interactions.
• shader/lit_vert.glsl, shader/lit_frag.glsl
Rendering pipeline assets: lighting shader used by models (README shows applying lit shader).
• plot/main.py
Offline visualization tool consuming logs produced by the simulation (pandas/matplotlib).
• .github/workflows/build.yml
CI: build & publish workflow (include in a “Dev/Delivery” view if desired).
• readme-resources/*
Documentation images (not runtime).
Goal: show what runs in-process, what external libraries are used, and major internal modules.
Ecosystems.exe (.NET process)
• Program (Entry / Bootstrap) — Program.cs
• Engine / Game Loop — Engine.cs
• World Generation (Island/Heightmap/Terrain) — likely inside Program.cs and/or Engine.cs (README mentions “random island generator” and groundHeightmap)
• Simulation / ECS-like domain (even if not formal ECS):
• Organism System — Organism.cs
• Fluid System — Fluid.cs
• Interactions (predation, eating, hydration) — likely within organism logic
• Rendering Subsystem
• Model/Texture Loader
• Shader Manager → uses shader/lit_*.glsl
• Input & Camera Controller (WASD, Space, Ctrl, Shift; click interaction)
• UI / Menus
• Main Menu (Tab)
• God Menu (click organism)
• Debug Overlay (stats above organisms, pathing target)
• Logging Subsystem
• Vinculum/Raylib (Rendering/Input/Window/Audio if used)
• Filesystem (for loading textures/models/shaders, and writing logs)
• Program → Engine.Start()/Run() (bootstrap)
• Engine Loop → Simulation.Update(dt) (control flow)
• Simulation → Logging.Append(metrics/events) (data)
• Input → Engine/UI and Input → Interaction (raycast/pick organism) (control + data)
• Shader Files (.glsl) → Shader Manager → Renderer (asset dependency)
• Models/Textures → Loader → Renderer/Organisms (asset dependency)
• Logging → Filesystem(log files) (output)
• Blue = control/orchestration (Program/Engine)
• Green = domain simulation (Organism/Fluid/WorldGen)
• Orange = rendering/assets (Shaders/Models/Textures)
• Purple = UI/Debug
• Gray = external dependencies (Raylib, filesystem)
Goal: show the most important truth of a simulation game: *the order of operations*.
UI Handling
• Tab menu toggles
• Click → selection → god menu actions (kill/feed/hydrate)
Simulation Step
• Update organisms (needs, traits, movement/pathing, interactions)
• Update fluids/resources
Present Frame
Goal: show the offline analysis workflow as a separate subsystem.
Components:
• Simulation Logging (C#) → produces Log Files
• Python Plot Tool (plot/main.py)
• pandas (ingest/transform)
• Graphs/Plots (output)
• C# Logging → log files → Python tool → plots
• log location (if known),
• log schema (metrics per tick? per organism? aggregate?).
Search for “logging” write points
• What triggers logging (menu toggle, always-on, debug).
• Document where logs are written and in what format.
Map organism lifecycle
• Spawn path (README: placeFeatures(...) in Program.cs)
• Update path (likely method on Organism)
• Interaction path (eat/hydrate/predation)
Rendering wiring
• Where shaders are loaded (reads shader/lit_*.glsl)
• Where models/textures are loaded (README shows example calls)
Input → interaction
• Left click: interaction + organism selection for god menu implies picking logic (raycast or bounding checks). Show this as a distinct “Selection/Interaction” component even if it’s just functions.
What to explicitly label
• File anchor: e.g., “Engine (Engine.cs)”
• Responsibility: one short line
• Key data it owns/produces:
• Organism list / traits
• Terrain heightmap
• Logs (metrics/events)
• Shader handles / model handles
• Key dependencies:
• “Uses Raylib API”
• “Reads shader/*.glsl”
• “Writes logs to disk”
Diagramming conventions (make it principal-engineer-grade)
• Boundaries
• One big boundary: “.NET Process: ecosystems”
• Outside boundary: “Vinculum/Raylib”, “Filesystem”, “Python runtime”
• Consistent naming
• Use the same terms as README: “God Menu”, “Debug mode”, “Logging Display”, “Island generator”.