A deterministic, interactive grid simulation environment for model-driven 2D experiments.
World-Simulator is a standalone, portable application for simulating complex physical and ecological systems on structured grids. The core principle is strict decoupling between simulation logic (the model package) and dynamic system state (world/profile/checkpoint data).
This separation supports reproducible experiments across machines when model identity, configuration, and seed are preserved.
- Researchers and Scientists: A testing environment for physical, ecological, economic, and other hypotheses
- Educators and Students: A pedagogical tool for interactively visualizing complex phenomena
- Game Developers: A simulation backend for procedural content generation and physics visualization
- Engineers and Modelers: A rapid prototyping platform for computational models
- Multi-Physics Simulation: Support for diverse simulation types including fluid dynamics, reaction-diffusion systems, ecological models, atmospheric science, urban climate, and more
- Interactive Runtime: Real-time parameter modification, perturbation injection, and live visualization
- Model Editor: Graph-oriented visual+text authoring surface with package round-trip verification and integrated validation
- World Generator: Procedural terrain and state initialization using Perlin/Simplex/Worley/Wavelet noise
- Checkpoints & Replay: Runtime checkpoints, event logging, replay support, and per-variable checkpoint cadence policies (e.g., persist A every 50 steps, B every 200, freeze unspecified variables)
- Live Patching: Modify simulation parameters and inject perturbations during runtime
- Strictly Typed IR: High-performance Intermediate Representation for simulation logic
- Domain Constraints: Physical validity checks and automatic clamping
- Time Integrators: Built-in registry entries include
explicit_euler,rk2_midpoint,rk3_heun,semi_implicit_euler,velocity_verlet,crank_nicolson, andrk4(with legacy-friendly aliases such asEuler Explicit,RK2,Verlet, andRK4); the active integrator can be switched live at runtime and is persisted in saved profiles/worlds. - Spatial Operators: Laplacian, gradient, advection, diffusion with configurable schemes
- Simulation logic: All physics subsystems execute on CPU only to ensure bit-exact reproducibility across platforms and runs
- Rendering: GPU-accelerated visualization (OpenGL) for real-time heatmap, vector, and contour display
- Shader editing: Experimental GLSL editor for custom visualization rules; shader code affects display only, not simulation stepping
- GPU compute for logic: Planned future optimization (not current baseline). GPU compute paths would require explicit opt-in and determinism verification against CPU results.
This architecture prioritizes reproducible research and debugging over raw throughput. Performance optimizations use CPU vectorization (SIMD, OpenMP) and memory-access patterns.
The project ships with several pre-configured simulation models:
- Conway's Game of Life - Classic cellular automaton
- Gray-Scott Reaction-Diffusion - Chemical pattern formation
- Environmental Model 2D - Atmosphere, hydrology, and biosphere
- Coastal Biogeochemistry - Estuarine ecosystem and transport
- Urban Microclimate - City-scale thermo-hydrologic dynamics
| Requirement | Minimum Version | Notes |
|---|---|---|
| C++ Compiler | C++20 capable | GCC 11+, Clang 15+, MSVC 2022+ |
| CMake | 3.20+ | Build system |
| OpenGL | 3.3+ | For GUI rendering |
| GLFW | 3.4+ | Window management (fetched) |
| Git | Any recent | For version control |
- Windows 10/11 (Primary - tested)
- Linux (Supported)
- macOS (Supported, requires X11 or Cocoa)
git clone https://github.com/wartets/World-Simulator.git
cd World-Simulatormkdir build && cd build# On Windows (CMake GUI or command line)
cmake .. -G "Visual Studio 17 2022" -A x64
cmake --build . --config Release
# On Linux/macOS
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j$(nproc)For multi-threaded simulation performance:
cmake .. -DWS_ENABLE_OPENMP=ON -DCMAKE_BUILD_TYPE=Release
cmake --build . -j$(nproc)After building, you will have:
world_sim- Command-line simulation runtimeworld_sim_gui- Interactive GUI application
From the configured build directory, package artifacts can be generated with CPack:
- Windows: ZIP package is always produced; NSIS installer is produced when
makensisis available. - Linux/macOS: ZIP package is produced.
Installed package layout includes:
bin/executables (world_sim_gui,world_sim)models/built-in model packages- top-level
LICENSEandREADME.md
Release diagnostics:
- Windows (MSVC): packaged builds include
.pdbsymbol files (Release/RelWithDebInfo) alongside executables. - GUI crash diagnostics write timestamped reports under per-user settings storage:
- Windows:
%APPDATA%/WorldSimulator/crash_reports/ - Linux:
${XDG_CONFIG_HOME:-~/.config}/WorldSimulator/crash_reports/ - macOS:
~/Library/Application Support/WorldSimulator/crash_reports/
- Windows:
On Windows NSIS builds, uninstallation is provided by the generated installer and removes installed application-managed files while preserving user settings/data stored outside the install directory.
Windows NSIS builds also register per-user file associations for:
.simmodel(model package).wscp(checkpoint).wsexpand.wsworld(world export/import package)
Double-click shell-open for those extensions launches world_sim_gui and routes through the same startup parser used by explicit CLI arguments.
Launch the graphical interface:
# Windows
./build/Release/world_sim_gui.exe
# Linux/macOS
./build/world_sim_guiThe GUI executable accepts startup arguments for model/world/checkpoint workflows:
--model <path>: select model scope and open Session Manager.--edit-model <path>: open model directly in Model Editor.--world <name>: open stored world by name (uses current or--modelscope).--import-world <path>: import exported world package and open it.--checkpoint <path>: start runtime and restore a checkpoint file.--open <path>or positional<path>: route by extension:.simmodel→ Model Editor.wscp→ Checkpoint loader.wsexp/.wsworld→ World import + open
# Run with a specific model
./build/world_sim --model models/game_of_life_model.simmodel --grid 128x128
# Run the environmental model
./build/world_sim --model models/environmental_model_2d.simmodel --steps 1000- Open
world_sim_gui - Select Model Editor from the main menu
- Create new variables (state, parameter, derived, forcing)
- Define interactions between variables
- Save the model as
my_model.simmodel - Generate a world using the World Generator
- Run and observe the simulation
World-Simulator has multiple persistence layers. Understanding these layers avoids accidental data loss and improves reproducibility.
| Change type | Typical effect | Persisted automatically | Notes |
|---|---|---|---|
| Playback controls (play/pause/step/seek) | Immediate runtime control | No | Affects current runtime session state only |
| Runtime parameter edits / manual patches | Immediate or next-step runtime effect | No | Save world/checkpoint/event log to retain changes |
| Wizard generation settings | Applied at world creation | No | Applies to newly created world, not already-running world |
| Display/viewport preferences | UI behavior/rendering | Session/display prefs | May be stored separately from world state |
| Checkpoint creation | Snapshot of runtime state | Yes (checkpoint storage) | Supports deterministic scrubbing/replay workflows |
| Save active world | Writes world/profile data | Yes | Use before switching model/state to avoid losing in-memory changes |
- Profile: configuration metadata and runtime-facing settings for a world.
- Checkpoint: concrete state snapshot at a simulation step.
- Saved world: world identity plus associated persisted artifacts.
- Event log: intervention history for replayable operations.
Resume behavior depends on available artifacts (checkpoint-backed resume vs profile-only regeneration).
The model editor provides graph editing, package authoring, and validation loops suitable for end-to-end .simmodel workflows.
- Save/export writes packaged
.simmodelarchives. - Save/export performs package round-trip verification by reloading and validating required payloads (
model.json,logic.ir, compiled model binary) before reporting success. - Undo/redo restores serialized graph snapshots captured in the editor history.
- Validation includes syntax, units, structure, and dependency checks for undeclared formula identifiers.
Use this flow for normal authoring when your model package requirements align with the current runtime scope.
An in-app guided onboarding tutorial is available from:
Shift+F1(direct tutorial launch)F1shortcut help modal via Start guided onboarding
The tutorial provides step-by-step guidance across model selection, world setup, wizard preflight, runtime controls, and persistence workflow. Each step includes a Take me there action to jump to the recommended UI state.
An experimental GLSL shader editor is available for advanced rendering customization:
- Sandboxed compilation: Shaders are validated before execution with security constraints (no file I/O, max complexity/uniform limits).
- Live preview mode: Enable real-time shader compilation and preview without requiring restart.
- Error recovery: Failed shader compilations automatically revert to the last known-good version.
- Resource detection: Uniforms and attribute bindings are automatically detected and listed.
- Limitations: Current implementation focuses on fragment/vertex shader validation; advanced features (geometry shaders, compute shaders) are not yet supported.
The shader editor is provided as an experimental pathway; production use should be validated with your specific rendering requirements.
- Supported formats: CSV, PGM image (
P2/P5), GeoTIFF (requires GDAL, optional), NetCDF (requires NetCDF C++, optional). - CSV: Comma-separated numeric grid data.
- PGM: Portable Graymap image format (both ASCII
P2and binaryP5modes). - GeoTIFF: Geospatial tagged image format (build with
-DWS_ENABLE_GEOTIFF=ONif GDAL is available). - NetCDF: Network Common Data Form (build with
-DWS_ENABLE_NETCDF=ONif NetCDF C++ is available). - Imported grids are automatically resampled to match model dimensions and normalized to parameter domain ranges.
F1is reserved for global help/shortcut reference.- Prefer avoiding
F1for custom viewport-local bindings to prevent context conflicts.
- Runtime and model tooling continue to accept practical unit expressions.
- Validation now flags derived-unit aliases (for example
Pa,N,J) and suggests SI base-unit expansions. - Preferred authoring format in model files is explicit SI base units (for example
kg/(m*s^2)instead ofPa).
| Model | Description | Complexity |
|---|---|---|
| Game of Life | Conway's classic cellular automaton | Tier 1 |
| Gray-Scott RD | Chemical reaction-diffusion patterns | Tier 2 |
| Environmental 2D | Atmosphere, hydrology, biosphere | Tier 3 |
| Coastal Biogeochemistry | Estuarine ecosystem dynamics | Tier 3 |
| Urban Microclimate | City-scale climate modeling | Tier 4 |
Each .simmodel package contains:
model.json- Variable definitions and stage graphlogic.ir- Intermediate Representation computationsmetadata.json- Model metadata and author informationversion.json- Format and engine version compatibility
Define your simulation by specifying:
- Grid Configuration: Dimensions, topology, boundary conditions
- Variables: State, parameter, derived, and forcing types
- Domains: Physical validity constraints (min/max intervals)
- Stages: Ordered execution stages for one timestep
- Interactions: Mathematical logic in IR format
Current runtime scope is 2D Cartesian. Model compilation accepts grid.dimensions as either two explicit extents (for example [256, 256]) or legacy scalar 2; higher-dimensional declarations are rejected with a validation error.
Global runtime boundary modes currently support clamp, wrap, and reflect (including common aliases such as periodic, fixed, dirichlet, neumann, and reflecting).
Example variable definition:
{
"id": "temperature",
"role": "state",
"support": "cell",
"type": "f32",
"units": "K",
"domain": "temperature_physical"
}Example interaction:
// Simple diffusion interaction
@interaction(diffuse_temperature)
func diffuse_temperature() {
%temp = Load("temperature", 0, 0)
%lap = Laplacian("temperature")
%diff_coeff = GlobalLoad("diffusivity")
%dt = GlobalLoad("dt")
%change = Mul(%diff_coeff, %lap)
%delta = Mul(%change, %dt)
Store("temperature", Add(%temp, %delta))
}| Action | Control |
|---|---|
| Play/Pause | Space bar or button |
| Step Forward (paused) | Right Arrow |
| Step Backward | Ctrl + Left |
| State History | Alt + Left / Alt + Right |
| Shortcut Help | F1 |
| Time Jump | Timeline slider |
| Pan View | Middle mouse drag |
| Zoom | Scroll wheel |
world_sim [OPTIONS]
Options:
--model <path> Path to .simmodel file
--world <path> Path to world/state file
--grid <WxH> Grid dimensions (e.g., 256x256)
--steps <N> Number of steps to run
--output <path> Output checkpoint file
--profile <name> Runtime profile to use
--verbose Enable verbose logging
--help Show this help messageDuring runtime, you can:
- Modify global parameters: Double-click parameter in the panel
- Paint cell values: Available through viewport/world editing workflows where enabled
- Inject perturbations: Define forcing regions with the perturbation tool
- Create checkpoints: Save state at any timestep for later replay
- Manage checkpoints: Browse in-memory checkpoints, restore, rename, or delete them from the checkpoint panel
- Use native file pickers: Browse parameter presets and event logs through the OS file chooser when available
- Run guided analysis recipes: Use the Analysis tab to quickly set up global trend probes and checkpoint comparisons
- Use replay preflight: Review replayable vs skipped events, capture a baseline checkpoint, then replay compatible entries while paused
World-Simulator/
├── src/
│ ├── core/ # Simulation engine (IR, scheduler, runtime)
│ ├── app/ # High-level application (shell, storage)
│ └── gui/ # Graphical user interface
├── include/ws/ # Public API headers
├── models/ # Built-in simulation models
└── docs/ # Documentation
- Model-State Separation: Models define rules; state holds data
- Stage-Based Execution: Ordered computation stages per timestep
- Double Buffering: Read/write state isolation for parallelism
- Type Safety: Strict typing in IR prevents runtime errors
- Deterministic Runtime Contract: input patch ingestion → event queue apply → scheduler execution → state metadata/hash commit
- Language: C++20
- Build System: CMake 3.20+
- UI Framework: Dear ImGui
- Graphics: OpenGL 3.3+
- JSON Parsing: nlohmann/json
- Schema: FlatBuffers
- Compression: miniz
Contributions are welcome! Please read our guidelines before submitting.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- New simulation model implementations
- Performance optimizations
- GUI improvements and new visualizations
- Documentation improvements
- Bug fixes and test coverage
- Platform support enhancements
- Follow C++20 best practices
- Use the repository naming policy (types
PascalCase, functions/variablescamelCase, constantskPascalCase) - Add documentation for new features
- Ensure cross-platform compatibility
- Test thoroughly before submitting
For naming lint on project-owned C++ sources, enable clang-tidy during configuration:
cmake .. -DWS_ENABLE_CLANG_TIDY=ON
Identifier naming checks are configured in .clang-tidy.
This project is licensed under the MIT License - see the LICENSE file for details.
World-Simulator uses the following open-source libraries:
- Dear ImGui - Bloat-free immediate mode GUI
- GLFW - Window and input management
- nlohmann/json - JSON parsing
- FlatBuffers - Schema-based serialization
- miniz - ZIP file handling
- Google Test - Unit testing framework
- CMake - Build system