ruby2d 0.12.1 → 1.0.0

data/lib/ruby2d/atlas_parser.rb

@@ -0,0 +1,194 @@
+# Ruby2D::AtlasParser
+
+module Ruby2D
+  # Internal parser for sprite-sheet atlas files. Reads either Sparrow XML or
+  # TexturePacker JSON (Hash or Array variants) and returns a uniform shape:
+  #
+  #     { image_path: 'sheet.png',
+  #       frames: { 'frame_name' => { x:, y:, width:, height: }, ... } }
+  #
+  # Hand-written and Regexp-free so it works on mruby builds without the
+  # regex mrbgem.
+  module AtlasParser
+    class ParseError < StandardError; end
+
+    def self.parse_file(path)
+      data = File.read(path)
+      lower = path.to_s.downcase
+      if lower.end_with?('.xml')
+        parse_xml(data)
+      elsif lower.end_with?('.json')
+        parse_json(data)
+      else
+        sniff(data, path)
+      end
+    end
+
+    def self.sniff(data, path)
+      i = 0
+      i += 1 while i < data.length && ws?(data[i])
+      first = data[i]
+      return parse_xml(data) if first == '<'
+      return parse_json(data) if first == '{'
+
+      raise ParseError, "Cannot determine atlas format for #{path}"
+    end
+
+    def self.parse_xml(str)
+      atlas_attrs = find_tags(str, 'TextureAtlas').first
+      image_path = atlas_attrs && parse_xml_attrs(atlas_attrs)['imagePath']
+
+      frames = {}
+      find_tags(str, 'SubTexture').each do |attrs_str|
+        attrs = parse_xml_attrs(attrs_str)
+        name = attrs['name']
+        next unless name
+
+        rect = {
+          x: (attrs['x'] || '0').to_i,
+          y: (attrs['y'] || '0').to_i,
+          width: (attrs['width'] || '0').to_i,
+          height: (attrs['height'] || '0').to_i
+        }
+        # Extended Sparrow trim attributes: `frameWidth`/`frameHeight` give
+        # the original frame's logical dimensions, and `frameX`/`frameY` are
+        # the (negative) offset from the original frame's top-left to where
+        # the trimmed rect begins. Convert to a positive `trim_x`/`trim_y`.
+        if attrs['frameWidth'] || attrs['frameHeight'] || attrs['frameX'] || attrs['frameY']
+          rect[:source_width]  = (attrs['frameWidth']  || rect[:width]).to_i
+          rect[:source_height] = (attrs['frameHeight'] || rect[:height]).to_i
+          rect[:trim_x] = -(attrs['frameX'] || '0').to_i
+          rect[:trim_y] = -(attrs['frameY'] || '0').to_i
+        end
+        frames[name] = rect
+      end
+
+      { image_path: image_path, frames: frames }
+    end
+
+    def self.parse_json(str)
+      data = JsonParser.parse(str)
+      raise ParseError, 'Invalid JSON atlas: top-level value must be an object' unless data.is_a?(Hash)
+
+      meta = data['meta']
+      image_path = meta.is_a?(Hash) ? meta['image'] : nil
+
+      frames = {}
+      frames_data = data['frames']
+      if frames_data.is_a?(Hash)
+        frames_data.each { |name, info| frames[name] = extract_json_frame(info) }
+      elsif frames_data.is_a?(Array)
+        frames_data.each do |info|
+          next unless info.is_a?(Hash)
+
+          name = info['filename']
+          frames[name] = extract_json_frame(info) if name
+        end
+      else
+        raise ParseError, "Invalid JSON atlas: 'frames' must be a hash or array"
+      end
+
+      { image_path: image_path, frames: frames }
+    end
+
+    def self.extract_json_frame(info)
+      frame = info.is_a?(Hash) ? info['frame'] : nil
+      frame = {} unless frame.is_a?(Hash)
+      result = {
+        x: (frame['x'] || 0).to_i,
+        y: (frame['y'] || 0).to_i,
+        width: (frame['w'] || frame['width'] || 0).to_i,
+        height: (frame['h'] || frame['height'] || 0).to_i
+      }
+      # TexturePacker can pack frames rotated 90° to save atlas space.
+      # We capture the flag so the consumer can refuse or handle it; the
+      # key is omitted when false to keep the common-case hash lean.
+      result[:rotated] = true if info.is_a?(Hash) && info['rotated'] == true
+
+      # Trim metadata: `sourceSize` is the original frame's logical size,
+      # `spriteSourceSize.x/y` is where the packed pixels live within it.
+      source = info.is_a?(Hash) ? info['sourceSize'] : nil
+      sprite_source = info.is_a?(Hash) ? info['spriteSourceSize'] : nil
+      if source.is_a?(Hash) && (source['w'] || source['h'])
+        result[:source_width]  = (source['w'] || result[:width]).to_i
+        result[:source_height] = (source['h'] || result[:height]).to_i
+        if sprite_source.is_a?(Hash)
+          result[:trim_x] = (sprite_source['x'] || 0).to_i
+          result[:trim_y] = (sprite_source['y'] || 0).to_i
+        else
+          result[:trim_x] = 0
+          result[:trim_y] = 0
+        end
+      end
+
+      result
+    end
+
+    # Locate every `<TagName ...>` (or `<TagName ... />`) opening tag in `str`
+    # and return the inner attribute strings, in document order.
+    def self.find_tags(str, tag_name)
+      results = []
+      marker = "<#{tag_name}"
+      marker_len = marker.length
+      i = 0
+      while (pos = str.index(marker, i))
+        after_idx = pos + marker_len
+        after = str[after_idx]
+        # Confirm this is the right tag boundary (not a longer name like
+        # `<TextureAtlasFoo`)
+        if after && (ws?(after) || after == '>' || after == '/')
+          end_pos = str.index('>', after_idx)
+          break unless end_pos
+
+          attrs_str = str[after_idx...end_pos]
+          # Drop the trailing slash from self-closing tags.
+          attrs_str = attrs_str[0...-1] if attrs_str.end_with?('/')
+          results << attrs_str
+          i = end_pos + 1
+        else
+          i = pos + 1
+        end
+      end
+      results
+    end
+
+    # Parse `name="value"` (or `name='value'`) attributes out of an XML tag's
+    # attribute string. Tolerates extra whitespace between tokens.
+    def self.parse_xml_attrs(str)
+      attrs = {}
+      return attrs unless str
+
+      i = 0
+      len = str.length
+      while i < len
+        i += 1 while i < len && ws?(str[i])
+        break if i >= len
+
+        name_start = i
+        i += 1 while i < len && str[i] != '=' && !ws?(str[i])
+        name = str[name_start...i]
+
+        i += 1 while i < len && ws?(str[i])
+        break unless i < len && str[i] == '='
+
+        i += 1
+        i += 1 while i < len && ws?(str[i])
+        break unless i < len
+
+        quote = str[i]
+        break unless quote == '"' || quote == "'"
+
+        i += 1
+        val_start = i
+        i += 1 while i < len && str[i] != quote
+        attrs[name] = str[val_start...i]
+        i += 1 if i < len
+      end
+      attrs
+    end
+
+    def self.ws?(c)
+      c == ' ' || c == "\t" || c == "\n" || c == "\r"
+    end
+  end
+end

data/lib/ruby2d/audio.rb

@@ -0,0 +1,73 @@
+module Ruby2D
+  class Audio
+    attr_reader :path
+
+    # Create an audio object from a file
+    def initialize(path, loop: false)
+      @path = path.to_s
+      raise Error, "Cannot find audio file `#{@path}`" unless File.exist? @path
+
+      @loop = loop ? true : false
+      @ext_audio = Ext.audio_load(@path)
+    end
+
+    # Play the sound
+    def play
+      Ext.audio_play(@ext_audio, @loop)
+    end
+
+    # Pause the music
+    def pause
+      Ext.audio_pause(@ext_audio)
+    end
+
+    # Resume paused music
+    def resume
+      Ext.audio_resume(@ext_audio)
+    end
+
+    # Stop the sound
+    def stop(ms_fade = 0)
+      Ext.audio_stop(@ext_audio, ms_fade)
+    end
+
+    # Whether the audio loops on play
+    def looping?
+      @loop
+    end
+
+    # Set looping
+    def loop=(value)
+      @loop = value ? true : false
+      Ext.audio_set_loop(@ext_audio, @loop)
+    end
+
+    # Returns the length in seconds
+    def length
+      Ext.audio_length(@ext_audio)
+    end
+
+    # Get the volume of the sound, 0.0 to 1.0
+    def volume
+      Ext.audio_get_volume(@ext_audio)
+    end
+
+    # Set the volume of the sound, 0.0 to 1.0
+    def volume=(volume)
+      Ext.audio_set_volume(@ext_audio, volume.clamp(0.0, 1.0))
+    end
+
+    class << self
+      # Get the mixer volume, 0.0 to 1.0
+      def volume
+        Ext.audio_get_mixer_volume
+      end
+
+      # Set the mixer volume, 0.0 to 1.0
+      def volume=(volume)
+        Ext.audio_set_mixer_volume(volume.clamp(0.0, 1.0))
+      end
+    end
+
+  end
+end

data/lib/ruby2d/benchmark.rb

@@ -0,0 +1,259 @@
+module Ruby2D
+  # Lightweight benchmarking harness for Ruby 2D rendering performance.
+  #
+  # Runs a scene with fps_cap: :infinity (vsync off, no frame cap) and records
+  # per-frame deltas plus GC activity over a timed window.
+  # After a warmup period the harness samples each frame's duration,
+  # then auto-closes and prints a frame-time histogram and GC summary.
+  #
+  # Usage:
+  #
+  #   Ruby2D::Benchmark.run('My Scene', warmup: 10, duration: 5) do
+  #     # set up your scene / render block here
+  #   end
+  #
+  class Benchmark
+    DEFAULTS = { warmup: 10, duration: 5 }.freeze
+
+    # Per-frame CPU/present split. The wall-clock frame delta the harness
+    # records includes `SDL_RenderPresent`, which on a desktop compositor can
+    # be the dominant, floor-setting cost — so raw fps hides whether a change
+    # moved the CPU work at all (an empty window can even measure slower than a
+    # populated one). These accumulators, filled by the two wrappers installed
+    # in `run`, let the report separate CPU-build time from the present wait.
+    #   present_ns — time inside `Ext.end_frame` (≈ present; the cap delay is
+    #                off at fps_cap :infinity)
+    #   render_ns  — time inside `Window#render_objects` (scene-graph draw:
+    #                dispatch + FFI marshaling, plus any `render do` block)
+    # Both are summed per frame and read+reset each update tick. Wrapper-only
+    # state lives here (module methods can't close over harness locals); it is
+    # bench-only and never loaded by the gem proper.
+    module Clock
+      class << self
+        attr_accessor :present_ns, :render_ns
+      end
+      self.present_ns = 0.0
+      self.render_ns  = 0.0
+    end
+
+    # Wraps `Ext.end_frame` to accumulate present time. Prepended to the Ext
+    # singleton in `run`. The extra `Ext.now` reads are sub-microsecond and
+    # apply to every benchmark equally, so A/B comparisons stay consistent.
+    module PresentTimer
+      def end_frame(*args)
+        t = Ext.now
+        super
+      ensure
+        Clock.present_ns += Ext.now - t
+      end
+    end
+
+    # Wraps `Window#render_objects` to accumulate scene-graph draw time.
+    # Prepended to the benchmark window's singleton in `run`.
+    module RenderTimer
+      def render_objects(*args)
+        t = Ruby2D::Ext.now
+        super
+      ensure
+        Clock.render_ns += Ruby2D::Ext.now - t
+      end
+    end
+
+    attr_reader :name, :warmup, :duration
+
+    def initialize(name, warmup: DEFAULTS[:warmup], duration: DEFAULTS[:duration])
+      @name     = name
+      @warmup   = warmup
+      @duration = duration
+    end
+
+    def self.run(name, **opts, &block)
+      new(name, **opts).run(&block)
+    end
+
+    def run(&setup)
+      frame_times   = []
+      cpu_times     = []
+      render_times  = []
+      phase         = :warmup
+      phase_start   = nil
+      warmup_frames = 0
+      measure_start = nil
+      prev_t        = nil
+
+      gc_alloc_start = nil
+      gc_minor_start = nil
+      gc_major_start = nil
+      # mruby (the web build) has no `GC.stat`; skip the allocation section
+      # there rather than fault. CRuby reports it as before.
+      gc_available = GC.respond_to?(:stat)
+      @reported = false
+
+      w = DSL.window
+
+      # Install the CPU/present split probes (idempotent — prepend is a no-op
+      # if the module is already in the ancestor chain from a prior run).
+      Ext.singleton_class.prepend(PresentTimer)
+      w.singleton_class.prepend(RenderTimer)
+
+      # Uncap frame rate so we measure raw throughput
+      w.set(fps_cap: :infinity)
+
+      # Let the caller configure the scene (add objects, render blocks, etc.)
+      setup.call
+
+      # Chain any update proc the setup block registered so per-frame
+      # benchmark work runs alongside the harness phase logic.
+      user_update = w.instance_variable_get(:@update_proc)
+
+      w.update do
+        # Monotonic clock (matching the engine): immune to wall-clock jumps that
+        # would corrupt the frame-time histogram mid-measurement.
+        now = Ext.now
+
+        # Lazily initialise the phase timer on the first real frame —
+        # this avoids counting window-creation overhead as warmup time.
+        first_frame = phase_start.nil?
+        if first_frame
+          phase_start = now
+          prev_t = now
+        end
+
+        delta = now - prev_t
+        prev_t = now
+
+        # Read + reset the split the wrappers accumulated since the previous
+        # update tick — i.e. the frame that just completed, the same frame
+        # `delta` spans. `cpu` is the frame minus its present wait; clamp away
+        # sub-microsecond clock jitter that could make it momentarily negative.
+        present = Clock.present_ns
+        render  = Clock.render_ns
+        Clock.present_ns = 0.0
+        Clock.render_ns  = 0.0
+        cpu = delta - present
+        cpu = 0.0 if cpu.negative?
+
+        # Run the caller's update proc, forwarding the frame delta if it takes
+        # one (mirrors Window#update_callback's arity handling).
+        if user_update
+          user_update.arity.zero? ? user_update.call : user_update.call(delta)
+        end
+
+        next if first_frame  # exclude the first frame from phase timing
+
+        case phase
+        when :warmup
+          warmup_frames += 1
+          if now - phase_start >= @warmup
+            phase = :measure
+            measure_start = now
+            if gc_available
+              gc_alloc_start = GC.stat(:total_allocated_objects)
+              gc_minor_start = GC.stat(:minor_gc_count)
+              gc_major_start = GC.stat(:major_gc_count)
+            end
+          end
+        when :measure
+          frame_times  << delta
+          cpu_times    << cpu
+          render_times << render
+          if now - measure_start >= @duration
+            if gc_available
+              @gc_alloc_delta = GC.stat(:total_allocated_objects) - gc_alloc_start
+              @gc_minor_delta = GC.stat(:minor_gc_count) - gc_minor_start
+              @gc_major_delta = GC.stat(:major_gc_count) - gc_major_start
+            end
+            # Print from inside the loop: on the web build `w.show` never
+            # returns (emscripten unwinds the C stack, and `close` is a no-op
+            # there), so a report after `show` would be dead code
+            # there. The `@reported` guard keeps it to a single print.
+            unless @reported
+              report(frame_times, cpu_times, render_times, warmup_frames)
+              @reported = true
+            end
+            w.close
+          end
+        end
+      end
+
+      w.show
+
+      # CRuby returns here once the window closes; the web build never does
+      # (it reported from inside the loop above). Report only if the loop
+      # somehow exited without doing so.
+      report(frame_times, cpu_times, render_times, warmup_frames) unless @reported
+    end
+
+    private
+
+    def report(frame_times, cpu_times, render_times, warmup_frames)
+      puts "Ruby 2D Benchmark — #{@name}"
+      puts '-' * 60
+
+      if frame_times.empty?
+        puts '  No samples collected!'
+        puts
+        return
+      end
+
+      total       = frame_times.size
+      total_time  = frame_times.sum
+      avg_ms      = (total_time * 1000.0) / total
+      fps         = total / total_time
+
+      sorted   = frame_times.sort
+      pct      = ->(s, p) { s[[(s.size * p).floor, s.size - 1].min] * 1000.0 }
+      p50      = pct.call(sorted, 0.50)
+      p95      = pct.call(sorted, 0.95)
+      p99      = pct.call(sorted, 0.99)
+      p999     = pct.call(sorted, 0.999)
+      max_ms   = sorted.last * 1000.0
+
+      # CPU build (frame minus present) and its share of the scene-graph draw.
+      cpu_time    = cpu_times.sum
+      cpu_avg_ms  = (cpu_time * 1000.0) / total
+      cpu_fps     = cpu_time.positive? ? total / cpu_time : 0.0
+      cpu_sorted  = cpu_times.sort
+      present_avg_ms = ((total_time - cpu_time) * 1000.0) / total
+      render_avg_ms  = (render_times.sum * 1000.0) / total
+      render_p95_ms  = pct.call(render_times.sort, 0.95)
+
+      puts format('  %-14s %s', 'Warmup:', "#{@warmup}s (#{warmup_frames} frames)")
+      puts format('  %-14s %s', 'Measured:', "#{@duration}s (#{total} frames)")
+      puts
+      puts format('  %-14s %.1f fps  (%.2f ms/frame)', 'Throughput:', fps, avg_ms)
+      puts
+      puts '  Frame time (wall clock, incl. present):'
+      puts format('    %-10s %.2f ms', 'p50:', p50)
+      puts format('    %-10s %.2f ms', 'p95:', p95)
+      puts format('    %-10s %.2f ms', 'p99:', p99)
+      puts format('    %-10s %.2f ms', 'p99.9:', p999)
+      puts format('    %-10s %.2f ms', 'max:', max_ms)
+      puts
+      puts '  CPU build (frame minus present) — the per-object cost:'
+      puts format('    %-10s %.1f fps-equiv  (%.2f ms/frame)', 'throughput:', cpu_fps, cpu_avg_ms)
+      puts format('    %-10s %.2f ms', 'p50:', pct.call(cpu_sorted, 0.50))
+      puts format('    %-10s %.2f ms', 'p95:', pct.call(cpu_sorted, 0.95))
+      puts format('    %-10s %.2f ms', 'p99:', pct.call(cpu_sorted, 0.99))
+      puts format('    %-10s %.2f ms  (p95 %.2f ms)', 'render:', render_avg_ms, render_p95_ms)
+      puts format('    %-10s %.2f ms', 'present:', present_avg_ms)
+      puts
+
+      # GC stats are CRuby-only (see `gc_available`); the web build omits them.
+      if @gc_alloc_delta
+        puts '  GC:'
+        puts format('    %-12s %s objects (%s / frame)', 'Allocations:',
+                    thousands(@gc_alloc_delta), thousands((@gc_alloc_delta.to_f / total).round))
+        puts format('    %-12s %d', 'Minor GCs:', @gc_minor_delta)
+        puts format('    %-12s %d', 'Major GCs:', @gc_major_delta)
+      end
+      puts '-' * 60
+      puts
+    end
+
+    def thousands(n)
+      sign = n.negative? ? '-' : ''
+      "#{sign}#{n.abs.to_s.reverse.scan(/\d{1,3}/).join(',').reverse}"
+    end
+  end
+end

data/lib/ruby2d/bitmap_text.rb

@@ -0,0 +1,155 @@
+# Ruby2D::BitmapText
+
+module Ruby2D
+  # Text drawn with the built-in bitmap font (no TTF file needed)
+  class BitmapText
+    include Renderable
+
+    attr_reader :content, :scale, :x, :y
+    attr_accessor :rotate
+
+    # Set the x position. BitmapText has no symbolic alignment, so x must be a
+    # number — a symbol would otherwise crash with a type error at draw time.
+    def x=(value)
+      @x = _validate_coordinate(:x, value)
+    end
+
+    # Set the y position (numeric only — see `x=`).
+    def y=(value)
+      @y = _validate_coordinate(:y, value)
+    end
+
+    # Get the rotation center x coordinate (defaults to the text's center)
+    def rx
+      @_user_rx.nil? ? @x + @width / 2.0 : @_user_rx
+    end
+
+    # Get the rotation center y coordinate
+    def ry
+      @_user_ry.nil? ? @y + @height / 2.0 : @_user_ry
+    end
+
+    # Set the rotation center x coordinate
+    def rx=(val)
+      @_user_rx = val
+    end
+
+    # Set the rotation center y coordinate
+    def ry=(val)
+      @_user_ry = val
+    end
+
+    # Create a bitmap text object
+    def initialize(content, x: 0, y: 0, z: 0, scale: 3,
+                   rotate: 0, rx: nil, ry: nil,
+                   color: nil, colour: nil, opacity: nil,
+                   add: true, visible: true)
+      self.x = x
+      self.y = y
+      @z = z
+      @rotate = rotate
+      @_user_rx = rx
+      @_user_ry = ry
+      @content = content.to_s
+      @scale = validate_scale(scale)
+
+      self.color = color || colour || 'white'
+      self.opacity = opacity unless opacity.nil?
+      Ext.bitmap_text_create(self)
+
+      @visible = visible
+      self.add if add
+    end
+
+    # Set the text content. A no-op when the content is unchanged — rebuilding
+    # the texture is the expensive part, and per-frame assignments of the same
+    # string (HUDs, score counters) are common.
+    def content=(msg)
+      msg = msg.to_s
+      return if msg == @content
+
+      @content = msg
+      Ext.bitmap_text_create(self)
+    end
+
+    # Set the scale. A no-op when unchanged, like `content=` — rebuilding the
+    # texture is the expensive part.
+    def scale=(s)
+      s = validate_scale(s)
+      return if s == @scale
+
+      @scale = s
+      Ext.bitmap_text_create(self)
+    end
+
+    # Render the text. Called with overrides for one-shot rendering inside a
+    # render block; with no arguments it draws the same frame the scene graph
+    # does (delegating to `_render_scene`).
+    def render(x: nil, y: nil, scale: nil, rotate: nil, color: nil, colour: nil, opacity: nil)
+      if x.nil? && y.nil? && scale.nil? && rotate.nil? && color.nil? && colour.nil? && opacity.nil?
+        return _render_scene
+      end
+
+      Window.render_ready_check
+
+      saved_x, saved_y = @x, @y
+      saved_scale = @scale
+      saved_rotate = @rotate
+      saved_color = @color
+
+      @x = x if x
+      @y = y if y
+      @scale = validate_scale(scale) if scale
+      @rotate = rotate if rotate
+
+      c = color || colour
+      if c || opacity
+        @color = c ? Color.new(c) : Color.new(saved_color)
+        @color.opacity = opacity if opacity
+      end
+
+      begin
+        Ext.bitmap_text_draw(self, rx, ry)
+      ensure
+        @x, @y = saved_x, saved_y
+        @scale = saved_scale
+        @rotate = saved_rotate
+        @color = saved_color
+      end
+    end
+
+    private
+
+    # Scene-graph draw hook (see Renderable#_render_scene): `render` with no
+    # overrides, minus its keyword handling — a zero-arg call into a
+    # keyword-heavy `render` still pays microseconds of keyword setup on wasm
+    # mruby.
+    def _render_scene
+      Ext.bitmap_text_draw(self, rx, ry)
+    end
+    public :_render_scene
+
+    def _validate_coordinate(axis, value)
+      unless value.is_a?(Numeric)
+        raise Error,
+              "BitmapText #{axis} must be a number; symbolic alignment " \
+              "(e.g. #{axis}: :center) is not supported — use Text instead"
+      end
+      value
+    end
+
+    # Ensure the scale is a positive number, raising a clear error instead of
+    # letting an invalid value reach the native renderer (where a non-numeric
+    # value surfaces as a cryptic `TypeError` and zero/negative silently builds
+    # a blank, zero-or-negative-sized texture). Coerce to the same integer the
+    # native renderer uses (truncation toward zero) so the `scale` reader equals
+    # the scale actually rendered — e.g. `scale: 2.9` renders and reports 2.
+    def validate_scale(scale)
+      unless scale.is_a?(Numeric) && scale > 0
+        raise Error, "BitmapText scale must be a positive number, got #{scale.inspect}"
+      end
+
+      scale.to_i
+    end
+  end
+end