jolt-ruby 1.0.0

data/lib/jolt/native/platform.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Jolt
+  module Native
+    module Platform
+      module_function
+
+      def tag(cpu: RbConfig::CONFIG.fetch("host_cpu"), os: RbConfig::CONFIG.fetch("host_os"))
+        case os
+        when /darwin/
+          "#{darwin_cpu(cpu)}-darwin"
+        when /linux/
+          "#{linux_cpu(cpu)}-linux"
+        when /mswin|mingw/
+          "#{windows_cpu(cpu)}-mingw-ucrt"
+        else
+          "#{cpu}-#{os}".downcase.gsub(/[^a-z0-9._-]+/, "-")
+        end
+      end
+
+      def darwin_cpu(cpu)
+        case cpu
+        when "arm64", "aarch64" then "arm64"
+        when "x86_64", "amd64" then "x86_64"
+        else cpu
+        end
+      end
+      private_class_method :darwin_cpu
+
+      def linux_cpu(cpu)
+        case cpu
+        when "arm64", "aarch64" then "aarch64"
+        when "x64", "amd64", "x86_64" then "x86_64"
+        else cpu
+        end
+      end
+      private_class_method :linux_cpu
+
+      def windows_cpu(cpu)
+        case cpu
+        when "x64", "amd64", "x86_64" then "x64"
+        when "arm64", "aarch64" then "arm64"
+        else cpu
+        end
+      end
+      private_class_method :windows_cpu
+    end
+  end
+end

data/lib/jolt/native/query_functions.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Jolt
+  module Native
+    module QueryFunctions
+      module_function
+
+      def attach(native)
+        install_object_layer_filter(native)
+      end
+
+      def object_layer_filter(native, layer_ids, layer_count)
+        context = FFI::MemoryPointer.new(:uint8, layer_count + 4, true)
+        context.write_uint32(layer_count)
+        layer_ids.each { |id| context.put_uint8(id + 4, 1) }
+        filter = native.JPH_ObjectLayerFilter_Create(context)
+        raise InitializationError, "failed to create object layer filter" if filter.null?
+
+        [filter, context]
+      end
+
+      def install_object_layer_filter(native)
+        @object_layer_callback ||= FFI::Function.new(:bool, %i[pointer uint32]) do |context, layer|
+          count = context.read_uint32
+          layer < count && context.get_uint8(layer + 4) == 1
+        end
+        @object_layer_procs ||= ObjectLayerFilterProcs.new.tap do |procs|
+          procs[:should_collide] = @object_layer_callback
+        end
+        native.JPH_ObjectLayerFilter_SetProcs(@object_layer_procs.pointer)
+      end
+
+      def body_collector
+        hits = []
+        callback = FFI::Function.new(:float, %i[pointer uint32]) do |_context, body_id|
+          hits << body_id
+          1.0
+        end
+        [callback, hits]
+      end
+    end
+  end
+end

data/lib/jolt/native/types.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "generated"
+
+module Jolt
+  module Native
+    Vec3 = Generated::Vec3
+    Vec4 = Generated::Vec4
+    Quat = Generated::Quat
+    Mat4 = Generated::Mat4
+    MassProperties = Generated::MassProperties
+    PhysicsSystemSettings = Generated::PhysicsSystemSettings
+    RayCastResult = Generated::RayCastResult
+    IndexedTriangle = Generated::IndexedTriangle
+    ObjectLayerFilterProcs = Generated::ObjectLayerFilter_Procs
+
+    class ContactEvent < FFI::Struct
+      layout :type, :uint32,
+             :body_a, :uint32,
+             :body_b, :uint32,
+             :sub_shape_a, :uint32,
+             :sub_shape_b, :uint32,
+             :point, [:float, 3],
+             :normal, [:float, 3],
+             :penetration, :float
+    end
+  end
+end

data/lib/jolt/native.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "ffi"
+require "rbconfig"
+require_relative "native/platform"
+require_relative "native/types"
+require_relative "native/core_functions"
+require_relative "native/query_functions"
+require_relative "native/constraint_functions"
+require_relative "native/character_functions"
+
+module Jolt
+  module Native
+    extend FFI::Library
+
+    class << self
+      def load!
+        return self if @loaded
+
+        ffi_lib(*Loader.library_paths)
+        Generated.attach(self)
+        [
+          CoreFunctions,
+          QueryFunctions,
+          ConstraintFunctions,
+          CharacterFunctions
+        ].each { |functions| functions.attach(self) }
+        @loaded = true
+        self
+      rescue LoadError => error
+        raise NativeLoadError, error.message
+      end
+
+      def loaded?
+        @loaded == true
+      end
+
+    end
+
+    module Loader
+      module_function
+
+      def library_paths
+        directory = candidate_directories.find { |path| libraries_exist?(path) }
+        return library_names unless directory
+
+        library_names.map { |name| File.join(directory, name) }
+      end
+
+      def candidate_directories
+        [
+          ENV["JOLT_RUBY_NATIVE_DIR"],
+          File.join(__dir__, "native", platform),
+          installed_extension_directory,
+          File.join(project_root, "tmp", "native", platform, "lib"),
+          File.join(project_root, "tmp", "native", platform, "lib", "Release"),
+          File.join(project_root, "tmp", "native", platform, "Release")
+        ].compact
+      end
+
+      def installed_extension_directory
+        return unless defined?(Gem)
+
+        specification = Gem.loaded_specs["jolt-ruby"]
+        return unless specification
+
+        File.join(specification.extension_dir, "jolt", "native", platform)
+      end
+
+      def platform
+        Platform.tag
+      end
+
+      def project_root
+        File.expand_path("../..", __dir__)
+      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 libraries_exist?(directory)
+        library_names.all? { |name| File.file?(File.join(directory, name)) }
+      end
+    end
+  end
+end

data/lib/jolt/shape.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Jolt
+  class Shape
+    extend ShapeBuilders
+
+    DEFAULT_CONVEX_RADIUS = 0.05
+
+    class << self
+      def box(half_extents, convex_radius: DEFAULT_CONVEX_RADIUS)
+        Jolt.init
+        extents = Conversions.native_vec3(half_extents, name: "half_extents")
+        %i[x y z].each do |component|
+          raise InvalidArgumentError, "half_extents must be positive" unless extents[component].positive?
+        end
+        radius = Conversions.non_negative_float(convex_radius, "convex_radius")
+        build(Native.JPH_BoxShape_Create(extents.pointer, radius), :box)
+      end
+
+      def sphere(radius)
+        Jolt.init
+        build(Native.JPH_SphereShape_Create(Conversions.positive_float(radius, "radius")), :sphere)
+      end
+
+      def capsule(half_height:, radius:)
+        Jolt.init
+        height = Conversions.non_negative_float(half_height, "half_height")
+        radius = Conversions.positive_float(radius, "radius")
+        build(Native.JPH_CapsuleShape_Create(height, radius), :capsule)
+      end
+
+      def cylinder(half_height:, radius:)
+        Jolt.init
+        height = Conversions.positive_float(half_height, "half_height")
+        radius = Conversions.positive_float(radius, "radius")
+        build(Native.JPH_CylinderShape_Create(height, radius), :cylinder)
+      end
+
+      private
+
+      def build(pointer, kind)
+        raise ShapeError, "failed to create #{kind} shape" if pointer.null?
+
+        new(pointer, kind)
+      end
+    end
+
+    attr_reader :kind
+
+    def initialize(pointer, kind)
+      @pointer = pointer
+      @kind = kind
+      @released = false
+    end
+
+    def release
+      return if @released
+
+      Native.JPH_Shape_Destroy(@pointer)
+      @released = true
+      @pointer = nil
+      nil
+    end
+
+    def released?
+      @released
+    end
+
+    def volume
+      check_alive!
+      Native.JPH_Shape_GetVolume(@pointer)
+    end
+
+    def must_be_static?
+      check_alive!
+      Native.JPH_Shape_MustBeStatic(@pointer)
+    end
+
+    def native_pointer
+      check_alive!
+      @pointer
+    end
+
+    private
+
+    def check_alive!
+      raise UseAfterDestroyError, "shape has been released" if @released
+    end
+  end
+end

data/lib/jolt/shape_builders.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Jolt
+  module ShapeBuilders
+    def convex_hull(points, max_convex_radius: Shape::DEFAULT_CONVEX_RADIUS)
+      Jolt.init
+      coordinates = packed_floats(points, 3, "points")
+      raise InvalidArgumentError, "convex hull requires at least 4 points" if coordinates.length < 12
+
+      point_memory = float_memory(coordinates)
+      settings = Native.JPH_ConvexHullShapeSettings_Create(
+        point_memory, coordinates.length / 3,
+        Conversions.non_negative_float(max_convex_radius, "max_convex_radius")
+      )
+      create_from_settings(settings, :convex_hull, :JPH_ConvexHullShapeSettings_CreateShape)
+    end
+
+    def mesh(vertices:, indices:)
+      Jolt.init
+      coordinates = packed_floats(vertices, 3, "vertices")
+      triangles = packed_indices(indices)
+      vertex_count = coordinates.length / 3
+      raise InvalidArgumentError, "mesh requires at least 3 vertices" if vertex_count < 3
+      raise InvalidArgumentError, "mesh requires at least 1 triangle" if triangles.empty?
+      raise InvalidArgumentError, "mesh index is out of bounds" if triangles.any? { |index| index >= vertex_count }
+
+      vertex_memory = float_memory(coordinates)
+      triangle_memory = indexed_triangle_memory(triangles)
+      settings = Native.JPH_MeshShapeSettings_Create2(
+        vertex_memory, vertex_count, triangle_memory, triangles.length / 3
+      )
+      create_from_settings(settings, :mesh, :JPH_MeshShapeSettings_CreateShape)
+    end
+
+    def heightfield(samples:, size:, offset: [0, 0, 0], scale: [1, 1, 1])
+      Jolt.init
+      unless size.is_a?(Integer) && size >= 4
+        raise InvalidArgumentError, "size must be an integer greater than or equal to 4"
+      end
+      values = packed_floats(samples, 1, "samples")
+      unless values.length == size * size
+        raise InvalidArgumentError, "samples must contain size * size values"
+      end
+
+      sample_memory = float_memory(values)
+      offset = Conversions.native_vec3(offset, name: "offset")
+      scale = Conversions.native_vec3(scale, name: "scale")
+      settings = Native.JPH_HeightFieldShapeSettings_Create(
+        sample_memory, offset.pointer, scale.pointer, size, nil
+      )
+      create_from_settings(settings, :heightfield, :JPH_HeightFieldShapeSettings_CreateShape)
+    end
+
+    def compound(children)
+      Jolt.init
+      children = children.to_a
+      raise InvalidArgumentError, "compound requires at least one child" if children.empty?
+
+      settings = Native.JPH_StaticCompoundShapeSettings_Create
+      raise ShapeError, "failed to create compound settings" if settings.null?
+
+      children.each_with_index do |child, index|
+        shape, position, rotation = child
+        raise InvalidArgumentError, "child #{index} shape must be a Jolt::Shape" unless shape.is_a?(Shape)
+
+        position = Conversions.native_vec3(position || [0, 0, 0], name: "child position")
+        rotation = Conversions.native_quat(rotation || [0, 0, 0, 1], name: "child rotation")
+        Native.JPH_CompoundShapeSettings_AddShape2(
+          settings, position.pointer, rotation.pointer, shape.native_pointer, index
+        )
+      end
+      build(Native.JPH_StaticCompoundShape_Create(settings), :compound)
+    ensure
+      Native.JPH_ShapeSettings_Destroy(settings) if settings && !settings.null?
+    end
+
+    def scaled(shape, scale)
+      validate_shape(shape)
+      scale = Conversions.native_vec3(scale, name: "scale")
+      build(Native.JPH_ScaledShape_Create(shape.native_pointer, scale.pointer), :scaled)
+    end
+
+    def offset(shape, position: [0, 0, 0], rotation: [0, 0, 0, 1])
+      validate_shape(shape)
+      position = Conversions.native_vec3(position, name: "position")
+      rotation = Conversions.native_quat(rotation)
+      pointer = Native.JPH_RotatedTranslatedShape_Create(
+        position.pointer, rotation.pointer, shape.native_pointer
+      )
+      build(pointer, :offset)
+    end
+
+    private
+
+    def create_from_settings(settings, kind, function)
+      raise ShapeError, "failed to create #{kind} settings" if settings.null?
+
+      build(Native.public_send(function, settings), kind)
+    ensure
+      Native.JPH_ShapeSettings_Destroy(settings) if settings && !settings.null?
+    end
+
+    def packed_floats(value, tuple_size, name)
+      if value.is_a?(String) && !(value.bytesize % FFI.type_size(:float)).zero?
+        raise InvalidArgumentError, "#{name} packed f32 buffer has trailing bytes"
+      end
+      values = value.is_a?(String) ? value.unpack("e*") : value.to_a.flatten
+      unless (values.length % tuple_size).zero?
+        raise InvalidArgumentError, "#{name} has an incomplete tuple"
+      end
+
+      values.map.with_index { |item, index| Conversions.finite_float(item, "#{name}[#{index}]") }
+    rescue NoMethodError
+      raise InvalidArgumentError, "#{name} must be an array or packed f32 String"
+    end
+
+    def packed_indices(value)
+      if value.is_a?(String) && !(value.bytesize % FFI.type_size(:uint32)).zero?
+        raise InvalidArgumentError, "indices packed u32 buffer has trailing bytes"
+      end
+      values = value.is_a?(String) ? value.unpack("V*") : value.to_a.flatten
+      raise InvalidArgumentError, "indices has an incomplete triangle" unless (values.length % 3).zero?
+      unless values.all? { |index| index.is_a?(Integer) && index >= 0 }
+        raise InvalidArgumentError, "indices must contain non-negative integers"
+      end
+
+      values
+    rescue NoMethodError
+      raise InvalidArgumentError, "indices must be an array or packed u32 String"
+    end
+
+    def float_memory(values)
+      FFI::MemoryPointer.new(:float, values.length).tap { |memory| memory.write_array_of_float(values) }
+    end
+
+    def indexed_triangle_memory(indices)
+      count = indices.length / 3
+      FFI::MemoryPointer.new(Native::IndexedTriangle, count).tap do |memory|
+        indices.each_slice(3).with_index do |(i1, i2, i3), index|
+          triangle = Native::IndexedTriangle.new(memory + index * Native::IndexedTriangle.size)
+          triangle[:i1], triangle[:i2], triangle[:i3] = i1, i2, i3
+          triangle[:material_index] = 0
+          triangle[:user_data] = 0
+        end
+      end
+    end
+
+    def validate_shape(shape)
+      raise InvalidArgumentError, "shape must be a Jolt::Shape" unless shape.is_a?(Shape)
+
+      shape.native_pointer
+      Jolt.init
+    end
+  end
+end

data/lib/jolt/system.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module Jolt
+  class System
+    include SystemContacts
+    include SystemQueries
+    include SystemConstraints
+    include SystemCharacters
+
+    DEFAULT_LIMITS = {
+      max_bodies: 10_240,
+      max_body_pairs: 65_536,
+      max_contact_constraints: 10_240
+    }.freeze
+    MAX_UINT32 = 0xffff_ffff
+    MAX_INT32 = 0x7fff_ffff
+
+    attr_reader :layers, :bodies, :constraints, :contact_events
+
+    def initialize(max_bodies: DEFAULT_LIMITS[:max_bodies],
+                   max_body_pairs: DEFAULT_LIMITS[:max_body_pairs],
+                   max_contact_constraints: DEFAULT_LIMITS[:max_contact_constraints],
+                   gravity: [0, -9.81, 0], layers: Layers.default,
+                   contact_queue_capacity: 65_536)
+      Jolt.init
+      @destroyed = false
+      @active_thread = nil
+      @body_registry = {}
+      @constraint_registry = []
+      @character_registry = []
+      @user_data = {}
+      @shapes = {}
+      @layers = validate_layers(layers)
+      create_native_system(
+        max_bodies, max_body_pairs, max_contact_constraints, contact_queue_capacity
+      )
+      self.gravity = gravity
+      @bodies = BodyCollection.new(self)
+      @constraints = ConstraintCollection.new(self)
+      Jolt.__register_system(self)
+    rescue StandardError
+      destroy_native_resources
+      raise
+    end
+
+    def update(delta_time, collision_steps: 1)
+      __check_alive!
+      delta_time = Conversions.positive_float(delta_time, "delta_time")
+      unless collision_steps.is_a?(Integer) && collision_steps.between?(1, MAX_INT32)
+        raise InvalidArgumentError, "collision_steps must be a positive 32-bit integer"
+      end
+
+      __with_native_operation("recursive System#update is not allowed") do
+        @body_registry.each_value(&:__capture_before_step)
+        error = Native.JPH_PhysicsSystem_Update(@pointer, delta_time, collision_steps, @job_system)
+        @body_registry.each_value(&:__capture_after_step)
+        __drain_contact_events
+        raise_update_error!(error) unless error.zero?
+        self
+      end
+    end
+
+    def gravity
+      __check_alive!
+      native = Native::Vec3.new
+      Native.JPH_PhysicsSystem_GetGravity(@pointer, native.pointer)
+      Conversions.vec3(native)
+    end
+
+    def gravity=(value)
+      __check_alive!
+      native = Conversions.native_vec3(value, name: "gravity")
+      Native.JPH_PhysicsSystem_SetGravity(@pointer, native.pointer)
+      value
+    end
+
+    def optimize_broad_phase
+      __check_alive!
+      Native.JPH_PhysicsSystem_OptimizeBroadPhase(@pointer)
+      self
+    end
+
+    def destroy
+      return if @destroyed
+
+      __check_alive!
+      if @active_thread
+        raise ConcurrentAccessError, "cannot destroy a system during a native operation"
+      end
+
+      __destroy_all_constraints
+      __destroy_all_characters
+      @body_registry.each_value(&:__mark_destroyed)
+      @body_registry.clear
+      @user_data.clear
+      destroy_native_resources
+      @shapes.each_value { |shape| shape.release unless shape.released? }
+      @shapes.clear
+      @destroyed = true
+      Jolt.__unregister_system(self)
+      nil
+    end
+
+    def destroyed?
+      @destroyed
+    end
+
+    def __body_interface
+      __check_alive!
+      @body_interface
+    end
+
+    def __register_body(body, shape)
+      @body_registry[body.id] = body
+      @shapes[shape.object_id] = shape
+    end
+
+    def __destroy_body(body)
+      return if body.destroyed?
+
+      __check_alive!
+      registered = @body_registry.delete(body.id)
+      raise InvalidArgumentError, "body does not belong to this system" unless registered.equal?(body)
+
+      __destroy_constraints_for(body)
+      Native.JPH_BodyInterface_RemoveAndDestroyBody(@body_interface, body.id)
+      @user_data.delete(body.id)
+      body.__mark_destroyed
+      nil
+    end
+
+    def __body(id)
+      __check_alive!
+      @body_registry[id]
+    end
+
+    def __native_pointer
+      __check_alive!
+      @pointer
+    end
+
+    def __bodies_snapshot
+      __check_alive!
+      @body_registry.values
+    end
+
+    def __user_data(id)
+      __check_alive!
+      @user_data[id]
+    end
+
+    def __set_user_data(id, value)
+      __check_alive!
+      @user_data[id] = value
+    end
+
+    def __check_alive!
+      raise UseAfterDestroyError, "system has been destroyed" if @destroyed
+      return unless @active_thread && !@active_thread.equal?(Thread.current)
+
+      raise ConcurrentAccessError, "system is in use by another thread"
+    end
+
+    def __with_native_operation(recursive_message = "recursive native operation is not allowed")
+      acquired = false
+      __check_alive!
+      raise Error, recursive_message if @active_thread
+
+      @active_thread = Thread.current
+      acquired = true
+      yield
+    ensure
+      @active_thread = nil if acquired
+    end
+
+    private
+
+    def validate_layers(layers)
+      raise InvalidArgumentError, "layers must be a Jolt::Layers" unless layers.is_a?(Layers)
+
+      layers
+    end
+
+    def create_native_system(max_bodies, max_body_pairs, max_contact_constraints, contact_queue_capacity)
+      limits = [max_bodies, max_body_pairs, max_contact_constraints]
+      unless limits.all? { |value| value.is_a?(Integer) && value.between?(1, MAX_UINT32) }
+        raise InvalidArgumentError, "system limits must be positive 32-bit integers"
+      end
+
+      @layer_resources = @layers.native_resources
+      @job_system = Native.JPH_JobSystemThreadPool_Create(nil)
+      raise InitializationError, "failed to create Jolt job system" if @job_system.null?
+
+      settings = Native::PhysicsSystemSettings.new
+      settings[:max_bodies], settings[:max_body_pairs], settings[:max_contact_constraints] = limits
+      settings[:num_body_mutexes] = 0
+      settings[:padding] = 0
+      settings[:broad_phase_layer_interface] = @layer_resources.broad_phase_interface
+      settings[:object_layer_pair_filter] = @layer_resources.object_pair_filter
+      settings[:object_vs_broad_phase_layer_filter] = @layer_resources.object_vs_broad_phase_filter
+      @pointer = Native.JPH_PhysicsSystem_Create(settings.pointer)
+      raise InitializationError, "failed to create Jolt physics system" if @pointer.null?
+
+      @layer_resources.transfer_to_system!
+      @body_interface = Native.JPH_PhysicsSystem_GetBodyInterface(@pointer)
+      raise InitializationError, "failed to get Jolt body interface" if @body_interface.null?
+
+      @narrow_phase_query = Native.JPH_PhysicsSystem_GetNarrowPhaseQuery(@pointer)
+      raise InitializationError, "failed to get Jolt narrow-phase query" if @narrow_phase_query.null?
+
+      @broad_phase_query = Native.JPH_PhysicsSystem_GetBroadPhaseQuery(@pointer)
+      raise InitializationError, "failed to get Jolt broad-phase query" if @broad_phase_query.null?
+
+      __create_contact_queue(contact_queue_capacity)
+    end
+
+    def destroy_native_resources
+      __destroy_contact_queue
+      Native.JPH_PhysicsSystem_Destroy(@pointer) if @pointer && !@pointer.null?
+      Native.JPH_JobSystem_Destroy(@job_system) if @job_system && !@job_system.null?
+      @layer_resources&.destroy
+      @pointer = nil
+      @job_system = nil
+      @body_interface = nil
+      @broad_phase_query = nil
+      @narrow_phase_query = nil
+      @layer_resources = nil
+    end
+
+    def raise_update_error!(error)
+      names = []
+      names << "manifold cache full" unless (error & 1).zero?
+      names << "body pair cache full" unless (error & 2).zero?
+      names << "contact constraints full" unless (error & 4).zero?
+      raise PhysicsUpdateError, "physics update failed: #{names.join(", ")}"
+    end
+  end
+end