ruby2d 0.12.1 → 1.0.0

data/lib/ruby2d/color.rb

@@ -1,55 +1,80 @@
-# frozen_string_literal: true
-
 # Ruby2D::Color
 
 module Ruby2D
-  # Colors are represented by the Color class. Colors can be created from keywords
-  # (based on css), a hexadecimal value or an array containing a collection of
-  # red, green, blue, and alpha (transparency) values expressed as a Float from 0.0 to 1.0.
+  # A color from a keyword, hex value, or RGBA array
   class Color
-    # Color::Set represents an array of colors.
+    # An array of colors
     class Set
       include Enumerable
 
+      # Create a color set from an array of colors
       def initialize(colors)
+        raise Error, 'a Color::Set requires at least one color, got an empty array' if colors.empty?
+
         @colors = colors.map { |c| Color.new(c) }
       end
 
+      # Get a color by index
       def [](index)
         @colors[index]
       end
 
+      # Get the number of colors in the set
       def length
         @colors.length
       end
 
-      alias count length
-
+      # Iterate over each color
       def each(&block)
         @colors.each(&block)
       end
 
-      def first
-        @colors.first
+      # Get the first color, or the first `n` colors if a count is given
+      def first(*args)
+        @colors.first(*args)
       end
 
-      def last
-        @colors.last
+      # Get the last color, or the last `n` colors if a count is given
+      def last(*args)
+        @colors.last(*args)
       end
 
+      # Get the opacity of the first color
       def opacity
         @colors.first.opacity
       end
 
+      # Set the opacity for all colors
       def opacity=(opacity)
+        unless opacity.is_a?(Numeric)
+          raise ArgumentError, "opacity must be a number between 0.0 and 1.0, got #{opacity.inspect}"
+        end
+
         @colors.each do |color|
           color.opacity = opacity
         end
       end
+
+      # The color for the i-th vertex. Paired with `Color#vertex` so per-vertex
+      # rendering code can uniformly call `color.vertex(i)` whether it holds a
+      # single `Color` (every vertex is the same) or a `Color::Set`.
+      def vertex(i)
+        @colors[i]
+      end
     end
 
     attr_accessor :r, :g, :b, :a
 
+    # Bounded cache of parsed color strings, keyed by the user input.
+    # `'random'` is never cached (re-randomized on each call).
+    PARSE_CACHE_MAX = 256
+    @parse_cache = {}
+
+    # Bounded cache of shared Color instances for immediate-mode `.render`
+    # calls, keyed by the color string. See `Color.for_render`.
+    RENDER_CACHE_MAX = 256
+    @render_cache = {}
+
     # Based on clrs.cc
     NAMED_COLORS = {
       'navy' => '#001F3F',
@@ -73,17 +98,18 @@ module Ruby2D
       'random' => ''
     }.freeze
 
+    # Create a color from a keyword, hex string, array, or Color
     def initialize(color)
-      raise Error, "`#{color}` is not a valid color" unless self.class.valid? color
+      raise Error, "#{color.inspect} is not a valid color" unless self.class.valid? color
 
       case color
       when String
         init_from_string color
       when Array
-        @r = color[0]
-        @g = color[1]
-        @b = color[2]
-        @a = color[3]
+        @r = channel(color[0])
+        @g = channel(color[1])
+        @b = channel(color[2])
+        @a = color.length == 4 ? channel(color[3]) : 1.0
       when Color
         @r = color.r
         @g = color.g
@@ -93,10 +119,15 @@ module Ruby2D
     end
 
     class << self
-      # Return a color set if an array of valid colors
+      # Create a Color or Color::Set from the given value
       def set(colors)
-        # If a valid array of colors, return a `Color::Set` with those colors
-        if colors.is_a?(Array) && colors.all? { |el| Color.valid? el }
+        # Already a Color::Set (e.g. re-applying a gradient fill): pass through.
+        return colors if colors.is_a?(Color::Set)
+
+        # A non-empty array of valid colors becomes a `Color::Set`. An empty
+        # array is not a valid gradient, so it falls through to `Color.new`,
+        # which raises a clear "not a valid color" at the mistake site.
+        if colors.is_a?(Array) && !colors.empty? && colors.all? { |el| Color.valid? el }
           Color::Set.new(colors)
         # Otherwise, return single color
         else
@@ -104,86 +135,177 @@ module Ruby2D
         end
       end
 
-      # Check if string is a proper hex value
+      # Resolve a color for an immediate-mode class-level `.render` call.
+      # Behaves like `.set`, except string colors and flat `[r, g, b(, a)]`
+      # numeric arrays return a shared cached Color instance, skipping the
+      # validation re-scan and object allocation `.new` pays on every call —
+      # those two forms are the common case in per-frame draws, and on the web
+      # (mruby/wasm) that per-call cost dominates the frame budget. The cached
+      # instance is read and forwarded to the native draw call immediately; it
+      # must never be stored on an object or handed to user code (a later
+      # mutation would corrupt every subsequent lookup) — use `.set` anywhere
+      # the color is kept. `'random'` is never cached, so each call still
+      # rolls a fresh color.
+      def for_render(colors)
+        if colors.is_a?(String)
+          cached = @render_cache[colors]
+          return cached if cached
+          return Color.new(colors) if colors == 'random'
+
+          @render_cache.shift if @render_cache.size >= RENDER_CACHE_MAX
+          @render_cache[colors] = Color.new(colors)
+        elsif colors.is_a?(Array) && colors[0].is_a?(Numeric) && rgba_array?(colors)
+          # ^ The two inline checks pre-screen the non-match cases (an array of
+          # colors starts with a String/Array/Color, never a Numeric) so this
+          # per-draw-call path only pays the `rgba_array?` method call when the
+          # input is almost certainly a cacheable [r, g, b(, a)] array.
+          # Array keys are looked up by value, so mutating a previously seen
+          # array can't corrupt the mapping — it just misses and inserts a new
+          # entry. The stored key is a frozen copy for the same reason.
+          cached = @render_cache[colors]
+          return cached if cached
+
+          c = Color.new(colors)
+          @render_cache.shift if @render_cache.size >= RENDER_CACHE_MAX
+          @render_cache[colors.dup.freeze] = c
+        else
+          set(colors)
+        end
+      end
+
+      # A flat `[r, g, b]` or `[r, g, b, a]` numeric array — the array form a
+      # single color takes (an array of *colors* is a `Color::Set`, and its
+      # elements are never bare Numerics). `while`, not blocks — this guards
+      # the per-draw-call render path and block calls dominate on wasm mruby.
+      def rgba_array?(colors)
+        return false unless colors.is_a?(Array)
+
+        n = colors.length
+        return false unless n == 3 || n == 4
+
+        i = 0
+        while i < n
+          return false unless colors[i].is_a?(Numeric)
+          i += 1
+        end
+        true
+      end
+
+      # Check if the string is a valid hex color value
+      # Byte comparisons, not slicing: `valid?` calls this on every `Color.new`
+      # and on every per-vertex color of every immediate-mode draw, and the
+      # readable form (`[0]`, `[1..]`, `.chars`, plus a fresh literal for the
+      # allowed set) allocated about ten short-lived strings each time.
       def hex?(color_string)
-        # MRuby doesn't support regex, otherwise we'd do:
-        #   !(/^#[0-9A-F]{6}$/i.match(a).nil?)
-        color_string.instance_of?(String) &&
-          color_string[0] == '#' &&
-          color_string.length == 7
+        return false unless color_string.instance_of?(String) &&
+                            color_string.getbyte(0) == 35 # '#'
+
+        len = color_string.length
+        return false unless len == 4 || len == 7 || len == 9
+
+        i = 1
+        while i < len
+          b = color_string.getbyte(i)
+          return false unless (b >= 48 && b <= 57) ||   # 0-9
+                              (b >= 65 && b <= 70) ||   # A-F
+                              (b >= 97 && b <= 102)     # a-f
+
+          i += 1
+        end
+        true
       end
 
-      # Check if the color is valid
+      # Check if the value is a valid color
       def valid?(color)
         color.is_a?(Color) ||             # color object
           NAMED_COLORS.key?(color) ||     # keyword
           hex?(color) ||                  # hexadecimal value
-          (                               # Array of Floats from 0.0..1.0
+          (                               # [r, g, b] or [r, g, b, a] numbers
             color.instance_of?(Array) &&
-            color.length == 4 &&
+            (color.length == 3 || color.length == 4) &&
             color.all? { |el| el.is_a?(Numeric) }
           )
       end
 
-      #
-      # Backwards compatibility
-      alias is_valid? valid?
-      alias is_hex? valid?
+      # Parse a color string into a frozen `[r, g, b, a]` tuple, caching the
+      # result. Named colors and hex strings are cached; `'random'` is not.
+      # Callers must not mutate the returned array.
+      def parse_string(color)
+        # Check the cache first so the hot path (a previously-seen named or hex
+        # color) returns before the `'random'` literal comparison, which would
+        # otherwise allocate a fresh `'random'` string on every call. `'random'`
+        # is never cached, so it still falls through to a fresh value below.
+        cached = @parse_cache[color]
+        return cached if cached
+
+        return [rand, rand, rand, 1.0] if color == 'random'
+
+        source = hex?(color) ? color : NAMED_COLORS[color]
+        rgba = hex_to_f(source).freeze
+        @parse_cache.shift if @parse_cache.size >= PARSE_CACHE_MAX
+        @parse_cache[color] = rgba
+      end
+
+      private
+
+      # Convert a hex color (e.g. #FFF, #FFF000, #FFF000FF) to [r, g, b, a]
+      # floats in 0.0..1.0.
+      def hex_to_f(hex_color)
+        hex = hex_color[1..]
+        hex = hex.chars.map { |c| c * 2 }.join if hex.length == 3
+        rgba = hex.chars.each_slice(2).map { |pair| pair.join.to_i(16) }
+        rgba << 255 if rgba.length == 3
+        rgba.map { |n| n / 255.0 }
+      end
     end
 
-    # Convenience methods to alias `opacity` to `@a`
+    # Get the opacity
     def opacity
       @a
     end
 
+    # Set the opacity. Must be a single number; per-vertex opacity (an array)
+    # is only supported by shapes that handle it explicitly, such as Polyline.
+    # The value is clamped to 0.0..1.0 so an animation that momentarily drives
+    # opacity out of range degrades to fully transparent/opaque rather than
+    # wrapping the Uint8 alpha cast into a wrong, near-opaque byte.
     def opacity=(opacity)
-      @a = opacity
+      unless opacity.is_a?(Numeric)
+        raise ArgumentError, "opacity must be a number between 0.0 and 1.0, got #{opacity.inspect}"
+      end
+
+      @a = opacity.clamp(0.0, 1.0)
     end
 
-    # Return colour components as an array +[r, g, b, a]+
+    # Return the color components as an array
     def to_a
       [@r, @g, @b, @a]
     end
 
-    private
-
-    def init_from_string(color)
-      if color == 'random'
-        init_random_color
-      elsif self.class.hex?(color)
-        @r, @g, @b, @a = hex_to_f(color)
-      else
-        @r, @g, @b, @a = hex_to_f(NAMED_COLORS[color])
-      end
+    # The color for the i-th vertex. A single `Color` represents "every vertex
+    # is the same color," so every index returns self. Mirrors `Color::Set#vertex`
+    # so per-vertex rendering code can call `color.vertex(i)` without branching.
+    def vertex(_i)
+      self
     end
 
-    def init_random_color
-      @r = rand
-      @g = rand
-      @b = rand
-      @a = 1.0
-    end
+    private
 
-    # Convert from Fixnum (0..255) to Float (0.0..1.0)
-    def i_to_f(color_array)
-      b = []
-      color_array.each do |n|
-        b.push(n / 255.0)
-      end
-      b
+    def init_from_string(color)
+      @r, @g, @b, @a = self.class.parse_string(color)
     end
 
-    # Convert from hex value (e.g. #FFF000) to Float (0.0..1.0)
-    def hex_to_f(hex_color)
-      hex_color = (hex_color[1..]).chars.each_slice(2).map(&:join)
-      a = []
-
-      hex_color.each do |el|
-        a.push(el.to_i(16))
-      end
+    # Interpret a color channel on the 0.0..1.0 scale — the graphics-programming
+    # convention also used internally and by the renderer. Both integers and
+    # floats are taken at face value on this scale, so `1` is full intensity and
+    # `0` is none; for 0..255 byte values, use a hex string like `'#FF8000'`. An
+    # out-of-range value warns once and clamps to the nearest bound so the stored
+    # color always stays in range.
+    def channel(value)
+      return value.to_f if value >= 0.0 && value <= 1.0
 
-      a.push(255)
-      i_to_f(a)
+      Ruby2D.warn("color value #{value} is out of range; components must be 0.0..1.0")
+      value < 0.0 ? 0.0 : 1.0
     end
   end
 

data/lib/ruby2d/core.rb

@@ -1,32 +1,50 @@
-# frozen_string_literal: true
-
 # Ruby2D module and native extension loader
 
 unless RUBY_ENGINE == 'mruby'
   require 'ruby2d/cli/colorize'
   require 'ruby2d/exceptions'
+  require 'ruby2d/warnings'
+  require 'ruby2d/window/class_methods'
+  require 'ruby2d/window/key_events'
+  require 'ruby2d/window/mouse_events'
+  require 'ruby2d/window/gamepad_events'
+  require 'ruby2d/window/object_events'
+  require 'ruby2d/gamepad'
+  require 'ruby2d/window'
+  require 'ruby2d/interactive'
   require 'ruby2d/renderable'
   require 'ruby2d/color'
-  require 'ruby2d/window'
-  require 'ruby2d/dsl'
-  require 'ruby2d/quad'
-  require 'ruby2d/line'
+  require 'ruby2d/audio'
+  require 'ruby2d/canvas'
   require 'ruby2d/circle'
-  require 'ruby2d/rectangle'
-  require 'ruby2d/square'
-  require 'ruby2d/triangle'
-  require 'ruby2d/pixel'
-  require 'ruby2d/pixmap'
-  require 'ruby2d/pixmap_atlas'
+  require 'ruby2d/ellipse'
+  require 'ruby2d/font'
   require 'ruby2d/image'
+  require 'ruby2d/json_parser'
+  require 'ruby2d/atlas_parser'
+  require 'ruby2d/sprite_sheet'
+  require 'ruby2d/line'
+  require 'ruby2d/polygon'
+  require 'ruby2d/polyline'
+  require 'ruby2d/quad'
+  require 'ruby2d/rectangle'
   require 'ruby2d/sprite'
-  require 'ruby2d/tileset'
-  require 'ruby2d/font'
+  require 'ruby2d/square'
   require 'ruby2d/text'
-  require 'ruby2d/canvas'
-  require 'ruby2d/sound'
-  require 'ruby2d/music'
-  require 'ruby2d/texture'
+  require 'ruby2d/bitmap_text'
+  require 'ruby2d/tileset'
+  require 'ruby2d/triangle'
+  require 'ruby2d/button'
   require 'ruby2d/vertices'
-  require 'ruby2d/ruby2d' # load native extension
+  begin
+    require 'ruby2d/ruby2d' # load native extension
+  rescue LoadError
+    # The extension isn't built — most often because SDL3 wasn't available at
+    # install time (see ext/ruby2d/extconf.rb, which then installs without it).
+    # Print the same recovery guidance the install shows and stop cleanly, so
+    # the user gets the notice — not a cryptic "cannot load such file" backtrace.
+    require 'ruby2d/deps_help'
+    abort Ruby2D::DepsHelp.notice
+  end
+  require 'ruby2d/dsl' # must loaded last, needs native extension
 end

data/lib/ruby2d/deps_help.rb

@@ -0,0 +1,89 @@
+# Extension-free guidance for when Ruby 2D's native dependency, SDL3, isn't
+# available. Shared by `ext/ruby2d/extconf.rb` (install time, when the extension
+# can't link) and the native-load rescue in `ruby2d/core` (run time, when the
+# extension was never built) — so the message is authored once and can't drift.
+#
+# `require_relative` (not `require`) so it resolves both at install time, when
+# `lib/` isn't on the load path, and at run time, when it is.
+
+require_relative 'cli/colorize'
+require_relative '../../assets/target'
+
+module Ruby2D
+  module DepsHelp
+    module_function
+
+    # Detect the Linux distribution family from /etc/os-release.
+    def linux_distro
+      return :unknown unless File.exist?('/etc/os-release')
+
+      ids = File.read('/etc/os-release')
+                .scan(/^(?:ID|ID_LIKE)="?([^"\n]+)"?/)
+                .flatten
+                .flat_map(&:split)
+
+      return :debian   if ids.any? { |id| %w[ubuntu debian linuxmint].include?(id) }
+      return :fedora   if ids.any? { |id| %w[fedora rhel centos rocky almalinux].include?(id) }
+      return :arch     if ids.any? { |id| %w[arch manjaro endeavouros].include?(id) }
+      return :opensuse if ids.any? { |id| id.include?('suse') }
+
+      :unknown
+    end
+
+    # The package-manager command that installs the SDL3 development libraries on
+    # this platform, or nil when we can't name one (unknown Linux distro or BSD).
+    def sdl3_install_command
+      case AssetsTarget.host_os
+      when 'macos'
+        'brew install sdl3 sdl3_image sdl3_mixer sdl3_ttf'
+      when 'windows'
+        'pacman -S mingw-w64-ucrt-x86_64-SDL3 mingw-w64-ucrt-x86_64-SDL3_image mingw-w64-ucrt-x86_64-SDL3_mixer mingw-w64-ucrt-x86_64-SDL3_ttf'
+      when 'linux'
+        {
+          debian:   'sudo apt install libsdl3-dev libsdl3-image-dev libsdl3-mixer-dev libsdl3-ttf-dev',
+          fedora:   'sudo dnf install SDL3-devel SDL3_image-devel SDL3_mixer-devel SDL3_ttf-devel',
+          arch:     'sudo pacman -S sdl3 sdl3_image sdl3_mixer sdl3_ttf',
+          opensuse: 'sudo zypper install libSDL3-devel libSDL3_image-devel libSDL3_mixer-devel libSDL3_ttf-devel',
+        }[linux_distro]
+      when 'bsd'
+        host = RbConfig::CONFIG['host_os'].downcase
+        if    host.include?('freebsd') then 'sudo pkg install sdl3 sdl3_image sdl3_mixer sdl3_ttf'
+        elsif host.include?('openbsd') then 'doas pkg_add sdl3 sdl3-image sdl3-mixer sdl3-ttf'
+        elsif host.include?('netbsd')  then 'sudo pkgin install SDL3 SDL3_image SDL3_mixer SDL3_ttf'
+        end
+      end
+    end
+
+    # The two-path recovery notice, framed like the install banner. Either
+    # install SDL3 with a package manager and rebuild with `gem pristine`, or
+    # build the libraries locally with `ruby2d setup` (which rebuilds the
+    # extension for you). Shown when no SDL3 — bundled, cached, or system — is
+    # found, both at install time and when a Ruby 2D app is run before setup.
+    def notice
+      cmd = sdl3_install_command
+
+      body = []
+      body << "Ruby 2D installed, but its native extension isn't built —"
+      body << "no SDL3 libraries were found for #{AssetsTarget.target_id}."
+      body << ''
+      body << 'To finish, choose one:'
+      body << ''
+      if cmd
+        body << '• Install SDL3 with your package manager (easiest), then rebuild:'
+        body << "    #{cmd.bold}"
+        body << "    #{'gem pristine ruby2d'.bold}"
+      else
+        body << "• Install the SDL3 development libraries, then run #{'gem pristine ruby2d'.bold}"
+      end
+      body << ''
+      body << '• Build the libraries locally (no system packages needed):'
+      body << "    #{'ruby2d setup'.bold}"
+      body << ''
+      body << "See #{'ruby2d.com'.bold} for help."
+
+      header = '== Ruby 2D: native extension not built '.ljust(70, '=')
+      lines = ['', header, '', *body.map { |l| l.empty? ? '' : "  #{l}" }, '', '=' * 70, '']
+      lines.join("\n")
+    end
+  end
+end

data/lib/ruby2d/dsl.rb

@@ -1,52 +1,91 @@
-# frozen_string_literal: true
-
 module Ruby2D
-  # Ruby2D::DSL
+  # Domain-specific language methods for the top-level Ruby2D interface
   module DSL
-    @window = Ruby2D::Window.new
-
+    # Get the DSL window instance, constructing a default on first access
     def self.window
-      @window
+      @window ||= Ruby2D::Window.new
     end
 
+    # Set the DSL window instance
     def self.window=(window)
       @window = window
     end
 
-    def get(sym, opts = nil)
-      DSL.window.get(sym, opts)
+    # Whether a DSL window already exists, without constructing one. Used to
+    # enforce the single-window rule (reading `window` would auto-create one).
+    def self.window?
+      !@window.nil?
+    end
+
+    # Get a window attribute by name
+    def get(sym)
+      DSL.window.get(sym)
     end
 
+    # Set window attributes
     def set(opts)
       DSL.window.set(opts)
     end
 
-    def on(event, &proc)
-      DSL.window.on(event, &proc)
+    # Take a screenshot, saving to `path` (or a timestamped file if omitted)
+    def screenshot(path = nil)
+      DSL.window.screenshot(path)
     end
 
+    # Register an event handler
+    def on(event = nil, **filters, &proc)
+      DSL.window.on(event, **filters, &proc)
+    end
+
+    # Remove an event handler
     def off(event_descriptor)
       DSL.window.off(event_descriptor)
     end
 
+    # Set the update callback
     def update(&proc)
       DSL.window.update(&proc)
     end
 
-    def render(&proc)
-      DSL.window.render(&proc)
+    # Set the render callback. `z:` positions the block in the scene's
+    # z-order — `:foreground` (default), `:background`, or a number.
+    def render(z: :foreground, &proc)
+      DSL.window.render(z: z, &proc)
+    end
+
+    # Monotonic seconds since the engine started (see `Window#elapsed`)
+    def elapsed
+      DSL.window.elapsed
     end
 
+    # Clear all objects from the window
     def clear
       DSL.window.clear
     end
 
+    # The connected gamepads, in connect order
+    def gamepads
+      DSL.window.gamepads
+    end
+
+    # Load a gamepad mapping from a file path or a single mapping string
+    def add_gamepad_mapping(path_or_string)
+      DSL.window.add_gamepad_mapping(path_or_string)
+    end
+
+    # Show the window
     def show
       DSL.window.show
     end
 
+    # Close the window
     def close
       DSL.window.close
     end
+
+    # Request a render on the next tick (for :on_demand render mode)
+    def request_render
+      DSL.window.request_render
+    end
   end
 end