Fx2D — 2D Rigid Body Physics Engine

A 2D rigid body physics engine written in C++20, using SAT collision detection, XPBD constraint solving, and raylib for rendering.

Examples

Key Features

• Unified shape model: Circles, capsules, edges, chains (open polylines for level geometry), polygons, and rounded (skin-radius) rectangles and polygons, all stored as vertices[] + skin_radius and handled by one skin-aware SAT narrow phase
• Dynamic AABB broad phase: SAH-guided dynamic AABB tree with fat boxes and dual-tree pair descent
• Continuous collision: Opt-in speculative contacts (ccd: true) that anticipate impacts to curb tunneling for fast bodies
• XPBD constraint solver: Substepped position-based dynamics with compliance control, warm starting, and Coulomb friction
• Joints with motors: Revolute and prismatic joints with position / velocity / effort control modes and PID tuning
• Spatial queries: Ray casts, overlap and point queries sharing the simulation's own narrow phase, for line of sight, area effects, click-picking and RL observations
• Entity groups: Named sets managed as one thing — bulk delete/enable, restored by reset, and intra-group collision filtering via one integer per body
• Contacts, events, and sensors: Buffered contacts after each step, begin/end contact events, and trigger-only sensor entities
• Keyboard and mouse input: Renderer-agnostic input for gameplay code, with world-space cursor position and headless injection for scripted or agent-driven scenes
• Sleeping: Resting bodies fall asleep and stop consuming solver time until disturbed
• YAML based scene description: Declarative setup of entities, textures, and physics parameters in .yml files
• Headless mode: Build and run the physics core with no renderer, for testing, CI, and data collection
• FxArray & Math Utilities: NumPy-style FxArray and comprehensive linear-algebra utilities in Fx2D/Math.h
• raylib-based rendering: Lightweight, cross-platform renderer with raylib and ImGui integration

Dependencies

• CMake 3.16+ - Build system generator
• Eigen3 3.3+ - Linear algebra and math operations
• raylib 4.5+ - Scene rendering and graphics
• yaml-cpp - YAML parsing for scene configuration
• ImGui 1.92 - User interface framework
• rlImGui - Raylib-ImGui integration

Installation & Build

The repository keeps lib/imgui and lib/rlImGui as placeholder folders in Git, but it does not commit the third-party sources. Populate those folders locally before building.

Method 1: CMake

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

Method 2: Using fxmake

chmod +x fxmake       # Make executable
./fxmake              # Build in Release mode
./fxmake debug        # Build in Debug mode
./fxmake rebuild      # Clean and rebuild
./fxmake clean        # Clean build artifacts

Getting Started

Basic Usage

#include "Fx2D/Core.h"

int main() {
    // Load scene from YAML
    auto scene = FxYAML::buildScene("./Scene.yml");

    // Initialize renderer with 60 FPS target
    FxRylbRenderer renderer(scene, 60);
    
    // Start the simulation loop
    renderer.run();
    return 0;
}

For headless simulation, testing, or data collection. Include Fx2D/Physics.h instead of Fx2D/Core.h — it pulls in no raylib, Dear ImGui or rlImGui headers, so no graphics stack is needed at all.

#include "Fx2D/Physics.h"

int main() {
    // Load scene from YAML
    auto scene = FxYAML::buildScene("./Scene.yml");

    const double dt = 0.001f;             // Fixed time step in seconds
    auto ball = scene.get_entity("ball"); // Get the poiner to the entity by name "ball"
    for (size_t i = 0; i < 10; ++i) {
        scene.step(dt); // Advance physics without rendering
        std::cout<< ball->pose <<std::endl;  
    }
    return 0;
}

Running Examples

Build the visual examples from the repo root (textures live next to each example under examples/*/assets/):

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DFX2D_BUILD_EXAMPLES=ON
cmake --build build -j --target example_truck example_stacked_boxes example_joint_control
# run from the repo root so Scene.yml texture paths resolve
./build/example_stacked_boxes
./build/example_truck
./build/example_joint_control

Headless examples skip the graphics stack entirely:

./scripts/build_headless.sh
./build-headless/truck_headless        # run from the repo root
./build-headless/joint_control_demo

Available examples: stacked_boxes · truck · joint_control_demo — revolute and prismatic joint motor control (position, velocity, and effort modes) · angry_boxes — mouse-driven slingshot: drag the ball back, release, topple the tower · chain_terrain — chain collider terrain: click to drop balls and watch them settle

Documentation

Doc	Description
scene_yml.md	Full reference for writing Scene.yml files — scene block, entities, geometry types, physics fields
xpbd_solver.md	How the XPBD solver works — per-substep pipeline, constraint kernel equations, constraint types
collision_resolution.md	Collision detection and response — SAT narrow phase, penetration correction, restitution & friction
contacts_and_events.md	Reading contacts after a step, begin/end contact events, and sensor (trigger) entities
queries.md	Ray casts, overlap and point queries — line of sight, lidar fans, explosions, click-picking
simd_plan.md	The plan of record for vectorizing the solver — SoA gather/scatter, bulk loops, colored 8-wide velocity solve
entity_groups.md	Named entity sets — bulk operations, intra-group collision filtering, reset semantics, naming
input.md	Keyboard and mouse input for gameplay — renderer polling, world-space cursor, headless injection
raylib_renderer.md	Raylib renderer API — window setup, background, camera, draw callbacks
headless_mode.md	Running the simulation without a renderer for testing and data collection
joint_control.md	Joint motor API — revolute and prismatic joints, control modes (position/velocity/effort), PID tuning
math_utils.md	FxArray, vector/matrix math utilities, and helper functions

Contributing

Contributions are welcome — see CONTRIBUTING.md for the workflow, lint gate (./scripts/lint.sh), and how to run the test suite.

License

BSD-3-Clause License