ruby2d 0.12.0 → 1.0.0

data/lib/ruby2d/triangle.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 # Ruby2D::Triangle
 
 module Ruby2D
@@ -9,22 +7,65 @@ module Ruby2D
 
     attr_accessor :x1, :y1,
                   :x2, :y2,
-                  :x3, :y3
-    attr_reader :color
-
-    # Create a triangle
-    # @param x1 [Numeric]
-    # @param y1 [Numeric]
-    # @param x2 [Numeric]
-    # @param y2 [Numeric]
-    # @param x3 [Numeric]
-    # @param y3 [Numeric]
-    # @param z [Numeric]
-    # @param color [String, Array] A single colour or an array of exactly 3 colours
-    # @param opacity [Numeric] Opacity of the image when rendering
-    # @raise [ArgumentError] if an array of colours does not have 3 entries
+                  :x3, :y3,
+                  :rotate,
+                  :fill, :stroke_width
+    attr_reader :color, :stroke_color
+    alias_method :stroke_colour, :stroke_color
+
+    # The x coordinate of the centroid
+    def x
+      (@x1 + @x2 + @x3) / 3.0
+    end
+
+    # The y coordinate of the centroid
+    def y
+      (@y1 + @y2 + @y3) / 3.0
+    end
+
+    # Set the x coordinate of the centroid, translating all vertices
+    def x=(new_x)
+      _require_numeric_position(:x, new_x)
+      dx = new_x - x
+      @x1 += dx
+      @x2 += dx
+      @x3 += dx
+    end
+
+    # Set the y coordinate of the centroid, translating all vertices
+    def y=(new_y)
+      _require_numeric_position(:y, new_y)
+      dy = new_y - y
+      @y1 += dy
+      @y2 += dy
+      @y3 += dy
+    end
+
+    # Bounding-box width and height (extent across the three vertices)
+    def width
+      xs = [@x1, @x2, @x3]
+      xs.max - xs.min
+    end
+
+    def height
+      ys = [@y1, @y2, @y3]
+      ys.max - ys.min
+    end
+
+    # Create a triangle. Specify vertices via `points:` or via `x1:`/`y1:`/...
+    # `points:` takes precedence if both are given.
     def initialize(x1: 50, y1: 0, x2: 100, y2: 100, x3: 0, y3: 100,
-                   z: 0, color: 'white', colour: nil, opacity: nil)
+                   points: nil,
+                   z: 0, rotate: 0, rx: nil, ry: nil,
+                   color: nil, colour: nil, opacity: nil,
+                   fill: true, stroke_width: 0, stroke_color: nil, stroke_colour: nil,
+                   add: true, visible: true)
+      if points
+        Triangle.send(:validate_points, points)
+        x1, y1 = points[0]
+        x2, y2 = points[1]
+        x3, y3 = points[2]
+      end
       @x1 = x1
       @y1 = y1
       @x2 = x2
@@ -32,14 +73,32 @@ module Ruby2D
       @x3 = x3
       @y3 = y3
       @z  = z
-      self.color = color || colour
-      self.color.opacity = opacity if opacity
-      add
+      @rotate = rotate
+      @_user_rx = rx
+      @_user_ry = ry
+      self.color = color || colour || 'white'
+      self.opacity = opacity unless opacity.nil?
+      @fill = fill
+      @stroke_width = stroke_width
+      self.stroke_color = stroke_color || stroke_colour || (color || colour)
+      self.stroke_color.opacity = opacity unless opacity.nil?
+      @visible = visible
+      self.add if add
     end
 
-    # Change the colour of the line
-    # @param [String, Array] color A single colour or an array of exactly 3 colours
-    # @raise [ArgumentError] if an array of colours does not have 3 entries
+    # Set the stroke color. Accepts a single color or a `Color::Set` of 3
+    # (one per vertex) interpolated around the perimeter. If nil, defaults to
+    # the fill color (preserving a per-vertex set when the fill is per-vertex).
+    def stroke_color=(c)
+      @stroke_color = Renderable.resolve_color_or_default(c, 3, label: self.class)
+      # A single stroke Color (not a per-vertex Set) takes the compact
+      # `stroke_triangle_uniform` fast path.
+      @_stroke_color_uniform = !@stroke_color.is_a?(Color::Set)
+      @_stroke_cc = nil
+    end
+    alias_method :stroke_colour=, :stroke_color=
+
+    # Set the color of the triangle
     def color=(color)
       # convert to Color or Color::Set
       color = Color.set(color)
@@ -51,81 +110,257 @@ module Ruby2D
       end
 
       @color = color # converted above
-      invalidate_color_components
+      # A single Color (not a per-vertex Set) is uniform across all three
+      # vertices, so it takes the compact `draw_triangle_uniform` fast path.
+      @_color_uniform = !color.is_a?(Color::Set)
+      @_cc = nil # invalidate cached color components
     end
 
-    # A point is inside a triangle if the area of 3 triangles, constructed from
-    # triangle sides and the given point, is equal to the area of triangle.
+    # Check if the triangle contains the given point (inside the rendered fill)
     def contains?(x, y)
-      self_area = triangle_area(@x1, @y1, @x2, @y2, @x3, @y3)
-      questioned_area =
-        triangle_area(@x1, @y1, @x2, @y2, x, y) +
-        triangle_area(@x2, @y2, @x3, @y3, x, y) +
-        triangle_area(@x3, @y3, @x1, @y1, x, y)
-
-      questioned_area <= self_area
-    end
-
-    # Draw a triangle
-    # @param x1 [Numeric]
-    # @param y1 [Numeric]
-    # @param x2 [Numeric]
-    # @param y2 [Numeric]
-    # @param x3 [Numeric]
-    # @param y3 [Numeric]
-    # @param z [Numeric]
-    # @param color [Array<Array<float,float,float,float>>] An array of 3 arrays of colour components
-    #                                  (e.g. [[1.0, 0, 0, 1.0], ...])
-    def self.draw(x1:, y1:, x2:, y2:, x3:, y3:, color:)
+      x, y = _unrotate(x, y)
+      _point_in_polygon?([@x1, @y1, @x2, @y2, @x3, @y3], x, y)
+    end
+
+    # Get the rotation center x coordinate
+    def rx
+      @_user_rx.nil? ? x : @_user_rx
+    end
+
+    # Get the rotation center y coordinate
+    def ry
+      @_user_ry.nil? ? y : @_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
+
+    # Render a triangle without creating an instance
+    def self.render(x1: 50, y1: 0, x2: 100, y2: 100, x3: 0, y3: 100,
+                    points: nil,
+                    rotate: 0, rx: nil, ry: nil,
+                    color: nil, colour: nil, opacity: nil,
+                    fill: true, stroke_width: 0, stroke_color: nil, stroke_colour: nil)
       Window.render_ready_check
-      ext_draw([
-                 x1, y1, *color[0], # splat the colour components
-                 x2, y2, *color[1],
-                 x3, y3, *color[2]
-               ])
+      if points
+        validate_points(points)
+        x1, y1 = points[0]
+        x2, y2 = points[1]
+        x3, y3 = points[2]
+      end
+      fill_input = color || colour
+      # Resolve the fill color once. A single Color (not a per-vertex Set) with
+      # scalar opacity is uniform across all three vertices and draws via the
+      # compact `draw_triangle_uniform`; otherwise build the per-vertex color
+      # array from the already-resolved color (no second parse).
+      # A per-vertex color flattens straight to floats, skipping the
+      # `Color::Set` the general path builds — that allocates and parses one
+      # `Color` per vertex on every call. `resolved` stays nil in that case
+      # and the stroke below resolves for itself if it ends up needing one.
+      # The `is_a?(Array)` guard is inline so the common single-color call
+      # doesn't pay for a method call that would only decline.
+      c = fill_input.is_a?(Array) ? Renderable.flatten_per_vertex(fill_input, 3, opacity) : nil
+      if c
+        resolved = nil
+        uniform = false
+      else
+        resolved = Color.for_render(fill_input.nil? ? 'white' : fill_input)
+        uniform = !resolved.is_a?(Color::Set) && !opacity.is_a?(Array)
+        c = uniform ? nil : Renderable.flatten_resolved_color(resolved, 3, opacity, label: self)
+      end
+
+      # Rotation is inlined into locals (as in `render` below and Line#render):
+      # a helper returning the rotated points would allocate an array per
+      # rotated shape per frame — measured 2.9µs vs 1.8µs per quad on wasm.
+      if rotate != 0
+        cx = rx || ((x1 + x2 + x3) / 3.0)
+        cy = ry || ((y1 + y2 + y3) / 3.0)
+        rad = rotate * Math::PI / 180.0
+        sa = Math.sin(rad)
+        ca = Math.cos(rad)
+        dx = x1 - cx; dy = y1 - cy
+        x1 = dx * ca - dy * sa + cx; y1 = dx * sa + dy * ca + cy
+        dx = x2 - cx; dy = y2 - cy
+        x2 = dx * ca - dy * sa + cx; y2 = dx * sa + dy * ca + cy
+        dx = x3 - cx; dy = y3 - cy
+        x3 = dx * ca - dy * sa + cx; y3 = dx * sa + dy * ca + cy
+      end
+
+      if fill
+        if uniform
+          a = opacity || resolved.a
+          Ext.draw_triangle_uniform(x1, y1, x2, y2, x3, y3, resolved.r, resolved.g, resolved.b, a)
+        else
+          c1r, c1g, c1b, c1a, c2r, c2g, c2b, c2a, c3r, c3g, c3b, c3a = c
+          Ext.draw_triangle(
+            x1, y1, c1r, c1g, c1b, c1a,
+            x2, y2, c2r, c2g, c2b, c2a,
+            x3, y3, c3r, c3g, c3b, c3a
+          )
+        end
+      end
+
+      # Resolve the stroke color only when actually stroking. A single stroke
+      # color draws via the compact `stroke_triangle_uniform`; a per-vertex Set
+      # keeps the splatting path. When no explicit stroke is given the stroke
+      # reuses the already-resolved fill color. (An explicit stroke color is
+      # still validated at stroke_width 0 below, matching the instance constructor.)
+      if stroke_width > 0
+        stroke_input = stroke_color || stroke_colour || fill_input
+        sresolved = if !stroke_input.equal?(fill_input)
+                      Color.for_render(stroke_input)
+                    else
+                      resolved || Color.for_render(fill_input.nil? ? 'white' : fill_input)
+                    end
+        if !sresolved.is_a?(Color::Set) && !opacity.is_a?(Array)
+          sa = opacity || sresolved.a
+          Ext.stroke_triangle_uniform(x1, y1, x2, y2, x3, y3, stroke_width,
+                                      sresolved.r, sresolved.g, sresolved.b, sa)
+        else
+          s1r, s1g, s1b, s1a, s2r, s2g, s2b, s2a, s3r, s3g, s3b, s3a =
+            Renderable.flatten_resolved_color(sresolved, 3, opacity, label: self)
+          Ext.stroke_triangle(
+            x1, y1, x2, y2, x3, y3, stroke_width,
+            s1r, s1g, s1b, s1a,
+            s2r, s2g, s2b, s2a,
+            s3r, s3g, s3b, s3a
+          )
+        end
+      elsif stroke_color || stroke_colour
+        Renderable.flatten_color(stroke_color || stroke_colour, 3, opacity, label: self)
+      end
     end
 
     private
 
+    def self.validate_points(points)
+      raise ArgumentError, 'Triangle requires exactly 3 points' unless points.length == 3
+      raise ArgumentError, 'points must be an array of [x, y] pairs' \
+        unless points.all? { |p| p.is_a?(Array) && p.length == 2 }
+    end
+    private_class_method :validate_points
+
     def render
-      color_comp_arrays = color_components
-      self.class.ext_draw([
-                            @x1, @y1, *color_comp_arrays[0], # splat the colour components
-                            @x2, @y2, *color_comp_arrays[1],
-                            @x3, @y3, *color_comp_arrays[2]
-                          ])
-    end
-
-    def triangle_area(x1, y1, x2, y2, x3, y3)
-      (x1 * y2 + x2 * y3 + x3 * y1 - x3 * y2 - x1 * y3 - x2 * y1).abs / 2
-    end
-
-    # Return colours as a memoized array of 3 x colour component arrays
-    def color_components
-      check_if_opacity_changed
-      @color_components ||= if @color.is_a? Color::Set
-                              # Extract colour component arrays; see +def color=+ where colour set
-                              # size is enforced
-                              [
-                                @color[0].to_a, @color[1].to_a, @color[2].to_a
-                              ]
-                            else
-                              # All vertex colours are the same
-                              c_a = @color.to_a
-                              [
-                                c_a, c_a, c_a
-                              ]
-                            end
-    end
-
-    # Invalidate memoized colour components if opacity has been changed via +color=+
-    def check_if_opacity_changed
-      @color_components = nil if @color_components && @color_components.first[3] != @color.opacity
-    end
-
-    # Invalidate the memoized colour components. Called when Line's colour is changed
-    def invalidate_color_components
-      @color_components = nil
+      ensure_cc
+      ensure_scc if @stroke_width && @stroke_width > 0
+
+      x1, y1, x2, y2, x3, y3 = @x1, @y1, @x2, @y2, @x3, @y3
+
+      # Rotation inlined into locals — see the `Triangle.render` note.
+      if @rotate != 0
+        cx = rx; cy = ry
+        rad = @rotate * Math::PI / 180.0
+        sa = Math.sin(rad)
+        ca = Math.cos(rad)
+        dx = x1 - cx; dy = y1 - cy
+        x1 = dx * ca - dy * sa + cx; y1 = dx * sa + dy * ca + cy
+        dx = x2 - cx; dy = y2 - cy
+        x2 = dx * ca - dy * sa + cx; y2 = dx * sa + dy * ca + cy
+        dx = x3 - cx; dy = y3 - cy
+        x3 = dx * ca - dy * sa + cx; y3 = dx * sa + dy * ca + cy
+      end
+
+      if @fill
+        cc = @_cc
+        if @_color_uniform
+          Ext.draw_triangle_uniform(x1, y1, x2, y2, x3, y3, cc[0], cc[1], cc[2], cc[3])
+        else
+          Ext.draw_triangle(
+            x1, y1, cc[0], cc[1], cc[2],  cc[3],
+            x2, y2, cc[4], cc[5], cc[6],  cc[7],
+            x3, y3, cc[8], cc[9], cc[10], cc[11]
+          )
+        end
+      end
+
+      if @stroke_width && @stroke_width > 0
+        scc = @_stroke_cc
+        if @_stroke_color_uniform
+          Ext.stroke_triangle_uniform(x1, y1, x2, y2, x3, y3, @stroke_width, scc[0], scc[1], scc[2], scc[3])
+        else
+          Ext.stroke_triangle(
+            x1, y1, x2, y2, x3, y3, @stroke_width,
+            scc[0], scc[1], scc[2],  scc[3],
+            scc[4], scc[5], scc[6],  scc[7],
+            scc[8], scc[9], scc[10], scc[11]
+          )
+        end
+      end
+    end
+
+    # Scene-graph draw hook (see Renderable#_render_scene). Triangle's `render`
+    # is already zero-arg, so the hook is the same method under the scene name.
+    alias_method :_render_scene, :render
+    public :_render_scene
+
+    # Build/rebuild flat per-vertex stroke color cache (3 × rgba = 12 floats)
+    def ensure_scc
+      if @_stroke_color_uniform
+        c = @stroke_color
+        if @_stroke_cc.nil? || @_stroke_cc[0] != c.r || @_stroke_cc[1] != c.g || @_stroke_cc[2] != c.b || @_stroke_cc[3] != c.a
+          @_stroke_cc = [c.r, c.g, c.b, c.a]
+        end
+      elsif @_stroke_cc.nil? || !scc_matches?
+        @_stroke_cc = Array.new(12)
+        3.times do |i|
+          c = @stroke_color.vertex(i)
+          @_stroke_cc[i * 4]     = c.r
+          @_stroke_cc[i * 4 + 1] = c.g
+          @_stroke_cc[i * 4 + 2] = c.b
+          @_stroke_cc[i * 4 + 3] = c.a
+        end
+      end
+    end
+
+    def scc_matches?
+      3.times do |i|
+        c = @stroke_color.vertex(i)
+        return false if @_stroke_cc[i * 4]     != c.r
+        return false if @_stroke_cc[i * 4 + 1] != c.g
+        return false if @_stroke_cc[i * 4 + 2] != c.b
+        return false if @_stroke_cc[i * 4 + 3] != c.a
+      end
+      true
+    end
+
+    # Build/rebuild flat color cache for the native extension
+    def ensure_cc
+      # Solid fill: cache 4 floats and validity-check 4 comparisons (the
+      # per-frame check still catches in-place `color.opacity=` fades). Mirrors
+      # the Circle/Ellipse single-color cache.
+      if @_color_uniform
+        c = @color
+        if @_cc.nil? || @_cc[0] != c.r || @_cc[1] != c.g || @_cc[2] != c.b || @_cc[3] != c.a
+          @_cc = [c.r, c.g, c.b, c.a]
+        end
+      elsif @_cc.nil? || !cc_matches?
+        @_cc = Array.new(12)
+        3.times do |i|
+          c = @color.vertex(i)
+          @_cc[i * 4]     = c.r
+          @_cc[i * 4 + 1] = c.g
+          @_cc[i * 4 + 2] = c.b
+          @_cc[i * 4 + 3] = c.a
+        end
+      end
+    end
+
+    def cc_matches?
+      3.times do |i|
+        c = @color.vertex(i)
+        return false if @_cc[i * 4]     != c.r
+        return false if @_cc[i * 4 + 1] != c.g
+        return false if @_cc[i * 4 + 2] != c.b
+        return false if @_cc[i * 4 + 3] != c.a
+      end
+      true
     end
   end
 end

data/lib/ruby2d/version.rb

@@ -1,7 +1,5 @@
-# frozen_string_literal: true
-
 # Ruby2D::VERSION
 
 module Ruby2D
-  VERSION = '0.12.0'
+  VERSION = '1.0.0'
 end

data/lib/ruby2d/vertices.rb

@@ -1,125 +1,102 @@
-# frozen_string_literal: true
-
 # Ruby2D::Vertices
 
 module Ruby2D
-  # This internal class generates a vertices array which are passed to the openGL rendering code.
-  # The vertices array is split up into 4 groups (1 - top left, 2 - top right, 3 - bottom right, 4 - bottom left)
-  # This class is responsible for transforming textures, it can scale / crop / rotate and flip textures
+  # Vertex and texture coordinates for tile placements
   class Vertices
+    # Texture coordinates for an uncropped quad (full image)
+    TEX_UNCROPPED_COORDS = [
+      0.0, 0.0, # top left
+      1.0, 0.0, # top right
+      1.0, 1.0, # bottom right
+      0.0, 1.0  # bottom left
+    ].freeze
+
+    # Create a vertex set for a tile placement
     def initialize(x, y, width, height, rotate, crop: nil, flip: nil)
-      @flip = flip
       @x = x
       @y = y
       @width = width.to_f
       @height = height.to_f
       @rotate = rotate
+      @crop = crop
+      apply_flip(flip)
       @rx = @x + (@width / 2.0)
       @ry = @y + (@height / 2.0)
-      @crop = crop
-      @coordinates = nil
-      @texture_coordinates = nil
-      _apply_flip unless @flip.nil?
     end
 
+    # Get the quad corner coordinates as a flat array
     def coordinates
-      @coordinates ||= if @rotate.zero?
-                         _unrotated_coordinates
-                       else
-                         _calculate_coordinates
-                       end
+      @coordinates ||= @rotate.zero? ? unrotated_coordinates : rotated_coordinates
     end
 
-    TEX_UNCROPPED_COORDS = [
-      0.0, 0.0, # top left
-      1.0, 0.0,   # top right
-      1.0, 1.0,   # bottom right
-      0.0, 1.0    # bottom left
-    ].freeze
-
+    # Get the texture UV coordinates as a flat array
     def texture_coordinates
-      @texture_coordinates ||= if @crop.nil?
-                                 TEX_UNCROPPED_COORDS
-                               else
-                                 _calculate_texture_coordinates
-                               end
+      @texture_coordinates ||= @crop ? cropped_texture_coordinates : TEX_UNCROPPED_COORDS
     end
 
     private
 
-    def rotate(x, y)
-      # Convert from degrees to radians
-      angle = @rotate * Math::PI / 180.0
+    def unrotated_coordinates
+      [
+        @x,          @y,           # top left
+        @x + @width, @y,           # top right
+        @x + @width, @y + @height, # bottom right
+        @x,          @y + @height  # bottom left
+      ]
+    end
 
-      # Get the sine and cosine of the angle
+    def rotated_coordinates
+      angle = @rotate * Math::PI / 180.0
       sa = Math.sin(angle)
       ca = Math.cos(angle)
 
-      # Translate point to origin
-      x -= @rx
-      y -= @ry
-
-      # Rotate point
-      xnew = x * ca - y * sa
-      ynew = x * sa + y * ca
-
-      # Translate point back
-      x = xnew + @rx
-      y = ynew + @ry
-
-      [x, y]
+      [
+        *rotate_point(@x,          @y,           sa, ca), # top left
+        *rotate_point(@x + @width, @y,           sa, ca), # top right
+        *rotate_point(@x + @width, @y + @height, sa, ca), # bottom right
+        *rotate_point(@x,          @y + @height, sa, ca)  # bottom left
+      ]
     end
 
-    def _unrotated_coordinates
-      x1 = @x
-      y1 = @y;           # Top left
-      x2 = @x + @width
-      y2 = @y;           # Top right
-      x3 = @x + @width
-      y3 = @y + @height; # Bottom right
-      x4 = @x
-      y4 = @y + @height; # Bottom left
-      [x1, y1, x2, y2, x3, y3, x4, y4]
-    end
+    # Rotate a point around the center of the quad, given the precomputed sine
+    # and cosine of the rotation angle
+    def rotate_point(x, y, sa, ca)
+      dx = x - @rx
+      dy = y - @ry
 
-    def _calculate_coordinates
-      x1, y1 = rotate(@x,          @y);           # Top left
-      x2, y2 = rotate(@x + @width, @y);           # Top right
-      x3, y3 = rotate(@x + @width, @y + @height); # Bottom right
-      x4, y4 = rotate(@x,          @y + @height); # Bottom left
-      [x1, y1, x2, y2, x3, y3, x4, y4]
+      [dx * ca - dy * sa + @rx,
+       dx * sa + dy * ca + @ry]
     end
 
-    def _calculate_texture_coordinates
-      img_width = @crop[:image_width].to_f
-      img_height = @crop[:image_height].to_f
-
-      # Top left
-      tx1 = @crop[:x] / img_width
-      ty1 = @crop[:y] / img_height
-      # Top right
-      tx2 = tx1 + (@crop[:width] / img_width)
-      ty2 = ty1
-      # Botttom right
-      tx3 = tx2
-      ty3 = ty1 + (@crop[:height] / img_height)
-      # Bottom left
-      # tx4 = tx1
-      # ty4 = ty3
-
-      [tx1, ty1, tx2, ty2, tx3, ty3, tx1, ty3]
+    def cropped_texture_coordinates
+      img_w = @crop[:image_width].to_f
+      img_h = @crop[:image_height].to_f
+
+      left   = @crop[:x] / img_w
+      top    = @crop[:y] / img_h
+      right  = left + (@crop[:width] / img_w)
+      bottom = top + (@crop[:height] / img_h)
+
+      [
+        left,  top,    # top left
+        right, top,    # top right
+        right, bottom, # bottom right
+        left,  bottom  # bottom left
+      ]
     end
 
-    def _apply_flip
-      if @flip == :horizontal || @flip == :both
+    def apply_flip(flip)
+      return unless flip
+
+      if flip == :horizontal || flip == :both
         @x += @width
         @width = -@width
       end
 
-      return unless @flip == :vertical || @flip == :both
-
-      @y += @height
-      @height = -@height
+      if flip == :vertical || flip == :both
+        @y += @height
+        @height = -@height
+      end
     end
   end
 end

data/lib/ruby2d/warnings.rb

@@ -0,0 +1,29 @@
+module Ruby2D
+  # Messages already emitted by `warn`, so a bad value produced every frame in a
+  # render loop warns a single time rather than flooding the console. Keyed by
+  # the message string.
+  @warned_messages = {}
+
+  # Emit a warning at most once per distinct message. Mirrors the native
+  # extension's `R2D_Log(R2D_WARN, ...)`: a bold-yellow `[WARN]` tag
+  # (`String#warning` shares the C side's `1;33`) followed by the message, on
+  # stderr — so Ruby and C warnings render identically. `Kernel#warn` isn't
+  # available under mruby, so write to `$stderr` directly.
+  def self.warn(message)
+    return if @warned_messages.key?(message)
+
+    @warned_messages[message] = true
+    $stderr.puts "#{'[WARN]'.warning} #{message}"
+  end
+
+  # Emit an informational diagnostic, mirroring the native extension's
+  # `R2D_Log(R2D_INFO, ...)`: a bold-blue `[INFO]` tag (`String#info` and the C
+  # side both use `1;34`) followed by the message, on stderr. Like the C side,
+  # INFO is suppressed unless diagnostics are enabled (`set(diagnostics: true)`)
+  # and — unlike `warn` — it never dedupes, so every diagnostic event prints.
+  def self.info(message)
+    return unless DSL.window? && DSL.window.diagnostics
+
+    $stderr.puts "#{'[INFO]'.info} #{message}"
+  end
+end