JaguarEngine Documentation¶

JaguarEngine

Next-Generation Multi-Domain Physics Simulation Platform

Overview¶

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.

### Multi-Domain Physics Unified framework supporting aircraft, ground vehicles, surface vessels, and spacecraft in a single simulation. ### High Performance Data-oriented design with Structure-of-Arrays (SoA) memory layout, SIMD optimization, and per-tick allocation elimination. GPU compute backends (CUDA, OpenCL, Metal) exist but are not yet wired into the engine loop — see the [feature matrix](../tools/benchdash.md). ### Accurate Models 6-DOF rigid body dynamics, US Standard Atmosphere 1976, Bekker-Wong terramechanics, MMG ship maneuvering, SGP4 near-Earth orbital propagation (validated to 6 sig figs vs Vallado). ### Distributed Simulation Complete IEEE 1278.1-2012 DIS protocol with real UDP transport. IEEE 1516-2010 HLA RTI interface — in-memory RTI only; no vendor RTI linked (Experimental). ### Machine Learning ML inference interface: stub only — no ONNX Runtime linked. Roadmap item. ### Cloud Native Auto-scaling cloud burst capability with distributed state synchronization, Raft consensus, and spatial partitioning for massively concurrent simulations. ### XR Ready Full OpenXR integration with spatial audio, haptic feedback, and training scenario management for immersive simulation experiences. ### Digital Thread Complete lifecycle tracking with history store, predictive degradation models, and physics-based failure prediction for digital twin applications. ### Scriptable Python and Lua bindings for rapid prototyping and integration with data science workflows.

Quick Links¶

Getting Started	Reference	Advanced
Installation Guide	API Reference	Architecture
Quick Start Tutorial	Configuration	Custom Models
First Simulation	Python API	Network Integration

Phase 7 Modules
Cloud Burst	Digital Thread	Machine Learning
Federation	GPU Compute	Sensors

Domain Overview¶

Air Domain¶

Coefficient-based aerodynamics with N-dimensional interpolation tables
Turbofan/turbojet propulsion with altitude-Mach corrections
Flight control system with rate limiting and autopilot

Learn more about Air Domain →

Land Domain¶

Bekker-Wong terramechanics for soil-vehicle interaction
Spring-damper suspension with bump stops
Tracked and wheeled vehicle dynamics

Learn more about Land Domain →

Sea Domain¶

Buoyancy with metacentric height stability
MMG (Maneuvering Mathematical Group) hydrodynamics
Pierson-Moskowitz and JONSWAP wave spectra
RAO-based ship motion response

Learn more about Sea Domain →

Space Domain¶

SGP4/SDP4 orbital propagation
High-fidelity gravity models (J2, J4, EGM96)
Atmospheric drag (JBH08 model)

Learn more about Space Domain →

Installation¶

# Clone the repository
git clone https://github.com/jaguarcode/JaguarEngine.git
cd JaguarEngine

# Build
mkdir build && cd build
cmake ..
make -j$(nproc)

# Run tests
./jaguar_unit_tests

Complete installation guide →

Basic Usage¶

#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, -10000.0};  // 10 km altitude
    state.velocity = Vec3{250.0, 0.0, 0.0};     // 250 m/s forward
    state.mass = 12000.0;
    engine.set_entity_state(aircraft, state);

    // Run simulation
    for (int i = 0; i < 1000; ++i) {
        engine.step(0.01);  // 100 Hz
    }

    engine.shutdown();
    return 0;
}

View more examples →

Project Status¶

Component	Status	Version
Core Engine	Production	0.7.0
Air Domain	Functional	0.7.0
Land Domain	Functional	0.7.0
Sea Domain	Functional	0.7.0
Space Domain (SGP4)	Functional	0.7.0
DIS Protocol (codec)	Production	0.7.0
DIS Protocol (network)	Functional	0.7.0
Thread Pool	Functional	0.7.0
Physics Integrators	Production	0.7.0
Events	Production	0.7.0
Digital Thread	Functional	0.7.0
Sensors (IMU)	Functional	0.7.0
GPU Compute (CPU backend)	Functional	0.7.0
GPU Compute (CUDA/Metal/OpenCL)	Partial — not wired	0.7.0
XR / OpenXR	Stub — interface only	0.7.0
Machine Learning	Stub — no ONNX Runtime	0.7.0
HLA Protocol	Stub — in-memory RTI	0.7.0
Cloud K8s autoscaler	Stub	0.7.0
Python Bindings	Functional	0.7.0
Lua Bindings	Functional	0.7.0

Test Coverage: 2213 / 2213 passing (v0.7.0)

What's New in v0.7.0¶

Stabilization & Performance Overhaul¶

JaguarEngine v0.7.0 is an audit-driven release that resolves foundational correctness and reliability problems discovered during a comprehensive codebase audit.

Stability - Per-entity integrator state: eliminates cross-entity state corruption in all multi-step integrators - NaN / Inf containment with automatic rollback to last valid state - Thread pool rewritten: six race classes eliminated, TSan-clean - GPU memory pool: two self-deadlocks fixed (21 test hangs eliminated) - Event dispatcher: snapshot-based dispatch eliminates use-after-free - Federation: orchestrator deadlock, DisSocket move-ctor race, and multicast close deadlock fixed - SGP4: five numerical corrections, validated to 6 significant figures vs Vallado

Performance - Dense EntityId-sorted active list replaces 3× unordered_map traversals - Per-tick allocations eliminated; lock-free terrain fast path - Geodetic Bowring capped at 2 iterations; LLA cached once per entity per tick - Parallel force stage (threshold: 64 entities); bit-identical to serial - Measured: 0.50 ms/step @100 entities, 0.64 ms/step @1 000, 4.9 ms/step @10 000 (Apple M3 Max)

Infrastructure - Version unified at 0.7.0 (was 3-way drift: 0.5.0/0.6.0/0.7.0) - 2213 tests registered and passing (30 previously orphaned tests fixed) - Real benchmark suite; ASAN/TSAN/UBSAN build options; CI hardened

See the full v0.7.0 Release Notes for details. - Model repository with versioning and A/B testing

Community & Support¶

GitHub Issues: Report bugs and request features
Discussions: Ask questions and share ideas
Contributing: Development guidelines

License¶

See LICENSE for details.