bullet3 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: af2691fadab6e9aa49453e54a0bc963c73df2b7c82293e67e0182a7e1a05f340
+  data.tar.gz: 45dc19eac3c36b5158899a11c660a55a530032105bd0068571316440d9989991
+SHA512:
+  metadata.gz: 2ad7ad00f698746f663feeb81406b3527de59d4ed7fe1d4207323f7fd73ea76891e6feabab6e19c92abeef156dfc76e8ccbdb72196de6f5d3d07d33fa381937e
+  data.tar.gz: 6c4aabaf3d0be52b88780ba5e926bdd8fd126dde2703be573247d9bb2a1379fcd9870fc9dd244c6d6249b1ec1a66957634e0899da69c043ab8637b67e1b7abe1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,194 @@
+# bullet3
+
+Ruby bindings for the Bullet Physics SDK.
+
+This project exposes a two-layer API:
+
+- low-level Bullet3 C++ bindings exposed under `Bullet3`
+- Ruby-friendly helpers and simulation APIs built on top of those bindings
+
+The current native extension covers LinearMath, collision shapes,
+`CollisionObject`/`CollisionWorld`, rigid bodies, dynamics worlds, constraints,
+ray/contact/closest-point queries, raycast vehicles, soft bodies, multibodies,
+primitive URDF loading, bundled data paths, and the high-level
+`Bullet3::Simulation` facade.
+
+## Installation
+
+Add the gem from this repository:
+
+```bash
+gem "bullet3", path: "path/to/bullet3"
+```
+
+Then install dependencies:
+
+```bash
+brew install bullet
+bundle install
+```
+
+On Linux, install the Bullet development package for your distribution before
+running `bundle install`:
+
+```bash
+sudo apt install libbullet-dev
+sudo dnf install bullet-devel
+```
+
+Compile the native extension before using the Bullet3-backed classes:
+
+```bash
+bundle exec rake compile
+```
+
+## Usage
+
+```ruby
+require "bullet3"
+
+v = Bullet3::Vector3.new(1, 2, 3)
+axis = Bullet3::Vector3.new(0, 0, 1)
+rotation = Bullet3::Quaternion.from_axis_angle(axis, Math::PI / 2)
+transform = Bullet3::Transform.new(rotation, Bullet3::Vector3.new(1, 0, 0))
+
+p transform * v
+```
+
+High-level direct simulation:
+
+```ruby
+sim = Bullet3::Simulation.new
+sim.set_gravity(0, -10, 0)
+
+plane = sim.create_collision_shape(:static_plane, normal: [0, 1, 0], offset: 0)
+sphere = sim.create_collision_shape(:sphere, radius: 1.0)
+
+sim.create_rigid_body(mass: 0.0, collision_shape: plane)
+body = sim.create_rigid_body(mass: 1.0, collision_shape: sphere, position: [0, 10, 0])
+
+120.times { sim.step_simulation(time_step: 1.0 / 60.0, fixed_time_step: 1.0 / 60.0) }
+p sim.get_base_position_and_orientation(body)
+puts sim.get_contact_points(body_a: body).inspect
+```
+
+By default `require "bullet3"` loads the native extension when it has been
+compiled. Set `BULLET3_SKIP_NATIVE=1` to force the pure Ruby fallback for
+non-native classes.
+
+Primitive URDF loading and data paths:
+
+```ruby
+sim = Bullet3::Simulation.new
+sim.set_gravity(0, 0, -10)
+
+plane = sim.load_urdf("plane.urdf", use_fixed_base: true)
+cube = sim.load_urdf("cube.urdf", base_position: [0, 0, 3])
+
+120.times { sim.step_simulation(time_step: 1.0 / 60.0) }
+p sim.get_aabb(cube)
+p sim.get_contact_points(body_a: plane, body_b: cube)
+```
+
+Lower-level APIs are available for direct Bullet3 usage:
+
+```ruby
+world = Bullet3::CollisionWorld.create
+shape = Bullet3::Shapes::SphereShape.new(1.0)
+object = Bullet3::CollisionObject.new(shape)
+world.add_collision_object(object)
+
+p world.ray_test([0, 5, 0], [0, -5, 0])
+```
+
+Native `.bullet` serialization and import:
+
+```ruby
+sim = Bullet3::Simulation.new
+shape = sim.create_collision_shape(:sphere, radius: 1.0)
+sim.create_rigid_body(mass: 0.0, collision_shape: shape)
+
+sim.save_bullet("world.bullet")
+
+loaded = Bullet3::Simulation.new
+importer = loaded.load_bullet("world.bullet")
+p importer.num_rigid_bodies
+```
+
+`.bullet` import support is enabled when Bullet's WorldImporter extras are
+available at build time. Set `BULLET3_EXTRAS_SOURCE_DIR` to Bullet's
+`Extras/Serialize` source directory before compiling if your system Bullet
+package does not ship those libraries.
+
+Debug drawing via Bullet3's `btIDebugDraw` interface:
+
+```ruby
+drawer = Bullet3::DebugDraw.new
+drawer.debug_mode = Bullet3::DebugDraw::DRAW_WIREFRAME | Bullet3::DebugDraw::DRAW_AABB
+sim.debug_draw_world(drawer)
+
+p drawer.lines.first
+```
+
+## Implemented Scope
+
+- LinearMath: `Vector3`, `Quaternion`, `Matrix3x3`, `Transform`
+- Collision shapes: primitive, compound, convex hull, triangle mesh,
+  convex triangle mesh, multi-sphere, heightfield
+- Collision world: standalone collision objects, broadphases, ray tests,
+  contact tests, pair tests, closest points
+- Dynamics: rigid bodies, motion states, default/explicit worlds,
+  constraints, contact manifolds, GVL-free stepping
+- Extras: raycast vehicles, soft bodies, multibodies
+- High-level API: direct/gui/shared-memory compatible local simulation modes,
+  primitive body creation, single- and multi-link URDF, SDF and MJCF primitive
+  import, ray/contact/AABB helpers, base pose, joint state/control helpers,
+  camera ray rendering, JSON world snapshots, native `.bullet` serialization
+  and import, debug drawing, dynamics updates, reset/disconnect
+
+Remaining limitations: GUI and shared-memory modes run through the same local
+simulation backend, and camera images use the built-in ray renderer rather than
+TinyRenderer/OpenGL.
+
+## Development
+
+After checking out the repo, install Bullet and Ruby dependencies:
+
+```bash
+brew install bullet
+bundle install
+```
+
+Use `BULLET_ROOT=/path/to/bullet` when Bullet is installed outside the standard
+system prefixes. `.bullet` import support also needs Bullet's WorldImporter
+extras; set `BULLET3_EXTRAS_SOURCE_DIR=/path/to/bullet3/Extras/Serialize` before
+compiling to enable it from a Bullet source checkout.
+
+Run the Ruby fallback test suite:
+
+```bash
+BULLET3_SKIP_NATIVE=1 bundle exec rake spec
+```
+
+Compile and test the native extension:
+
+```bash
+bundle exec rake compile
+bundle exec rake spec
+```
+
+Run examples:
+
+```bash
+bundle exec ruby examples/hello_world.rb
+bundle exec ruby examples/ray_casting.rb
+bundle exec ruby examples/urdf.rb
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/data/cube.urdf

@@ -0,0 +1,22 @@
+<?xml version="1.0"?>
+<robot name="cube">
+  <link name="baseLink">
+    <contact>
+      <lateral_friction value="1.0"/>
+      <rolling_friction value="0.0"/>
+      <contact_cfm value="0.0"/>
+      <contact_erp value="1.0"/>
+    </contact>
+    <inertial>
+      <origin rpy="0 0 0" xyz="0 0 0"/>
+      <mass value="1.0"/>
+      <inertia ixx="1" ixy="0" ixz="0" iyy="1" iyz="0" izz="1"/>
+    </inertial>
+    <collision>
+      <origin rpy="0 0 0" xyz="0 0 0"/>
+      <geometry>
+        <box size="1 1 1"/>
+      </geometry>
+    </collision>
+  </link>
+</robot>

data/data/plane.urdf

@@ -0,0 +1,19 @@
+<?xml version="1.0"?>
+<robot name="plane">
+  <link name="planeLink">
+    <contact>
+      <lateral_friction value="1"/>
+    </contact>
+    <inertial>
+      <origin rpy="0 0 0" xyz="0 0 0"/>
+      <mass value="0"/>
+      <inertia ixx="0" ixy="0" ixz="0" iyy="0" iyz="0" izz="0"/>
+    </inertial>
+    <collision>
+      <origin rpy="0 0 0" xyz="0 0 -5"/>
+      <geometry>
+        <box size="200 200 10"/>
+      </geometry>
+    </collision>
+  </link>
+</robot>

data/ext/bullet3/CMakeLists.txt

@@ -0,0 +1,224 @@
+cmake_minimum_required(VERSION 3.16)
+
+project(bullet3_native LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+find_package(Ruby REQUIRED COMPONENTS Development)
+find_package(PkgConfig QUIET)
+
+execute_process(
+  COMMAND ${RUBY_EXECUTABLE} -rrubygems -e "print Gem::Specification.find_by_name('rice').full_gem_path"
+  OUTPUT_VARIABLE RICE_GEM_PATH
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+  RESULT_VARIABLE RICE_LOOKUP_RESULT
+)
+
+if(NOT RICE_LOOKUP_RESULT EQUAL 0)
+  message(FATAL_ERROR "Rice gem is required to build bullet3")
+endif()
+
+set(BULLET_ROOT "" CACHE PATH "Path to a Bullet Physics SDK installation")
+if(NOT BULLET_ROOT AND DEFINED ENV{BULLET_ROOT})
+  set(BULLET_ROOT "$ENV{BULLET_ROOT}")
+endif()
+
+set(BULLET3_SEARCH_PREFIXES
+  "${BULLET_ROOT}"
+  "$ENV{BULLET_ROOT}"
+  /opt/homebrew/opt/bullet
+  /usr/local
+  /usr
+)
+list(REMOVE_ITEM BULLET3_SEARCH_PREFIXES "")
+
+set(BULLET3_INCLUDE_DIRS "")
+set(BULLET3_LIBRARIES "")
+set(BULLET3_LINK_TARGETS "")
+set(BULLET3_LIBRARY_DIRS "")
+
+find_package(Bullet QUIET)
+if(Bullet_FOUND OR BULLET_FOUND)
+  if(DEFINED BULLET_INCLUDE_DIRS)
+    set(BULLET3_INCLUDE_DIRS ${BULLET_INCLUDE_DIRS})
+  elseif(DEFINED BULLET_INCLUDE_DIR)
+    set(BULLET3_INCLUDE_DIRS ${BULLET_INCLUDE_DIR})
+  endif()
+  set(BULLET3_LIBRARIES ${BULLET_LIBRARIES})
+elseif(PkgConfig_FOUND)
+  pkg_check_modules(BULLET_PC QUIET IMPORTED_TARGET bullet)
+  if(BULLET_PC_FOUND)
+    if(TARGET PkgConfig::BULLET_PC)
+      list(APPEND BULLET3_LINK_TARGETS PkgConfig::BULLET_PC)
+    else()
+      set(BULLET3_INCLUDE_DIRS ${BULLET_PC_INCLUDE_DIRS})
+      set(BULLET3_LIBRARIES ${BULLET_PC_LIBRARIES})
+      set(BULLET3_LIBRARY_DIRS ${BULLET_PC_LIBRARY_DIRS})
+    endif()
+  endif()
+endif()
+
+if(NOT BULLET3_LINK_TARGETS AND NOT BULLET3_LIBRARIES)
+  find_path(BULLET3_INCLUDE_DIR
+    NAMES btBulletDynamicsCommon.h
+    HINTS ${BULLET3_SEARCH_PREFIXES}
+    PATH_SUFFIXES include/bullet include
+  )
+
+  set(BULLET3_REQUIRED_BULLET_LIBRARIES
+    BulletSoftBody
+    BulletDynamics
+    BulletCollision
+    LinearMath
+  )
+  set(BULLET3_MISSING_BULLET_LIBRARIES "")
+  foreach(BULLET3_LIBRARY_NAME IN LISTS BULLET3_REQUIRED_BULLET_LIBRARIES)
+    string(TOUPPER "${BULLET3_LIBRARY_NAME}" BULLET3_LIBRARY_VARIABLE)
+    find_library(BULLET3_${BULLET3_LIBRARY_VARIABLE}_LIBRARY
+      NAMES ${BULLET3_LIBRARY_NAME}
+      HINTS ${BULLET3_SEARCH_PREFIXES}
+      PATH_SUFFIXES lib lib64
+    )
+    if(BULLET3_${BULLET3_LIBRARY_VARIABLE}_LIBRARY)
+      list(APPEND BULLET3_LIBRARIES ${BULLET3_${BULLET3_LIBRARY_VARIABLE}_LIBRARY})
+    else()
+      list(APPEND BULLET3_MISSING_BULLET_LIBRARIES ${BULLET3_LIBRARY_NAME})
+    endif()
+  endforeach()
+
+  if(BULLET3_INCLUDE_DIR AND NOT BULLET3_MISSING_BULLET_LIBRARIES)
+    set(BULLET3_INCLUDE_DIRS ${BULLET3_INCLUDE_DIR})
+  endif()
+endif()
+
+if(NOT BULLET3_LINK_TARGETS AND (NOT BULLET3_INCLUDE_DIRS OR NOT BULLET3_LIBRARIES))
+  message(FATAL_ERROR "Bullet development files are required to build bullet3. Install Bullet or set BULLET_ROOT to the installation prefix.")
+endif()
+
+set(BULLET3_OPTIONAL_SOURCES "")
+set(BULLET3_OPTIONAL_INCLUDE_DIRS "")
+set(BULLET3_OPTIONAL_LIBRARIES "")
+
+set(BULLET3_EXTRAS_SOURCE_DIR "" CACHE PATH "Optional path to Bullet Extras/Serialize sources for .bullet import support")
+if(NOT BULLET3_EXTRAS_SOURCE_DIR AND DEFINED ENV{BULLET3_EXTRAS_SOURCE_DIR})
+  set(BULLET3_EXTRAS_SOURCE_DIR "$ENV{BULLET3_EXTRAS_SOURCE_DIR}")
+endif()
+
+if(BULLET3_EXTRAS_SOURCE_DIR)
+  set(BULLET3_FILE_LOADER_DIR "${BULLET3_EXTRAS_SOURCE_DIR}/BulletFileLoader")
+  set(BULLET3_WORLD_IMPORTER_DIR "${BULLET3_EXTRAS_SOURCE_DIR}/BulletWorldImporter")
+
+  if(NOT EXISTS "${BULLET3_FILE_LOADER_DIR}/btBulletFile.cpp" OR NOT EXISTS "${BULLET3_WORLD_IMPORTER_DIR}/btBulletWorldImporter.cpp")
+    message(FATAL_ERROR "BULLET3_EXTRAS_SOURCE_DIR must point to Bullet's Extras/Serialize directory")
+  endif()
+
+  list(APPEND BULLET3_OPTIONAL_SOURCES
+    "${BULLET3_FILE_LOADER_DIR}/bChunk.cpp"
+    "${BULLET3_FILE_LOADER_DIR}/bDNA.cpp"
+    "${BULLET3_FILE_LOADER_DIR}/bFile.cpp"
+    "${BULLET3_FILE_LOADER_DIR}/btBulletFile.cpp"
+    "${BULLET3_WORLD_IMPORTER_DIR}/btBulletWorldImporter.cpp"
+    "${BULLET3_WORLD_IMPORTER_DIR}/btWorldImporter.cpp"
+  )
+  list(APPEND BULLET3_OPTIONAL_INCLUDE_DIRS
+    "${BULLET3_FILE_LOADER_DIR}"
+    "${BULLET3_WORLD_IMPORTER_DIR}"
+  )
+  set(BULLET3_WITH_WORLD_IMPORTER TRUE)
+else()
+  find_path(BULLET3_WORLD_IMPORTER_INCLUDE_DIR
+    NAMES btBulletWorldImporter.h
+    HINTS ${BULLET3_SEARCH_PREFIXES}
+    PATH_SUFFIXES
+      include/bullet/Extras/Serialize/BulletWorldImporter
+      include/Extras/Serialize/BulletWorldImporter
+  )
+  find_library(BULLET3_WORLD_IMPORTER_LIBRARY
+    NAMES BulletWorldImporter
+    HINTS ${BULLET3_SEARCH_PREFIXES}
+    PATH_SUFFIXES lib lib64
+  )
+  find_library(BULLET3_FILE_LOADER_LIBRARY
+    NAMES BulletFileLoader Bullet2FileLoader
+    HINTS ${BULLET3_SEARCH_PREFIXES}
+    PATH_SUFFIXES lib lib64
+  )
+
+  if(BULLET3_WORLD_IMPORTER_INCLUDE_DIR AND BULLET3_WORLD_IMPORTER_LIBRARY AND BULLET3_FILE_LOADER_LIBRARY)
+    list(APPEND BULLET3_OPTIONAL_INCLUDE_DIRS ${BULLET3_WORLD_IMPORTER_INCLUDE_DIR})
+    list(APPEND BULLET3_OPTIONAL_LIBRARIES ${BULLET3_WORLD_IMPORTER_LIBRARY} ${BULLET3_FILE_LOADER_LIBRARY})
+    set(BULLET3_WITH_WORLD_IMPORTER TRUE)
+  endif()
+endif()
+
+add_library(bullet3 MODULE
+  bullet3.cpp
+  collision/rb_collision.cpp
+  collision/shapes/rb_collision_shape.cpp
+  constraints/rb_constraints.cpp
+  dynamics/rb_dynamics.cpp
+  io/rb_io.cpp
+  linear_math/rb_matrix3x3.cpp
+  linear_math/rb_quaternion.cpp
+  linear_math/rb_transform.cpp
+  linear_math/rb_vector3.cpp
+  multi_body/rb_multi_body.cpp
+  soft_body/rb_soft_body.cpp
+  util/rb_debug_draw.cpp
+  vehicle/rb_vehicle.cpp
+  ${BULLET3_OPTIONAL_SOURCES}
+)
+
+target_include_directories(bullet3 PRIVATE
+  ${BULLET3_INCLUDE_DIRS}
+  ${BULLET3_OPTIONAL_INCLUDE_DIRS}
+)
+
+target_include_directories(bullet3 SYSTEM PRIVATE
+  ${Ruby_INCLUDE_DIRS}
+  "${RICE_GEM_PATH}/include"
+)
+
+set(BULLET3_RUBY_LIBRARIES "")
+foreach(RUBY_LIBRARY IN LISTS Ruby_LIBRARIES)
+  if(RUBY_LIBRARY AND NOT RUBY_LIBRARY MATCHES "-NOTFOUND$")
+    list(APPEND BULLET3_RUBY_LIBRARIES ${RUBY_LIBRARY})
+  endif()
+endforeach()
+
+if(BULLET3_LIBRARY_DIRS)
+  target_link_directories(bullet3 PRIVATE ${BULLET3_LIBRARY_DIRS})
+endif()
+
+target_link_libraries(bullet3 PRIVATE
+  ${BULLET3_RUBY_LIBRARIES}
+  ${BULLET3_LINK_TARGETS}
+  ${BULLET3_LIBRARIES}
+  ${BULLET3_OPTIONAL_LIBRARIES}
+)
+
+if(APPLE)
+  target_link_options(bullet3 PRIVATE -undefined dynamic_lookup)
+endif()
+
+if(BULLET3_WITH_WORLD_IMPORTER)
+  target_compile_definitions(bullet3 PRIVATE BULLET3_WITH_WORLD_IMPORTER)
+endif()
+
+if(MSVC)
+  target_compile_options(bullet3 PRIVATE /W4)
+else()
+  target_compile_options(bullet3 PRIVATE
+    -Wall
+    -Wextra
+    $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang,GNU>:-include${CMAKE_CURRENT_SOURCE_DIR}/util/ruby_cpp_compat.hpp>
+  )
+endif()
+
+set_target_properties(bullet3 PROPERTIES
+  PREFIX ""
+  SUFFIX "${RUBY_EXTENSION_SUFFIX}"
+  LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
+)

data/ext/bullet3/bullet3.cpp

@@ -0,0 +1,34 @@
+#include <rice/rice.hpp>
+
+void Init_Shapes(Rice::Module rb_mBullet);
+void Init_Collision(Rice::Module rb_mBullet);
+void Init_SoftBody(Rice::Module rb_mBullet);
+void Init_Constraints(Rice::Module rb_mBullet);
+void Init_Dynamics(Rice::Module rb_mBullet);
+void Init_DebugDraw(Rice::Module rb_mBullet);
+void Init_IO(Rice::Module rb_mBullet);
+void Init_Matrix3x3(Rice::Module rb_mBullet);
+void Init_MultiBody(Rice::Module rb_mBullet);
+void Init_Quaternion(Rice::Module rb_mBullet);
+void Init_Transform(Rice::Module rb_mBullet);
+void Init_Vector3(Rice::Module rb_mBullet);
+void Init_Vehicle(Rice::Module rb_mBullet);
+
+extern "C"
+void Init_bullet3()
+{
+  Rice::Module rb_mBullet = Rice::define_module("Bullet3");
+  Init_Vector3(rb_mBullet);
+  Init_Quaternion(rb_mBullet);
+  Init_Matrix3x3(rb_mBullet);
+  Init_Transform(rb_mBullet);
+  Init_Shapes(rb_mBullet);
+  Init_Dynamics(rb_mBullet);
+  Init_Collision(rb_mBullet);
+  Init_Constraints(rb_mBullet);
+  Init_DebugDraw(rb_mBullet);
+  Init_IO(rb_mBullet);
+  Init_Vehicle(rb_mBullet);
+  Init_SoftBody(rb_mBullet);
+  Init_MultiBody(rb_mBullet);
+}