box2d-ruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b27be6541a6fc5670786520d3679496edadc41237328ff6f3d5f7c561d19a4d8
+  data.tar.gz: 8f5162a1673fc3c797507b33ef51b48004e50bbd546c8e7b44377e6bf33ebbf5
+SHA512:
+  metadata.gz: 1d29cb822f55e9ac3d222d3745c3e12ae323287f8098eb80752576d7cf090c0da8c4340d731491c66114d45bbfd8f0cff36223bf62b8dc2c84eb32e3c21f4439
+  data.tar.gz: d2972da3d6bd61af13f41619d3f6f9c2144718c53b1a04a1beac8233e76b8effe98fe49be0bf3514908a40d44b898d0361f5b561911655c36ae3a421d5c4f4f6

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ydah
+
+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,336 @@
+# box2d-ruby
+
+`box2d-ruby` is an idiomatic Ruby binding for the Box2D 3 C API. It ships a
+complete generated FFI layer and a memory-safe Ruby API for worlds, bodies,
+shapes, events, queries, joints, and debug drawing.
+
+The gem currently vendors Box2D 3.1.0.
+
+## API stability
+
+Version 1.0 freezes the documented Ruby API. Releases in the 1.x series follow
+semantic versioning: existing public methods and their documented behavior will
+remain compatible, and breaking changes require a new major version. The
+generated `Box2D::Native` layer mirrors the vendored Box2D headers exactly and
+is regenerated when that native dependency is intentionally upgraded.
+
+## Units and coordinates
+
+Box2D uses SI units: meters, kilograms, seconds, and radians. It has no built-in
+pixel scale and this binding uses a y-up coordinate system.
+
+Do not pass screen pixels directly to physics APIs. A common game scale is
+32–64 pixels per meter:
+
+```ruby
+scale = Box2D::PixelScale.new(64)
+physics_position = scale.vector_to_meters([320, 128])
+screen_position = scale.vector_to_pixels(physics_position)
+```
+
+## Installation
+
+Add the gem to your bundle:
+
+```sh
+bundle add box2d-ruby
+```
+
+Or install it directly:
+
+```sh
+gem install box2d-ruby
+```
+
+Platform gems contain a precompiled Box2D library. The source gem falls back to
+building the vendored C17 source with CMake and requires CMake 3.16 or newer, a
+C compiler, `make` (or another CMake build backend), and Ruby development
+headers.
+
+The runtime dependency is `ffi`. `larb` is optional: if it is already loaded,
+vector-returning APIs produce `Larb::Vec2`; otherwise they return two-element
+arrays.
+
+## Quick start
+
+```ruby
+require "box2d"
+
+world = Box2D::World.new(gravity: [0, -9.8]) do |configuration|
+  configuration.substeps = 4
+end
+
+world.create_body(type: :static, position: [0, -10]) do |body|
+  body.box(50, 10)
+end
+
+ball = world.create_body(
+  type: :dynamic,
+  position: [0, 4],
+  user_data: {kind: :ball}
+) do |body|
+  body.circle(
+    radius: 0.5,
+    density: 1.0,
+    friction: 0.3,
+    restitution: 0.6
+  )
+  body.bullet = true
+end
+
+60.times { world.step(1.0 / 60) }
+
+p ball.position
+ball.linear_velocity = [3, 0]
+ball.apply_impulse([0, 5])
+
+world.destroy
+```
+
+`World#step` releases Ruby's GVL while Box2D is solving. Accessing the same
+world from another Ruby thread during a step is rejected with
+`Box2D::ReentrantStepError`.
+
+## Fixed timestep
+
+`FixedStepper` implements an accumulator with a substep cap:
+
+```ruby
+stepper = Box2D::FixedStepper.new(hz: 60, max_substeps: 5)
+
+app.run do |delta_time|
+  alpha = stepper.advance(delta_time) { |step| world.step(step) }
+  render(alpha)
+end
+```
+
+`advance` returns interpolation alpha in `[0, 1)`. Excess accumulated time is
+discarded at `max_substeps` to prevent a spiral of death.
+
+## Shapes
+
+A body block is a shape builder:
+
+```ruby
+body = world.create_body(type: :dynamic, position: [0, 3]) do |builder|
+  builder.box(half_width, half_height, center: [0, 0], angle: 0)
+  builder.circle(radius: 0.5, center: [0, 0])
+  builder.capsule([-1, 0], [1, 0], radius: 0.25)
+  builder.polygon([[0, 0], [1, 0], [0, 1]])
+  builder.segment([-1, 0], [1, 0])
+end
+```
+
+Every shape builder accepts:
+
+- `density`, `friction`, `restitution`, and `rolling_resistance`
+- `sensor: true`
+- `filter: {category:, mask:, group:}`
+- `sensor_events`, `contact_events`, and `hit_events`
+- Ruby-owned `user_data`
+
+Chains are separate native objects:
+
+```ruby
+chain = ground.chain(
+  [[-4, 0], [-2, 1], [2, 1], [4, 0]],
+  loop: false,
+  friction: 0.8
+)
+```
+
+Box2D chains require at least four vertices.
+
+## Events
+
+Contact and sensor event buffers are transient in Box2D. `World#step` copies
+them into immutable Ruby values before returning:
+
+```ruby
+world.step(1.0 / 60)
+
+world.events.begin_contacts.each do |contact|
+  a = contact.shape_a.body.user_data
+  b = contact.shape_b.body.user_data
+  p [a, b, contact.manifold]
+end
+
+world.events.end_contacts.each { |contact| p contact }
+world.events.hits.each { |hit| p hit.approach_speed }
+world.events.sensor_begins.each { |event| p [event.sensor, event.visitor] }
+world.events.sensor_ends.each { |event| p [event.sensor, event.visitor] }
+```
+
+## Queries
+
+```ruby
+hit = world.raycast([0, 10], [0, -10])
+if hit
+  p [hit.shape, hit.point, hit.normal, hit.fraction]
+end
+
+world.overlap_aabb([-2, -2], [2, 2]) do |shape|
+  p shape
+end
+
+world.overlap_circle([0, 1], radius: 0.5) { |shape| p shape }
+world.overlap_capsule([-1, 0], [1, 0], radius: 0.25) { |shape| p shape }
+world.overlap_polygon(
+  [[-1, -1], [1, -1], [1, 1], [-1, 1]],
+  position: [4, 0],
+  angle: Math::PI / 4
+) { |shape| p shape }
+```
+
+All query methods accept `filter: {category:, mask:}`. Without a block, overlap
+queries return an `Enumerator`. Returning `false` from the block stops the
+query.
+
+## Joints
+
+The high-level API supports revolute, prismatic, distance, mouse, and weld
+joints:
+
+```ruby
+joint = world.create_revolute_joint(
+  body_a: arm,
+  body_b: hand,
+  anchor: [1, 2],
+  limits: (-0.5..0.5),
+  motor: {speed: 2.0, max_torque: 10.0}
+)
+
+joint.motor_speed = -2.0
+joint.destroy
+```
+
+Equivalent constructors are:
+
+- `create_prismatic_joint`
+- `create_distance_joint`
+- `create_mouse_joint`
+- `create_weld_joint`
+
+All anchors supplied to constructors are world coordinates and are converted to
+body-local coordinates internally.
+
+## Debug drawing
+
+Debug drawing converts native callbacks into arrays suitable for Ruby pattern
+matching:
+
+```ruby
+world.debug_draw(flags: [:shapes, :joints, :aabbs]) do |command|
+  case command
+  in [:polygon, points, color]
+    draw_outline(points, color)
+  in [:solid_circle, transform, radius, color]
+    draw_circle(transform[:position], radius, color)
+  in [:segment, point1, point2, color]
+    draw_line(point1, point2, color)
+  else
+    # Other commands include solid_polygon, solid_capsule, transform,
+    # point, circle, and string.
+  end
+end
+```
+
+The owning world retains every `FFI::Function` used by the draw session, so GC
+cannot collect a callback while native code is using it.
+
+Runnable line-renderer examples are included for both supported rendering
+styles:
+
+```sh
+gem install rugl glfw
+ruby examples/rugl_debug_draw.rb
+
+gem install stagecraft
+ruby examples/stagecraft_debug_draw.rb
+```
+
+Both adapters consume the same `Box2DDebugLines` converter in
+`examples/support`, which turns debug callbacks into colored line-list
+vertices.
+
+## Verification
+
+`bundle exec rake` builds the CMake extension, checks all generated FFI struct
+layouts, and runs the complete spec suite. Deterministic 100-body fixtures live
+under `spec/snapshots/100_boxes` for every supported native-gem target. Update
+the fixture for the current platform after an intentional solver change with:
+
+```sh
+bundle exec rake snapshots:update
+```
+
+`bundle exec rake native:verify_package` additionally builds a platform gem,
+extracts its packaged library, and reruns the full suite against that exact
+artifact. Release CI performs this check for all five supported targets before
+uploading any gem.
+
+## Ownership and destruction
+
+`World` owns every native body, shape, chain, and joint. Ruby wrappers are
+non-owning ID values and do not use GC finalizers.
+
+Destroy resources explicitly:
+
+```ruby
+shape.destroy
+body.destroy
+joint.destroy
+world.destroy # destroys all remaining children
+```
+
+Access through a destroyed handle raises `Box2D::UseAfterDestroyError`. Ruby
+objects assigned as `user_data` are held in world-side registries; Ruby object
+pointers are never written to Box2D's native `void*` fields.
+
+## Native API
+
+All 409 exported Box2D 3.1.0 functions are available under `Box2D::Native`.
+Structs, enums, and function signatures are generated from the vendored headers:
+
+```ruby
+version = Box2D::Native.b2GetVersion
+p [version[:major], version[:minor], version[:revision]]
+```
+
+Set `BOX2D_LIBRARY_PATH` to load a compatible external Box2D shared library
+instead of the bundled extension.
+
+## Development
+
+Install dependencies and run the complete quality gate:
+
+```sh
+bundle install
+bundle exec rake
+```
+
+The default task:
+
+1. builds the vendored native library;
+2. checks that generated FFI declarations match the headers;
+3. compiles a C layout probe and checks all 71 struct sizes, alignments, and
+   field offsets;
+4. runs the RSpec suite, including 1000 steps under `GC.stress`.
+
+Useful tasks:
+
+```sh
+bundle exec rake bindings:generate
+bundle exec rake bindings:check
+bundle exec rake native:compile
+bundle exec rake native:package
+bundle exec rake build
+```
+
+See `examples/` for complete runnable scripts.
+
+## License
+
+The Ruby binding is available under the MIT License. Vendored Box2D source is
+also MIT licensed; its license is included at
+`ext/box2d/vendor/box2d/LICENSE`.

data/examples/contact_events.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "box2d"
+
+world = nil
+begin
+  world = Box2D::World.new
+  world.create_body(position: [0, -1], user_data: :ground) { |body| body.box(10, 1) }
+  world.create_body(type: :dynamic, position: [0, 4], user_data: :ball) do |body|
+    body.circle(radius: 0.5)
+  end
+
+  120.times do
+    world.step(1.0 / 60)
+    world.events.begin_contacts.each do |contact|
+      names = [contact.shape_a.body.user_data, contact.shape_b.body.user_data]
+      puts "contact began: #{names.join(" <-> ")}"
+    end
+  end
+ensure
+  world&.destroy if world&.valid?
+end

data/examples/debug_draw.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "box2d"
+
+world = nil
+begin
+  world = Box2D::World.new
+  world.create_body { |body| body.box(2, 1) }
+
+  world.debug_draw(flags: [:shapes, :aabbs]) do |command|
+    p command
+  end
+ensure
+  world&.destroy if world&.valid?
+end

data/examples/falling_ball.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "box2d"
+
+world = nil
+begin
+  world = Box2D::World.new
+  world.create_body(position: [0, -1]) { |body| body.box(10, 1) }
+  ball = world.create_body(type: :dynamic, position: [0, 4]) do |body|
+    body.circle(radius: 0.5, restitution: 0.6)
+  end
+
+  120.times do |frame|
+    world.step(1.0 / 60)
+    puts format("%3d: x=% .3f y=% .3f", frame, *ball.position)
+  end
+ensure
+  world&.destroy if world&.valid?
+end

data/examples/rugl_debug_draw.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "box2d"
+require "rugl"
+require_relative "support/box2d_debug_lines"
+
+world = nil
+rugl = nil
+at_exit do
+  world&.destroy if world&.valid?
+  rugl&.destroy unless rugl&.destroyed?
+end
+
+world = Box2D::World.new
+world.create_body(position: [0, -1]) { |body| body.box(8, 1) }
+10.times do |index|
+  world.create_body(type: :dynamic, position: [(index % 5) - 2, 1 + index / 5.0]) do |body|
+    body.box(0.4, 0.4)
+  end
+end
+
+rugl = Rugl.create(width: 960, height: 720, title: "Box2D debug draw")
+positions = rugl.buffer(data: [], usage: :stream)
+colors = rugl.buffer(data: [], usage: :stream)
+draw_lines = rugl.command(
+  vert: <<~GLSL,
+    #version 410 core
+    layout(location = 0) in vec2 position;
+    layout(location = 1) in vec4 color;
+    out vec4 vertexColor;
+    void main() {
+      gl_Position = vec4(position * vec2(0.1, 0.12) + vec2(0.0, -0.65), 0.0, 1.0);
+      vertexColor = color;
+    }
+  GLSL
+  frag: <<~GLSL,
+    #version 410 core
+    in vec4 vertexColor;
+    out vec4 fragColor;
+    void main() {
+      fragColor = vertexColor;
+    }
+  GLSL
+  attributes: {
+    position: {buffer: positions, size: 2},
+    color: {buffer: colors, size: 4}
+  },
+  count: Rugl.prop(:count),
+  primitive: :lines,
+  line_width: 1.5
+)
+
+lines = Box2DDebugLines.new
+stepper = Box2D::FixedStepper.new(hz: 60)
+previous_time = 0.0
+rugl.frame do |context|
+  delta_time = context[:time] - previous_time
+  previous_time = context[:time]
+  stepper.advance(delta_time) { |step| world.step(step) }
+
+  lines.clear
+  world.debug_draw(flags: [:shapes, :joints]) { |command| lines << command }
+  positions.update(data: lines.positions)
+  colors.update(data: lines.colors)
+
+  rugl.clear(color: [0.04, 0.05, 0.08, 1.0])
+  draw_lines.call(count: lines.positions.length)
+end

data/examples/stagecraft_debug_draw.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "box2d"
+require "stagecraft"
+require_relative "support/box2d_debug_lines"
+
+world = nil
+app = nil
+at_exit do
+  world&.destroy if world&.valid?
+  if app && !app.renderer.disposed?
+    app.renderer.dispose
+    app.window.close
+  end
+end
+
+world = Box2D::World.new
+world.create_body(position: [0, -1]) { |body| body.box(8, 1) }
+10.times do |index|
+  world.create_body(type: :dynamic, position: [(index % 5) - 2, 1 + index / 5.0]) do |body|
+    body.circle(radius: 0.4)
+  end
+end
+
+app = Stagecraft::App.new(title: "Box2D debug draw", width: 960, height: 720)
+scene = Stagecraft::Scene.new
+scene.background = "#0a0d14"
+camera = Stagecraft::Cameras::Orthographic.new(
+  left: -10, right: 10, top: 12, bottom: -3, near: 0.1, far: 20
+)
+camera.position.z = 10
+
+geometry = Stagecraft::Geometry.new(topology: :line_list)
+geometry.set_attribute(:position, data: "".b, format: :float32x3, count: 0)
+geometry.set_attribute(:color, data: "".b, format: :float32x4, count: 0)
+mesh = Stagecraft::Mesh.new(geometry, Stagecraft::Materials::Unlit.new)
+mesh.frustum_culled = false
+scene.add(mesh)
+
+lines = Box2DDebugLines.new
+stepper = Box2D::FixedStepper.new(hz: 60)
+app.run do |delta_time|
+  stepper.advance(delta_time) { |step| world.step(step) }
+  lines.clear
+  world.debug_draw(flags: [:shapes, :joints]) { |command| lines << command }
+
+  next_geometry = Stagecraft::Geometry.new(topology: :line_list)
+  next_geometry.set_attribute(
+    :position,
+    data: lines.positions.flat_map { |x, y| [x, y, 0.0] }.pack("e*"),
+    format: :float32x3,
+    count: lines.positions.length
+  )
+  next_geometry.set_attribute(
+    :color,
+    data: lines.colors.flatten.pack("e*"),
+    format: :float32x4,
+    count: lines.colors.length
+  )
+  mesh.geometry = next_geometry
+  geometry.dispose
+  geometry = next_geometry
+  app.renderer.render(scene, camera)
+end

data/examples/support/box2d_debug_lines.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+class Box2DDebugLines
+  CIRCLE_SEGMENTS = 24
+
+  attr_reader :positions, :colors
+
+  def initialize
+    clear
+  end
+
+  def clear
+    @positions = []
+    @colors = []
+    self
+  end
+
+  def <<(command)
+    type, *arguments = command
+    case type
+    when :polygon
+      points, color = arguments
+      add_loop(points, color)
+    when :solid_polygon
+      transform, points, _radius, color = arguments
+      add_loop(transform_points(points, transform), color)
+    when :circle
+      center, radius, color = arguments
+      add_circle(center, radius, color)
+    when :solid_circle
+      transform, radius, color = arguments
+      add_circle(transform.fetch(:position), radius, color)
+    when :solid_capsule
+      point1, point2, radius, color = arguments
+      add_capsule(point1, point2, radius, color)
+    when :segment
+      point1, point2, color = arguments
+      add_segment(point1, point2, color)
+    when :transform
+      add_transform(arguments.fetch(0))
+    when :point
+      point, _size, color = arguments
+      add_point(point, color)
+    end
+    self
+  end
+
+  private
+
+  def add_loop(points, color)
+    return if points.empty?
+
+    points.each_with_index do |point, index|
+      add_segment(point, points[(index + 1) % points.length], color)
+    end
+  end
+
+  def add_circle(center, radius, color)
+    points = CIRCLE_SEGMENTS.times.map do |index|
+      angle = index * Math::PI * 2 / CIRCLE_SEGMENTS
+      [center[0] + Math.cos(angle) * radius, center[1] + Math.sin(angle) * radius]
+    end
+    add_loop(points, color)
+  end
+
+  def add_capsule(point1, point2, radius, color)
+    add_circle(point1, radius, color)
+    add_circle(point2, radius, color)
+    dx = point2[0] - point1[0]
+    dy = point2[1] - point1[1]
+    length = Math.hypot(dx, dy)
+    return if length.zero?
+
+    normal = [-dy * radius / length, dx * radius / length]
+    add_segment(offset(point1, normal), offset(point2, normal), color)
+    add_segment(offset(point1, normal, -1), offset(point2, normal, -1), color)
+  end
+
+  def add_transform(transform)
+    origin = transform.fetch(:position)
+    angle = transform.fetch(:angle)
+    x_axis = [origin[0] + Math.cos(angle) * 0.4, origin[1] + Math.sin(angle) * 0.4]
+    y_axis = [origin[0] - Math.sin(angle) * 0.4, origin[1] + Math.cos(angle) * 0.4]
+    add_segment(origin, x_axis, 0xFF0000)
+    add_segment(origin, y_axis, 0x00FF00)
+  end
+
+  def add_point(point, color)
+    add_segment([point[0] - 0.05, point[1]], [point[0] + 0.05, point[1]], color)
+    add_segment([point[0], point[1] - 0.05], [point[0], point[1] + 0.05], color)
+  end
+
+  def add_segment(point1, point2, color)
+    rgba = hex_color(color)
+    @positions.push(point1.to_a, point2.to_a)
+    @colors.push(rgba, rgba)
+  end
+
+  def transform_points(points, transform)
+    position = transform.fetch(:position)
+    angle = transform.fetch(:angle)
+    cosine = Math.cos(angle)
+    sine = Math.sin(angle)
+    points.map do |x, y|
+      [
+        position[0] + x * cosine - y * sine,
+        position[1] + x * sine + y * cosine
+      ]
+    end
+  end
+
+  def offset(point, normal, direction = 1)
+    [point[0] + normal[0] * direction, point[1] + normal[1] * direction]
+  end
+
+  def hex_color(value)
+    color = Integer(value) & 0xFFFFFF
+    [
+      ((color >> 16) & 0xFF) / 255.0,
+      ((color >> 8) & 0xFF) / 255.0,
+      (color & 0xFF) / 255.0,
+      1.0
+    ]
+  end
+end