MiniPhys is a small 3D rigid body physics engine written in C++17 (core) with Python bindings via pybind11. It’s meant for learning and experimentation: constraints (hinges), a simple iterative solver, and box-box collisions (AABB broadphase + SAT narrowphase).

• C++17 core using Eigen3 math
• Python package miniphys (compiled extension _miniphys)
• Hinge joints
• Box-box collision detection (OBB SAT) + impulse solver with friction
• Polyscope-based visualization demos (Python)

• Python 3.9+ (this repo is tested with Python 3.12)
• A C++ compiler toolchain
  • Windows: Visual Studio 2022 Build Tools (MSVC) recommended
• CMake 3.20+

Optional (for demos):

• polyscope (Python package)

Create and activate a virtual environment:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip

Install runtime dependencies and the package (builds the C++ extension):

python -m pip install numpy polyscope
python -m pip install -v --force-reinstall .

.\.venv\Scripts\python.exe -m unittest discover -s tests -p "test_*.py" -v

Demos live in the demo directory:

.\.venv\Scripts\python.exe .\demo\demo_pyramid.py
.\.venv\Scripts\python.exe .\demo\demo_wall_break.py
.\.venv\Scripts\python.exe .\demo\demo_chain.py
.\.venv\Scripts\python.exe .\demo\demo_box_chain.py

Pause/Resume in demo_box_chain.py:

• Click the Pause/Resume button, or press Space.

Each RigidBody is currently treated as an oriented box for collision:

• box_half_extents: half-size of the box (e.g. size (1,1,1) => half extents (0.5,0.5,0.5))
• rotation: quaternion stored as (w, x, y, z) in Python

The collision pipeline is:

1. Broadphase: compute AABBs for each box and test overlap
2. Narrowphase: SAT (15 axes) OBB-vs-OBB to produce a contact manifold
3. Solver: sequential impulses (normal + friction) + positional correction

Rebuild the native extension after changing C++:

.\.venv\Scripts\python.exe -m pip install -v --force-reinstall .