rgame 0.4.0-x86_64-linux-gnu

data/lib/rgame/engine/contact_set.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # The colliders one collider is touching, this step and last. CollisionWorld owns
+    # one of these per registered collider and drives it, and together they are what
+    # turns a per-step overlap test into the two edges a game actually wants: the step
+    # a contact starts and the step it ends. Pure logic; no graphics.
+    #
+    # Nothing here is about overlapping, though, and it has a second user:
+    # every Components::Mover keeps one of *what stopped its step*, and gets on_blocked
+    # and on_unblocked out of it on exactly the same terms. What this class is, underneath
+    # its names, is "the set of things that were true this step and last".
+    #
+    # Two arrays, swapped rather than reallocated. `begin_frame` makes this step's list
+    # into last step's and empties the other one for refilling, so after the first few
+    # frames nothing here allocates — `Array#clear` keeps the capacity it grew to, the
+    # same trick SpatialHash#clear relies on.
+    #
+    # Membership is a linear scan by identity, and deliberately so. A Set or a Hash
+    # allocates on insert, and both are slower than scanning a handful of entries; a
+    # collider touching more than a handful of things at once is a design problem
+    # somewhere else, not a reason to index this.
+    class ContactSet
+      def initialize
+        @current = []
+        @previous = []
+      end
+
+      # Start a step: this step's contacts become the ones to compare against, and the
+      # list being filled is emptied. Swapped through a temporary rather than by
+      # `@current, @previous = @previous, @current`, which would allocate an Array every
+      # step — see .rubocop.yml on Style/SwapValues.
+      def begin_frame
+        filled = @current
+        @current = @previous
+        @previous = filled
+        @current.clear
+      end
+
+      # Forget everything, both steps. CollisionWorld calls this when a collider
+      # registers, so a pooled entity that died mid-contact cannot come back still
+      # holding the contacts it had in its previous life — which would otherwise
+      # surface as one spurious `on_separated` on its first step.
+      def reset
+        @current.clear
+        @previous.clear
+      end
+
+      # Record a contact for this step.
+      def add(other) = @current << other
+
+      # Already recorded this step? The broadphase offers a pair once per cell the two
+      # share, so this is what keeps one overlap from being counted twice.
+      def touching?(other) = @current.include?(other)
+
+      # Is this the *start* of a contact — a pair that was not touching last step? It
+      # reads only last step's list, so it gives the same answer either side of #add,
+      # and asking before recording is what reads as a guard.
+      def started?(other) = !@previous.include?(other)
+
+      # Yield every collider that was in contact last step and is not in contact now —
+      # the ending edge. Call it once every pair for the step has been recorded.
+      def each_ended
+        i = 0
+        while i < @previous.size
+          other = @previous[i]
+          i += 1
+          yield other unless @current.include?(other)
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/culling.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # Skipping a drawable that the viewport cannot show.
+    #
+    # Mixed into the components that draw a node's own footprint, which are the
+    # ones that know both where they put it and how big it is.
+    #
+    # ## Why it is worth doing at all
+    #
+    # It was not, while the world was drawn once: a handful of skipped draws
+    # against a frame's worth of work. Split-screen changes the arithmetic —
+    # the world is walked once per viewport, and an actor at one player's end of
+    # the map is off the *other* player's view every frame. What used to be a
+    # small saving becomes a saving multiplied by the number of people playing.
+    #
+    # ## Conservative on purpose
+    #
+    # Culling one frame too eagerly is a sprite popping in at the edge of the
+    # screen, which is worse than the draw it saved. So two rules:
+    #
+    # - **No size means no culling.** `node.width`/`height` are what a drawable's
+    #   footprint is measured from, and a node that never set them (nothing
+    #   requires it) reads as 0×0, which would otherwise cull everything
+    #   instantly. Unknown means draw.
+    # - **A rotated node is measured generously.** `Node2D#draw` rotates about the
+    #   node's own origin, so a rotated footprint can reach further than its
+    #   box in any direction. The margin is `width + height`, which is always at
+    #   least the diagonal `hypot(width, height)` and costs no square root on a
+    #   path that runs once per drawable per viewport.
+    module Culling
+      private
+
+      # hot-path
+      def culled?(view, x, y, width, height)
+        return false if width.zero? || height.zero?
+        return !view.visible?(x, y, width, height) if node.world_angle.zero?
+
+        margin = width + height
+        !view.visible?(x - margin, y - margin, width + (margin * 2), height + (margin * 2))
+      end
+    end
+  end
+end

data/lib/rgame/engine/debug_overlay.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # A hard-wired development overlay, toggled by F1 (see RGame::Game), reporting
+    # runtime health in the bottom-right corner: frame rate (FPS), the process'
+    # cumulative allocated-object count (OBJ), and the objects allocated since the last
+    # frame (Δ/f).
+    #
+    # **Δ/f is the one to watch, and it is a standing guard rather than a
+    # diagnostic for one past bug.** A clean per-frame path holds it near zero; a
+    # steady nonzero number is a garbage collection being scheduled. The cost is
+    # invisible by every other measure — nothing looks wrong, nothing is slower,
+    # until a pause lands mid-frame — so without a number on screen it is not
+    # noticed at all.
+    #
+    # Every layer can break it and each has its own way of doing so. Core can
+    # allocate in a binding, the engine layer in a component's `draw`, and game
+    # code in a scene that builds a string or an array per frame. RuboCop's
+    # `Game/NoInterpolationInHotPath` and `Game/NoNeedlessAllocation` catch the
+    # shapes they can see in *this* repo; they cannot see a game built on top,
+    # and they cannot see an allocation that happens inside a method they think
+    # is cheap. This can.
+    #
+    # Pure: it reads only GC.stat and draws against the renderer interface, so it stays
+    # headless-testable. The crux is that it must not allocate while drawing — the values
+    # change every frame, so the usual "cache the string, rebuild on change" trick would
+    # allocate a String per frame, and the meter would be measuring itself. Instead
+    # numbers are drawn digit-by-digit from a fixed set of pre-built single-character
+    # strings, which the font caches per glyph.
+    class DebugOverlay
+      DIGITS = %w[0 1 2 3 4 5 6 7 8 9].freeze
+
+      FPS_LABEL   = 'FPS'
+      OBJ_LABEL   = 'OBJ'
+      DELTA_LABEL = 'Δ/f'
+
+      COLOR = [80, 255, 120].freeze
+      PAD   = 8
+      GAP   = 8
+
+      def initialize
+        @visible = false
+        @prev_allocated = 0
+        @digit_widths  = Array.new(10)
+        @label_widths  = {}
+      end
+
+      def visible? = @visible
+
+      def toggle
+        @visible = !@visible
+        @prev_allocated = GC.stat(:total_allocated_objects) if @visible
+      end
+
+      # Laid out against the view it is drawn into rather than against the
+      # window, so it stays in the corner of whatever region it is given. It
+      # takes `fps` rather than reading it, for the same reason nothing here
+      # reads a clock: the number is measured by the shell that owns the loop
+      # and handed down. See CLAUDE.md, "`draw` renders state".
+      # Its own `:debug` band, which is the last one, so this lands over every
+      # other thing in the frame however the scene is arranged. Not a node, so
+      # it opens its own layer rather than being given one by the traversal.
+      def draw(renderer, view, fps)
+        return unless @visible
+
+        allocated = GC.stat(:total_allocated_objects)
+        delta = allocated - @prev_allocated
+        @prev_allocated = allocated
+
+        line_h  = renderer.text_height
+        right_x = view.width - PAD
+        top_y   = view.height - PAD - (line_h * 3)
+
+        renderer.layered(:debug) do
+          draw_line(renderer, FPS_LABEL, fps, right_x, top_y)
+          draw_line(renderer, OBJ_LABEL, allocated, right_x, top_y + line_h)
+          draw_line(renderer, DELTA_LABEL, delta, right_x, top_y + (line_h * 2))
+        end
+      end
+
+      private
+
+      def draw_line(renderer, label, value, right_x, y)
+        number_left = draw_uint(renderer, value, right_x, y)
+        renderer.text(label, number_left - GAP - label_width(renderer, label), y, color: COLOR)
+      end
+
+      def draw_uint(renderer, value, right_x, y)
+        x = right_x
+        more = true
+        while more
+          digit = value % 10
+          value /= 10
+          x -= digit_width(renderer, digit)
+          renderer.text(DIGITS[digit], x, y, color: COLOR)
+          more = value.positive?
+        end
+        x
+      end
+
+      def digit_width(renderer, digit)
+        @digit_widths[digit] ||= renderer.text_width(DIGITS[digit])
+      end
+
+      def label_width(renderer, label)
+        @label_widths[label] ||= renderer.text_width(label)
+      end
+    end
+  end
+end

data/lib/rgame/engine/i18n/plural.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module I18n
+      # A translation that varies with `count`: one `Template` per CLDR category
+      # the table spells out, and the locale of the table it came from, whose
+      # language decides which category a count falls into.
+      #
+      # Internal to `I18n`. A nested Hash in a table compiles to a Plural when
+      # every key is a category, every value is text, and `other` is among them;
+      # any other Hash is a level of nesting.
+      #
+      # @api private
+      class Plural
+        CATEGORIES = %i[zero one two few many other].freeze
+        CATEGORY_NAMES = CATEGORIES.map(&:name).freeze
+
+        attr_reader :locale
+
+        # The variable names any form uses, each once, and `count`, which every
+        # form is chosen by whether it prints it or not.
+        attr_reader :names
+
+        def self.forms?(entries)
+          entries.key?('other') &&
+            entries.all? { |name, value| CATEGORY_NAMES.include?(name) && value.is_a?(String) }
+        end
+
+        def initialize(locale, entries)
+          @locale = locale
+          @forms = entries.to_h { |name, source| [name.to_sym, Template.compile(source)] }.freeze
+          @names = @forms.values.flat_map(&:names).push(:count).uniq.freeze
+        end
+
+        # The template for `count`, whose category under this table's language
+        # is `category`. An explicit `zero` form wins for 0 in every language,
+        # and a category the table leaves out reads `other`.
+        def template_for(count, category)
+          (count == 0 && @forms[:zero]) || @forms[category] || @forms.fetch(:other) # rubocop:disable Style/NumericPredicate -- count may be any object
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/i18n/plural_rules.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module I18n
+      # CLDR plural categories for whole numbers, one rule per language. A rule
+      # takes the `count` a caller passed and returns one of `Plural::CATEGORIES`.
+      # Every built-in rule answers `:other` for a count that is not an Integer,
+      # because fractional counts have categories of their own that no built-in
+      # table spells out.
+      #
+      # Rules are keyed by language, and `I18n.plural_rule` adds or replaces one;
+      # a language with no rule counts like English.
+      #
+      # Source: the CLDR plural rules, https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html
+      module PluralRules
+        TWO_TO_FOUR = (2..4)
+        TWELVE_TO_FOURTEEN = (12..14)
+
+        def self.whole(&rule) = ->(count) { count.is_a?(Integer) ? rule.call(count.abs) : :other } # rubocop:disable Performance/RedundantBlockCall -- the rule runs after whole has returned, where yield has no block
+
+        def self.slavic_few?(count) = TWO_TO_FOUR.cover?(count % 10) && !TWELVE_TO_FOURTEEN.cover?(count % 100)
+
+        def self.million(count) = count.positive? && (count % 1_000_000).zero? ? :many : :other
+
+        private_class_method :whole, :slavic_few?, :million
+
+        ONE_OTHER = whole { |n| n == 1 ? :one : :other }
+        ONE_MILLION_OTHER = whole { |n| n == 1 ? :one : million(n) }
+        ZERO_ONE_MILLION_OTHER = whole { |n| n <= 1 ? :one : million(n) }
+
+        EAST_SLAVIC = whole do |n|
+          if n % 10 == 1 && n % 100 != 11 then :one
+          elsif slavic_few?(n) then :few
+          else :many
+          end
+        end
+
+        POLISH = whole do |n|
+          if n == 1 then :one
+          elsif slavic_few?(n) then :few
+          else :many
+          end
+        end
+
+        CZECH = whole do |n|
+          if n == 1 then :one
+          elsif TWO_TO_FOUR.cover?(n) then :few
+          else :other
+          end
+        end
+
+        ARABIC = whole do |n|
+          case n
+          when 0 then :zero
+          when 1 then :one
+          when 2 then :two
+          else
+            case n % 100
+            when 3..10 then :few
+            when 11..99 then :many
+            else :other
+            end
+          end
+        end
+
+        OTHER = ->(_count) { :other }
+
+        BUILT_IN = {
+          en: ONE_OTHER, de: ONE_OTHER, nl: ONE_OTHER, sv: ONE_OTHER, da: ONE_OTHER, nb: ONE_OTHER, fi: ONE_OTHER,
+          it: ONE_MILLION_OTHER, es: ONE_MILLION_OTHER,
+          fr: ZERO_ONE_MILLION_OTHER, pt: ZERO_ONE_MILLION_OTHER,
+          ru: EAST_SLAVIC, uk: EAST_SLAVIC, pl: POLISH, cs: CZECH,
+          ja: OTHER, zh: OTHER, ko: OTHER,
+          ar: ARABIC
+        }.freeze
+
+        DEFAULT = ONE_OTHER
+      end
+    end
+  end
+end

data/lib/rgame/engine/i18n/template.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module I18n
+      # One translated string, compiled once at load: the literal runs and the
+      # `%{name}` placeholders between them, so rendering is an append per part
+      # rather than a parse. `%%{` in the source is a literal `%{`.
+      #
+      # Internal to `I18n`; a game reaches translations through `I18n.t` or a
+      # `Text`, never through a Template.
+      #
+      # @api private
+      class Template
+        PLACEHOLDER = /%%\{|%\{([A-Za-z_]\w*)\}/
+
+        # The variable names the source uses, each once, in order of appearance.
+        attr_reader :names
+
+        def self.compile(source)
+          parts = []
+          literal = +''
+          position = 0
+          while (match = PLACEHOLDER.match(source, position))
+            literal << source[position...match.begin(0)]
+            if match[1]
+              parts << literal.freeze unless literal.empty?
+              parts << match[1].to_sym
+              literal = +''
+            else
+              literal << '%{'
+            end
+            position = match.end(0)
+          end
+          literal << source[position..]
+          parts << literal.freeze unless literal.empty?
+          new(parts)
+        end
+
+        def initialize(parts)
+          @parts = parts.freeze
+          @names = parts.grep(Symbol).uniq.freeze
+          @constant = @names.empty? ? -parts.join : nil
+        end
+
+        # The string with each placeholder replaced by `vars[name].to_s`. A
+        # template without placeholders returns the same frozen String every
+        # time. Every name in `names` must be a key of `vars`.
+        def render(vars)
+          return @constant if @constant
+
+          @parts.each_with_object(+'') do |part, out|
+            out << (part.is_a?(Symbol) ? vars.fetch(part).to_s : part)
+          end
+        end
+      end
+    end
+  end
+end