box2d-ruby 1.0.0

data/lib/box2d/native_loader.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Box2D
+  module NativeLoader
+    module_function
+
+    ENVIRONMENT_KEY = "BOX2D_LIBRARY_PATH"
+    EXTENSION_NAME = "native.#{RbConfig::CONFIG.fetch("DLEXT")}"
+
+    def library_path
+      explicit_path = ENV[ENVIRONMENT_KEY]
+      return validate_explicit_path(explicit_path) if explicit_path
+
+      path = candidates.find { |candidate| File.file?(candidate) }
+      return path if path
+
+      raise LoadError, missing_library_message
+    end
+
+    def candidates
+      relative_path = File.join("box2d", EXTENSION_NAME)
+      load_path_candidates = $LOAD_PATH.map { |path| File.expand_path(relative_path, path) }
+      source_candidate = File.expand_path("../../ext/box2d/#{EXTENSION_NAME}", __dir__)
+
+      (load_path_candidates << source_candidate).uniq
+    end
+
+    def validate_explicit_path(path)
+      expanded_path = File.expand_path(path)
+      return expanded_path if File.file?(expanded_path)
+
+      raise LoadError, "#{ENVIRONMENT_KEY} does not point to a file: #{expanded_path}"
+    end
+
+    def missing_library_message
+      <<~MESSAGE.chomp
+        Box2D native library was not found. Reinstall the gem to build it, run
+        `bundle exec rake native:compile` from a source checkout, or set
+        #{ENVIRONMENT_KEY} to a compatible Box2D 3.1 shared library.
+      MESSAGE
+    end
+  end
+end

data/lib/box2d/pixel_scale.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Box2D
+  class PixelScale
+    attr_reader :pixels_per_meter
+
+    def initialize(pixels_per_meter = 32)
+      @pixels_per_meter = ValueConversion.positive_float(pixels_per_meter, label: "pixels_per_meter")
+    end
+
+    def to_pixels(meters)
+      ValueConversion.finite_float(meters, label: "meters") * @pixels_per_meter
+    end
+
+    def to_meters(pixels)
+      ValueConversion.finite_float(pixels, label: "pixels") / @pixels_per_meter
+    end
+
+    def vector_to_pixels(vector)
+      x, y = vector
+      [to_pixels(x), to_pixels(y)]
+    end
+
+    def vector_to_meters(vector)
+      x, y = vector
+      [to_meters(x), to_meters(y)]
+    end
+  end
+end

data/lib/box2d/shape.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Box2D
+  class Shape < Handle
+    ID_CLASS = Native::ShapeId
+    TYPES = {
+      Native::ShapeType::CIRCLE_SHAPE => :circle,
+      Native::ShapeType::CAPSULE_SHAPE => :capsule,
+      Native::ShapeType::SEGMENT_SHAPE => :segment,
+      Native::ShapeType::POLYGON_SHAPE => :polygon,
+      Native::ShapeType::CHAIN_SEGMENT_SHAPE => :chain_segment
+    }.freeze
+
+    attr_reader :body
+
+    def initialize(world, id, body: nil)
+      super(world, id)
+      @body = body
+    end
+
+    def destroy
+      ensure_valid!
+      Native.b2DestroyShape(@id, true)
+      invalidate!
+      @world.unregister_shape(self)
+      @body&.unregister_shape(self)
+      true
+    end
+
+    def type
+      ensure_valid!
+      TYPES.fetch(Native.b2Shape_GetType(@id))
+    end
+
+    def sensor?
+      ensure_valid!
+      Native.b2Shape_IsSensor(@id)
+    end
+
+    def density
+      ensure_valid!
+      Native.b2Shape_GetDensity(@id)
+    end
+
+    def density=(value)
+      ensure_valid!
+      Native.b2Shape_SetDensity(@id, ValueConversion.non_negative_float(value, label: "density"), true)
+    end
+
+    def friction
+      ensure_valid!
+      Native.b2Shape_GetFriction(@id)
+    end
+
+    def friction=(value)
+      ensure_valid!
+      Native.b2Shape_SetFriction(@id, ValueConversion.non_negative_float(value, label: "friction"))
+    end
+
+    def restitution
+      ensure_valid!
+      Native.b2Shape_GetRestitution(@id)
+    end
+
+    def restitution=(value)
+      ensure_valid!
+      Native.b2Shape_SetRestitution(@id, ShapeDefinition.coefficient(value, "restitution"))
+    end
+
+    def filter
+      ensure_valid!
+      native_filter = Native.b2Shape_GetFilter(@id)
+      {
+        category: native_filter[:categoryBits],
+        mask: native_filter[:maskBits],
+        group: native_filter[:groupIndex]
+      }
+    end
+
+    def filter=(options)
+      ensure_valid!
+      native_filter = Native.b2Shape_GetFilter(@id)
+      ShapeDefinition.apply_filter(native_filter, options)
+      Native.b2Shape_SetFilter(@id, native_filter)
+    end
+
+    def user_data
+      ensure_valid!
+      @world.shape_user_data(self)
+    end
+
+    def user_data=(value)
+      ensure_valid!
+      @world.set_shape_user_data(self, value)
+    end
+
+    def aabb
+      ensure_valid!
+      bounds = Native.b2Shape_GetAABB(@id)
+      [ValueConversion.vec2(bounds[:lowerBound]), ValueConversion.vec2(bounds[:upperBound])]
+    end
+
+    protected
+
+    def native_valid?
+      Native.b2Shape_IsValid(@id)
+    end
+  end
+end

data/lib/box2d/shape_definition.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Box2D
+  module ShapeDefinition
+    module_function
+
+    def build(options)
+      definition = Native.b2DefaultShapeDef
+      material = definition[:material]
+      material[:friction] = ValueConversion.non_negative_float(options.fetch(:friction, 0.6), label: "friction")
+      material[:restitution] = coefficient(options.fetch(:restitution, 0.0), "restitution")
+      material[:rollingResistance] = coefficient(options.fetch(:rolling_resistance, 0.0), "rolling_resistance")
+      material[:tangentSpeed] = ValueConversion.finite_float(options.fetch(:tangent_speed, 0.0), label: "tangent_speed")
+      material[:userMaterialId] = Integer(options.fetch(:material, 0))
+      definition[:density] = ValueConversion.non_negative_float(options.fetch(:density, 1.0), label: "density")
+      definition[:isSensor] = !!options.fetch(:sensor, false)
+      definition[:enableSensorEvents] = !!options.fetch(:sensor_events, true)
+      definition[:enableContactEvents] = !!options.fetch(:contact_events, true)
+      definition[:enableHitEvents] = !!options.fetch(:hit_events, true)
+      apply_filter(definition[:filter], options.fetch(:filter, {}))
+      definition
+    end
+
+    def query_filter(options)
+      filter = Native.b2DefaultQueryFilter
+      filter[:categoryBits] = Integer(options.fetch(:category, filter[:categoryBits]))
+      filter[:maskBits] = Integer(options.fetch(:mask, filter[:maskBits]))
+      filter
+    end
+
+    def apply_filter(filter, options)
+      filter[:categoryBits] = Integer(options.fetch(:category, filter[:categoryBits]))
+      filter[:maskBits] = Integer(options.fetch(:mask, filter[:maskBits]))
+      filter[:groupIndex] = Integer(options.fetch(:group, filter[:groupIndex]))
+    end
+
+    def coefficient(value, label)
+      number = ValueConversion.non_negative_float(value, label:)
+      return number if number <= 1.0
+
+      raise ArgumentError, "#{label} must be between 0 and 1"
+    end
+  end
+end

data/lib/box2d/value_conversion.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Box2D
+  module ValueConversion
+    module_function
+
+    def native_vec2(value, label: "vector")
+      x, y = pair(value, label:)
+      Native::Vec2.new.tap do |vector|
+        vector[:x] = finite_float(x, label: "#{label}.x")
+        vector[:y] = finite_float(y, label: "#{label}.y")
+      end
+    end
+
+    def native_rot(angle)
+      radians = finite_float(angle, label: "angle")
+      Native::Rot.new.tap do |rotation|
+        rotation[:c] = Math.cos(radians)
+        rotation[:s] = Math.sin(radians)
+      end
+    end
+
+    def vec2(value)
+      x = value[:x]
+      y = value[:y]
+      return Larb::Vec2.new(x, y) if defined?(Larb::Vec2)
+
+      [x, y]
+    end
+
+    def finite_float(value, label:)
+      number = Float(value)
+      return number if number.finite?
+
+      raise ArgumentError, "#{label} must be finite"
+    rescue TypeError, ArgumentError
+      raise ArgumentError, "#{label} must be a finite number"
+    end
+
+    def positive_float(value, label:)
+      number = finite_float(value, label:)
+      return number if number.positive?
+
+      raise ArgumentError, "#{label} must be greater than zero"
+    end
+
+    def non_negative_float(value, label:)
+      number = finite_float(value, label:)
+      return number if number >= 0.0
+
+      raise ArgumentError, "#{label} must be non-negative"
+    end
+
+    def copy_struct(struct_class, value)
+      struct_class.new.tap do |copy|
+        copy.pointer.put_bytes(0, value.pointer.read_bytes(struct_class.size))
+      end
+    end
+
+    def id_key(id)
+      members = id.class.members
+      key = Integer(id[:index1]) | (Integer(id[:generation]) << 32)
+      return key unless members.include?(:world0)
+
+      key | (Integer(id[:world0]) << 48)
+    end
+
+    def pair(value, label:)
+      pair = if value.respond_to?(:to_ary)
+        value.to_ary
+      elsif value.respond_to?(:x) && value.respond_to?(:y)
+        [value.x, value.y]
+      end
+      return pair if pair&.length == 2
+
+      raise ArgumentError, "#{label} must contain exactly two components"
+    end
+    private_class_method :pair
+  end
+end

data/lib/box2d/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Box2D
+  VERSION = "1.0.0"
+end
+
+Box2d = Box2D unless Object.const_defined?(:Box2d)

data/lib/box2d/world.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Box2D
+  class World
+    include WorldRegistry
+    include BodyDefinition
+    include WorldJoints
+    include WorldQueries
+
+    BODY_TYPES = Body::TYPE_VALUES
+
+    attr_reader :id
+
+    def initialize(gravity: [0, -9.8], substeps: 4, sleep: true, continuous: true)
+      definition = Native.b2DefaultWorldDef
+      definition[:gravity] = ValueConversion.native_vec2(gravity, label: "gravity")
+      definition[:enableSleep] = !!sleep
+      definition[:enableContinuous] = !!continuous
+
+      @id = Native.b2CreateWorld(definition.pointer)
+      @destroyed = false
+      @stepping = false
+      @drawing = false
+      initialize_registries
+      @events = Events.empty
+      self.substeps = substeps
+
+      yield self if block_given?
+    rescue Exception
+      destroy if @id && !@destroyed
+      raise
+    end
+
+    def valid?
+      raise ReentrantStepError, "the world cannot be accessed during a native operation" if @stepping || @drawing
+
+      !@destroyed && Native.b2World_IsValid(@id)
+    end
+
+    def destroyed?
+      !valid?
+    end
+
+    def destroy
+      return false if @destroyed
+
+      ensure_access!
+      Native.b2DestroyWorld(@id)
+      @destroyed = true
+      clear_registries
+      @events = Events.empty
+      true
+    end
+
+    def substeps
+      @substeps
+    end
+
+    def substeps=(value)
+      count = Integer(value)
+      raise ArgumentError, "substeps must be greater than zero" unless count.positive?
+
+      @substeps = count
+    end
+
+    def gravity
+      ensure_access!
+      ValueConversion.vec2(Native.b2World_GetGravity(@id))
+    end
+
+    def gravity=(value)
+      ensure_access!
+      Native.b2World_SetGravity(@id, ValueConversion.native_vec2(value, label: "gravity"))
+    end
+
+    def step(delta_time)
+      ensure_access!
+      time_step = ValueConversion.non_negative_float(delta_time, label: "delta_time")
+      @stepping = true
+      begin
+        Native.b2World_Step(@id, time_step, @substeps)
+        @events = Events.capture(self)
+        self
+      ensure
+        @stepping = false
+      end
+    end
+
+    def events
+      ensure_access!
+      @events
+    end
+
+    def create_body(type: :static, position: [0, 0], angle: 0, **options)
+      ensure_access!
+      definition = build_body_definition(type:, position:, angle:, options:)
+      body = Body.new(self, Native.b2CreateBody(@id, definition.pointer))
+      register_body(body)
+      body.user_data = options[:user_data] if options.key?(:user_data)
+
+      begin
+        yield body if block_given?
+      rescue Exception
+        body.destroy if body.valid?
+        raise
+      end
+      body
+    end
+
+    def debug_draw(flags: [:shapes])
+      raise ArgumentError, "a debug draw block is required" unless block_given?
+
+      ensure_access!
+      @debug_draw = DebugDraw.new(flags) { |command| yield command }
+      @drawing = true
+      begin
+        Native.b2World_Draw(@id, @debug_draw.definition.pointer)
+      ensure
+        @drawing = false
+      end
+      @debug_draw.raise_callback_error
+      self
+    end
+
+    def ensure_access!
+      raise UseAfterDestroyError, "Box2D::World has been destroyed" if @destroyed
+      if @stepping || @drawing
+        raise ReentrantStepError, "the world cannot be accessed during a native operation"
+      end
+
+      true
+    end
+
+  end
+end

data/lib/box2d/world_joints.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Box2D
+  module WorldJoints
+    def create_revolute_joint(body_a:, body_b:, anchor:, limits: nil, motor: nil, spring: nil, **options)
+      create_typed_joint(:revolute, body_a:, body_b:, options:) do |definition|
+        definition[:localAnchorA] = local_point(body_a, anchor)
+        definition[:localAnchorB] = local_point(body_b, anchor)
+        definition[:referenceAngle] = body_b.angle - body_a.angle
+        configure_limits(definition, limits, :lowerAngle, :upperAngle)
+        configure_motor(definition, motor, maximum: :maxMotorTorque)
+        configure_spring(definition, spring)
+      end
+    end
+
+    def create_prismatic_joint(body_a:, body_b:, anchor:, axis: [1, 0], limits: nil, motor: nil, spring: nil, **options)
+      create_typed_joint(:prismatic, body_a:, body_b:, options:) do |definition|
+        definition[:localAnchorA] = local_point(body_a, anchor)
+        definition[:localAnchorB] = local_point(body_b, anchor)
+        definition[:localAxisA] = Native.b2Body_GetLocalVector(
+          body_a.id,
+          ValueConversion.native_vec2(axis, label: "axis")
+        )
+        definition[:referenceAngle] = body_b.angle - body_a.angle
+        configure_limits(definition, limits, :lowerTranslation, :upperTranslation)
+        configure_motor(definition, motor, maximum: :maxMotorForce)
+        configure_spring(definition, spring)
+      end
+    end
+
+    def create_distance_joint(body_a:, body_b:, anchor_a: nil, anchor_b: nil, length: nil, limits: nil,
+      motor: nil, spring: nil, **options)
+      point_a = anchor_a || body_a.position
+      point_b = anchor_b || body_b.position
+      create_typed_joint(:distance, body_a:, body_b:, options:) do |definition|
+        definition[:localAnchorA] = local_point(body_a, point_a)
+        definition[:localAnchorB] = local_point(body_b, point_b)
+        definition[:length] = length ? ValueConversion.positive_float(length, label: "length") : distance(point_a, point_b)
+        configure_limits(definition, limits, :minLength, :maxLength)
+        configure_motor(definition, motor, maximum: :maxMotorForce)
+        configure_spring(definition, spring)
+      end
+    end
+
+    def create_mouse_joint(body_a:, body_b:, target:, max_force:, hertz: 5.0, damping_ratio: 0.7, **options)
+      create_typed_joint(:mouse, body_a:, body_b:, options:) do |definition|
+        definition[:target] = ValueConversion.native_vec2(target, label: "target")
+        definition[:maxForce] = ValueConversion.positive_float(max_force, label: "max_force")
+        definition[:hertz] = ValueConversion.non_negative_float(hertz, label: "hertz")
+        definition[:dampingRatio] = ValueConversion.non_negative_float(damping_ratio, label: "damping_ratio")
+      end
+    end
+
+    def create_weld_joint(body_a:, body_b:, anchor:, linear: nil, angular: nil, **options)
+      create_typed_joint(:weld, body_a:, body_b:, options:) do |definition|
+        definition[:localAnchorA] = local_point(body_a, anchor)
+        definition[:localAnchorB] = local_point(body_b, anchor)
+        definition[:referenceAngle] = body_b.angle - body_a.angle
+        configure_weld_spring(definition, linear, :linear)
+        configure_weld_spring(definition, angular, :angular)
+      end
+    end
+
+    private
+
+    JOINT_TYPES = {
+      revolute: [Native.method(:b2DefaultRevoluteJointDef), Native.method(:b2CreateRevoluteJoint), RevoluteJoint],
+      prismatic: [Native.method(:b2DefaultPrismaticJointDef), Native.method(:b2CreatePrismaticJoint), PrismaticJoint],
+      distance: [Native.method(:b2DefaultDistanceJointDef), Native.method(:b2CreateDistanceJoint), DistanceJoint],
+      mouse: [Native.method(:b2DefaultMouseJointDef), Native.method(:b2CreateMouseJoint), MouseJoint],
+      weld: [Native.method(:b2DefaultWeldJointDef), Native.method(:b2CreateWeldJoint), WeldJoint]
+    }.freeze
+
+    def create_typed_joint(type, body_a:, body_b:, options:)
+      ensure_access!
+      validate_joint_bodies(body_a, body_b)
+      default_function, create_function, wrapper_class = JOINT_TYPES.fetch(type)
+      definition = default_function.call
+      definition[:bodyIdA] = body_a.id
+      definition[:bodyIdB] = body_b.id
+      definition[:collideConnected] = !!options.fetch(:collide_connected, false)
+      yield definition
+
+      joint = wrapper_class.new(
+        self,
+        create_function.call(@id, definition.pointer),
+        body_a:,
+        body_b:,
+        user_data: options[:user_data]
+      )
+      body_a.register_joint(joint)
+      body_b.register_joint(joint)
+      register_joint(joint)
+    end
+
+    def validate_joint_bodies(body_a, body_b)
+      raise ArgumentError, "joint bodies must be distinct" if body_a.equal?(body_b)
+      raise ArgumentError, "joint bodies must belong to this world" unless body_a.world.equal?(self) && body_b.world.equal?(self)
+      raise UseAfterDestroyError, "joint body has been destroyed" unless body_a.valid? && body_b.valid?
+    end
+
+    def local_point(body, point)
+      Native.b2Body_GetLocalPoint(body.id, ValueConversion.native_vec2(point, label: "anchor"))
+    end
+
+    def configure_limits(definition, limits, lower_field, upper_field)
+      return unless limits
+
+      lower = ValueConversion.finite_float(limits.begin, label: "lower_limit")
+      upper = ValueConversion.finite_float(limits.end, label: "upper_limit")
+      raise ArgumentError, "lower limit must not exceed upper limit" if lower > upper
+
+      definition[:enableLimit] = true
+      definition[lower_field] = lower
+      definition[upper_field] = upper
+    end
+
+    def configure_motor(definition, motor, maximum:)
+      return unless motor
+
+      definition[:enableMotor] = true
+      definition[:motorSpeed] = ValueConversion.finite_float(motor.fetch(:speed, 0), label: "motor.speed")
+      definition[maximum] = ValueConversion.non_negative_float(
+        motor.fetch(maximum == :maxMotorTorque ? :max_torque : :max_force),
+        label: "motor maximum"
+      )
+    end
+
+    def configure_spring(definition, spring)
+      return unless spring
+
+      definition[:enableSpring] = true
+      definition[:hertz] = ValueConversion.non_negative_float(spring.fetch(:hertz), label: "spring.hertz")
+      definition[:dampingRatio] = ValueConversion.non_negative_float(
+        spring.fetch(:damping_ratio, 0.7),
+        label: "spring.damping_ratio"
+      )
+    end
+
+    def configure_weld_spring(definition, spring, prefix)
+      return unless spring
+
+      definition[:"#{prefix}Hertz"] = ValueConversion.non_negative_float(spring.fetch(:hertz), label: "#{prefix}.hertz")
+      definition[:"#{prefix}DampingRatio"] = ValueConversion.non_negative_float(
+        spring.fetch(:damping_ratio, 0.7),
+        label: "#{prefix}.damping_ratio"
+      )
+    end
+
+    def distance(point_a, point_b)
+      vector_a = ValueConversion.native_vec2(point_a, label: "anchor_a")
+      vector_b = ValueConversion.native_vec2(point_b, label: "anchor_b")
+      Math.hypot(vector_b[:x] - vector_a[:x], vector_b[:y] - vector_a[:y])
+    end
+  end
+end