If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/jrouwe/JoltPhysics shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit today
• 12 active contributors
• MIT licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 78% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live jrouwe/JoltPhysics repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/jrouwe/JoltPhysics.

What it runs against: a local clone of jrouwe/JoltPhysics — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in jrouwe/JoltPhysics | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of jrouwe/JoltPhysics. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/jrouwe/JoltPhysics.git
#   cd JoltPhysics
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of jrouwe/JoltPhysics and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "jrouwe/JoltPhysics(\\.git)?\\b" \\
  && ok "origin remote is jrouwe/JoltPhysics" \\
  || miss "origin remote is not jrouwe/JoltPhysics (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Build/CMakeLists.txt" \\
  && ok "Build/CMakeLists.txt" \\
  || miss "missing critical file: Build/CMakeLists.txt"
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"
test -f "Build/Android/PerformanceTest/src/main/cpp/CMakeLists.txt" \\
  && ok "Build/Android/PerformanceTest/src/main/cpp/CMakeLists.txt" \\
  || miss "missing critical file: Build/Android/PerformanceTest/src/main/cpp/CMakeLists.txt"
test -f ".clang-format" \\
  && ok ".clang-format" \\
  || miss "missing critical file: .clang-format"
test -f "Assets/Shaders/DX/TriangleVertexShader.hlsl" \\
  && ok "Assets/Shaders/DX/TriangleVertexShader.hlsl" \\
  || miss "missing critical file: Assets/Shaders/DX/TriangleVertexShader.hlsl"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/jrouwe/JoltPhysics"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Jolt Physics is a multi-threaded C++ rigid body physics engine and collision detection library optimized for game engines and VR. It emphasizes concurrent access to physics data during simulation—collision queries can run parallel to physics updates, and background threads can prepare/batch bodies without blocking the main simulation. It powers AAA titles like Horizon Forbidden West and Death Stranding 2. Monolithic single-repo structure: core physics simulation logic in the main source tree, with parallel Assets/ (animation skeletons, shaders for DX/Metal/Vulkan), Samples/ for demos, and build configuration via CMakeLists.txt and Android Gradle at src/main/cpp/CMakeLists.txt. Shader code separated by graphics API (Assets/Shaders/DX/, MTL/, VK/).

Game engine developers and VR application engineers who need a production-grade physics solver that doesn't serialize access to physics data; specifically those building on custom engines or integrating physics into multi-threaded game loops where lock-free concurrent queries are critical.

Production-ready and actively maintained. The project is battle-tested in AAA shipped titles, has comprehensive CI/CD (GitHub Actions workflows for build, determinism checks, Sonar Cloud code quality), and the monolithic C++ codebase (~5.9M LOC) shows signs of active development. The presence of platform-specific shaders (HLSL, Metal, GLSL) and Android/multi-ABI support indicates maturity.

Single maintainer (jrouwe) is a potential bus factor risk. The project is C++-heavy with deep platform coupling (SIMD, DX12, Metal, Vulkan paths) making cross-platform contributions non-trivial. No visible dependency manager (raw CMake build), so vendor lock-in to custom build setup. Breaking changes possible but mitigated by use in shipped products.

Active CI/CD pipeline with determinism validation, SonarCloud integration for code quality gates, and recent Android support (NDK 29.0.14206865, compileSdk 36, multi-ABI builds). The .github/workflows/ show ongoing investment in build stability and cross-platform testing.

Clone with git clone https://github.com/jrouwe/JoltPhysics.git, then for the main library: mkdir build && cd build && cmake .. && cmake --build .. For Android: use Android Studio with the Gradle build at the root, or gradlew build (compileSdk 36, C++17 via CMake integration). Requires CMake 3.22.1+.

Daily commands: For the library: cmake --build ./build --config Release or cmake --build ./build --config Debug. For Android: ./gradlew assembleDebug or ./gradlew assembleRelease. Samples likely run from ./build/samples/* on desktop. Check Docs/Samples.md for specific demo invocation.

• Build/CMakeLists.txt — Master build configuration orchestrating all platform targets (Windows, Linux, Android, macOS); any contributor touching compilation must understand this.
• .github/workflows/build.yml — CI/CD pipeline validating multi-platform builds across Windows, Linux, and Android; defines the contract for what 'building successfully' means.
• Build/Android/PerformanceTest/src/main/cpp/CMakeLists.txt — Android native build configuration with C++17 and JoltPhysics integration; critical for mobile platform support.
• .clang-format — Code style enforcement file; all contributors must format their C++ code to this standard to pass CI checks.
• Assets/Shaders/DX/TriangleVertexShader.hlsl — Core graphics rendering shader; fundamental to visualization of physics simulations across DirectX platforms.
• Build/cmake_vs2022_cl_cross_platform_deterministic.bat — Deterministic build configuration for cross-platform reproducibility; critical for matching behavior across platforms in games like Horizon Forbidden West.
• .gitignore — Build artifact exclusions and platform-specific ignores; ensures clean repository state and avoids committing generated binaries.

Add Support for a New Platform Target

1. Create a new CMake build script in Build/ following the pattern of existing platform scripts (Build/cmake_vs2022_cl.bat)
2. Add platform-specific C++ compiler flags and dependencies to the main CMakeLists.txt (Build/CMakeLists.txt)
3. Create a new GitHub Actions workflow job for the platform in build.yml (.github/workflows/build.yml)
4. Add platform-specific shaders if graphics rendering is required (e.g., new graphics API) (Assets/Shaders/DX/TriangleVertexShader.hlsl)
5. Run determinism check to ensure physics output matches across platforms (.github/workflows/determinism_check.yml)

Add a New Physics Test to Android Test Suite

1. Create test source files in Build/Android/UnitTests/src/main/cpp/ (Build/Android/UnitTests/src/main/cpp/CMakeLists.txt)
2. Link test executable to JoltPhysics library and set C++ standard to C++17 with physics debug flags (Build/Android/UnitTests/build.gradle)
3. Define test APK package structure and permissions in manifest (Build/Android/UnitTests/src/main/AndroidManifest.xml)
4. Add test execution step to Android build workflow (.github/workflows/build.yml)

Add Visualization Shaders for a New Graphics API

1. Create shader files in Assets/Shaders/{API}/ directory with vertex and pixel/fragment shaders (Assets/Shaders/VK/TriangleVertexShader.vert)
2. Include shared vertex constant definitions matching platform conventions (Assets/Shaders/VK/VertexConstants.h)
3. Create pixel/fragment shader with same io signature as vertex shader (Assets/Shaders/VK/TrianglePixelShader.frag)
4. Update build system to compile and embed new shaders (Build/CMakeLists.txt)

Configure Deterministic Physics Build for Game Shipping

1. Use the cross-platform deterministic build script to ensure reproducible physics across all target platforms (Build/cmake_vs2022_cl_cross_platform_deterministic.bat)
2. Verify build output matches across platforms using determinism check workflow (.github/workflows/determinism_check.yml)
3. Enable profile and debug renderer flags if needed for in-game diagnostics (Build/Android/PerformanceTest/build.gradle)
4. Review code formatting matches enforced standard to avoid compilation differences (.clang-format)

• C++17 — Modern systems language with zero-cost abstractions, SIMD support, and multi-threaded primitives required for high-performance physics at 60+ FPS across game platforms.
• CMake — Cross-platform build system enabling single source tree to target Windows (MSVC), Linux (GCC/Clang), macOS, Android (NDK), WebAssembly, and UWP with deterministic output.
• HLSL/GLSL/Metal Shaders — GPU compute kernels for graphics visualization (DirectX, Vulkan, Metal) to render physics bodies and debug information in real-time during game development.
• Android NDK + Gradle — Native performance on mobile platforms (arm64, ARMv7, x86) with seamless integration into Android ecosystem for VR applications.
• GitHub Actions CI/CD — Automated multi-platform builds and determinism validation ensuring physics output consistency across Horizon Forbidden West and Death Stranding 2 targets.

• Deterministic FP arithmetic (-ffp-contract=off across all platforms)
  • Why: Games like Horizon Forbidden West require identical physics behavior across console/PC/mobile platforms for networked play and consistent gameplay.
  • Consequence: Disables some FP optimizations, slight performance penalty (~5-10%), but guarantees reproducible collision and constraint solving.

Determinism is enforced across platforms (flag -DCROSS_PLATFORM_DETERMINISTIC=ON mandatory in Android build)—floating-point math must be reproducible or tests fail. SIMD intrinsics vary by platform; -ffp-contract=off disables FMA to ensure consistency. Debug renderer requires -DJPH_DEBUG_RENDERER flag; omitting it breaks sample visualization. No visible package manager—all deps must be pre-installed or vendored. C++17 required (hardcoded in build config).

• Lock-free concurrency in physics simulation — Jolt's core design allows queries and updates to run in parallel without serialization; understanding atomic operations and memory ordering is essential to contribute safely to the solver loop
• Broad-phase and narrow-phase collision detection — Jolt splits collision detection into coarse (broad-phase) and fine (narrow-phase) stages; design decisions here directly impact frame time and query latency in concurrent contexts
• Rigid body dynamics (RBD) and constraint solving — The core physics kernel solves ODEs for rigid body motion and applies constraints (joints, contacts); familiarity with Lagrangian mechanics and iterative solvers is required for core physics changes
• SIMD vectorization and platform intrinsics — Jolt heavily uses SSE/AVX (x86) and NEON (ARM) for performance; the -ffp-contract=off flag and cross-platform determinism settings enforce specific SIMD behavior to ensure reproducibility
• Deterministic floating-point computation — AAA games require bit-identical physics replay for netplay and debugging; Jolt's cross-platform determinism flag forces strict FP ordering, violating some compiler optimizations for reproducibility
• Job scheduling and work stealing — Multi-core friendly architecture implies Jolt batches and schedules physics work across threads; understanding how bodies and constraints are partitioned into jobs is key to performance tuning
• Batch insertion and background loading — Jolt allows preparing physics bodies on background threads and inserting in bulk; this pattern requires careful synchronization and is a novel design point vs. traditional physics engines

• bulletphysics/bullet3 — Long-standing competitor physics engine; Jolt's design explicitly addresses concurrency limitations in Bullet's lock-based architecture
• reactive-physics3d/react3d — Newer physics engine with similar multi-threading goals; relevant for comparing design tradeoffs in concurrent physics solvers
• google/filament — AAA-grade rendering engine that Jolt samples integrate with for visualization; Jolt shaders (HLSL/Metal/GLSL) target Filament-compatible pipelines
• google/benchmark — Performance measurement library likely used for Jolt's determinism and multi-core scaling validation in CI workflows
• godotengine/godot — Game engine that uses physics engines; Jolt is candidate drop-in replacement for Godot's physics, relevant for integration patterns

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add WebAssembly (WASM) build target and CI workflow

Jolt Physics is used in games and VR applications. WebAssembly is a critical platform for browser-based physics simulations and game engines like Babylon.js and Needle Engine. Currently, the repo has Android, DX, Metal, and Vulkan support but no WASM build configuration. This would unlock browser-based demos and increase adoption in web game development.

• [ ] Create Build/WASM directory with CMakeLists.txt configuration for Emscripten toolchain
• [ ] Add WASM-specific compiler flags (e.g., -s WASM=1, -s ALLOW_MEMORY_GROWTH=1) matching existing C++17 standards from Android config
• [ ] Create .github/workflows/build-wasm.yml CI workflow to test WASM builds on every commit (similar to build.yml structure)
• [ ] Add WASM-specific documentation in a new Assets/WASM/ directory with build instructions and basic browser example

Add performance regression detection CI using existing determinism_check.yml pattern

The repo already has determinism_check.yml workflow, showing commitment to reproducible physics. However, there's no automated performance regression testing. With multi-core optimization as a core feature, tracking benchmark performance across commits is critical. The Android PerformanceTest app exists but has no CI integration.

• [ ] Extend .github/workflows/build.yml to compile and run Build/Android/PerformanceTest benchmarks on Linux with CMake
• [ ] Create a benchmark result storage mechanism (e.g., JSON artifact) to track metrics like FPS, memory, and physics step time
• [ ] Add conditional failure logic: fail CI if performance degrades by >5% on core metrics (consistent with game engine standards)
• [ ] Document expected benchmark results in Build/Android/PerformanceTest/README.md with baseline numbers

Add comprehensive shader documentation and validation workflow

The repo contains shader files across three graphics APIs (DX, Metal, Vulkan) in Assets/Shaders/, but there's no validation, documentation, or lint workflow. Shader compilation errors can silently break rendering. Adding shader validation ensures cross-platform rendering stability for game integrations like Horizon Forbidden West.

• [ ] Create .github/workflows/validate-shaders.yml to compile all HLSL (DX), Metal, and GLSL (Vulkan) shaders using appropriate validators (fxc for HLSL, spirv-val for SPIR-V)
• [ ] Add shader compilation flags documentation in Assets/Shaders/README.md with per-API build instructions and version requirements
• [ ] Add pre-commit hook configuration (.husky/ or in build guide) to validate shaders before commits
• [ ] Document shader constant struct synchronization between Assets/Shaders/*/VertexConstants.h files to prevent graphics bugs

• Add unit tests for the Android NDK build path—currently no visible test/ directory in the file list; contributors could write CMake-based tests validating the cross-compilation toolchain and ABI targets (arm64-v8a, x86_64).
• Document the determinism flags (-DCROSS_PLATFORM_DETERMINISTIC, -ffp-contract=off) in a CONTRIBUTING.md with worked examples of why they matter; currently only visible in build configs, not in README or onboarding docs.
• Expand Assets/Shaders/VK/ GLSL coverage—Metal (MTL/) and DirectX (DX/) have feature parity, but Vulkan paths are sparse; porting one missing shader (e.g., TriangleDepthPixelShader) from HLSL would unblock Vulkan sample demo completeness.

The Jolt Physics codebase demonstrates good security practices overall with no critical vulnerabilities detected in the provided configuration. The project uses modern build tools, enables compiler warnings as errors, and maintains active CI/CD pipelines with code quality monitoring via SonarCloud. However, there are some medium-severity concerns related to Android SDK versions and low-severity issues around release build configuration. The C++ nature of the project mitigates common web-based vulnerabilities like SQL injection and XSS. No hardcoded secrets were detected in the analyzed files. Recommendations focus on updating to stable API levels, enabling code minification for release builds, and proper signing configuration management.

• Medium · Android NDK Version Potentially Outdated — Build/Android/PerformanceTest/build.gradle (ndkVersion = "29.0.14206865"). The build configuration specifies NDK version 29.0.14206865. While this is a relatively recent version, NDK versions can have security vulnerabilities. Regular updates should be monitored and applied when available. Fix: Monitor Android NDK security advisories and update to the latest stable version. Consider implementing automated dependency checking via Dependabot or similar tools.
• Medium · Android compileSdk and targetSdk Set to Latest Unstable Version — Build/Android/PerformanceTest/build.gradle (compileSdk = 36, targetSdk = 36). The build configuration uses compileSdk = 36 and targetSdk = 36, which may be a development/unreleased API level. Using unreleased API levels can introduce compatibility issues and potential security gaps. Fix: Use stable, officially released API levels. Consider targeting API 34 or the latest stable released version. Verify that API 36 is officially released before deploying to production.
• Low · Debug Signing Configuration in Default Build — Build/Android/PerformanceTest/build.gradle (signingConfig = signingConfigs.debug). The defaultConfig includes 'signingConfig = signingConfigs.debug' which applies debug signing to the default build. While this is common during development, it may be accidentally used in release builds if build configuration is not properly separated. Fix: Ensure that release builds use proper production signing credentials. Implement build variant-specific signing configurations and ensure debug signing is only used for debug builds.
• Low · Minify Not Enabled for Release Build — Build/Android/PerformanceTest/build.gradle (minifyEnabled = false in release block). The release build type has 'minifyEnabled = false', which means code obfuscation and optimization are disabled. This can make reverse engineering the application easier and potentially expose sensitive logic. Fix: Enable minification for release builds by setting 'minifyEnabled = true' and configure appropriate ProGuard/R8 rules to obfuscate code while preserving necessary functionality.
• Low · Multiple Architecture Support May Increase Attack Surface — Build/Android/PerformanceTest/build.gradle (ndk.abiFilters). The application supports multiple ABIs: 'arm64-v8a', 'armeabi-v7a', 'x86_64', 'x86'. While necessary for compatibility, this increases the number of compiled binaries that must be secured and maintained. Fix: Consider targeting only essential architectures (primarily arm64-v8a for modern devices). Ensure all binaries are built with consistent security flags and tested thoroughly.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.