ruby-sfml 3.0.0.0

data/lib/sfml/window/joystick.rb

@@ -0,0 +1,90 @@
+module SFML
+  # Global gamepad / joystick state — peer to Keyboard and Mouse.
+  #
+  #   if SFML::Joystick.connected?(0)
+  #     x = SFML::Joystick.axis_position(0, :x)        # -100.0 .. 100.0
+  #     fire = SFML::Joystick.button_pressed?(0, 0)
+  #     info = SFML::Joystick.identification(0)
+  #     # => { name: "Xbox Controller", vendor_id: 0x045e, product_id: 0x028e }
+  #   end
+  #
+  # SFML supports up to MAX_COUNT joysticks (0..MAX_COUNT-1). Axes are
+  # addressed by symbol (:x, :y, :z, :r, :u, :v, :pov_x, :pov_y) so callers
+  # don't have to remember the sfJoystickAxis enum order.
+  module Joystick
+    # Order matches sfJoystickAxis in CSFML/Window/Joystick.h.
+    AXES = %i[x y z r u v pov_x pov_y].freeze
+    AXIS_INDEX = AXES.each_with_index.to_h.freeze
+
+    # Friendly aliases — POV axes are also called "hat" or "dpad" in some
+    # gamepad APIs.
+    AXIS_ALIASES = {
+      hat_x: :pov_x, hat_y: :pov_y,
+      dpad_x: :pov_x, dpad_y: :pov_y,
+    }.freeze
+
+    MAX_COUNT        = 8
+    MAX_BUTTON_COUNT = 32
+    MAX_AXIS_COUNT   = AXES.length
+
+    module_function
+
+    def connected?(joystick)
+      C::Window.sfJoystick_isConnected(_id(joystick))
+    end
+
+    def button_count(joystick)
+      C::Window.sfJoystick_getButtonCount(_id(joystick))
+    end
+
+    def has_axis?(joystick, axis)
+      C::Window.sfJoystick_hasAxis(_id(joystick), _axis_code(axis))
+    end
+
+    # Axis value in the range [-100.0, 100.0]. Returns 0.0 for axes that
+    # don't exist on the device, so it's safe to call without first
+    # checking has_axis?.
+    def axis_position(joystick, axis)
+      C::Window.sfJoystick_getAxisPosition(_id(joystick), _axis_code(axis))
+    end
+
+    def button_pressed?(joystick, button)
+      C::Window.sfJoystick_isButtonPressed(_id(joystick), Integer(button))
+    end
+
+    # Returns a Hash {name:, vendor_id:, product_id:} describing the
+    # device, or nil if the joystick isn't connected.
+    def identification(joystick)
+      return nil unless connected?(joystick)
+      ident = C::Window.sfJoystick_getIdentification(_id(joystick))
+      name_ptr = ident[:name]
+      {
+        name:       name_ptr.null? ? "" : name_ptr.read_string.force_encoding("UTF-8"),
+        vendor_id:  ident[:vendor_id],
+        product_id: ident[:product_id],
+      }
+    end
+
+    # Refresh joystick state. SFML auto-updates as part of pollEvent, so
+    # most code never needs this. Call it explicitly only if you're
+    # polling joystick state without an active event loop.
+    def update
+      C::Window.sfJoystick_update
+    end
+
+    # @!visibility private
+    def _id(joystick)
+      n = Integer(joystick)
+      raise ArgumentError, "Joystick id must be in 0..#{MAX_COUNT - 1}, got #{n}" if n < 0 || n >= MAX_COUNT
+      n
+    end
+
+    # @!visibility private
+    def _axis_code(axis)
+      sym = AXIS_ALIASES.fetch(axis, axis)
+      AXIS_INDEX.fetch(sym) do
+        raise ArgumentError, "Unknown joystick axis: #{axis.inspect}. Expected: #{AXES.inspect}"
+      end
+    end
+  end
+end

data/lib/sfml/window/keyboard.rb

@@ -0,0 +1,60 @@
+module SFML
+  # Keyboard key code <-> symbol translation, plus Keyboard.key_pressed?(:esc).
+  #
+  # The KEY_CODES array order is load-bearing: it matches the sfKeyCode enum
+  # in CSFML/Window/Keyboard.h exactly. sfKeyUnknown is -1 and represented
+  # here by :unknown returned via #code_to_symbol.
+  module Keyboard
+    KEY_CODES = %i[
+      a b c d e f g h i j k l m n o p q r s t u v w x y z
+      num0 num1 num2 num3 num4 num5 num6 num7 num8 num9
+      escape
+      l_control l_shift l_alt l_system
+      r_control r_shift r_alt r_system
+      menu
+      l_bracket r_bracket
+      semicolon comma period apostrophe slash backslash grave equal hyphen
+      space enter backspace tab
+      page_up page_down end_key home insert delete
+      add subtract multiply divide
+      left right up down
+      numpad0 numpad1 numpad2 numpad3 numpad4
+      numpad5 numpad6 numpad7 numpad8 numpad9
+      f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12 f13 f14 f15
+      pause
+    ].freeze
+
+    SYMBOL_TO_CODE = KEY_CODES.each_with_index.to_h.freeze
+
+    # Friendly aliases users might reach for naturally.
+    ALIASES = {
+      esc:    :escape,
+      lctrl:  :l_control,
+      rctrl:  :r_control,
+      lshift: :l_shift,
+      rshift: :r_shift,
+      space_bar: :space,
+      return: :enter,
+    }.freeze
+
+    module_function
+
+    def code_to_symbol(code)
+      return :unknown if code < 0 || code >= KEY_CODES.length
+      KEY_CODES[code]
+    end
+
+    def symbol_to_code(symbol)
+      symbol = ALIASES.fetch(symbol, symbol)
+      SYMBOL_TO_CODE.fetch(symbol) do
+        raise ArgumentError, "Unknown key symbol: #{symbol.inspect}. " \
+                             "See SFML::Keyboard::KEY_CODES."
+      end
+    end
+
+    # SFML::Keyboard.key_pressed?(:escape)
+    def key_pressed?(symbol)
+      C::Window.sfKeyboard_isKeyPressed(symbol_to_code(symbol))
+    end
+  end
+end

data/lib/sfml/window/mouse.rb

@@ -0,0 +1,71 @@
+module SFML
+  # Global mouse state — peer to SFML::Keyboard. Use it for "is this
+  # button held right now?" and for current pointer coordinates outside
+  # of the event loop.
+  #
+  #   SFML::Mouse.button_pressed?(:left)    #=> true while LMB is held
+  #   SFML::Mouse.position                  #=> Vector2 — desktop coords
+  #   SFML::Mouse.position(window)          #=> Vector2 — relative to window
+  #   SFML::Mouse.set_position([400, 300], window)
+  #
+  # Buttons are addressed by symbol; the raw sfMouseButton enum order is
+  # exposed via BUTTONS for users who need it.
+  module Mouse
+    BUTTONS = %i[left right middle extra1 extra2].freeze
+    BUTTON_INDEX = BUTTONS.each_with_index.to_h.freeze
+
+    # Friendly aliases — SFML 2 used "X-button" terminology; some users
+    # still reach for it.
+    ALIASES = {
+      x1:        :extra1,
+      x2:        :extra2,
+      x_button1: :extra1,
+      x_button2: :extra2,
+    }.freeze
+
+    module_function
+
+    # Returns true if the named mouse button is currently held.
+    def button_pressed?(button)
+      C::Window.sfMouse_isButtonPressed(_code(button))
+    end
+
+    # Pointer position. With no argument, returns desktop-relative
+    # coordinates. With a RenderWindow, returns coordinates relative to
+    # that window's client area (top-left = 0, 0).
+    def position(window = nil)
+      vec = if window
+              C::Graphics.sfMouse_getPositionRenderWindow(window.handle)
+            else
+              C::Window.sfMouse_getPosition(nil)
+            end
+      Vector2.new(vec[:x], vec[:y])
+    end
+
+    # Move the OS pointer. Without `window`, the coordinates are desktop-
+    # relative. Useful for FPS-style mouse-look (warp the cursor back to
+    # screen centre each frame).
+    def set_position(point, window = nil)
+      px, py = point.is_a?(Vector2) ? [point.x, point.y] : point
+      vec = C::System::Vector2i.new
+      vec[:x] = Integer(px)
+      vec[:y] = Integer(py)
+
+      if window
+        C::Graphics.sfMouse_setPositionRenderWindow(vec, window.handle)
+      else
+        C::Window.sfMouse_setPosition(vec, nil)
+      end
+    end
+
+    # @!visibility private
+    def _code(button)
+      sym = ALIASES.fetch(button, button)
+      BUTTON_INDEX.fetch(sym) do
+        raise ArgumentError,
+              "Unknown mouse button: #{button.inspect}. " \
+              "Expected one of: #{BUTTONS.inspect}"
+      end
+    end
+  end
+end

data/lib/sfml/window/video_mode.rb

@@ -0,0 +1,37 @@
+module SFML
+  # Video mode = (width, height, bits-per-pixel). Used when creating windows.
+  #
+  #   SFML::VideoMode.new(800, 600)
+  #   SFML::VideoMode.desktop_mode
+  class VideoMode
+    attr_reader :width, :height, :bits_per_pixel
+
+    def initialize(width, height, bits_per_pixel = 32)
+      @width = Integer(width)
+      @height = Integer(height)
+      @bits_per_pixel = Integer(bits_per_pixel)
+      freeze
+    end
+
+    def self.desktop_mode
+      from_native(C::Window.sfVideoMode_getDesktopMode)
+    end
+
+    def size = Vector2.new(@width, @height)
+
+    def to_s = "#<SFML::VideoMode #{@width}x#{@height}@#{@bits_per_pixel}>"
+    alias inspect to_s
+
+    def self.from_native(struct) # :nodoc:
+      new(struct[:size][:x], struct[:size][:y], struct[:bits_per_pixel])
+    end
+
+    def to_native # :nodoc:
+      C::Window::VideoMode.new.tap do |m|
+        m[:size][:x] = @width
+        m[:size][:y] = @height
+        m[:bits_per_pixel] = @bits_per_pixel
+      end
+    end
+  end
+end

data/lib/sfml/window/window.rb

@@ -0,0 +1,149 @@
+module SFML
+  # A bare window with input + an OpenGL context, **without** SFML's
+  # 2D batcher. Use this when you want raw OpenGL (or another
+  # rendering library) and just need SFML to manage the platform-level
+  # window and event loop. For 2D drawing with SFML's API, you want
+  # SFML::RenderWindow instead.
+  #
+  #   win = SFML::Window.new(800, 600, "GL")
+  #   while win.open?
+  #     win.each_event do |event|
+  #       case event
+  #       in {type: :closed} then win.close
+  #       in {type: :key_pressed, code: :escape} then win.close
+  #       else
+  #       end
+  #     end
+  #
+  #     # ... draw with raw OpenGL calls here ...
+  #
+  #     win.display
+  #   end
+  class Window
+    DEFAULT_STYLE = C::Window::Style::DEFAULT
+
+    def initialize(*args, **opts)
+      mode, title = parse_args(args)
+      style = opts.fetch(:style, DEFAULT_STYLE)
+      state = opts[:fullscreen] ? :fullscreen : :windowed
+
+      ptr = C::Window.sfWindow_create(
+        mode.to_native,
+        title.to_s,
+        style,
+        C::Window::State[state],
+        nil,
+      )
+      raise Error, "sfWindow_create returned NULL" if ptr.null?
+
+      @handle       = FFI::AutoPointer.new(ptr, C::Window.method(:sfWindow_destroy))
+      @event_buffer = C::Window::Event.new
+
+      self.framerate_limit = opts[:framerate] if opts[:framerate]
+      self.vsync = opts[:vsync]               unless opts[:vsync].nil?
+    end
+
+    def open?
+      C::Window.sfWindow_isOpen(@handle)
+    end
+
+    def close
+      C::Window.sfWindow_close(@handle)
+      self
+    end
+
+    def display
+      C::Window.sfWindow_display(@handle)
+      self
+    end
+
+    # Returns the next pending Event or nil. Same shape as RenderWindow#poll_event.
+    def poll_event
+      return nil unless C::Window.sfWindow_pollEvent(@handle, @event_buffer)
+      Event.from_native(@event_buffer)
+    end
+
+    def each_event
+      return enum_for(:each_event) unless block_given?
+      while (event = poll_event)
+        yield event
+      end
+      self
+    end
+
+    def title=(value)
+      C::Window.sfWindow_setTitle(@handle, value.to_s)
+    end
+
+    def size
+      v = C::Window.sfWindow_getSize(@handle)
+      Vector2.new(v[:x], v[:y])
+    end
+
+    def size=(value)
+      vec = value.is_a?(Vector2) ? value : Vector2.new(*value)
+      v = C::System::Vector2u.new
+      v[:x] = Integer(vec.x); v[:y] = Integer(vec.y)
+      C::Window.sfWindow_setSize(@handle, v)
+    end
+
+    def position
+      v = C::Window.sfWindow_getPosition(@handle)
+      Vector2.new(v[:x], v[:y])
+    end
+
+    def position=(value)
+      vec = value.is_a?(Vector2) ? value : Vector2.new(*value)
+      v = C::System::Vector2i.new
+      v[:x] = Integer(vec.x); v[:y] = Integer(vec.y)
+      C::Window.sfWindow_setPosition(@handle, v)
+    end
+
+    def visible=(value)
+      C::Window.sfWindow_setVisible(@handle, value ? true : false)
+    end
+
+    def framerate_limit=(value)
+      C::Window.sfWindow_setFramerateLimit(@handle, Integer(value))
+    end
+
+    def vsync=(enabled)
+      C::Window.sfWindow_setVerticalSyncEnabled(@handle, enabled ? true : false)
+    end
+
+    def key_repeat_enabled=(value)
+      C::Window.sfWindow_setKeyRepeatEnabled(@handle, value ? true : false)
+    end
+
+    def request_focus
+      C::Window.sfWindow_requestFocus(@handle)
+    end
+
+    def focused?
+      C::Window.sfWindow_hasFocus(@handle)
+    end
+
+    # Make this window's GL context current on the calling thread.
+    # Useful when juggling multiple windows / off-screen contexts.
+    def active=(value)
+      C::Window.sfWindow_setActive(@handle, value ? true : false)
+    end
+
+    attr_reader :handle # :nodoc:
+
+    private
+
+    def parse_args(args)
+      case args.length
+      when 2
+        [args[0], args[1]]
+      when 3
+        [VideoMode.new(args[0], args[1]), args[2]]
+      else
+        raise ArgumentError,
+              "Window.new takes either (video_mode, title) or " \
+              "(width, height, title), got #{args.length} positional arg(s)"
+      end
+    end
+  end
+end

data/lib/sfml.rb

@@ -0,0 +1,98 @@
+require "sfml/version"
+
+module SFML
+  class Error < StandardError; end
+  class LoadError < Error; end
+end
+
+# Tame process-exit teardown so CSFML doesn't crash.
+#
+# Two things race during a normal Ruby exit:
+#
+# 1. ObjectSpace finalizers run in non-deterministic order. CSFML's
+#    GL-bound resources (RenderWindow's GL context, Font glyph atlases,
+#    View copies) freed in the wrong sequence segfault inside the
+#    SFML/GL stack. Setting autorelease = false on every live
+#    FFI::AutoPointer skips the destruction; the OS reclaims memory
+#    anyway, so this costs nothing.
+#
+# 2. SFML's audio thread is still pumping samples while Ruby starts to
+#    tear the interpreter down. If a `Sound` or `Music` is mid-loop,
+#    OpenAL is reading buffers we're about to free → segfault inside
+#    libopenal. Stopping every live source first quiets the audio
+#    thread before anything starts disappearing.
+#
+# Unreferenced objects still get cleaned up at runtime via the normal
+# GC cycle; we only neuter the *teardown-time* pass.
+at_exit do
+  # 1. Capture the desired exit status before we tamper with anything.
+  status =
+    if    $!.is_a?(SystemExit) then $!.status
+    elsif $!.nil?              then 0
+    else                            1
+    end
+
+  # 2. Quiet the audio thread before anything else — OpenAL holds onto
+  #    sample buffers and crashes if Ruby starts freeing them while
+  #    a Sound/Music is mid-loop.
+  ObjectSpace.each_object(SFML::Sound) { |s| s.stop rescue nil } if defined?(SFML::Sound)
+  ObjectSpace.each_object(SFML::Music) { |m| m.stop rescue nil } if defined?(SFML::Music)
+
+  # 3. Bypass Ruby's natural finalizer pass entirely. Process memory is
+  #    about to be reclaimed by the kernel anyway, and Ruby's
+  #    non-deterministic destruction order races with CSFML's GL/audio
+  #    internals — segfaulting inside libopenal/libGL is the typical
+  #    failure mode. exit! kills the interpreter cleanly via _exit(2).
+  #
+  # Caveat: any user `at_exit` hook registered *before* `require "sfml"`
+  # won't run. Hooks registered after the require run first (LIFO),
+  # then our hook, so the common case is unaffected.
+  exit!(status)
+end
+
+require "sfml/c"
+require "sfml/system/time"
+require "sfml/system/clock"
+require "sfml/system/vector2"
+require "sfml/system/vector3"
+require "sfml/system/rect"
+require "sfml/window/keyboard"
+require "sfml/window/mouse"
+require "sfml/window/joystick"
+require "sfml/window/cursor"
+require "sfml/window/clipboard"
+require "sfml/window/video_mode"
+require "sfml/window/event"
+require "sfml/window/window"
+require "sfml/graphics/color"
+require "sfml/graphics/transformable"
+require "sfml/graphics/image"
+require "sfml/graphics/texture"
+require "sfml/graphics/sprite"
+require "sfml/graphics/circle_shape"
+require "sfml/graphics/rectangle_shape"
+require "sfml/graphics/convex_shape"
+require "sfml/graphics/vertex"
+require "sfml/graphics/vertex_array"
+require "sfml/graphics/font"
+require "sfml/graphics/text"
+require "sfml/graphics/view"
+require "sfml/graphics/blend_mode"
+require "sfml/graphics/shader"
+require "sfml/graphics/transform"
+require "sfml/graphics/render_states"
+require "sfml/graphics/render_target"
+require "sfml/graphics/render_window"
+require "sfml/graphics/render_texture"
+require "sfml/audio/sound_buffer"
+require "sfml/audio/sound"
+require "sfml/audio/music"
+require "sfml/audio/listener"
+require "sfml/audio/sound_recorder"
+require "sfml/audio/sound_buffer_recorder"
+require "sfml/network/ip_address"
+require "sfml/network/tcp_socket"
+require "sfml/network/tcp_listener"
+require "sfml/network/udp_socket"
+require "sfml/assets"
+require "sfml/game"

data/ruby-sfml.gemspec

@@ -0,0 +1,38 @@
+require_relative "lib/sfml/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "ruby-sfml"
+  spec.version     = SFML::VERSION
+  spec.authors     = ["Mykhailo Melnyk"]
+  spec.email       = ["m1kh41l.melnyk@gmail.com"]
+
+  spec.summary     = "Modern Ruby bindings for SFML 3.x"
+  spec.description = "Idiomatic Ruby bindings for SFML 3 via CSFML and FFI. Build games and multimedia apps in Ruby."
+  spec.homepage    = "https://github.com/sOM2H/ruby-sfml"
+  spec.license     = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"]      = spec.homepage
+  spec.metadata["source_code_uri"]   = spec.homepage
+  spec.metadata["bug_tracker_uri"]   = "#{spec.homepage}/issues"
+  spec.metadata["documentation_uri"] = "https://www.rubydoc.info/gems/#{spec.name}"
+  spec.metadata["changelog_uri"]     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "lib/sfml/assets/**/*",
+    "ext/**/*.rb",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE.txt",
+    "ruby-sfml.gemspec"
+  ]
+  spec.require_paths = ["lib"]
+  spec.extensions    = ["ext/ruby-sfml/extconf.rb"]
+
+  spec.add_dependency "ffi", "~> 1.16"
+
+  spec.add_development_dependency "rake",  "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "rdoc",  "~> 7.0"
+end