Kepler3D

Kepler3D is an experimental 3D rigid-body physics engine prototype focused on physical realism and CPU efficiency.

Project Status

This repository is an unreleased personal project that was never fully finished.

• Development status: archived/inactive
• Stability: research/prototype quality
• API status: unstable and not production-ready

The code is shared as a reference for architecture ideas, math/physics utilities, and collision/solver experiments.

Design Goals

• Model linear and angular rigid-body dynamics using classical mechanics.
• Keep simulation behavior physically motivated (no arcade-style damping hacks by default).
• Support multiple primitive shapes and contact generation.
• Organize simulation steps as explicit engine actions.
• Scale simulation work across CPU cores through a master/worker architecture.

Current Scope

Implemented components include:

• Math/types layer: vectors, matrices, quaternions, transforms, fixed-point abstractions.
• Physics core: force integration, manifolds, constraints, and contact/friction constraint types.
• Collision pipeline: broadphase/narrowphase structure and MPR-based collider implementation.
• Shapes: sphere, box, capsule, cylinder, convex hull.
• Engine architecture: scheduler, command/postulation model, worker orchestration.

Known limitations:

• Incomplete feature set and limited documentation.
• Public API and module boundaries still reflect work-in-progress decisions.
• Rendering demos/tests are experimental and intended for local validation.

Building

Kepler3D uses CMake (minimum 3.6) and C++17.

Configure + Build (library only)

cmake -S . -B out/build -DKEPLER3D_TESTS=OFF
cmake --build out/build --config Release

Configure + Build (with tests)

cmake -S . -B out/build-tests -DKEPLER3D_TESTS=ON
cmake --build out/build-tests --config Release

Run Tests

From the build directory:

ctest --output-on-failure

If you use a multi-config generator (for example Visual Studio), run:

ctest -C Release --output-on-failure

CMake Options

• KEPLER3D_TESTS: Build tests (default ON for top-level builds).
• KEPLER3D_WARNINGS_AS_ERRORS: Treat warnings as errors.
• KEPLER3D_USE_FIXED_POINT: Declared CMake option for fixed-point mode (currently not fully wired through compile definitions).
• KEPLER3D_DEBUG_BUILD: Use debug-oriented compile options.

Repository Layout

• src/: engine source code.
• include/: public include directory (currently minimal; Kepler3D.h is present as a placeholder).
• tests/: unit tests and rendering/engine experiments.
• externals/: vendored dependencies (for example Catch2).
• dependencies/: test/demo support libraries.

Name

The project is named in tribute to Johannes Kepler and his work on planetary motion.

License

Licensed under the zlib license. See LICENSE.

Acknowledgments

This project was strongly inspired by modern physics engine design work, especially Box2D by Erin Catto.