jolt-ruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 509d377cf15f0161227805d8d345983bf07dec680a2ed7aecf38c73ace3590f5
+  data.tar.gz: d7a89c5121b6cecabcb41b1c936c24c169cac11baf4929c1cda9bd7976ad2bb3
+SHA512:
+  metadata.gz: afe48cf43dc719295618c46950959280bc13e61005846b5b28d2dadaef963156da74a4ba29340d078471dc6dc5f29eea7cdfd440e4a8562d87f0ce971917ce33
+  data.tar.gz: 76ecbdfb1a0b21decd3f55f627f31e910f716c81d3d3370fb0bc76e033d372d0800539bb840d41f8384c6faf6a2e9f9215498b0db424e5fd67204bf5b966e9a0

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "ext/joltc"]
+	path = ext/joltc
+	url = https://github.com/amerkoleci/joltc.git

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,228 @@
+# jolt-ruby
+
+Ruby bindings for [Jolt Physics](https://github.com/jrouwe/JoltPhysics), built on
+the `joltc` C API, `ffi`, and `larb`.
+
+> jolt-ruby uses SI units in a right-handed, Y-up coordinate system: metres,
+> kilograms, seconds, and radians. Passing centimetres or degrees without
+> conversion will produce incorrect simulation results.
+
+## Installation
+
+```ruby
+gem "jolt-ruby"
+```
+
+```sh
+bundle install
+```
+
+Release builds use platform gems for x86-64/aarch64 Linux, arm64/x86-64 macOS,
+and x64-mingw-ucrt. On another platform RubyGems falls back to the source gem,
+which requires CMake 3.16 or newer and a C++17 compiler.
+
+The 1.x public API follows semantic versioning. Native declarations mirror the
+vendored `joltc` header; higher-level Ruby APIs are added deliberately rather
+than exposing unsafe ownership or callback behavior.
+
+## First simulation
+
+```ruby
+require "jolt"
+
+system = Jolt::System.new(gravity: [0, -9.81, 0])
+floor = system.bodies.create(
+  shape: Jolt::Shape.box([50, 0.5, 50]),
+  position: [0, -0.5, 0],
+  motion: :static,
+  layer: :non_moving
+)
+ball = system.bodies.create(
+  shape: Jolt::Shape.sphere(0.5),
+  position: [0, 5, 0],
+  mass: 2,
+  restitution: 0.6,
+  ccd: true
+)
+
+system.update(1.0 / 60)
+puts ball.position
+
+system.destroy
+Jolt.shutdown
+```
+
+`Jolt.init` is called automatically. A `System` owns its bodies, constraints,
+characters, and retained shapes. Destroying the system invalidates their Ruby
+handles; subsequent access raises `Jolt::UseAfterDestroyError`. Explicit
+`destroy`/`release` is supported, and shutdown is also registered with
+`at_exit`.
+
+## Layers
+
+`Layers.default` provides `:non_moving` and `:moving`. Custom collision matrices
+remain entirely native during simulation:
+
+```ruby
+layers = Jolt::Layers.define do |layer|
+  layer.broad_phase :static_bp, :dynamic_bp
+  layer.object :ground, broad_phase: :static_bp
+  layer.object :player, :enemy, broad_phase: :dynamic_bp
+  layer.collide :player, with: %i[ground enemy]
+  layer.collide :enemy, with: %i[ground player enemy]
+end
+
+system = Jolt::System.new(layers:)
+```
+
+## Shapes and bodies
+
+Primitive shapes:
+
+```ruby
+Jolt::Shape.box([1, 0.5, 1])
+Jolt::Shape.sphere(0.5)
+Jolt::Shape.capsule(half_height: 0.8, radius: 0.3)
+Jolt::Shape.cylinder(half_height: 1, radius: 0.5)
+```
+
+The advanced builders are `convex_hull`, `mesh`, `heightfield`, `compound`,
+`scaled`, and `offset`. Hull vertices and mesh vertices accept nested arrays or
+packed little-endian f32 strings; mesh indices also accept packed u32 strings.
+Mesh and heightfield shapes are static-only.
+
+Bodies support `:static`, `:kinematic`, and `:dynamic` motion. Common operations
+include:
+
+```ruby
+body.linear_velocity = [1, 0, 0]
+body.angular_velocity = [0, 1, 0]
+body.apply_impulse([0, 10, 0])
+body.add_force([5, 0, 0], point: [0, 1, 0])
+body.friction = 0.4
+body.sensor = true
+body.kinematic_move_to([2, 0, 0], [0, 0, 0, 1], 1.0 / 60)
+```
+
+Arbitrary Ruby objects can be stored in `body.user_data`. They never cross the
+native boundary.
+
+## Contacts and queries
+
+Jolt invokes contact listeners from worker threads. jolt-ruby records those
+calls into a bounded native lock-free queue, then creates immutable Ruby
+snapshots after `System#update`:
+
+```ruby
+system.update(1.0 / 60)
+system.contact_events.added.each do |contact|
+  puts [contact.body_a, contact.body_b, contact.point, contact.normal].inspect
+end
+
+warn "contact queue overflow" if system.contact_events.dropped_count.positive?
+```
+
+Synchronous queries return registered `Jolt::Body` handles:
+
+```ruby
+hit = system.raycast(
+  origin: [0, 10, 0],
+  direction: [0, -20, 0],
+  layer_mask: %i[non_moving moving]
+)
+
+nearby = system.overlap_sphere([0, 0, 0], 2, layer_mask: :moving)
+system.overlap_point([0, 0, 0]) { |body| puts body.user_data }
+```
+
+Overlap queries use Jolt's broad phase and therefore report bodies whose bounds
+overlap the query.
+
+## Constraints
+
+The collection supports fixed, point, distance, hinge, and slider constraints:
+
+```ruby
+hinge = system.constraints.hinge(
+  body_a: door,
+  body_b: frame,
+  anchor: [0, 1, 0],
+  axis: [0, 1, 0],
+  limits: (-Math::PI / 2)..(Math::PI / 2)
+)
+hinge.motor_speed = 1.5
+hinge.disable_motor
+hinge.destroy
+```
+
+Destroying either body destroys its attached constraints first.
+
+## Virtual characters
+
+`CharacterVirtual#update` uses Jolt's extended update with stair walking and
+stick-to-floor enabled:
+
+```ruby
+character = Jolt::CharacterVirtual.new(
+  system,
+  shape: Jolt::Shape.capsule(half_height: 0.8, radius: 0.3),
+  position: [0, 2, 0],
+  max_slope: Math::PI / 4,
+  mass: 70
+)
+
+character.velocity = [3, character.velocity.y - 9.81 / 60, 0]
+character.update(1.0 / 60)
+puts character.ground_state # :on_ground, :sliding, or :in_air
+```
+
+## Fixed stepping and rendering
+
+`System#update` releases Ruby's GVL while Jolt runs. Use `FixedStepper` to keep
+simulation stable and interpolate rendering transforms:
+
+```ruby
+stepper = Jolt::FixedStepper.new(hz: 60, max_substeps: 5)
+
+alpha = stepper.advance(frame_delta) { |step| system.update(step) }
+render_transform = ball.interpolated(alpha)
+```
+
+Each system permits one native operation at a time. Do not read, mutate, or
+destroy a system or one of its handles from another thread while
+`System#update` or `CharacterVirtual#update` is running. Such access raises
+`Jolt::ConcurrentAccessError`.
+
+The returned transform exposes `position` and `rotation` as `Larb::Vec3` and
+`Larb::Quat`, matching the stagecraft binding contract. See
+[`examples/stagecraft_binding.rb`](examples/stagecraft_binding.rb).
+
+## Development
+
+Initialize the submodule and run the complete build:
+
+```sh
+git submodule update --init
+bundle install
+bundle exec rake
+```
+
+Useful tasks:
+
+```sh
+bundle exec rake native:compile       # build joltc and the helper library
+bundle exec rake generator:generate   # regenerate all joltc FFI declarations
+bundle exec rake native:verify_layout # compare Clang, C++, and FFI layouts
+bundle exec rake native:gem           # build a precompiled platform gem
+bundle exec rake native:smoke_gem     # install and run the platform gem
+bundle exec rake package:smoke_source # compile, install, and run the source gem
+JOLT_STRESS=1 bundle exec rspec spec/stress
+```
+
+The generator reads `joltc.h` through `ffi-clang`. CI rejects stale output and
+compares all generated struct sizes and field offsets against a C++ probe.
+
+## License
+
+The gem is available under the [MIT License](LICENSE.txt). Jolt Physics and
+`joltc` retain their respective upstream licenses.

data/Rakefile

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "fileutils"
+require "open3"
+require "rspec/core/rake_task"
+require "rbconfig"
+require "shellwords"
+require_relative "lib/jolt/native/platform"
+require_relative "lib/jolt/version"
+
+RSpec::Core::RakeTask.new(:spec)
+
+module NativeBuild
+  extend Rake::FileUtilsExt
+  module_function
+
+  ROOT = __dir__
+  PLATFORM = Jolt::Native::Platform.tag
+  BUILD_DIR = File.join(ROOT, "tmp", "native", PLATFORM)
+
+  def configure
+    arch = RbConfig::CONFIG.fetch("host_cpu")
+    command = [
+      "cmake",
+      "-S", File.join(ROOT, "ext", "jolt_ruby"),
+      "-B", BUILD_DIR,
+      "-DCMAKE_BUILD_TYPE=Release"
+    ]
+    command << "-DCMAKE_OSX_ARCHITECTURES=#{arch}" if RbConfig::CONFIG.fetch("host_os").include?("darwin")
+    sh(*command)
+  end
+
+  def build
+    sh("cmake", "--build", BUILD_DIR, "--config", "Release", "--parallel")
+  end
+
+  def library_names
+    case RbConfig::CONFIG.fetch("host_os")
+    when /darwin/
+      %w[libjoltc.dylib libjolt_ruby_helper.dylib]
+    when /mswin|mingw/
+      %w[joltc.dll jolt_ruby_helper.dll]
+    else
+      %w[libjoltc.so libjolt_ruby_helper.so]
+    end
+  end
+
+  def library_directory
+    [
+      File.join(BUILD_DIR, "lib"),
+      File.join(BUILD_DIR, "lib", "Release"),
+      File.join(BUILD_DIR, "Release")
+    ].find { |directory| library_names.all? { |name| File.file?(File.join(directory, name)) } } ||
+      raise("native libraries were not found in #{BUILD_DIR}")
+  end
+
+  def stage
+    destination = File.join(ROOT, "lib", "jolt", "native", PLATFORM)
+    FileUtils.rm_rf(destination)
+    FileUtils.mkdir_p(destination)
+    library_names.each do |name|
+      FileUtils.cp(File.join(library_directory, name), destination)
+    end
+  end
+
+  def verify_layout
+    directory = File.join(ROOT, "tmp", "layout")
+    FileUtils.mkdir_p(directory)
+    executable = File.join(directory, "layout_probe#{RbConfig::CONFIG.fetch("EXEEXT")}")
+    compiler = Shellwords.split(ENV.fetch("CXX", RbConfig::CONFIG.fetch("CXX")))
+    sh(
+      *compiler,
+      "-std=c++17",
+      "-I#{File.join(ROOT, "ext", "joltc", "include")}",
+      File.join(ROOT, "generator", "layout_probe.cpp"),
+      "-o", executable
+    )
+    output, status = Open3.capture2e(executable)
+    raise "layout probe failed:\n#{output}" unless status.success?
+
+    output_path = File.join(directory, "layouts.tsv")
+    File.binwrite(output_path, output)
+    sh(
+      RbConfig.ruby,
+      File.join(ROOT, "generator", "verify_layout.rb"),
+      output_path
+    )
+  end
+end
+
+module PackageSmoke
+  extend Rake::FileUtilsExt
+  module_function
+
+  ROOT = __dir__
+
+  def run(gem_path, label)
+    raise "gem was not built: #{gem_path}" unless File.file?(gem_path)
+
+    install_dir = File.join(ROOT, "tmp", "gem-smoke", label)
+    FileUtils.rm_rf(install_dir)
+    FileUtils.mkdir_p(install_dir)
+    sh(
+      "gem", "install", "--local", "--ignore-dependencies", "--no-document",
+      "--install-dir", install_dir, gem_path
+    )
+
+    gem_path_entries = [install_dir, *Gem.path].uniq.join(File::PATH_SEPARATOR)
+    environment = {
+      "GEM_HOME" => install_dir,
+      "GEM_PATH" => gem_path_entries,
+      "JOLT_RUBY_SMOKE_HOME" => install_dir
+    }
+    Bundler.with_unbundled_env do
+      sh(environment, RbConfig.ruby, File.join(ROOT, "script", "smoke_gem.rb"))
+    end
+  end
+end
+
+namespace :generator do
+  desc "Regenerate FFI declarations and the native layout probe"
+  task :generate do
+    sh(RbConfig.ruby, File.join(__dir__, "generator", "generate.rb"))
+  end
+
+  desc "Fail if generated FFI declarations are stale"
+  task :check do
+    sh(RbConfig.ruby, File.join(__dir__, "generator", "generate.rb"), "--check")
+  end
+end
+
+namespace :native do
+  desc "Configure the native joltc build"
+  task :configure do
+    NativeBuild.configure
+  end
+
+  desc "Build joltc and the jolt-ruby support library"
+  task compile: :configure do
+    NativeBuild.build
+  end
+
+  desc "Verify every generated FFI struct against the C compiler"
+  task verify_layout: "generator:check" do
+    NativeBuild.verify_layout
+  end
+
+  desc "Build a platform gem containing the native libraries"
+  task gem: :compile do
+    NativeBuild.stage
+    sh({ "JOLT_RUBY_PLATFORM_GEM" => "1" }, "gem", "build", "jolt.gemspec")
+  end
+
+  desc "Build, install, and execute the current platform gem"
+  task smoke_gem: :gem do
+    platform = Gem::Platform.new(NativeBuild::PLATFORM)
+    gem_path = File.join(__dir__, "jolt-ruby-#{Jolt::VERSION}-#{platform}.gem")
+    PackageSmoke.run(gem_path, "platform")
+  end
+end
+
+namespace :package do
+  desc "Build the source gem"
+  task :source_gem do
+    sh("gem", "build", "jolt.gemspec")
+  end
+
+  desc "Build, install, compile, and execute the source gem fallback"
+  task smoke_source: :source_gem do
+    gem_path = File.join(__dir__, "jolt-ruby-#{Jolt::VERSION}.gem")
+    PackageSmoke.run(gem_path, "source")
+  end
+end
+
+desc "Build the native libraries"
+task compile: "native:compile"
+
+task spec: [:compile, "native:verify_layout"]
+task default: :spec

data/examples/character_virtual.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "jolt"
+
+begin
+  system = Jolt::System.new
+  system.bodies.create(
+    shape: Jolt::Shape.box([10, 0.5, 10]),
+    position: [0, -0.5, 0],
+    motion: :static
+  )
+  character = Jolt::CharacterVirtual.new(
+    system,
+    shape: Jolt::Shape.capsule(half_height: 0.8, radius: 0.3),
+    position: [0, 2, 0]
+  )
+
+  180.times do |frame|
+    velocity = character.velocity
+    character.velocity = [1, velocity.y - 9.81 / 60, 0]
+    system.update(1.0 / 60)
+    character.update(1.0 / 60)
+    if (frame % 15).zero?
+      puts format(
+        "%3d  position=%s  ground=%s",
+        frame,
+        character.position.to_a.map { |value| value.round(3) },
+        character.ground_state
+      )
+    end
+  end
+ensure
+  system&.destroy
+  Jolt.shutdown
+end

data/examples/falling_sphere.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "jolt"
+
+begin
+  system = Jolt::System.new
+  system.bodies.create(
+    shape: Jolt::Shape.box([10, 0.5, 10]),
+    position: [0, -0.5, 0],
+    motion: :static
+  )
+  ball = system.bodies.create(
+    shape: Jolt::Shape.sphere(0.5),
+    position: [0, 5, 0],
+    restitution: 0.6
+  )
+
+  120.times do |frame|
+    system.update(1.0 / 60)
+    puts format("%3d  y=% .3f", frame, ball.position.y) if (frame % 10).zero?
+  end
+ensure
+  system&.destroy
+  Jolt.shutdown
+end

data/examples/stagecraft_binding.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "jolt"
+require "stagecraft"
+
+def run_stagecraft_physics(app:, mesh_node:)
+  begin
+    system = Jolt::System.new
+    ball = system.bodies.create(
+      shape: Jolt::Shape.sphere(0.5),
+      position: [0, 5, 0]
+    )
+
+    binding = Stagecraft::PhysicsBinding.new
+    binding.bind(mesh_node, ball)
+    stepper = Jolt::FixedStepper.new(hz: 60)
+
+    app.run do |delta_time|
+      alpha = stepper.advance(delta_time) { |step| system.update(step) }
+      binding.sync!(alpha)
+    end
+  ensure
+    system&.destroy
+    Jolt.shutdown
+  end
+end
+
+# Call from a stagecraft scene with:
+# run_stagecraft_physics(app:, mesh_node:)

data/ext/jolt_ruby/CMakeLists.txt

@@ -0,0 +1,42 @@
+cmake_minimum_required(VERSION 3.16)
+
+project(jolt_ruby_native LANGUAGES C CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
+
+set(JPH_MASTER_PROJECT OFF CACHE BOOL "" FORCE)
+set(JPH_BUILD_SHARED ON CACHE BOOL "" FORCE)
+set(JPH_INSTALL OFF CACHE BOOL "" FORCE)
+set(JPH_SAMPLES OFF CACHE BOOL "" FORCE)
+set(JPH_TESTS OFF CACHE BOOL "" FORCE)
+set(DEBUG_RENDERER_IN_DEBUG_AND_RELEASE ON CACHE BOOL "" FORCE)
+set(DEBUG_RENDERER_IN_DISTRIBUTION OFF CACHE BOOL "" FORCE)
+set(CROSS_PLATFORM_DETERMINISTIC ON CACHE BOOL "" FORCE)
+set(PROFILER_IN_DEBUG_AND_RELEASE OFF CACHE BOOL "" FORCE)
+set(PROFILER_IN_DISTRIBUTION OFF CACHE BOOL "" FORCE)
+set(ENABLE_OBJECT_STREAM OFF CACHE BOOL "" FORCE)
+set(JPH_USE_DX12 OFF CACHE BOOL "" FORCE)
+set(JPH_USE_VK OFF CACHE BOOL "" FORCE)
+set(JPH_USE_MTL OFF CACHE BOOL "" FORCE)
+
+set(JOLTC_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../joltc" CACHE PATH "Path to joltc")
+if(NOT EXISTS "${JOLTC_ROOT}/CMakeLists.txt")
+  message(FATAL_ERROR "joltc submodule is missing; run git submodule update --init")
+endif()
+
+add_subdirectory("${JOLTC_ROOT}" "${CMAKE_BINARY_DIR}/joltc")
+
+add_library(jolt_ruby_helper SHARED helper.cpp constraint_helper.cpp character_helper.cpp)
+target_include_directories(jolt_ruby_helper PRIVATE "${JOLTC_ROOT}/include")
+target_compile_definitions(jolt_ruby_helper PRIVATE JPH_SHARED_LIBRARY_INCLUDE=1)
+target_link_libraries(jolt_ruby_helper PRIVATE joltc)
+
+if(APPLE)
+  set_target_properties(jolt_ruby_helper PROPERTIES INSTALL_RPATH "@loader_path")
+elseif(UNIX)
+  set_target_properties(jolt_ruby_helper PROPERTIES INSTALL_RPATH "$ORIGIN")
+endif()

data/ext/jolt_ruby/character_helper.cpp

@@ -0,0 +1,44 @@
+#include "helper.h"
+
+#include <joltc.h>
+
+#include <cmath>
+
+JPH_CharacterVirtual* JR_CharacterVirtual_Create(
+    JPH_PhysicsSystem* system,
+    const JPH_Shape* shape,
+    const float* position,
+    const float* rotation,
+    float max_slope_angle,
+    float mass) {
+  if (!system || !shape || !position || !rotation) return nullptr;
+
+  JPH_CharacterVirtualSettings settings{};
+  JPH_CharacterVirtualSettings_Init(&settings);
+  settings.base.shape = shape;
+  settings.base.maxSlopeAngle = max_slope_angle;
+  settings.mass = mass;
+
+  const JPH_RVec3 native_position{position[0], position[1], position[2]};
+  const JPH_Quat native_rotation{
+      rotation[0], rotation[1], rotation[2], rotation[3]};
+  return JPH_CharacterVirtual_Create(
+      &settings, &native_position, &native_rotation, 0, system);
+}
+
+void JR_CharacterVirtual_ExtendedUpdate(
+    JPH_CharacterVirtual* character,
+    float delta_time,
+    uint32_t layer,
+    JPH_PhysicsSystem* system) {
+  JPH_ExtendedUpdateSettings settings{};
+  settings.stickToFloorStepDown = JPH_Vec3{0.0f, -0.5f, 0.0f};
+  settings.walkStairsStepUp = JPH_Vec3{0.0f, 0.4f, 0.0f};
+  settings.walkStairsMinStepForward = 0.02f;
+  settings.walkStairsStepForwardTest = 0.15f;
+  settings.walkStairsCosAngleForwardContact =
+      std::cos(75.0f * JPH_M_PI / 180.0f);
+  settings.walkStairsStepDownExtra = JPH_Vec3{0.0f, 0.0f, 0.0f};
+  JPH_CharacterVirtual_ExtendedUpdate(
+      character, delta_time, &settings, layer, system, nullptr, nullptr);
+}