jolt-ruby 1.0.0

data/lib/jolt/constraint_collection.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Jolt
+  class ConstraintCollection
+    include Enumerable
+
+    class << self
+      def interval(value, name)
+        values = value.is_a?(Range) ? [value.begin, value.end] : value.to_a
+        raise InvalidArgumentError, "#{name} must contain two values" unless values.length == 2
+
+        minimum = Conversions.finite_float(values[0], "#{name} minimum")
+        maximum = Conversions.finite_float(values[1], "#{name} maximum")
+        raise InvalidArgumentError, "#{name} minimum must not exceed maximum" if minimum > maximum
+
+        [minimum, maximum]
+      rescue NoMethodError
+        raise InvalidArgumentError, "#{name} must be a Range or two-element array"
+      end
+    end
+
+    def initialize(system)
+      @system = system
+    end
+
+    def fixed(body_a:, body_b:, anchor: nil)
+      create(:fixed, :JR_Constraint_CreateFixed, body_a, body_b, optional_vec(anchor, "anchor"))
+    end
+
+    def point(body_a:, body_b:, anchor:)
+      create(:point, :JR_Constraint_CreatePoint, body_a, body_b, vec(anchor, "anchor"))
+    end
+
+    def distance(body_a:, body_b:, point_a: nil, point_b: nil, limits: nil)
+      validate_body_pair(body_a, body_b)
+      point_a ||= body_a.position
+      point_b ||= body_b.position
+      minimum, maximum = limits ? self.class.interval(limits, "limits") : [-1.0, -1.0]
+      create(
+        :distance, :JR_Constraint_CreateDistance, body_a, body_b,
+        vec(point_a, "point_a"), vec(point_b, "point_b"), minimum, maximum
+      )
+    end
+
+    def hinge(body_a:, body_b:, anchor:, axis: [0, 1, 0], normal: nil, limits: nil)
+      axis = unit_vec(axis, "axis")
+      normal = normal ? unit_vec(normal, "normal") : perpendicular(axis)
+      has_limits, minimum, maximum = optional_interval(limits)
+      create(
+        :hinge, :JR_Constraint_CreateHinge, body_a, body_b,
+        vec(anchor, "anchor"), axis, normal, has_limits, minimum, maximum
+      )
+    end
+
+    def slider(body_a:, body_b:, anchor:, axis:, limits: nil)
+      has_limits, minimum, maximum = optional_interval(limits)
+      create(
+        :slider, :JR_Constraint_CreateSlider, body_a, body_b,
+        vec(anchor, "anchor"), unit_vec(axis, "axis"), has_limits, minimum, maximum
+      )
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block
+
+      @system.__constraints_snapshot.each(&block)
+    end
+
+    def size
+      @system.__constraints_snapshot.size
+    end
+    alias length size
+
+    private
+
+    def create(kind, function, body_a, body_b, *arguments)
+      validate_body_pair(body_a, body_b)
+      native_arguments = arguments.map { |argument| argument.is_a?(Native::Vec3) ? argument.pointer : argument }
+      pointer = Native.public_send(
+        function, @system.__native_pointer, body_a.id, body_b.id, *native_arguments
+      )
+      raise InitializationError, "failed to create #{kind} constraint" if pointer.null?
+
+      Constraint.new(@system, pointer, kind, body_a, body_b).tap do |constraint|
+        @system.__register_constraint(constraint)
+      end
+    end
+
+    def validate_body_pair(body_a, body_b)
+      [body_a, body_b].each do |body|
+        unless body.is_a?(Body) && body.system.equal?(@system) && !body.destroyed?
+          raise InvalidArgumentError, "constraint bodies must be live bodies from this system"
+        end
+      end
+      raise InvalidArgumentError, "constraint bodies must be different" if body_a.equal?(body_b)
+    end
+
+    def vec(value, name)
+      Conversions.native_vec3(value, name:)
+    end
+
+    def unit_vec(value, name)
+      Conversions.native_unit_vec3(value, name:)
+    end
+
+    def optional_vec(value, name)
+      value.nil? ? nil : vec(value, name)
+    end
+
+    def optional_interval(value)
+      return [false, 0.0, 0.0] if value.nil?
+
+      [true, *self.class.interval(value, "limits")]
+    end
+
+    def perpendicular(axis)
+      x, y, z = %i[x y z].map { |component| axis[component] }
+      reference = y.abs < 0.9 ? [0.0, 1.0, 0.0] : [1.0, 0.0, 0.0]
+      rx, ry, rz = reference
+      unit_vec([y * rz - z * ry, z * rx - x * rz, x * ry - y * rx], "normal")
+    end
+  end
+end

data/lib/jolt/contact_events.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Jolt
+  Contact = Data.define(
+    :body_a,
+    :body_b,
+    :sub_shape_a,
+    :sub_shape_b,
+    :point,
+    :normal,
+    :penetration
+  )
+
+  ContactEvents = Data.define(:added, :persisted, :removed, :dropped_count) do
+    def self.empty
+      new(added: [].freeze, persisted: [].freeze, removed: [].freeze, dropped_count: 0)
+    end
+  end
+end

data/lib/jolt/conversions.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "larb"
+
+module Jolt
+  module Conversions
+    module_function
+
+    def native_vec3(value, name: "vector")
+      values = components(value, 3, name)
+      Native::Vec3.new.tap do |native|
+        native[:x], native[:y], native[:z] = values
+      end
+    end
+
+    def native_quat(value, name: "rotation")
+      values = components(value, 4, name)
+      length = Math.sqrt(values.sum { |component| component * component })
+      raise InvalidArgumentError, "#{name} must not be a zero quaternion" if length <= Float::EPSILON
+
+      values.map! { |component| component / length }
+      Native::Quat.new.tap do |native|
+        native[:x], native[:y], native[:z], native[:w] = values
+      end
+    end
+
+    def native_unit_vec3(value, name:)
+      native = native_vec3(value, name:)
+      length = Math.sqrt(%i[x y z].sum { |component| native[component]**2 })
+      raise InvalidArgumentError, "#{name} must not be zero" if length <= Float::EPSILON
+
+      %i[x y z].each { |component| native[component] /= length }
+      native
+    end
+
+    def vec3(native)
+      Larb::Vec3.new(native[:x], native[:y], native[:z])
+    end
+
+    def quat(native)
+      Larb::Quat.new(native[:x], native[:y], native[:z], native[:w])
+    end
+
+    def positive_float(value, name)
+      number = finite_float(value, name)
+      raise InvalidArgumentError, "#{name} must be greater than zero" unless number.positive?
+
+      number
+    end
+
+    def non_negative_float(value, name)
+      number = finite_float(value, name)
+      raise InvalidArgumentError, "#{name} must be non-negative" if number.negative?
+
+      number
+    end
+
+    def finite_float(value, name)
+      number = Float(value)
+      raise InvalidArgumentError, "#{name} must be finite" unless number.finite?
+
+      number
+    rescue TypeError, ArgumentError
+      raise InvalidArgumentError, "#{name} must be a number"
+    end
+
+    def components(value, count, name)
+      values = value.respond_to?(:to_a) ? value.to_a : nil
+      unless values&.length == count
+        raise InvalidArgumentError, "#{name} must contain exactly #{count} components"
+      end
+
+      values.map.with_index { |component, index| finite_float(component, "#{name}[#{index}]") }
+    end
+  end
+end

data/lib/jolt/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Jolt
+  class Error < StandardError; end
+  class NativeLoadError < Error; end
+  class InitializationError < Error; end
+  class InvalidArgumentError < Error; end
+  class UseAfterDestroyError < Error; end
+  class ConcurrentAccessError < Error; end
+  class ShapeError < Error; end
+  class PhysicsUpdateError < Error; end
+end

data/lib/jolt/fixed_stepper.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Jolt
+  class FixedStepper
+    attr_reader :step, :max_substeps
+
+    def initialize(hz: 60, max_substeps: 5)
+      frequency = Conversions.positive_float(hz, "hz")
+      unless max_substeps.is_a?(Integer) && max_substeps.positive?
+        raise InvalidArgumentError, "max_substeps must be a positive integer"
+      end
+
+      @step = 1.0 / frequency
+      @max_substeps = max_substeps
+      @accumulator = 0.0
+    end
+
+    def advance(delta_time)
+      raise ArgumentError, "a block is required" unless block_given?
+
+      @accumulator += Conversions.non_negative_float(delta_time, "delta_time")
+      substeps = 0
+      while @accumulator >= @step && substeps < @max_substeps
+        yield @step
+        @accumulator -= @step
+        substeps += 1
+      end
+      @accumulator %= @step if @accumulator >= @step
+      @accumulator / @step
+    end
+
+    def reset
+      @accumulator = 0.0
+      self
+    end
+  end
+end

data/lib/jolt/hit.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Jolt
+  Hit = Data.define(:body, :fraction, :point, :normal, :sub_shape_id)
+end

data/lib/jolt/layers.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Jolt
+  class Layers
+    class << self
+      def default
+        @default ||= define do |layers|
+          layers.broad_phase :static_bp, :dynamic_bp
+          layers.object :non_moving, broad_phase: :static_bp
+          layers.object :moving, broad_phase: :dynamic_bp
+          layers.collide :non_moving, with: :moving
+          layers.collide :moving, with: :moving
+        end
+      end
+
+      def define
+        builder = Builder.new
+        yield builder
+        builder.build
+      end
+    end
+
+    attr_reader :object_layers, :broad_phase_layers
+
+    def initialize(object_layers:, broad_phase_layers:, mappings:, collisions:)
+      @object_layers = object_layers.freeze
+      @broad_phase_layers = broad_phase_layers.freeze
+      @mappings = mappings.freeze
+      @collisions = collisions.freeze
+      freeze
+    end
+
+    def object_layer_id(name)
+      @object_layers.fetch(name.to_sym)
+    rescue KeyError
+      raise InvalidArgumentError, "unknown object layer: #{name.inspect}"
+    end
+
+    def native_resources
+      NativeResources.new(self, @mappings, @collisions)
+    end
+
+    class Builder
+      def initialize
+        @broad_phase_layers = {}
+        @object_layers = {}
+        @mappings = {}
+        @collisions = Set.new
+      end
+
+      def broad_phase(*names)
+        names.each { |name| add_named_layer(@broad_phase_layers, name, 256, "broad-phase") }
+      end
+
+      def object(*names, broad_phase:)
+        broad_name = normalize_name(broad_phase)
+        names.each do |name|
+          object_name = add_named_layer(@object_layers, name, nil, "object")
+          @mappings[object_name] = broad_name
+        end
+      end
+
+      def collide(layer, with:)
+        first = normalize_name(layer)
+        Array(with).each do |other|
+          second = normalize_name(other)
+          @collisions << [first, second].sort.freeze
+        end
+      end
+
+      def build
+        raise InvalidArgumentError, "at least one broad-phase layer is required" if @broad_phase_layers.empty?
+        raise InvalidArgumentError, "at least one object layer is required" if @object_layers.empty?
+
+        missing_mappings = @mappings.values.reject { |name| @broad_phase_layers.key?(name) }.uniq
+        unless missing_mappings.empty?
+          raise InvalidArgumentError, "unknown broad-phase layer(s): #{missing_mappings.join(", ")}"
+        end
+
+        collision_names = @collisions.to_a.flatten.uniq
+        missing_collisions = collision_names.reject { |name| @object_layers.key?(name) }
+        unless missing_collisions.empty?
+          raise InvalidArgumentError, "unknown collision layer(s): #{missing_collisions.join(", ")}"
+        end
+
+        Layers.new(
+          object_layers: @object_layers.dup,
+          broad_phase_layers: @broad_phase_layers.dup,
+          mappings: @mappings.dup,
+          collisions: @collisions.to_a
+        )
+      end
+
+      private
+
+      def add_named_layer(collection, name, limit, kind)
+        normalized = normalize_name(name)
+        raise InvalidArgumentError, "duplicate #{kind} layer: #{normalized}" if collection.key?(normalized)
+        raise InvalidArgumentError, "too many #{kind} layers" if limit && collection.length >= limit
+
+        collection[normalized] = collection.length
+        normalized
+      end
+
+      def normalize_name(name)
+        normalized = name.to_sym
+        raise InvalidArgumentError, "layer name must not be empty" if normalized.to_s.empty?
+
+        normalized
+      rescue NoMethodError
+        raise InvalidArgumentError, "layer name must be convertible to a symbol"
+      end
+    end
+
+    class NativeResources
+      attr_reader :broad_phase_interface, :object_pair_filter, :object_vs_broad_phase_filter
+
+      def initialize(layers, mappings, collisions)
+        @destroyed = false
+        create_filters(layers, mappings, collisions)
+      rescue StandardError
+        destroy
+        raise
+      end
+
+      def destroy
+        return if @destroyed
+
+        Native.JPH_ObjectVsBroadPhaseLayerFilter_Destroy(@object_vs_broad_phase_filter) if present?(@object_vs_broad_phase_filter)
+        Native.JPH_ObjectLayerPairFilter_Destroy(@object_pair_filter) if present?(@object_pair_filter)
+        Native.JPH_BroadPhaseLayerInterface_Destroy(@broad_phase_interface) if present?(@broad_phase_interface)
+        @destroyed = true
+      end
+
+      def transfer_to_system!
+        @destroyed = true
+      end
+
+      private
+
+      def create_filters(layers, mappings, collisions)
+        object_count = layers.object_layers.length
+        broad_count = layers.broad_phase_layers.length
+        @broad_phase_interface = Native.JPH_BroadPhaseLayerInterfaceTable_Create(object_count, broad_count)
+        check_pointer!(@broad_phase_interface, "broad-phase layer interface")
+
+        mappings.each do |object_name, broad_name|
+          Native.JPH_BroadPhaseLayerInterfaceTable_MapObjectToBroadPhaseLayer(
+            @broad_phase_interface,
+            layers.object_layers.fetch(object_name),
+            layers.broad_phase_layers.fetch(broad_name)
+          )
+        end
+
+        @object_pair_filter = Native.JPH_ObjectLayerPairFilterTable_Create(object_count)
+        check_pointer!(@object_pair_filter, "object layer pair filter")
+        collisions.each do |first, second|
+          Native.JPH_ObjectLayerPairFilterTable_EnableCollision(
+            @object_pair_filter,
+            layers.object_layers.fetch(first),
+            layers.object_layers.fetch(second)
+          )
+        end
+
+        @object_vs_broad_phase_filter = Native.JPH_ObjectVsBroadPhaseLayerFilterTable_Create(
+          @broad_phase_interface, broad_count, @object_pair_filter, object_count
+        )
+        check_pointer!(@object_vs_broad_phase_filter, "object-vs-broad-phase filter")
+      end
+
+      def check_pointer!(pointer, description)
+        raise InitializationError, "failed to create #{description}" unless present?(pointer)
+      end
+
+      def present?(pointer)
+        pointer && !pointer.null?
+      end
+    end
+  end
+end

data/lib/jolt/native/character_functions.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Jolt
+  module Native
+    module CharacterFunctions
+      module_function
+
+      def attach(native)
+        native.attach_function :JR_CharacterVirtual_Create,
+                               %i[pointer pointer pointer pointer float float], :pointer
+        native.attach_function :JR_CharacterVirtual_ExtendedUpdate,
+                               %i[pointer float uint32 pointer], :void, blocking: true
+      end
+    end
+  end
+end

data/lib/jolt/native/constraint_functions.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Jolt
+  module Native
+    module ConstraintFunctions
+      module_function
+
+      def attach(native)
+        attach_constructors(native)
+      end
+
+      def attach_constructors(native)
+        native.attach_function :JR_Constraint_CreateFixed,
+                               %i[pointer uint32 uint32 pointer], :pointer
+        native.attach_function :JR_Constraint_CreatePoint,
+                               %i[pointer uint32 uint32 pointer], :pointer
+        native.attach_function :JR_Constraint_CreateDistance,
+                               %i[pointer uint32 uint32 pointer pointer float float], :pointer
+        native.attach_function :JR_Constraint_CreateHinge,
+                               %i[pointer uint32 uint32 pointer pointer pointer bool float float], :pointer
+        native.attach_function :JR_Constraint_CreateSlider,
+                               %i[pointer uint32 uint32 pointer pointer bool float float], :pointer
+      end
+
+    end
+  end
+end

data/lib/jolt/native/core_functions.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Jolt
+  module Native
+    module CoreFunctions
+      module_function
+
+      def attach(native)
+        native.attach_function :JR_ContactQueue_Create, [:uint32], :pointer
+        native.attach_function :JR_ContactQueue_Destroy, [:pointer], :void
+        native.attach_function :JR_ContactQueue_GetListener, [:pointer], :pointer
+        native.attach_function :JR_ContactQueue_Pop, %i[pointer pointer], :bool
+        native.attach_function :JR_ContactQueue_GetDroppedCount, [:pointer], :uint64
+      end
+    end
+  end
+end