How wesleycramblitt/scientificsimulator works
Purpose and executable entry
This is a C++ game-engine-style simulation prototype centered on an ECS-like entity/component model, real-time graphics, and FluidX3D fluid simulation integration. The executable begins at app/main.cpp, which delegates application lifecycle orchestration to app/include/core/app.hpp and app/src/core/app.cpp. CMake is the build boundary in CMakeLists.txt.
Application lifecycle, window, and events
The core layer owns the interactive runtime: window creation, graphics-context-facing state, and per-frame event handling. app/include/core/window.hpp / app/src/core/window.cpp isolate platform/window behavior; app/include/core/event_state.hpp / app/src/core/event_state.cpp represent input/event state. Systems consume this state rather than owning window control directly.
Entity registry and component state
Simulation and renderable scene state are modeled as entities with composable components through app/include/entities/registry.hpp and app/src/entities/registry.cpp. Architecturally important component groups are transforms and selection (app/include/components/transform.hpp, app/include/components/selected.hpp), renderability/material technique selection (app/include/components/renderable.hpp, app/include/components/render_technique_lit.hpp), and fluid-domain/simulation state (app/include/components/fluid_domain.hpp, app/include/components/fluid_physics.hpp, app/include/components/fluidx3d_config.hpp).
Scene construction and asset ingestion
app/include/scene/scene_manager.hpp / app/src/scene/scene_manager.cpp form the scene-level boundary that likely creates and manages entity collections. Assets enter through app/include/assets/file_importer.hpp and app/src/assets/file_importer.cpp; mesh entities are populated/maintained by app/include/systems/mesh_asset_system.hpp and app/src/systems/mesh_asset_system.cpp. Built-in geometry follows a separate primitive path in app/include/systems/primitive_mesh_system.hpp and app/src/systems/primitive_mesh_system.cpp. Source models and cubemap images are local filesystem assets under assets/models and assets/cubemaps.
Simulation pipeline
FluidX3D is the concrete solver integration, isolated in app/include/systems/fluidx3d_system.hpp and app/src/systems/fluidx3d_system.cpp. It consumes fluid configuration/domain/physics components and writes simulation-associated entity state, including status/reference components (app/include/components/simulation_status.hpp, app/include/components/simulation_reference.hpp). Domain visualization/boundary handling is associated with app/src/systems/domain_box.cpp. Other solver categories described in the README are planned rather than represented as corresponding runtime systems.
Graphics resources and rendering
The graphics layer manages CPU-to-GPU resource boundaries: meshes via app/include/graphics/mesh_manager.hpp / app/src/graphics/mesh_manager.cpp, textures via app/include/graphics/texture_manager.hpp / app/src/graphics/texture_manager.cpp, and shaders via app/include/graphics/shader_manager.hpp / app/src/graphics/shader_manager.cpp. app/include/systems/render_system.hpp / app/src/systems/render_system.cpp is the frame rendering coordinator: it reads camera, transform, and render components and dispatches rendering techniques. Technique implementations cover Lambertian, reflections, cubemaps, particles, and volume ray marching, e.g. app/src/graphics/render_techniques/volume_render_technique.cpp, backed by GLSL in shaders/volume/ray_march.frag.
Interaction, editor controls, and frame-oriented systems
Camera/input control is separated into app/include/systems/camera_controller_system.hpp / app/src/systems/camera_controller_system.cpp. Scene editing and diagnostics are represented by ImGui and ImGuizmo systems (app/src/systems/imgui_system.cpp, app/src/systems/imguizmo_system.cpp) plus gizmo and grid systems (app/src/systems/gizmo_system.cpp, app/src/systems/grid_system.cpp). Cubemap and polygon-mode systems adjust rendering state independently (app/src/systems/cubemap_system.cpp, app/src/systems/polygon_mode_system.cpp).
Runtime dependencies and boundaries
The repository is a native CMake application with GPU rendering and shader assets; no remote backend, database, or network service is present in the tree. External numerical/GPU capabilities are implied by the FluidX3D integration and graphics context abstractions (app/include/graphics/graphics_context.hpp), but dependency acquisition details are not visible here. Tests focus on FluidX3D behavior (tests/test_fluidx3d.cpp, tests/test_lbm_direct.cpp).
Main entry points: app.cpp Application Lifecycle · registry.cpp Entity Registry · render_system.cpp Render System · fluidx3d_system.cpp FluidX3D System
Components 20
Application Runtime
- Executable Entry
app/main.cpp - Application Lifecycle
app/src/core/app.cpp - Window & Context
app/src/core/window.cpp - Event State
app/src/core/event_state.cpp - Camera Controller
app/src/systems/camera_controller_system.cpp - Editor & Diagnostics · ImGui, ImGuizmo, gizmo, and grid tooling.
app/src/systems/imgui_system.cpp
Scene & ECS
- Entity Registry · Owns composable entity and component state.
app/src/entities/registry.cpp - Scene Manager
app/src/scene/scene_manager.cpp - File Importer
app/src/assets/file_importer.cpp - Mesh Asset System
app/src/systems/mesh_asset_system.cpp - Primitive Mesh System
app/src/systems/primitive_mesh_system.cpp
Fluid Simulation
- Fluid Components · Domain, physics, FluidX3D configuration, status, and references.
app/include/components/fluid_domain.hpp - FluidX3D System
app/src/systems/fluidx3d_system.cpp - Domain Box
app/src/systems/domain_box.cpp
Graphics & Rendering
- Graphics Context
app/include/graphics/graphics_context.hpp - GPU Resource Managers · Transfers and manages render resources.
app/src/graphics/mesh_manager.cpp - Render System · Dispatches rendering techniques from ECS state.
app/src/systems/render_system.cpp - Volume Ray Marching
app/src/graphics/render_techniques/volume_render_technique.cpp - Volume Shader
shaders/volume/ray_march.frag
Other components
- CMake Build · Native application build boundary.
CMakeLists.txt
Connections 24
- CMake Build → Executable Entry: builds
- Executable Entry → Application Lifecycle: starts
- Application Lifecycle → Window & Context: creates
- Window & Context → Graphics Context: provides context
- Application Lifecycle → Event State: updates per frame
- Application Lifecycle → Scene Manager: orchestrates
- Scene Manager → Entity Registry: creates entities
- File Importer → Mesh Asset System: imports models
- Mesh Asset System → Entity Registry: populates mesh entities
- Primitive Mesh System → Entity Registry: adds built-in geometry
- Application Lifecycle → FluidX3D System: runs per frame
- FluidX3D System → Entity Registry: reads and writes state
- Fluid Components → FluidX3D System: configures solver
- FluidX3D System → Domain Box: updates domain view
- Camera Controller → Event State: consumes input
- Camera Controller → Entity Registry: updates camera
- Editor & Diagnostics → Entity Registry: edits and inspects
- Application Lifecycle → Render System: renders each frame
- Render System → Entity Registry: reads scene state
- Render System → GPU Resource Managers: uses GPU assets
- GPU Resource Managers → Graphics Context: uploads through
- Render System → Volume Ray Marching: dispatches
- Volume Ray Marching → Volume Shader: uses
- Render System → Graphics Context: draws through