How yjplapian/joltphysics works
Project Type and Purpose
• Jolt Physics is a high-performance, multi-threaded C++ physics and collision detection library targeted at games and VR applications.
• It provides rigid body simulation, collision detection (broadphase & narrowphase), constraints, soft bodies, vehicles, character controllers, water buoyancy, determinism, and a double-precision mode.
File Structure Overview
Top-level directories reveal a layered, modular architecture:
• Jolt/ → Core engine modules (Core, Math, Geometry, Collision, Physics, Constraints, SoftBody, Vehicle, Renderer, ObjectStream, Skeleton, etc.)
• Samples/ → Sample application showing engine features, using TestFramework and Jolt library.
• JoltViewer/ → A standalone viewer application for recording/playback of physics simulations.
• PerformanceTest/→ A console app that benchmarks engine performance.
• HelloWorld/ → Minimal example integrating Jolt via CMake FetchContent.
• UnitTests/ → Doctest-based unit tests validating each module.
• Assets/ → Runtime assets (fonts, shaders, terrains, models) consumed by TestFramework, Samples, and JoltViewer.
• Build/ → CMake scripts, platform wrappers, Gradle wrappers, and other build orchestration files.
• Docs/, README, CI configs, bindings, and integrations.
Key Architecture Insights from README
• The engine is built as a standalone library with no external dependencies beyond STL.
• Supports multiple platforms and CPU instruction sets via CMake build profiles.
• Emphasizes data-oriented, concurrent access to physics data (lock-free or minimal locking).
• A clear separation exists between simulation core and visualization/test harness.
Components
a. Core Library Module:
• Core (memory, job system, profiling)
• Math (vectors, matrices, curves)
• Geometry (hulls, GJK/EPA)
• Physics (Bodies, Scenes, Systems, Updates)
• Constraints & Motors
• SoftBody & Vehicle modules
• ObjectStream (serialization)
• Renderer hooks (DebugRenderer)
b. TestFramework Module:
• Windowing & Input (Win/Linux/macOS)
• Renderer backends (DX12, Vulkan, MTL)
• Debug UI & 2D primitives
• Asset loading (TGA/BMP, fonts)
c. Applications:
• SamplesApp
• JoltViewer
• PerformanceTest
• HelloWorld example
d. Assets:
• Fonts, shaders (HLSL/GLSL/Metal), terrains, meshes
e. Build System:
• CMake entry points, platform scripts (VS, Xcode, Ninja)
• Android/Gradle integration
• CI pipelines (GitHub Actions, SonarCloud, Doxygen)
f. Unit Tests:
• Modules tested via TestFramework and doctest
Relationships and Data Flows
• Build System → compiles → Core Library + TestFramework + Applications + UnitTests
• Applications → link against → Core Library + TestFramework
• Applications → load → Assets
• UnitTests → link against → Core Library (isolated)
• CI/CD → orchestrates → Build System + runs tests + static analysis + docs generation
• External Bindings/Integrations (C#, Java, Rust, Godot plugin) → consume → Core Library API
Architectural Patterns & Principles
• Layered Architecture: Core engine → visualization/test framework → end-user applications.
• Modularization: Each domain in its own folder, clear module boundaries.
• Data-Oriented & Lock-Minimized: JobSystem, lock-free structures in Core.
• Platform Abstraction: Renderer, Input, Window separated by platform directories.
• Build-time Configuration: CPU feature switches, precision modes via CMake options.
• CI Integration: Automated builds across platforms, code quality gates.
Detail and Coverage
• Major modules (Core, Math, Geometry, Physics, Collision, Constraints, SoftBody, Vehicle, ObjectStream, Renderer).
• Platform-specific submodules under TestFramework (DX12, Vulkan, MTL).
• Don’t shy away from listing submodules if it aids clarity—this is a library designed for extensibility and multi-platform support.