ruby-sfml 3.0.0.5 → 3.0.0.6

data/lib/sfml/graphics/view.rb

@@ -21,7 +21,7 @@ module SFML
   class View
     def initialize(center: nil, size: nil, rotation: nil, viewport: nil, _handle: nil)
       ptr = _handle || C::Graphics.sfView_create
-      raise Error, "sfView_create returned NULL" if ptr.null?
+      raise GraphicsError, "sfView_create returned NULL" if ptr.null?
       @handle = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfView_destroy))
 
       self.center   = center   if center
@@ -41,7 +41,7 @@ module SFML
       native[:size][:y]     = rect.height.to_f
 
       ptr = C::Graphics.sfView_createFromRect(native)
-      raise Error, "sfView_createFromRect returned NULL" if ptr.null?
+      raise GraphicsError, "sfView_createFromRect returned NULL" if ptr.null?
       new(_handle: ptr)
     end
 
@@ -50,7 +50,7 @@ module SFML
     # by sfRenderWindow_getView). We deep-copy via sfView_copy so the Ruby
     # object owns its own lifetime.
     def self.from_borrowed(ptr)
-      raise Error, "borrowed view pointer is NULL" if ptr.null?
+      raise GraphicsError, "borrowed view pointer is NULL" if ptr.null?
       copy = C::Graphics.sfView_copy(ptr)
       new(_handle: copy)
     end

data/lib/sfml/input_actions.rb

@@ -0,0 +1,105 @@
+module SFML
+  # Class-level `action` DSL — named bindings over multiple physical
+  # inputs. Shared by `SFML::App` and `SFML::Scene`. Pairs with the
+  # `Keybindings` mixin: keybindings fire **events** (one-shot, on
+  # press), actions are **polled state** ("is the user holding this
+  # right now?").
+  #
+  #   class MyGame < SFML::App
+  #     action :jump,    keys: [:space, :w]
+  #     action :fire,    mouse_buttons: [:left]
+  #     action :left,    keys: [:a, :left],    scancodes: [:scan_a]
+  #     action :right,   keys: [:d, :right]
+  #     action :crouch,  joy_buttons: [[0, 0]]  # joystick 0, button 0
+  #
+  #     def update(dt)
+  #       speed = 200 * dt.as_seconds
+  #       @x += speed if action_pressed?(:right)
+  #       @x -= speed if action_pressed?(:left)
+  #       @ball.jump if action_pressed?(:jump)
+  #     end
+  #   end
+  #
+  # Keys are mapped via `SFML::Keyboard.key_pressed?` — the
+  # **logical** key under the current OS layout. Scancodes are
+  # mapped via `SFML::Keyboard.scancode_pressed?` — the **physical**
+  # position (recommended for WASD-style movement so the keys stay
+  # under the same fingers across layouts).
+  #
+  # `axis(:name)` is a convenience for digital pairs: pass `negative:`
+  # and `positive:` actions and you get a Float in [-1, 1].
+  #
+  #   class Player < SFML::App
+  #     action :go_left,  keys: [:a, :left]
+  #     action :go_right, keys: [:d, :right]
+  #
+  #     def update(dt)
+  #       move = axis(negative: :go_left, positive: :go_right)
+  #       @x += move * 200 * dt.as_seconds
+  #     end
+  #   end
+  module InputActions
+    # Class-side: declare a named action.
+    #
+    # @param name [Symbol] action identifier
+    # @param keys [Array<Symbol>] logical key symbols (see Keyboard::KEY_CODES)
+    # @param scancodes [Array<Symbol>] physical scancode symbols (see Keyboard::SCAN_CODES)
+    # @param mouse_buttons [Array<Symbol>] :left / :right / :middle / :extra1 / :extra2
+    # @param joy_buttons [Array<Array<Integer>>] [[joystick_id, button_id], ...]
+    def action(name, keys: [], scancodes: [], mouse_buttons: [], joy_buttons: [])
+      @action_bindings ||= {}
+      @action_bindings[name.to_sym] = {
+        keys:          Array(keys).map(&:to_sym),
+        scancodes:     Array(scancodes).map(&:to_sym),
+        mouse_buttons: Array(mouse_buttons).map(&:to_sym),
+        joy_buttons:   Array(joy_buttons).map { |pair| Array(pair).map(&:to_i) },
+      }
+    end
+
+    # `Hash{action_name => bindings}` — own bindings layered over the
+    # parent's. Subclass `action` calls add to the inherited set.
+    def action_bindings
+      own    = (@action_bindings ||= {})
+      parent = superclass.respond_to?(:action_bindings) ? superclass.action_bindings : {}
+      parent.merge(own)
+    end
+  end
+
+  # Instance-side helpers — included into App and Scene so user code
+  # can call `action_pressed?` / `axis` from `#update` etc.
+  module InputQueries
+    # `true` if any input bound to `action_name` is currently held.
+    # Looks up bindings on `self.class.action_bindings` (App-style)
+    # or falls back to the host App when called from a Scene.
+    def action_pressed?(action_name)
+      bindings = _resolve_action_bindings[action_name.to_sym]
+      return false unless bindings
+
+      bindings[:keys].any?           { |k| Keyboard.key_pressed?(k) }       ||
+        bindings[:scancodes].any?    { |s| Keyboard.scancode_pressed?(s) }  ||
+        bindings[:mouse_buttons].any? { |b| Mouse.button_pressed?(b) }      ||
+        bindings[:joy_buttons].any?  { |(j, b)| Joystick.button_pressed?(j, b) }
+    end
+
+    # Synthetic digital axis from two opposing actions. Returns -1.0,
+    # 0.0, or +1.0 — never both 1 and -1 (positive wins if both held).
+    def axis(negative:, positive:)
+      pos = action_pressed?(positive) ? 1.0 : 0.0
+      neg = action_pressed?(negative) ? 1.0 : 0.0
+      pos - neg
+    end
+
+    private
+
+    # When called from a Scene, look up actions on the host App's
+    # class first so scene-only code reads global actions naturally.
+    # When the receiver IS the App, just use its own class.
+    def _resolve_action_bindings
+      if respond_to?(:host) && (h = host) && h.class.respond_to?(:action_bindings)
+        h.class.action_bindings.merge(self.class.action_bindings)
+      else
+        self.class.action_bindings
+      end
+    end
+  end
+end

data/lib/sfml/network/ftp.rb

@@ -47,7 +47,7 @@ module SFML
 
       def initialize
         ptr = C::Network.sfFtp_create
-        raise Error, "sfFtp_create returned NULL" if ptr.null?
+        raise NetworkError, "sfFtp_create returned NULL" if ptr.null?
 
         @handle = FFI::AutoPointer.new(ptr, C::Network.method(:sfFtp_destroy))
       end

data/lib/sfml/network/http.rb

@@ -25,7 +25,7 @@ module SFML
 
       def initialize(host, port: 0)
         ptr = C::Network.sfHttp_create
-        raise Error, "sfHttp_create returned NULL" if ptr.null?
+        raise NetworkError, "sfHttp_create returned NULL" if ptr.null?
 
         @handle = FFI::AutoPointer.new(ptr, C::Network.method(:sfHttp_destroy))
         C::Network.sfHttp_setHost(@handle, host.to_s, Integer(port))
@@ -34,7 +34,7 @@ module SFML
       def send_request(method: :get, uri: "/", fields: nil, body: nil,
                        http_version: DEFAULT_VERSION, timeout: DEFAULT_TIMEOUT)
         request_ptr = C::Network.sfHttpRequest_create
-        raise Error, "sfHttpRequest_create returned NULL" if request_ptr.null?
+        raise NetworkError, "sfHttpRequest_create returned NULL" if request_ptr.null?
 
         begin
           method_idx = C::Network::HTTP_METHODS.index(method) ||
@@ -50,7 +50,7 @@ module SFML
 
           t = timeout.is_a?(Time) ? timeout : Time.seconds(timeout.to_f)
           response_ptr = C::Network.sfHttp_sendRequest(@handle, request_ptr, t.to_native)
-          raise Error, "sfHttp_sendRequest returned NULL" if response_ptr.null?
+          raise NetworkError, "sfHttp_sendRequest returned NULL" if response_ptr.null?
 
           Response.send(:_take_ownership, response_ptr)
         ensure

data/lib/sfml/network/packet.rb

@@ -23,7 +23,7 @@ module SFML
     class Packet
       def initialize
         ptr = C::Network.sfPacket_create
-        raise Error, "sfPacket_create returned NULL" if ptr.null?
+        raise NetworkError, "sfPacket_create returned NULL" if ptr.null?
         @handle = FFI::AutoPointer.new(ptr, C::Network.method(:sfPacket_destroy))
       end
 
@@ -108,7 +108,7 @@ module SFML
 
       def dup
         ptr = C::Network.sfPacket_copy(@handle)
-        raise Error, "sfPacket_copy returned NULL" if ptr.null?
+        raise NetworkError, "sfPacket_copy returned NULL" if ptr.null?
 
         copy = self.class.allocate
         copy.instance_variable_set(:@handle,

data/lib/sfml/network/socket_selector.rb

@@ -26,7 +26,7 @@ module SFML
     class SocketSelector
       def initialize
         ptr = C::Network.sfSocketSelector_create
-        raise Error, "sfSocketSelector_create returned NULL" if ptr.null?
+        raise NetworkError, "sfSocketSelector_create returned NULL" if ptr.null?
 
         @handle = FFI::AutoPointer.new(ptr, C::Network.method(:sfSocketSelector_destroy))
       end

data/lib/sfml/network/tcp_listener.rb

@@ -13,7 +13,7 @@ module SFML
     class TcpListener
       def initialize
         ptr = C::Network.sfTcpListener_create
-        raise Error, "sfTcpListener_create returned NULL" if ptr.null?
+        raise NetworkError, "sfTcpListener_create returned NULL" if ptr.null?
         @handle = FFI::AutoPointer.new(ptr, C::Network.method(:sfTcpListener_destroy))
       end
 

data/lib/sfml/network/tcp_socket.rb

@@ -16,7 +16,7 @@ module SFML
     class TcpSocket
       def initialize
         ptr = C::Network.sfTcpSocket_create
-        raise Error, "sfTcpSocket_create returned NULL" if ptr.null?
+        raise NetworkError, "sfTcpSocket_create returned NULL" if ptr.null?
         @handle = FFI::AutoPointer.new(ptr, C::Network.method(:sfTcpSocket_destroy))
       end
 

data/lib/sfml/network/udp_socket.rb

@@ -13,7 +13,7 @@ module SFML
 
       def initialize
         ptr = C::Network.sfUdpSocket_create
-        raise Error, "sfUdpSocket_create returned NULL" if ptr.null?
+        raise NetworkError, "sfUdpSocket_create returned NULL" if ptr.null?
         @handle = FFI::AutoPointer.new(ptr, C::Network.method(:sfUdpSocket_destroy))
       end
 

data/lib/sfml/scene.rb

@@ -34,9 +34,13 @@ module SFML
   class Scene
     class << self
       include Keybindings
+      include InputActions
     end
 
+    include InputQueries
+
     attr_reader :app
+    alias host app
 
     def initialize(app)
       @app = app

data/lib/sfml/system/vector2.rb

@@ -47,6 +47,72 @@ module SFML
     def dot(other)   = (@x * other.x) + (@y * other.y)
     def cross(other) = (@x * other.y) - (@y * other.x)
 
+    # Euclidean distance between two points.
+    def distance(other)    = (self - _coerce(other)).length
+    def distance_sq(other) = (self - _coerce(other)).length_sq
+
+    # Angle of this vector relative to +X axis, in radians (-π..π].
+    def angle = Math.atan2(@y, @x)
+
+    # Angle from this vector to `other` as positions, in radians.
+    def angle_to(other)
+      o = _coerce(other)
+      Math.atan2(o.y - @y, o.x - @x)
+    end
+
+    # Vector rotated by `degrees` counter-clockwise. Use `rotated_rad`
+    # if you already have radians.
+    def rotated(degrees) = rotated_rad(degrees * Math::PI / 180.0)
+
+    def rotated_rad(radians)
+      c, s = Math.cos(radians), Math.sin(radians)
+      Vector2.new(@x * c - @y * s, @x * s + @y * c)
+    end
+
+    # 90° counter-clockwise rotation — equivalent to `rotated_rad(π/2)`
+    # but skips the trig. Handy for "the normal of an edge in 2D".
+    def perpendicular = Vector2.new(-@y, @x)
+
+    # Linear interpolation toward `other`. `t` in [0, 1] gives the
+    # standard mix; outside the range extrapolates.
+    def lerp(other, t)
+      o = _coerce(other)
+      Vector2.new(@x + (o.x - @x) * t, @y + (o.y - @y) * t)
+    end
+
+    # Vector projection of `self` onto `other`.
+    def project_on(other)
+      o = _coerce(other)
+      d = o.length_sq
+      return Vector2.zero if d.zero?
+      o * (dot(o) / d)
+    end
+
+    # Reflect this vector across the plane with `normal`. `normal`
+    # should be unit-length for the standard "bounce" behaviour.
+    def reflect(normal)
+      n = _coerce(normal)
+      self - (n * (2 * dot(n)))
+    end
+
+    # Clamp the magnitude into [min_len, max_len]. Either bound may be
+    # nil to leave that side unclamped.
+    def clamp_length(min_len = nil, max_len)
+      len = length
+      return self if len.zero?
+      target =
+        if    max_len && len > max_len then max_len
+        elsif min_len && len < min_len then min_len
+        else len
+        end
+      return self if target == len
+      self * (target / len)
+    end
+
+    def zero?  = @x.zero? && @y.zero?
+    def abs    = Vector2.new(@x.abs, @y.abs)
+    def to_v3(z = 0.0) = Vector3.new(@x, @y, z)
+
     def to_a = [@x, @y]
     def to_h = { x: @x, y: @y }
     def deconstruct = [@x, @y]
@@ -62,5 +128,14 @@ module SFML
     def to_native_f # :nodoc:
       C::System::Vector2f.new.tap { |v| v[:x] = @x; v[:y] = @y }
     end
+
+    private
+
+    # Accept Vector2 or [x, y] interchangeably so user code can write
+    #   pos.distance(target)  # Vector2
+    #   pos.distance([10, 20])
+    def _coerce(value)
+      value.is_a?(Vector2) ? value : Vector2.new(*value)
+    end
   end
 end

data/lib/sfml/system/vector3.rb

@@ -44,6 +44,59 @@ module SFML
       )
     end
 
+    # Lets Ruby evaluate `2 * vec` as `vec * 2`.
+    def coerce(other)
+      raise TypeError, "Vector3 cannot coerce #{other.class}" unless other.is_a?(Numeric)
+      [self, other]
+    end
+
+    def distance(other)    = (self - _coerce(other)).length
+    def distance_sq(other) = (self - _coerce(other)).length_sq
+
+    def lerp(other, t)
+      o = _coerce(other)
+      Vector3.new(@x + (o.x - @x) * t, @y + (o.y - @y) * t, @z + (o.z - @z) * t)
+    end
+
+    # Angle between two direction vectors, in radians. Both vectors
+    # should be non-zero — returns 0 for either side zero.
+    def angle_between(other)
+      o  = _coerce(other)
+      la = length
+      lo = o.length
+      return 0.0 if la.zero? || lo.zero?
+      cos = (dot(o) / (la * lo)).clamp(-1.0, 1.0)
+      Math.acos(cos)
+    end
+
+    def project_on(other)
+      o = _coerce(other)
+      d = o.length_sq
+      return Vector3.zero if d.zero?
+      o * (dot(o) / d)
+    end
+
+    def reflect(normal)
+      n = _coerce(normal)
+      self - (n * (2 * dot(n)))
+    end
+
+    def clamp_length(min_len = nil, max_len)
+      len = length
+      return self if len.zero?
+      target =
+        if    max_len && len > max_len then max_len
+        elsif min_len && len < min_len then min_len
+        else len
+        end
+      return self if target == len
+      self * (target / len)
+    end
+
+    def zero? = @x.zero? && @y.zero? && @z.zero?
+    def abs   = Vector3.new(@x.abs, @y.abs, @z.abs)
+    def to_v2 = Vector2.new(@x, @y)
+
     def to_a = [@x, @y, @z]
     def to_h = { x: @x, y: @y, z: @z }
     def deconstruct = [@x, @y, @z]
@@ -59,5 +112,11 @@ module SFML
     def to_native_f # :nodoc:
       C::System::Vector3f.new.tap { |v| v[:x] = @x; v[:y] = @y; v[:z] = @z }
     end
+
+    private
+
+    def _coerce(value)
+      value.is_a?(Vector3) ? value : Vector3.new(*value)
+    end
   end
 end

data/lib/sfml/version.rb

@@ -15,5 +15,5 @@ module SFML
   #   "3.0.1.0"  — CSFML 3.0.1 ships, we re-cut from upstream
   #   "3.0.1.1"  — our patch on top of CSFML 3.0.1
   #   "3.1.0.0"  — CSFML 3.1.0 ships, we add new bindings
-  VERSION = "3.0.0.5"
+  VERSION = "3.0.0.6"
 end

data/lib/sfml/window/context.rb

@@ -14,7 +14,7 @@ module SFML
   class Context
     def initialize
       ptr = C::Window.sfContext_create
-      raise Error, "sfContext_create returned NULL" if ptr.null?
+      raise WindowError, "sfContext_create returned NULL" if ptr.null?
       @handle = FFI::AutoPointer.new(ptr, C::Window.method(:sfContext_destroy))
     end
 

data/lib/sfml/window/cursor.rb

@@ -31,7 +31,7 @@ module SFML
                              "Expected one of: #{TYPES.inspect}"
       end
       ptr = C::Window.sfCursor_createFromSystem(code)
-      raise Error, "sfCursor_createFromSystem returned NULL for #{type.inspect}" if ptr.null?
+      raise WindowError, "sfCursor_createFromSystem returned NULL for #{type.inspect}" if ptr.null?
       _wrap(ptr)
     end
 
@@ -52,7 +52,7 @@ module SFML
       hot[:x] = Integer(hotspot[0]); hot[:y] = Integer(hotspot[1])
 
       ptr = C::Window.sfCursor_createFromPixels(buf, size, hot)
-      raise Error, "sfCursor_createFromPixels returned NULL" if ptr.null?
+      raise WindowError, "sfCursor_createFromPixels returned NULL" if ptr.null?
       _wrap(ptr)
     end
 

data/lib/sfml/window/window.rb

@@ -34,7 +34,7 @@ module SFML
         C::Window::State[state],
         nil,
       )
-      raise Error, "sfWindow_create returned NULL" if ptr.null?
+      raise WindowError, "sfWindow_create returned NULL" if ptr.null?
 
       @handle       = FFI::AutoPointer.new(ptr, C::Window.method(:sfWindow_destroy))
       @event_buffer = C::Window::Event.new
@@ -206,7 +206,7 @@ module SFML
     def self.from_handle(handle)
       ptr = handle.is_a?(FFI::Pointer) ? handle : FFI::Pointer.new(:void, Integer(handle))
       raw = C::Window.sfWindow_createFromHandle(ptr, nil)
-      raise Error, "sfWindow_createFromHandle returned NULL" if raw.null?
+      raise WindowError, "sfWindow_createFromHandle returned NULL" if raw.null?
 
       win = allocate
       win.instance_variable_set(:@handle,

data/lib/sfml.rb

@@ -1,8 +1,47 @@
 require "sfml/version"
 
 module SFML
+  # Root of the ruby-sfml exception hierarchy. Every CSFML-side
+  # failure surfaces as something inheriting from `SFML::Error`, so
+  # `rescue SFML::Error` is the catch-all.
+  #
+  # Subclasses let callers target a domain:
+  #
+  #   rescue SFML::LoadError       # file / decode / GPU upload failed
+  #   rescue SFML::AudioError      # OpenAL / capture / playback issues
+  #   rescue SFML::NetworkError    # socket / packet framing
+  #   rescue SFML::ShaderError     # GLSL compile / uniform / link
+  #   rescue SFML::GraphicsError   # render-side issues other than load
+  #   rescue SFML::WindowError     # window/context creation / events
   class Error < StandardError; end
+
+  # An asset failed to load — file missing, format unsupported, GPU
+  # upload rejected, etc. Raised by `Texture.load` / `Font.load` /
+  # `Image.load` / `SoundBuffer.load` / `Music.load` and their
+  # `from_memory` / `from_stream` siblings.
   class LoadError < Error; end
+
+  # An audio operation failed at the OpenAL or CSFML capture layer —
+  # `SoundRecorder#start` couldn't open the device, channel-map was
+  # rejected, etc.
+  class AudioError < Error; end
+
+  # A network operation failed — socket couldn't open, packet framing
+  # was malformed, HTTP/FTP transport rejected the request.
+  class NetworkError < Error; end
+
+  # A shader couldn't compile or link, or an unknown uniform name was
+  # set. CSFML logs the compiler error to stderr; this exception just
+  # signals the failure.
+  class ShaderError < Error; end
+
+  # Generic graphics-side failure that isn't a load. Render-texture
+  # allocation, framebuffer setup, view/scissor math, etc.
+  class GraphicsError < Error; end
+
+  # Window or GL context couldn't be created, or a windowing primitive
+  # (cursor, clipboard) failed.
+  class WindowError < Error; end
 end
 
 # Tame process-exit teardown so CSFML doesn't crash.
@@ -109,6 +148,10 @@ require "sfml/graphics/render_states"
 require "sfml/graphics/render_target"
 require "sfml/graphics/render_window"
 require "sfml/graphics/render_texture"
+require "sfml/graphics/texture_atlas"
+require "sfml/graphics/sprite_sheet"
+require "sfml/graphics/animation"
+require "sfml/graphics/particle_system"
 require "sfml/audio/internal"
 require "sfml/audio/sound_buffer"
 require "sfml/audio/sound_cone"
@@ -128,5 +171,6 @@ require "sfml/network/http"
 require "sfml/network/ftp"
 require "sfml/assets"
 require "sfml/keybindings"
+require "sfml/input_actions"
 require "sfml/scene"
 require "sfml/app"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-sfml
 version: !ruby/object:Gem::Version
-  version: 3.0.0.5
+  version: 3.0.0.6
 platform: ruby
 authors:
 - Mykhailo Melnyk
@@ -98,12 +98,14 @@ files:
 - lib/sfml/c/network.rb
 - lib/sfml/c/system.rb
 - lib/sfml/c/window.rb
+- lib/sfml/graphics/animation.rb
 - lib/sfml/graphics/blend_mode.rb
 - lib/sfml/graphics/circle_shape.rb
 - lib/sfml/graphics/color.rb
 - lib/sfml/graphics/convex_shape.rb
 - lib/sfml/graphics/font.rb
 - lib/sfml/graphics/image.rb
+- lib/sfml/graphics/particle_system.rb
 - lib/sfml/graphics/rectangle_shape.rb
 - lib/sfml/graphics/render_states.rb
 - lib/sfml/graphics/render_target.rb
@@ -113,9 +115,11 @@ files:
 - lib/sfml/graphics/shape.rb
 - lib/sfml/graphics/shape_inspectable.rb
 - lib/sfml/graphics/sprite.rb
+- lib/sfml/graphics/sprite_sheet.rb
 - lib/sfml/graphics/stencil_mode.rb
 - lib/sfml/graphics/text.rb
 - lib/sfml/graphics/texture.rb
+- lib/sfml/graphics/texture_atlas.rb
 - lib/sfml/graphics/transform.rb
 - lib/sfml/graphics/transformable.rb
 - lib/sfml/graphics/transformable_object.rb
@@ -123,6 +127,7 @@ files:
 - lib/sfml/graphics/vertex_array.rb
 - lib/sfml/graphics/vertex_buffer.rb
 - lib/sfml/graphics/view.rb
+- lib/sfml/input_actions.rb
 - lib/sfml/keybindings.rb
 - lib/sfml/network/ftp.rb
 - lib/sfml/network/http.rb