ruby-sfml 3.0.0.5 → 3.0.0.6

data/lib/sfml/graphics/particle_system.rb

@@ -0,0 +1,165 @@
+module SFML
+  # A pool-backed particle emitter built on top of `SFML::VertexArray`.
+  # Each particle is two triangles (a quad) so a single CSFML draw
+  # call ships thousands at once.
+  #
+  #   class Sparks < SFML::ParticleSystem
+  #     def emit_one
+  #       angle = rand(0.0..2 * Math::PI)
+  #       speed = rand(80.0..200.0)
+  #       spawn(
+  #         position:  @origin,
+  #         velocity:  SFML::Vector2.new(Math.cos(angle), Math.sin(angle)) * speed,
+  #         lifetime:  0.8,
+  #         color:     SFML::Color.new(255, 200, 50),
+  #         size:      4,
+  #       )
+  #     end
+  #   end
+  #
+  #   sparks = Sparks.new(max: 500)
+  #
+  #   def update(dt)
+  #     5.times { sparks.emit_one } if mouse_down?
+  #     sparks.update(dt)
+  #   end
+  #
+  #   def draw
+  #     window.draw(sparks)
+  #   end
+  #
+  # Particles fade linearly from full alpha at spawn to zero alpha
+  # at `lifetime`. Override `#update_particle(p, dt)` to apply
+  # gravity, drag, custom colour curves, etc.
+  #
+  # Acceleration: pass `gravity:` to the constructor for the common
+  # case (px/s² added to velocity every frame). For richer behaviour,
+  # subclass and override.
+  class ParticleSystem
+    # A single particle. Plain Struct so allocations stay cheap;
+    # mutated in-place from `#update`.
+    Particle = Struct.new(
+      :x, :y,
+      :vx, :vy,
+      :age, :lifetime,
+      :r, :g, :b, :a,
+      :size,
+    ) do
+      def alive? = age < lifetime
+      def normalized_age = age / lifetime
+    end
+
+    DEFAULT_GRAVITY = [0.0, 0.0].freeze
+
+    def initialize(max: 1000, gravity: DEFAULT_GRAVITY, texture: nil)
+      @max          = Integer(max)
+      @gravity_x    = Float(gravity[0])
+      @gravity_y    = Float(gravity[1])
+      @texture      = texture
+      @particles    = []
+      @vertex_array = VertexArray.new(:triangles)
+    end
+
+    attr_reader :particles, :texture
+    def size = @particles.size
+    def empty? = @particles.empty?
+    def full?  = @particles.size >= @max
+
+    # Spawn a new particle. Silently dropped if the pool is full
+    # (better than reallocating; users can size up `max:`).
+    #
+    # @param position [Vector2, Array] world coords
+    # @param velocity [Vector2, Array] px/s
+    # @param lifetime [Numeric] seconds
+    # @param color [SFML::Color]
+    # @param size [Numeric] half-side of the quad in pixels
+    def spawn(position:, velocity: [0, 0], lifetime: 1.0, color: Color.white, size: 4)
+      return if full?
+
+      px, py = _xy(position)
+      vx, vy = _xy(velocity)
+
+      @particles << Particle.new(
+        Float(px), Float(py),
+        Float(vx), Float(vy),
+        0.0, Float(lifetime),
+        color.r, color.g, color.b, color.a,
+        Float(size),
+      )
+      self
+    end
+
+    # Drop every live particle.
+    def clear
+      @particles.clear
+      self
+    end
+
+    # Advance all particles by `dt` and remove dead ones.
+    def update(dt)
+      seconds = dt.is_a?(Time) ? dt.as_seconds : Float(dt)
+      gx, gy  = @gravity_x, @gravity_y
+
+      @particles.each do |p|
+        next unless p.alive?
+
+        # Gravity + integration. Subclasses can override
+        # update_particle to layer additional forces / drag.
+        p.vx += gx * seconds
+        p.vy += gy * seconds
+        p.x  += p.vx * seconds
+        p.y  += p.vy * seconds
+        p.age += seconds
+        update_particle(p, seconds)
+      end
+
+      @particles.delete_if { |p| !p.alive? }
+
+      self
+    end
+
+    # Hook: tweak a particle's state. Default does nothing; override
+    # for drag, attractors, colour curves over lifetime, etc.
+    def update_particle(_particle, _dt); end
+
+    # Drawable interface — rebuilds the VertexArray and forwards.
+    def draw_on(target, states_ptr = nil)
+      _rebuild_vertex_array
+      @vertex_array.draw_on(target, states_ptr)
+    end
+
+    private
+
+    def _xy(value)
+      case value
+      when Vector2 then [value.x, value.y]
+      when Array   then value
+      else raise ArgumentError, "expected Vector2 or [x, y]; got #{value.class}"
+      end
+    end
+
+    # Pack live particles into the vertex array as two triangles each.
+    # We rebuild from scratch every frame — for ~1000 particles this
+    # is ~6000 vertex writes per frame, which is well within budget.
+    def _rebuild_vertex_array
+      @vertex_array.clear
+      @particles.each do |p|
+        next unless p.alive?
+
+        s = p.size
+        # Fade alpha linearly from full → zero across lifetime.
+        alpha = (p.a * (1.0 - p.normalized_age)).round.clamp(0, 255)
+        col = Color.new(p.r, p.g, p.b, alpha)
+
+        # Two triangles forming a quad centred on (x, y).
+        tl = Vertex.new([p.x - s, p.y - s], color: col)
+        tr = Vertex.new([p.x + s, p.y - s], color: col)
+        bl = Vertex.new([p.x - s, p.y + s], color: col)
+        br = Vertex.new([p.x + s, p.y + s], color: col)
+
+        @vertex_array << tl << tr << br
+        @vertex_array << tl << br << bl
+      end
+    end
+  end
+end

data/lib/sfml/graphics/rectangle_shape.rb

@@ -14,7 +14,7 @@ module SFML
 
     def initialize(size:, **opts)
       ptr = C::Graphics.sfRectangleShape_create
-      raise Error, "sfRectangleShape_create returned NULL" if ptr.null?
+      raise GraphicsError, "sfRectangleShape_create returned NULL" if ptr.null?
       @handle = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfRectangleShape_destroy))
 
       self.size = size

data/lib/sfml/graphics/render_texture.rb

@@ -27,7 +27,7 @@ module SFML
       size[:y] = Integer(height)
 
       ptr = C::Graphics.sfRenderTexture_create(size, nil)
-      raise Error, "sfRenderTexture_create returned NULL" if ptr.null?
+      raise GraphicsError, "sfRenderTexture_create returned NULL" if ptr.null?
       @handle = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfRenderTexture_destroy))
 
       self.smooth   = smooth
@@ -96,7 +96,7 @@ module SFML
     def texture
       @texture ||= begin
         ptr = C::Graphics.sfRenderTexture_getTexture(@handle)
-        raise Error, "sfRenderTexture_getTexture returned NULL" if ptr.null?
+        raise GraphicsError, "sfRenderTexture_getTexture returned NULL" if ptr.null?
         # Borrowed — RenderTexture owns the underlying sf::Texture, so
         # we wrap with a raw pointer (no AutoPointer / no destructor).
         # Sprite.new(@texture) will still get a valid handle through it.

data/lib/sfml/graphics/render_window.rb

@@ -49,7 +49,7 @@ module SFML
         C::Window::State[state],
         ctx_ptr,
       )
-      raise Error, "sfRenderWindow_create returned NULL" if ptr.null?
+      raise WindowError, "sfRenderWindow_create returned NULL" if ptr.null?
 
       @handle = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfRenderWindow_destroy))
       @event_buffer = C::Window::Event.new
@@ -132,6 +132,30 @@ module SFML
       Vector2.new(v[:x], v[:y])
     end
 
+    # Capture the current back-buffer to disk. The format is inferred
+    # from the file extension (png / jpg / bmp / tga supported by
+    # CSFML's stb_image-based saver). Returns the path.
+    #
+    #   window.screenshot("screenshot.png")
+    #
+    # `format:` lets you save under a different name than the
+    # extension. For an in-memory copy, use `#capture_image` instead.
+    def screenshot(path, format: nil)
+      capture_image.save(path.to_s)
+      path
+    end
+
+    # Read the current back-buffer into a fresh CPU-side SFML::Image.
+    # Useful for processing/encoding the frame yourself (sending it
+    # over a socket, encoding as JPEG memory bytes, comparing
+    # against a reference, etc.).
+    def capture_image
+      w, h = size.x, size.y
+      tex  = Texture.create(w, h)
+      tex.update_from_render_window(self)
+      tex.to_image
+    end
+
     # Replace the window's title-bar / taskbar icon with the pixels from
     # the given SFML::Image. The OS scales it as needed; 32×32 RGBA
     # is the typical sweet spot.
@@ -247,7 +271,7 @@ module SFML
     def self.from_handle(handle)
       ptr = handle.is_a?(FFI::Pointer) ? handle : FFI::Pointer.new(:void, Integer(handle))
       raw = C::Graphics.sfRenderWindow_createFromHandle(ptr, nil)
-      raise Error, "sfRenderWindow_createFromHandle returned NULL" if raw.null?
+      raise WindowError, "sfRenderWindow_createFromHandle returned NULL" if raw.null?
 
       win = allocate
       win.instance_variable_set(:@handle,

data/lib/sfml/graphics/shader.rb

@@ -56,7 +56,7 @@ module SFML
       ptr = C::Graphics.sfShader_createFromFile(
         vertex&.to_s, geometry&.to_s, fragment&.to_s,
       )
-      raise Error, "sfShader_createFromFile failed (compile error or missing file?)" if ptr.null?
+      raise ShaderError, "sfShader_createFromFile failed (compile error or missing file?)" if ptr.null?
       _wrap(ptr)
     end
 
@@ -64,7 +64,7 @@ module SFML
     def self.from_source(vertex: nil, geometry: nil, fragment: nil)
       _check_at_least_one(vertex, geometry, fragment)
       ptr = C::Graphics.sfShader_createFromMemory(vertex, geometry, fragment)
-      raise Error, "sfShader_createFromMemory failed (GLSL compile error?)" if ptr.null?
+      raise ShaderError, "sfShader_createFromMemory failed (GLSL compile error?)" if ptr.null?
       _wrap(ptr)
     end
 
@@ -76,7 +76,7 @@ module SFML
       streams = [vertex, geometry, fragment].map { |io| io && SFML::InputStream.new(io) }
       ptrs    = streams.map { |s| s ? s.to_ptr : nil }
       ptr = C::Graphics.sfShader_createFromStream(*ptrs)
-      raise Error, "sfShader_createFromStream failed (GLSL compile error?)" if ptr.null?
+      raise ShaderError, "sfShader_createFromStream failed (GLSL compile error?)" if ptr.null?
       _wrap(ptr)
     end
 

data/lib/sfml/graphics/shape.rb

@@ -47,7 +47,7 @@ module SFML
       end
 
       ptr = C::Graphics.sfShape_create(@get_point_count_cb, @get_point_cb, nil)
-      raise Error, "sfShape_create returned NULL" if ptr.null?
+      raise GraphicsError, "sfShape_create returned NULL" if ptr.null?
       @handle = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfShape_destroy))
 
       self.fill_color         = opts[:fill_color]         if opts.key?(:fill_color)

data/lib/sfml/graphics/shape_inspectable.rb

@@ -78,7 +78,7 @@ module SFML
       # cheap to alias); transform/colour state is independent.
       def dup
         ptr = _csfml(:copy, @handle)
-        raise Error, "#{self.class.name}#dup returned NULL" if ptr.null?
+        raise GraphicsError, "#{self.class.name}#dup returned NULL" if ptr.null?
 
         destroy_fn = C::Graphics.method(:"#{self.class::CSFML_PREFIX}_destroy")
         copy = self.class.allocate

data/lib/sfml/graphics/sprite.rb

@@ -15,7 +15,7 @@ module SFML
       raise ArgumentError, "Sprite requires a SFML::Texture" unless texture.is_a?(Texture)
 
       ptr = C::Graphics.sfSprite_create(texture.handle)
-      raise Error, "sfSprite_create returned NULL" if ptr.null?
+      raise GraphicsError, "sfSprite_create returned NULL" if ptr.null?
       @handle  = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfSprite_destroy))
       @texture = texture # keep alive for GC
 
@@ -92,7 +92,7 @@ module SFML
     # objects), independent transform / colour state.
     def dup
       ptr = C::Graphics.sfSprite_copy(@handle)
-      raise Error, "sfSprite_copy returned NULL" if ptr.null?
+      raise GraphicsError, "sfSprite_copy returned NULL" if ptr.null?
 
       copy = self.class.allocate
       copy.instance_variable_set(:@handle,

data/lib/sfml/graphics/sprite_sheet.rb

@@ -0,0 +1,100 @@
+module SFML
+  # A grid-based slice of a texture. Where `TextureAtlas` loads an
+  # already-packed sheet with named frames, `SpriteSheet` slices a
+  # uniformly-gridded image into numbered frames at load time.
+  #
+  # Use a SpriteSheet when your art is a regular grid (run cycles
+  # baked at 32×32 cells); use a TextureAtlas when frames are
+  # densely packed at irregular sizes.
+  #
+  #   sheet = SFML::SpriteSheet.load("hero.png", frame_size: [32, 32])
+  #
+  #   sheet.frame_count       # 8 if the image is 256×32
+  #   sheet.region(0)         # SFML::Rect of the first cell
+  #   sheet.sprite(0)         # ready-to-draw SFML::Sprite of the first cell
+  #
+  # `frame_size` can be a `[w, h]` pair (one number for both if
+  # `frame_size: 32`). `padding` and `margin` let you skip pixels
+  # between cells and around the edge respectively — common when
+  # the source image has separators or a 1px outline to prevent
+  # bleed.
+  class SpriteSheet
+    def self.load(path, frame_size:, padding: 0, margin: 0, smooth: true)
+      new(texture: Texture.load(path, smooth: smooth),
+          frame_size: frame_size, padding: padding, margin: margin)
+    end
+
+    def initialize(texture:, frame_size:, padding: 0, margin: 0)
+      @texture = texture
+      fw, fh = _pair(frame_size)
+      pw, ph = _pair(padding)
+      mw, mh = _pair(margin)
+
+      tex_w, tex_h = texture.size.x, texture.size.y
+      @cols = (tex_w - 2 * mw + pw) / (fw + pw)
+      @rows = (tex_h - 2 * mh + ph) / (fh + ph)
+      @frame_w, @frame_h = fw, fh
+
+      # Pre-compute every rect once. Cheap (a few hundred at most),
+      # and #region becomes a flat array lookup.
+      @regions = Array.new(@cols * @rows) do |i|
+        col = i % @cols
+        row = i / @cols
+        x = mw + col * (fw + pw)
+        y = mh + row * (fh + ph)
+        Rect.new([x, y], [fw, fh])
+      end.freeze
+    end
+
+    attr_reader :texture, :cols, :rows, :frame_w, :frame_h
+
+    def frame_count = @regions.size
+
+    # The pixel Rect for cell `index` (0 = top-left, increases
+    # row-major). Negative indexes wrap (e.g. -1 = last).
+    def region(index)
+      i = Integer(index) % frame_count
+      @regions[i]
+    end
+
+    # `[col, row]` accessor for callers who prefer 2D coords.
+    def region_at(col, row)
+      raise IndexError, "col #{col} out of range (cols: #{@cols})" if col < 0 || col >= @cols
+      raise IndexError, "row #{row} out of range (rows: #{@rows})" if row < 0 || row >= @rows
+      @regions[row * @cols + col]
+    end
+
+    # Fresh Sprite pointing at cell `index`. Combine with `#sprite=`
+    # patterns or feed into `SFML::Animation`.
+    def sprite(index, **opts)
+      Sprite.new(@texture, **opts).tap { |s| s.texture_rect = region(index) }
+    end
+
+    # An Animation looping through `frame_indexes` (defaults to all
+    # frames in row-major order).
+    def animation(frame_indexes: nil, fps: 12, loop: true)
+      indexes = frame_indexes || (0...frame_count).to_a
+      Animation.new(
+        self,
+        frames: indexes.map { |i| region(i) },
+        fps:    fps,
+        loop:   loop,
+      )
+    end
+
+    def to_s = "#<SpriteSheet #{@cols}×#{@rows} (#{@frame_w}×#{@frame_h}px cells)>"
+    alias inspect to_s
+
+    private
+
+    # Accept 32 OR [32, 32] OR Vector2[32, 32].
+    def _pair(value)
+      case value
+      when Numeric then [Integer(value), Integer(value)]
+      when Vector2 then [Integer(value.x), Integer(value.y)]
+      when Array   then value.map { |n| Integer(n) }
+      else raise ArgumentError, "expected Integer, [w, h], or Vector2; got #{value.class}"
+      end
+    end
+  end
+end

data/lib/sfml/graphics/text.rb

@@ -27,7 +27,7 @@ module SFML
       raise ArgumentError, "Text requires a SFML::Font" unless font.is_a?(Font)
 
       ptr = C::Graphics.sfText_create(font.handle)
-      raise Error, "sfText_create returned NULL" if ptr.null?
+      raise GraphicsError, "sfText_create returned NULL" if ptr.null?
       @handle = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfText_destroy))
       @font   = font # keep alive for GC
 
@@ -161,7 +161,7 @@ module SFML
     # (Fonts are shareable; each owns its own glyph atlas).
     def dup
       ptr = C::Graphics.sfText_copy(@handle)
-      raise Error, "sfText_copy returned NULL" if ptr.null?
+      raise GraphicsError, "sfText_copy returned NULL" if ptr.null?
 
       copy = self.class.allocate
       copy.instance_variable_set(:@handle, FFI::AutoPointer.new(ptr, C::Graphics.method(:sfText_destroy)))

data/lib/sfml/graphics/texture.rb

@@ -16,7 +16,7 @@ module SFML
       ptr = srgb \
         ? C::Graphics.sfTexture_createSrgbFromFile(path.to_s, nil) \
         : C::Graphics.sfTexture_createFromFile(path.to_s, nil)
-      raise Error, "Could not load texture from #{path.inspect}" if ptr.null?
+      raise LoadError, "Could not load texture from #{path.inspect}" if ptr.null?
 
       tex = allocate
       tex.send(:_take_ownership, ptr)
@@ -33,7 +33,7 @@ module SFML
       size = C::System::Vector2u.new
       size[:x] = Integer(width); size[:y] = Integer(height)
       ptr = srgb ? C::Graphics.sfTexture_createSrgb(size) : C::Graphics.sfTexture_create(size)
-      raise Error, "sfTexture_create returned NULL — out of GPU memory?" if ptr.null?
+      raise GraphicsError, "sfTexture_create returned NULL — out of GPU memory?" if ptr.null?
 
       tex = allocate
       tex.send(:_take_ownership, ptr)
@@ -51,7 +51,7 @@ module SFML
       ptr = srgb \
         ? C::Graphics.sfTexture_createSrgbFromMemory(buf, bytes.bytesize, nil) \
         : C::Graphics.sfTexture_createFromMemory(buf, bytes.bytesize, nil)
-      raise Error, "sfTexture_createFromMemory returned NULL — unsupported format?" if ptr.null?
+      raise LoadError, "sfTexture_createFromMemory returned NULL — unsupported format?" if ptr.null?
 
       tex = allocate
       tex.send(:_take_ownership, ptr)
@@ -69,7 +69,7 @@ module SFML
       ptr = srgb \
         ? C::Graphics.sfTexture_createSrgbFromStream(stream.to_ptr, nil) \
         : C::Graphics.sfTexture_createFromStream(stream.to_ptr, nil)
-      raise Error, "sfTexture_createFromStream returned NULL — unsupported format?" if ptr.null?
+      raise LoadError, "sfTexture_createFromStream returned NULL — unsupported format?" if ptr.null?
 
       tex = allocate
       tex.send(:_take_ownership, ptr)
@@ -86,7 +86,7 @@ module SFML
       ptr = srgb \
         ? C::Graphics.sfTexture_createSrgbFromImage(image.handle, nil) \
         : C::Graphics.sfTexture_createFromImage(image.handle, nil)
-      raise Error, "sfTexture_createFromImage returned NULL" if ptr.null?
+      raise LoadError, "sfTexture_createFromImage returned NULL" if ptr.null?
 
       tex = allocate
       tex.send(:_take_ownership, ptr)
@@ -110,7 +110,7 @@ module SFML
     # — useful for screenshots or post-processing inspection.
     def to_image
       ptr = C::Graphics.sfTexture_copyToImage(@handle)
-      raise Error, "sfTexture_copyToImage returned NULL" if ptr.null?
+      raise GraphicsError, "sfTexture_copyToImage returned NULL" if ptr.null?
       img = Image.allocate
       img.send(:_take_ownership, ptr)
       img
@@ -164,7 +164,7 @@ module SFML
     # Deep copy. The returned texture has its own GPU memory.
     def dup
       ptr = C::Graphics.sfTexture_copy(@handle)
-      raise Error, "sfTexture_copy returned NULL" if ptr.null?
+      raise GraphicsError, "sfTexture_copy returned NULL" if ptr.null?
 
       tex = self.class.allocate
       tex.send(:_take_ownership, ptr)

data/lib/sfml/graphics/texture_atlas.rb

@@ -0,0 +1,126 @@
+require "json"
+
+module SFML
+  # A sprite-sheet plus a frame-name → rectangle index. Loads the
+  # JSON descriptors that Aseprite and TexturePacker export — both
+  # use the same `frames + meta` shape, just with a few field
+  # differences we paper over.
+  #
+  #   atlas = SFML::TextureAtlas.load("hero.json")
+  #
+  #   atlas.texture                  #=> SFML::Texture
+  #   atlas.region("hero-walk-0")    #=> SFML::Rect
+  #   atlas.frame_names              #=> [...]
+  #   atlas.sprite("hero-walk-0")    #=> ready-to-draw SFML::Sprite
+  #   atlas.duration("hero-walk-0")  #=> Integer ms (Aseprite only)
+  #
+  # The image path inside the JSON is resolved relative to the JSON
+  # file's directory. Override with `image: "path/to/img.png"`.
+  #
+  # Frame lookups are tolerant of the `.png` extension — Aseprite
+  # exports `walk-0.png`, but you can write `atlas.region("walk-0")`.
+  class TextureAtlas
+    IMAGE_EXTS = /\.(?:png|jpg|jpeg|bmp|tga|gif)\z/i
+
+    # @param json_path [String] path to the atlas JSON
+    # @param image [String, nil] explicit image path (overrides
+    #   the path embedded in the JSON's `meta.image` field)
+    # @return [TextureAtlas]
+    def self.load(json_path, image: nil, smooth: true)
+      data = JSON.parse(File.read(json_path))
+      image_path = image || File.expand_path(data.dig("meta", "image") || "", File.dirname(json_path))
+      raise LoadError, "TextureAtlas: image not found at #{image_path}" unless File.file?(image_path)
+
+      texture = Texture.load(image_path, smooth: smooth)
+      regions, durations = _parse_frames(data["frames"])
+      new(texture: texture, regions: regions, durations: durations, source: json_path)
+    end
+
+    # Build directly from a Texture + a frame Hash — useful when
+    # generating atlases procedurally or when the descriptor lives
+    # in a different format you've already parsed.
+    def initialize(texture:, regions:, durations: {}, source: nil)
+      @texture   = texture
+      @regions   = regions.transform_keys { |k| _normalize(k) }.freeze
+      @durations = durations.transform_keys { |k| _normalize(k) }.freeze
+      @source    = source
+    end
+
+    attr_reader :texture, :source
+
+    def frame_names = @regions.keys
+
+    # @return [SFML::Rect] the pixel rect for frame `name`.
+    # @raise [SFML::LoadError] if the frame isn't in this atlas.
+    def region(name)
+      @regions[_normalize(name)] or
+        raise LoadError, "TextureAtlas: no frame named #{name.inspect} " \
+                         "(have: #{@regions.keys.first(5).inspect}...)"
+    end
+
+    # Build a fresh Sprite bound to the atlas texture with its
+    # texture_rect set to this frame.
+    def sprite(name, **opts)
+      Sprite.new(@texture, **opts).tap { |s| s.texture_rect = region(name) }
+    end
+
+    # Build an Animation from a list of frame names. When `fps:` is
+    # nil and Aseprite-style `duration` data is present, the per-frame
+    # durations are used directly — letting artists set timing in
+    # Aseprite without re-tuning in code. Pass an explicit `fps:` to
+    # override.
+    def animation(frame_names, fps: nil, loop: true)
+      rects = frame_names.map { |n| region(n) }
+      if fps.nil? && frame_names.first && duration(frame_names.first) > 0
+        # Use Aseprite's per-frame ms timings — collapse to average
+        # fps for the Animation; per-frame durations would need a
+        # variable-rate Animation we don't ship yet.
+        avg_ms = frame_names.map { |n| duration(n) }.sum / frame_names.size.to_f
+        fps = 1000.0 / avg_ms if avg_ms > 0
+      end
+      Animation.new(self, frames: rects, fps: fps || 12, loop: loop)
+    end
+
+    # Integer milliseconds per frame, as exported by Aseprite. Returns
+    # 0 if the source didn't include durations (TexturePacker etc.).
+    def duration(name) = @durations[_normalize(name)] || 0
+
+    # The internal frame-name → Rect hash. Useful for filtering:
+    #
+    #   walk_frames = atlas.regions.select { |k, _| k.start_with?("walk-") }
+    def regions = @regions
+
+    def to_s = "#<TextureAtlas #{@regions.size} frames#{@source ? " from #{File.basename(@source)}" : ""}>"
+    alias inspect to_s
+
+    # @!visibility private
+    def self._parse_frames(raw)
+      regions   = {}
+      durations = {}
+
+      entries =
+        case raw
+        when Hash  then raw.map { |name, entry| [name, entry] }
+        when Array then raw.map { |entry| [entry.fetch("filename"), entry] }
+        else            raise LoadError, "TextureAtlas: unexpected `frames` shape: #{raw.class}"
+        end
+
+      entries.each do |name, entry|
+        rect = entry.fetch("frame")
+        regions[name]   = Rect.new([rect["x"], rect["y"]], [rect["w"], rect["h"]])
+        durations[name] = entry["duration"] if entry["duration"]
+      end
+
+      [regions, durations]
+    end
+    private_class_method :_parse_frames
+
+    private
+
+    # Frame names are stored stripped of any image extension so
+    # callers can use either `walk-0` or `walk-0.png`.
+    def _normalize(name)
+      name.to_s.sub(IMAGE_EXTS, "")
+    end
+  end
+end

data/lib/sfml/graphics/transformable_object.rb

@@ -16,7 +16,7 @@ module SFML
 
     def initialize(**opts)
       ptr = C::Graphics.sfTransformable_create
-      raise Error, "sfTransformable_create returned NULL" if ptr.null?
+      raise GraphicsError, "sfTransformable_create returned NULL" if ptr.null?
       @handle = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfTransformable_destroy))
 
       self.position = opts[:position] if opts.key?(:position)
@@ -35,7 +35,7 @@ module SFML
 
     def dup
       ptr = C::Graphics.sfTransformable_copy(@handle)
-      raise Error, "sfTransformable_copy returned NULL" if ptr.null?
+      raise GraphicsError, "sfTransformable_copy returned NULL" if ptr.null?
       copy = self.class.allocate
       copy.instance_variable_set(:@handle,
         FFI::AutoPointer.new(ptr, C::Graphics.method(:sfTransformable_destroy)))

data/lib/sfml/graphics/vertex_array.rb

@@ -25,7 +25,7 @@ module SFML
 
     def initialize(primitive_type = :points, vertices = nil)
       ptr = C::Graphics.sfVertexArray_create
-      raise Error, "sfVertexArray_create returned NULL" if ptr.null?
+      raise GraphicsError, "sfVertexArray_create returned NULL" if ptr.null?
       @handle = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfVertexArray_destroy))
 
       self.primitive_type = primitive_type
@@ -113,7 +113,7 @@ module SFML
     # don't affect the other.
     def dup
       ptr = C::Graphics.sfVertexArray_copy(@handle)
-      raise Error, "sfVertexArray_copy returned NULL" if ptr.null?
+      raise GraphicsError, "sfVertexArray_copy returned NULL" if ptr.null?
       copy = self.class.allocate
       copy.instance_variable_set(:@handle,
         FFI::AutoPointer.new(ptr, C::Graphics.method(:sfVertexArray_destroy)))

data/lib/sfml/graphics/vertex_buffer.rb

@@ -49,7 +49,7 @@ module SFML
       end
 
       ptr = C::Graphics.sfVertexBuffer_create(n, ptype, uidx)
-      raise Error, "sfVertexBuffer_create returned NULL " \
+      raise GraphicsError, "sfVertexBuffer_create returned NULL " \
                    "(VBOs unavailable on this GPU?)" if ptr.null?
       @handle = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfVertexBuffer_destroy))
 
@@ -101,7 +101,7 @@ module SFML
       end
 
       ok = C::Graphics.sfVertexBuffer_update(@handle, buf, n, Integer(offset))
-      raise Error, "sfVertexBuffer_update failed " \
+      raise GraphicsError, "sfVertexBuffer_update failed " \
                    "(buffer too small or driver rejected the upload?)" unless ok
       self
     end