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/bulletphysics/bullet3 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.

WAIT — Slowing — last commit 7mo ago

• Last commit 7mo ago
• 23+ active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 7mo ago
• ⚠ Concentrated ownership — top contributor handles 63% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{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 bulletphysics/bullet3 repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/bulletphysics/bullet3.

What it runs against: a local clone of bulletphysics/bullet3 — 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 bulletphysics/bullet3 | Confirms the artifact applies here, not a fork | | 2 | License is still Other | 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 ≤ 230 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of bulletphysics/bullet3. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/bulletphysics/bullet3.git
#   cd bullet3
#
# 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 bulletphysics/bullet3 and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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 "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "src/BulletCollision" \\
  && ok "src/BulletCollision" \\
  || miss "missing critical file: src/BulletCollision"
test -f "src/BulletDynamics" \\
  && ok "src/BulletDynamics" \\
  || miss "missing critical file: src/BulletDynamics"
test -f "src/LinearMath" \\
  && ok "src/LinearMath" \\
  || miss "missing critical file: src/LinearMath"
test -f "Extras/InverseDynamics" \\
  && ok "Extras/InverseDynamics" \\
  || miss "missing critical file: Extras/InverseDynamics"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 230 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~200d)"
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/bulletphysics/bullet3"
  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).

Bullet Physics SDK is a C++ real-time collision detection and rigid-body dynamics engine used in games, VR, robotics, and machine learning. It provides GPU-accelerated physics simulation via OpenCL and is also available as PyBullet, a Python binding for reinforcement learning and robotics research. Core capabilities include convex decomposition (Extras/ConvexDecomposition/), GIMPACT triangle mesh collision (Extras/GIMPACTUtils/), and multi-body rigid body simulation. Monolithic C++ library with modular extras: src/ contains core collision and dynamics, Extras/ contains optional features (ConvexDecomposition, BulletRobotics, GIMPACTUtils). Python bindings (PyBullet) wrap the C++ engine. Build system is CMake-based (CMakeLists.txt, BulletConfig.cmake.in) with support for Lua scripting (Extras/ConvexDecomposition/premake4.lua). CI/CD driven by .github/workflows/cmake.yml and Docker configs in .ci/docker/.

Game developers, roboticists, VR/AR engineers, and ML researchers who need fast physics simulation. PyBullet users specifically target reinforcement learning (deep_mimic examples), robot manipulation research, and visual effects pipelines. C++ users integrate it into engines or custom simulators.

Production-ready and actively maintained. The codebase is ~10M+ lines of C++, has CI/CD pipelines (GitHub Actions in .github/workflows/cmake.yml, Travis/AppVeyor badges), and is widely used in industry and academia. PyBullet has stable pip releases and documentation. The main issue tracker was closed due to volume, redirecting users to forums—a sign of popularity rather than abandonment.

Low technical risk for stable use cases, but moderate maintenance risk: Erwin Coumans appears to be the primary maintainer (single-maintainer risk visible in citation and repo structure). Issue tracker closure means community support is forum-based, not GitHub-tracked. GPU/OpenCL support is experimental and brittle (README warns of kernel compilation failures on some drivers). Dependency on legacy OpenGL 2/3 for demos may age poorly.

Active PyBullet and robotics focus visible in Extras/BulletRobotics/ and Extras/BulletRoboticsGUI/ directories. GitHub Actions workflow (cmake.yml) runs automated builds. Recent emphasis on reinforcement learning integration (deep_mimic examples) and VR/robotics use cases per README. No recent breaking changes visible in file structure, suggesting stable API maintenance.

git clone https://github.com/bulletphysics/bullet3.git
cd bullet3
mkdir build && cd build
cmake ..
make -j$(nproc)
# Or for Python bindings:
pip3 install pybullet --upgrade --user
python3 -c "import pybullet; print(pybullet.URDF_CACHE_EXPANSION_ENABLED)"

Daily commands:

# C++ examples (after build above):
./bin/App_ExampleBrowser
# Python PyBullet:
python3 -m pybullet_envs.examples.enjoy_TF_AntBulletEnv_v0_2017may
python3 -m pybullet_envs.deep_mimic.testrl --arg_file run_humanoid3d_backflip_args.txt
# Run tests:
ctest -j$(nproc)

• CMakeLists.txt — Root build configuration that defines the entire SDK compilation, linking, and library structure for all platforms.
• src/BulletCollision — Core collision detection algorithms and broadphase/narrowphase implementations—the foundation of the entire physics engine.
• src/BulletDynamics — Multi-body dynamics solver and constraint system that handles rigid body physics simulation and interactions.
• src/LinearMath — Vector/matrix mathematics and transform utilities used throughout the entire codebase for all physics calculations.
• Extras/InverseDynamics — Advanced robotics module providing inverse dynamics computations essential for robot control and manipulation workflows.
• Extras/ConvexDecomposition — Mesh decomposition utilities that convert complex geometry into convex shapes for efficient collision handling.
• .github/workflows/cmake.yml — CI/CD pipeline definition that validates builds across platforms—critical for understanding deployment and testing practices.

• Broadphase (btBroadphaseInterface) (Dynamic AABB tree, sorted axis sort, hash grid) — Maintains spatial acceleration structure (AABB trees, grid cells); detects potentially overlapping rigid body pairs without detailed collision testing
  • Failure mode: Slow culling → high false-positive pairs →

Add a new collision shape type

1. Define the shape class inheriting from btConvexShape or btConcaveShape in src/BulletCollision/CollisionShapes/ (src/BulletCollision/CollisionShapes)
2. Implement required virtual methods: getShapeType(), getMargin(), localGetSupportingVertex(), and batchedUnitVectorGetSupportingVertex() (src/BulletCollision/CollisionShapes/btCollisionShape.h)
3. Register the shape type ID in btBroadphaseProxy.h (src/BulletCollision/BroadphaseCollision/btBroadphaseProxy.h)
4. Add narrowphase algorithm in src/BulletCollision/NarrowPhaseCollision/ using existing dispatcher pattern (e.g., btSphereTriangleDetector) (src/BulletCollision/NarrowPhaseCollision)

Add a new constraint type for dynamics

1. Create a new constraint class inheriting from btTypedConstraint in src/BulletDynamics/ConstraintSolver/ (src/BulletDynamics/ConstraintSolver)
2. Implement getConstraintType() and getSerializationUid() for constraint identification (src/BulletDynamics/ConstraintSolver/btTypedConstraint.h)
3. Add jacobian and error calculation in buildJacobian() or getInfo2() depending on constraint type (src/BulletDynamics/ConstraintSolver)
4. Register constraint in the dynamics world via btDynamicsWorld::addConstraint() (src/BulletDynamics/Dynamics/btDynamicsWorld.h)

Integrate custom geometry file format (like URDF for robots)

1. Create a parser module in Extras/ (see Extras/InverseDynamics/btMultiBodyFromURDF.hpp for reference) (Extras)
2. Implement file reading and btRigidBody/btMultiBody instantiation from parsed data (Extras/InverseDynamics/btMultiBodyFromURDF.hpp)
3. Add serialization support in Extras/Serialize/ if persistence is needed (Extras/Serialize)
4. Extend CMakeLists.txt in Extras/ to include your new module as an optional library (Extras/CMakeLists.txt)

• C++ — High-performance real-time physics requires low-level memory control, SIMD intrinsics, and minimal GC overhead—essential for VR/games running at 60–120 Hz.
• CMake — Cross-platform build system supporting Windows, Linux, macOS, and mobile—eliminates platform-specific build files while maintaining single source of truth.
• Constraint-based solver (Sequential Impulse / LCP) — Scalable contact resolution that handles many interacting bodies; more stable than penalty methods for stiff constraints and joint limits.
• Broadphase spatial partitioning (AABB trees, hash grids) — Reduces O(n²) collision checks to near-linear; critical bottleneck optimization for scenes with hundreds of objects.

• Constraint-based rigid body dynamics over finite element (deformable) by default

  • Why: Rigid body simulation is 10–100× faster, suitable for real-time VR/games; deformable bodies via add-ons only.
  • Consequence: Cannot simulate cloth, soft tissue, or flexible deformation in main engine—requires external libraries.

• Single-threaded constraint solver core with optional parallel broadphase

  • Why: Constraint dependencies create data hazards; parallelizing the solver is complex and may not improve wallclock time.
  • Consequence: Throughput limited by CPU core performance; large scenes with 1000+ bodies may bottleneck on solver iterations.

• Convex-only narrowphase by default; triangle meshes via GIMPACT (slower) or compound shapes

  • Why: Convex collision is O(1) with GJK; arbitrary mesh collision requires expensive broad-to-narrow iteration.
  • Consequence: Complex non-convex geometry must be decomposed or approximated—adds preprocessing overhead.

• PyBullet Python bindings recommended over C++ API for ease-of-use

  • Why: Python reduces barrier to entry for robotics, RL, and prototyping; C++ used only when performance is critical.
  • Consequence: C++ API remains complex and underdocumented; most new users learn via PyBullet instead.

• Real-time deformable body simulation (cloth, soft-tissue) as primary feature—use Extras modules or external solvers
• GPU-accelerated physics on consumer GPUs—focus is CPU SIMD and multi-core, not CUDA/Metal
• Distributed/networked physics synchronization—designed for single-machine simulation
• Built-in visual rendering—physics only; rendering delegated to application or PyBullet visualizer

GPU/OpenCL: Kernel compilation is fragile; many drivers fail silently. Requires high-end discrete GPU (AMD 7970/NVIDIA GTX 680+); laptop GPUs often too slow or unsupported. Python: PyBullet wheel binaries may lag C++ releases; building from source requires SWIG. Demos: Graphical examples require OpenGL 2+ context; headless operation is available but not default. URDF parsing: Some edge cases with floating-base robots; test extensively before production. Licensing: Entire codebase is zlib EXCEPT individual folders marked differently (e.g., ConvexDecomposition has separate LICENSE.txt); verify before commercial use. Issue tracker: Closed and unmaintained; real support is only via pybullet.org forums, not GitHub Issues.

• Convex Decomposition — Games and physics engines use convex shapes for fast collision detection. Extras/ConvexDecomposition/ breaks arbitrary meshes into convex hulls; critical for asset pipelines and this repo's core value prop.
• SAP (Sweep and Prune) Broadphase — Bullet's default broad-phase collision algorithm; determines which object pairs to test for collision. Understanding SAP is essential for performance tuning in Bullet.
• GJK Algorithm (Gilbert-Johnson-Keerthi) — Narrow-phase collision detection used by Bullet for convex-convex distance/penetration queries. Core to physics accuracy and simulation stability.
• GIMPACT (Generic Integrated Mesh Processing via AABB Trees) — Bullet's triangle mesh collision system (Extras/GIMPACTUtils/). Allows static/dynamic mesh collisions without precomputation; alternative to convex decomposition.
• Constraint-Based Dynamics — Bullet solves rigid body dynamics via constraint solvers (src/BulletDynamics/ConstraintSolver/). Understands how joint limits, motors, and contact constraints are enforced.
• URDF (Unified Robot Description Format) — XML format for robot descriptions (parsed by Extras/BulletRobotics/). Essential for loading robot models in PyBullet and robotics research.
• OpenCL GPGPU Compute — Bullet can offload entire physics pipeline to GPU via OpenCL (src/Bullet3OpenCL/). Enables 100x+ speedup for large-scale simulations on compatible hardware.
• Quaternion Interpolation (SLERP) — Physics engines must smoothly interpolate rotations; Bullet uses quaternion-based rigid body state. Understanding SLERP avoids gimbal lock in animations/replay.

• erwincoumans/bullet2 — Predecessor to Bullet3; legacy version still used in some production systems, reference for API evolution
• openai/gym — OpenAI Gym is the standard RL environment interface; PyBullet environments (pybullet_envs/) are Gym-compatible wrappers
• gazebosim/gazebo-classic — ROS/robotics simulator that uses Bullet as optional physics engine; primary consumer for Extras/BulletRobotics features
• erwincoumans/pybullet-gym — Official PyBullet-only RL environments maintained separately; easier to use for ML than full Bullet3 repo
• deepmind/dm_control — DeepMind's physics-based RL framework that supports Bullet as backend; competitor and integration target

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 GitHub Actions workflow for Python/PyBullet binding validation

The repo has .github/workflows/cmake.yml for C++ builds but lacks automated testing for PyBullet Python bindings. Given that PyBullet is prominently featured in the README and recommended for users, a dedicated workflow would catch binding regressions early. This should validate Python package installation, import tests, and basic functionality across multiple Python versions.

• [ ] Create .github/workflows/pybullet.yml to test Python binding compilation and basic imports
• [ ] Add matrix strategy for Python 3.8, 3.9, 3.10, 3.11 versions
• [ ] Include pip install pybullet and validation script from examples/
• [ ] Reference existing Docker environments in .ci/docker/ for consistency

Add unit tests for Extras/ConvexDecomposition module

The ConvexDecomposition module in Extras/ lacks visible test coverage. With 20+ source files handling critical geometry operations (ConvexBuilder, bestfit algorithms, wavefront parsing, mesh volume calculations), regression tests would ensure stability. This is foundational for robotics and VR use cases mentioned in the README.

• [ ] Create test/ConvexDecompositionTest.cpp with test fixtures for ConvexBuilder.cpp operations
• [ ] Add tests for wavefront file parsing (cd_wavefront.cpp) with sample .obj files in test/fixtures/
• [ ] Test mesh volume calculations (meshvolume.cpp) against known geometries
• [ ] Update CMakeLists.txt in Extras/ConvexDecomposition/ to conditionally build tests when BUILD_TESTING=ON

Add docker-based CI validation script for robotics and machine learning examples

The repo has Docker environments in .ci/docker/ but the .ci/script.sh doesn't reference the Extras/BulletRobotics module that's critical for the stated use cases. Adding validation ensures robotics simulations and inverse dynamics (Extras/InverseDynamics) don't regress, especially important since the README highlights robotics and ML as key applications.

• [ ] Extend .ci/script.sh to compile and validate Extras/BulletRobotics/ and Extras/InverseDynamics/ builds
• [ ] Add smoke tests loading sample URDF files if available, or create minimal test URDFs
• [ ] Update .ci/docker/ubuntu-bionic and ubuntu-xenial env.list to include any additional robotics-specific dependencies
• [ ] Document the robotics validation steps in a new section of contributing guide

• Add unit tests for Extras/ConvexDecomposition/bestfitobb.cpp. Currently no dedicated test file exists; would catch regressions in OBB fitting used by asset pipelines.: Medium: Core utility used in many games/tools but has no test coverage
• Document the CMake build flags in README.md. The repo has BUILD_EXTRAS, BUILD_TESTING, BUILD_PYBULLET, BUILD_OPENGL3_CORE_PROFILE but no guide on which flags enable GPU, robotics, or Python. Create a configuration matrix.: Easy: Reduces confusion for contributors and users; purely documentation, no code changes needed
• Add OpenCL device fallback for CPUs in src/Bullet3OpenCL/. README states 'doesn't work on OpenCL CPU devices' but doesn't explain why. Investigate and either fix or add explicit CPU->CPU compute path with early return.: Hard: Unblocks GPU code for CI/testing on machines without discrete GPUs; significant impact on developer experience

The Bullet Physics SDK repository shows a reasonable security posture with proper license documentation for third-party code and organized build system. However, there are concerns around: (1) potential exposure of environment configuration in Docker files, (2) limited visibility into CI/CD security practices, (3) multiple third-party components requiring active maintenance and security monitoring, and (4) standard risks associated with C++ physics simulation code (buffer overflows, memory safety). The codebase lacks visible evidence of SAST/DAST integration, security policy documentation, or vulnerability disclosure procedures. Recommendation: Implement automated security scanning in CI/CD, maintain an SBOM, conduct regular security audits of third-party components, and establish a security.md file for responsible disclosure.

• Medium · Potential Insecure Docker Configuration — .ci/docker/env.list. Docker environment files (.ci/docker/env.list) are present but content not visible. These files may contain sensitive configuration or environment variables that could be exposed if not properly secured. Fix: Ensure .env and env.list files are added to .gitignore, never commit secrets, and use Docker secrets management or environment variable injection at runtime. Review the file contents to ensure no credentials, API keys, or sensitive data are stored.
• Medium · Third-Party Code Without Clear License Tracking — Extras/ subdirectories (ConvexDecomposition, HACD, GIMPACTUtils). Multiple third-party components (ConvexDecomposition, HACD, GIMPACTUtils) are included with their own LICENSE.txt files. While licenses are present, the integration and maintenance of these external libraries could introduce supply chain risks if not regularly updated for security patches. Fix: Establish a dependency management policy. Regularly audit third-party code for security vulnerabilities, maintain updated versions, and document the license compliance status. Consider using SBOM (Software Bill of Materials) tools.
• Low · Build Configuration Exposure via CMake — CMakeLists.txt, Extras/*/CMakeLists.txt. CMakeLists.txt and build configuration files are present throughout the repository. If the build process accepts untrusted input or user-controlled paths without validation, this could lead to local privilege escalation or arbitrary code execution during compilation. Fix: Validate all user-provided CMake variables and paths. Use CMake best practices for secure builds. Avoid executing arbitrary commands from user input during the build process.
• Low · CI/CD Pipeline Security Not Fully Visible — .github/workflows/cmake.yml, .ci/script.sh. GitHub Actions workflow (.github/workflows/cmake.yml) and CI scripts (.ci/script.sh) are present but contents not provided. These may contain security misconfigurations such as exposed secrets in logs, insecure artifact storage, or privilege escalation paths. Fix: Review CI/CD pipeline files for: 1) No secrets in logs, 2) Use of GitHub Secrets for sensitive data, 3) Minimal container privileges, 4) Signed artifacts. Enable branch protection and require code review for main branch.
• Low · Code Style Configuration File Present — .style.yapf. YAPF style configuration file (.style.yapf) exists but without content visibility. While formatting configs are generally low-risk, misconfigured linting could mask actual security issues. Fix: Ensure code style enforcement doesn't disable security-related linting. Use static analysis tools (clang-analyzer, cppcheck) in addition to style checks to catch potential vulnerabilities.

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.