Next-Generation Multi-Domain Physics Simulation Platform — v0.7.0
JaguarEngine is a high-performance physics simulation framework designed for defense modeling and simulation (M&S) applications. It supports Air, Land, Sea, and Space domains within a unified architecture, inspired by JSBSim's proven design patterns while leveraging modern C++20 capabilities.
- WebSocket scenario/combat/AAR server enhancements: mission planning, objective tracking, weapon engagement simulation, after-action review
- Benchmark suite and web dashboard:
tools/benchdash/for integrated benchmark visualization - Sanitizer and coverage build options:
JAGUAR_ENABLE_ASAN,JAGUAR_ENABLE_TSAN,JAGUAR_ENABLE_UBSAN,JAGUAR_ENABLE_COVERAGE - Telemetry library wired into build: Prometheus/OTLP metric export is now a first-class build target
- Bug fixes: per-entity integrator state isolation, NaN containment, event dispatcher re-entrancy, federation deadlock, DIS socket move, real UDP networking, thread pool races, GPU memory pool hangs, XR test failures
These features are in regular use and validated by the test suite:
- Multi-Domain Physics: Unified 6-DOF rigid body framework for Air, Land, Sea, and Space entities
- High Performance: Data-oriented SoA memory layout, SIMD optimization, work-stealing thread pool
- Advanced Integrators: RK4, ABM4, Symplectic Euler, Verlet, Adaptive Dormand-Prince (RK45), Boris
- Constraint System: Joint, distance, and angle constraints with split-impulse sequential-impulse solver
- Domain Models: US Standard Atmosphere 1976 + Dryden turbulence, Bekker-Wong terramechanics, MMG hydrodynamics, SGP4/SDP4 orbital propagation
- Event System: Thread-safe pub/sub event bus, type-safe dispatching, async and deferred events
- Python bindings (pybind11 2.13.6, NumPy interop): 123/123 tests passing; new APIs include
ecef_to_lla/lla_to_ecef,StandardAtmosphere/atmosphere_query,Engine.set_integrator,Engine.nan_containment_count, DIS codec (EntityStatePDU,dis_encode/dis_decode_entity_state) and more — and Lua bindings (sol2 v3.3.0) - GDAL terrain integration: GeoTIFF / HDF5 elevation data with bilinear interpolation
- DIS PDU codec: Real UDP networking implementing IEEE 1278.1-2012 Entity State and Fire/Detonate PDUs
- WebSocket server: Real-time simulation data streaming with scenario, combat, and AAR subsystems
- Telemetry: Prometheus and OTLP metric export (
src/telemetry/) - Property System: Reflection and introspection for runtime configuration
These subsystems exist in the codebase but are not yet production-ready:
- GPU compute backends (CUDA / Metal / Vulkan): Implemented but not yet wired into the main engine tick loop; must be explicitly enabled and tested per-platform
- ML inference (
JAGUAR_ENABLE_ML): Neural autopilot and RL environment use a mock ONNX inference engine; real ONNX Runtime integration is not yet complete - OpenXR (
JAGUAR_ENABLE_XR,JAGUAR_ENABLE_OPENXR): Interface layer and test scaffolding only; no shipping XR runtime integration - HLA federation (
JAGUAR_ENABLE_HLA): In-memory RTI stub; no connection to a vendor RTI (VTMaK, Pitch, etc.) - Cloud / K8s autoscaler (
JAGUAR_ENABLE_CLOUD): Stub HTTP client; no live Kubernetes integration - Unity / Unreal plugins: Scaffolding exists under
plugins/; not functional
- C++20 compatible compiler (GCC 11+, Clang 14+, MSVC 2022+)
- CMake 3.25+
- Eigen3 (auto-fetched if not found)
git clone https://github.com/jaguarcode/JaguarEngine.git
cd JaguarEngine
mkdir build && cd build
cmake ..
make -j$(nproc)./jaguar_unit_tests#include <jaguar/jaguar.h>
int main() {
using namespace jaguar;
// Create and initialize engine
interface::Engine engine;
engine.initialize();
// Create an aircraft entity
EntityId aircraft = engine.create_entity("F16", Domain::Air);
// Set initial state
physics::EntityState state;
state.position = Vec3{0.0, 0.0, -1000.0}; // 1000m altitude
state.velocity = Vec3{200.0, 0.0, 0.0}; // 200 m/s forward
state.orientation = Quat::Identity();
state.mass = 12000.0; // kg
engine.set_entity_state(aircraft, state);
// Run simulation loop
Real dt = 0.01; // 100 Hz
for (int i = 0; i < 1000; ++i) {
engine.step(dt);
}
engine.shutdown();
return 0;
}import jaguar
# Create and initialize engine
engine = jaguar.Engine()
engine.initialize()
# Create an aircraft entity
aircraft = engine.create_entity("F16", jaguar.Domain.Air)
# Set initial state
state = jaguar.EntityState()
state.position = jaguar.Vec3(0, 0, -1000) # 1000m altitude
state.velocity = jaguar.Vec3(200, 0, 0) # 200 m/s
state.mass = 12000.0
engine.set_entity_state(aircraft, state)
# Run simulation
for _ in range(100):
engine.step(0.01)
# Get final position
final = engine.get_entity_state(aircraft)
print(f"Final altitude: {-final.position.z:.1f} m")
engine.shutdown()local jag = require("jaguar")
-- Create and initialize engine
local engine = Engine()
engine:initialize()
-- Create an aircraft entity
local aircraft = engine:create_entity("F16", Domain.Air)
-- Set initial state
local state = EntityState()
state.position = Vec3(0, 0, -1000) -- 1000m altitude
state.velocity = Vec3(200, 0, 0) -- 200 m/s
state.mass = 12000.0
engine:set_entity_state(aircraft, state)
-- Run simulation
for i = 1, 100 do
engine:step(0.01)
end
-- Get final position
local final = engine:get_entity_state(aircraft)
print(string.format("Final altitude: %.1f m", -final.position.z))
engine:shutdown()#include <jaguar/jaguar.h>
int main() {
using namespace jaguar;
interface::Engine engine;
engine.initialize();
// Load terrain from GeoTIFF file
auto terrain = environment::Terrain::from_gdal("data/terrain/dem.tif");
engine.set_environment(terrain);
// Create vehicle entity
EntityId vehicle = engine.create_entity("Humvee", Domain::Land);
// Set position - suspension will automatically adapt to terrain
physics::EntityState state;
state.position = Vec3{100.0, 50.0, 0.0}; // Z will be set by terrain elevation
state.mass = 2500.0;
engine.set_entity_state(vehicle, state);
// Run simulation with terrain-aware physics
for (int i = 0; i < 100; ++i) {
engine.step(0.01);
}
engine.shutdown();
return 0;
}JaguarEngine/
├── include/jaguar/ # Public headers
│ ├── core/ # Core types, math, memory, threading
│ ├── physics/ # Entity management, forces, integrators, constraints
│ │ ├── integrators/ # RK4, ABM4, Symplectic, Verlet, Dormand-Prince, Boris
│ │ └── constraints/ # Joint, distance, and angle constraints
│ ├── domain/ # Domain-specific physics (air, land, sea, space)
│ ├── environment/ # Terrain, atmosphere, ocean, turbulence
│ ├── events/ # Event bus and type-safe dispatching
│ ├── gpu/ # GPU compute backends (CUDA, Metal, Vulkan)
│ ├── sensors/ # Sensor simulation (IMU, GPS, radar)
│ ├── xr/ # XR integration (OpenXR, spatial audio)
│ └── interface/ # API facade, configuration, scripting
├── src/ # Implementation
├── tests/ # Unit, integration, and GPU tests
├── examples/ # Example applications
│ ├── frontend/ # React/Cesium visualization frontend
│ └── server/ # WebSocket server for real-time data
├── docs/ # Documentation
└── data/ # Configuration files and models
| Document | Description |
|---|---|
| Architecture | System design and component overview |
| Installation | Build instructions and dependencies |
| API Reference | Complete API documentation |
| Examples Guide | Walkthrough of example code |
| Configuration | XML configuration reference |
| Module | Description |
|---|---|
| Core | Types, math, memory, property system |
| Physics | Entity management, integrators, constraints |
| Air Domain | Aerodynamics, propulsion, flight control |
| Land Domain | Terramechanics, suspension |
| Sea Domain | Hydrodynamics, buoyancy, waves |
| Space Domain | Orbital mechanics, SGP4 |
| Environment | Terrain, atmosphere, ocean, turbulence |
| GPU Compute | CUDA/Metal/Vulkan backends, hybrid physics |
| XR Integration | OpenXR, spatial audio, haptics, motion platform |
| Sensors | IMU simulation, noise models, failure modes |
| Events | Event bus, dispatching, threshold monitoring |
| Cloud | Distributed simulation, auto-scaling |
| Federation | DIS/HLA protocols, network transport |
| Digital Thread | Lifecycle management, history, degradation |
| Machine Learning | ONNX inference, neural autopilot, RL env |
| Language | Documentation | Description |
|---|---|---|
| Python | Full API reference | pybind11 bindings with NumPy support |
| Lua | Full API reference | sol2 bindings with table conversion |
- Coefficient-based aerodynamics with N-dimensional interpolation tables
- Turbofan/turbojet propulsion with altitude-Mach corrections
- Flight control system with rate limiting
- Bekker-Wong terramechanics for soil-vehicle interaction
- Spring-damper suspension with bump stops
- Tracked vehicle dynamics
- Buoyancy with metacentric height stability
- MMG (Maneuvering Mathematical Group) hydrodynamics
- Pierson-Moskowitz and JONSWAP wave spectra
- RAO-based ship motion response
- SGP4/SDP4 orbital propagation
- High-fidelity gravity models (J2, J4, EGM96)
- Atmospheric drag (JBH08 model)
1150+ tests across 100+ test suites
- Math: Vector, quaternion, matrix operations
- Physics: Entity state, force accumulation, integration
- Integrators: Symplectic Euler, Verlet, Dormand-Prince, Boris
- Constraints: Joint, distance, angle constraints
- Coordinates: ECEF, NED, ECI transformations
- Atmosphere: US Standard 1976 verification
- Air Domain: Aerodynamics, propulsion, flight control
- Land Domain: Terramechanics, suspension, tracked vehicles
- Sea Domain: Buoyancy, hydrodynamics, waves, RAO
- GPU: Compute backend validation, collision detection
- Events: Event bus, async dispatching
- XR: Session management, tracking, spatial audio
- Sensors: IMU, GPS, radar simulation
- Cloud: Partitioning, auto-scaling, state sync, distributed time
- Federation: DIS protocol, HLA RTI, network transport
- Digital Thread: Lifecycle, history store, degradation model
- Machine Learning: Inference, neural autopilot, RL environment
| Option | Default | Description |
|---|---|---|
JAGUAR_BUILD_TESTS |
ON | Build unit test suite |
JAGUAR_BUILD_BENCHMARKS |
ON | Build performance benchmarks |
JAGUAR_BUILD_EXAMPLES |
ON | Build example applications |
JAGUAR_BUILD_PYTHON |
OFF | Build Python bindings |
JAGUAR_BUILD_LUA |
OFF | Build Lua bindings |
JAGUAR_ENABLE_DIS |
OFF | Enable DIS network support |
JAGUAR_ENABLE_HLA |
OFF | Enable HLA network support |
JAGUAR_ENABLE_SIMD |
ON | Enable SIMD optimizations |
JAGUAR_ENABLE_CUDA |
OFF | Enable CUDA GPU acceleration |
JAGUAR_ENABLE_METAL |
OFF | Enable Metal GPU acceleration (macOS) |
JAGUAR_ENABLE_VULKAN |
OFF | Enable Vulkan compute |
JAGUAR_ENABLE_XR |
ON | Enable XR (VR/AR) support |
JAGUAR_ENABLE_OPENXR |
OFF | Enable OpenXR runtime |
JAGUAR_ENABLE_CLOUD |
ON | Enable cloud/distributed simulation |
JAGUAR_ENABLE_THREAD |
ON | Enable Digital Thread support |
JAGUAR_ENABLE_ML |
ON | Enable Machine Learning support |
JAGUAR_ENABLE_ASAN |
OFF | AddressSanitizer (mutually exclusive with TSAN) |
JAGUAR_ENABLE_TSAN |
OFF | ThreadSanitizer (mutually exclusive with ASAN) |
JAGUAR_ENABLE_UBSAN |
OFF | UndefinedBehaviorSanitizer |
JAGUAR_ENABLE_COVERAGE |
OFF | Code coverage (--coverage) |
| Library | Version | Purpose | Required |
|---|---|---|---|
| Eigen3 | 3.4+ | Linear algebra | Yes (auto-fetched) |
| pugixml | 1.14+ | XML parsing | Yes (auto-fetched) |
| GDAL | 3.0+ | Geospatial terrain | Optional |
| GoogleTest | 1.14+ | Testing | Auto-fetched |
| pybind11 | 2.13.6 | Python bindings | Optional (auto-fetched) |
| sol2 | v3.3.0 | Lua bindings | Optional (auto-fetched) |
| Lua | 5.4+ | Lua runtime | Optional (bundled) |
tools/benchdash/ is a web-based integrated benchmark dashboard and interactive engine testbed. The dashboard tab displays historical benchmark data, test pass/fail trends, and per-suite latency plots (reads Google Benchmark JSON and CTest XML). The Testbed tab lets you drive a live engine instance interactively via the Python bindings:
- Scenario presets:
multi_domain,air_patrol,orbit_demo, or custom entity mix - Play/pause/step controls and real-time time-scale adjustment
- Live entity table, altitude chart, and trajectory visualization
- Feature test panels: atmosphere profile, integrator comparison with divergence detection, DIS codec roundtrip with hex dump, NaN containment injection demo
- REST API
/api/testbed/*(contract v1); gracefully degrades whenpyjaguaris absent
Launch (standard — benchmark dashboard only):
python3 tools/benchdash/run_bench.pyLaunch (with interactive testbed — requires Python bindings):
cmake -DJAGUAR_BUILD_PYTHON=ON -B build && cmake --build build
python3 tools/benchdash/run_bench.py --serveSee CONTRIBUTING.md for development guidelines.
Copyright (c) 2026 JaguarEngine Contributors. All rights reserved.