rgame 0.2.0 → 0.3.1

data/lib/rgame/engine/components/world.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # How big the world is — the contract, not an implementation.
+      #
+      # Two systems answer it: `World` below, which is nothing *but* the answer,
+      # and `TileWorld`, which derives it from the map it parsed. A component
+      # that needs bounds asks for the contract — `node.system(WorldBounds)` —
+      # and gets whichever of the two the scene mounted. That works because
+      # Node2D#get_component matches with `is_a?`, which matches an included
+      # module as readily as a class.
+      #
+      # Naming the contract is what keeps the two from drifting: ScreenWrap does
+      # not know which kind of world it is wrapping inside, and must not need to.
+      #
+      # ## The bounds are in world coordinates
+      #
+      # The world runs from (0, 0) to (world_width, world_height) in **world**
+      # space — the space `Node2D#world_x` answers in, and the one the tile grid,
+      # the collision world and the camera already use. So everything that
+      # compares a node against these bounds compares `world_x`/`world_y`, never
+      # the node's local `x`/`y`: an entity grouped under an offset container is
+      # still inside the world when it is, whatever its position in the container.
+      # spec/support/shared_examples/a_world_edge_response.rb holds every reader to it.
+      module WorldBounds
+        def world_width = raise(NotImplementedError, "#{self.class} must define #world_width")
+        def world_height = raise(NotImplementedError, "#{self.class} must define #world_height")
+
+        # The bounds a component should use: whatever it was handed, falling back
+        # to the world system on `node` for either axis left nil. The single place
+        # that fallback is written, so the components sharing it cannot drift.
+        #
+        # Call it from `on_attach`, not `initialize` — a node has no scene to ask
+        # until it is in the tree, and a pooled entity is built long before it is.
+        def self.resolve(node, width, height)
+          return [width, height] if width && height
+
+          bounds = node.system(self)
+          if bounds.nil?
+            raise 'no world bounds in scope: mount a World (or TileWorld) system on the scene, ' \
+                  'or pass explicit width:/height:'
+          end
+
+          [width || bounds.world_width, height || bounds.world_height]
+        end
+
+        # Refuse a node carrying more than one response to the edge of the world:
+        # ScreenWrap, DespawnOffscreen, or a Mover declaring `blocked_by: [:bounds]`.
+        #
+        # Stopping at the edge, wrapping past it and being freed beyond it are three
+        # answers to one question, and no two of them mean anything together. Stop and
+        # wrap disagree about where the node ends up; wrap and despawn race on which
+        # margin is reached first; and the stop works on the collision box while the
+        # other two test the node's origin, so a box with an offset holds the origin
+        # just past the edge and the other response fires on a node that was held.
+        # Rather than a rule each game has to remember, it raises.
+        #
+        # Folding wrap and despawn into Mover as one `at_edge:` option would make two
+        # responses inexpressible too, but they act on the node however it moved — a reset,
+        # an ancestor, a direct write — and every option there is a branch on the free
+        # step's path. A refusal at attach costs no frame anything. It is also the place
+        # to change if a game wants wrapping on one axis and stopping on the other: the
+        # rule then becomes one response per axis.
+        #
+        # Every response calls this from its own on_attach, which is what makes it
+        # order-free: a node assembled outside the tree already holds all its
+        # components when the first attaches, and on a live node each attaches on
+        # arrival, so the second response always finds the first.
+        #
+        # A pooled node re-attaches on every spawn, so this walks the components
+        # without allocating, and builds a message only when it raises.
+        def self.one_response!(node)
+          first = nil
+          node.components.each do |component|
+            next unless edge_response?(component)
+            next first = component if first.nil?
+
+            raise "#{node.class} has two responses to the edge of the world: " \
+                  "#{describe_response(first)} and #{describe_response(component)}. " \
+                  'A node can stop at the edge, wrap past it or be freed beyond it, but ' \
+                  'only one of those — keep the one this node is for.'
+          end
+        end
+
+        def self.edge_response?(component)
+          component.is_a?(ScreenWrap) || component.is_a?(DespawnOffscreen) ||
+            (component.is_a?(Mover) && component.blocked_by?(Mover::BOUNDS))
+        end
+        private_class_method :edge_response?
+
+        def self.describe_response(component)
+          name = component.class.name&.split('::')&.last || component.class.inspect
+          component.is_a?(Mover) ? "#{name} (blocked_by :bounds)" : name
+        end
+        private_class_method :describe_response
+      end
+
+      # The scene-scoped world: how big it is, and nothing else yet.
+      #
+      # A game whose world is a plain rectangle mounts one on its scene, and the
+      # components that need bounds — ScreenWrap, DespawnOffscreen — find it
+      # rather than having the numbers threaded through every constructor between
+      # the scene and the entity. That threading is what this replaces, and it was
+      # worse than it looks: a pooled entity is built outside the tree, so its
+      # factory had to close over the size, and every scene above the factory had
+      # to carry the size in order to build it.
+      #
+      # It is deliberately **not** the window size. The two coincide in a
+      # single-screen game, which is exactly what makes the mistake easy to make
+      # and hard to see: bind wrapping to the viewport and the world silently
+      # changes shape when the window is resized, or when the screen is split and
+      # each half is its own viewport. Ask `Viewports` (or the `View` a draw is
+      # handed) how big the *window* is; ask this how big the *world* is.
+      #
+      # The bounds are immutable, which is what lets the components resolve them
+      # once at attach rather than re-reading them every frame. A world that
+      # genuinely changes size is a new scene.
+      class World < Engine::Component
+        include WorldBounds
+
+        attr_reader :world_width, :world_height
+
+        def initialize(width:, height:)
+          super()
+          @world_width = width
+          @world_height = height
+        end
+      end
+    end
+  end
+end

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

@@ -22,22 +22,20 @@ module RGame
     #
     # - **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 — `examples/14_asteroids` does not) reads as 0×0, which would
-    #   otherwise cull everything instantly. Unknown means draw.
+    #   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 absolute origin, so a rotated footprint can reach further than its
+    #   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
 
-      # Can this box be skipped for `view`? Coordinates are in the space the
-      # caller draws in — world coordinates under a camera.
       # 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.abs_angle.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))

data/lib/rgame/engine/debug_overlay.rb

@@ -35,22 +35,21 @@ module RGame
       OBJ_LABEL   = 'OBJ'
       DELTA_LABEL = 'Δ/f'
 
-      COLOR = [80, 255, 120].freeze # frozen so the renderer caches the resolved colour
-      PAD   = 8                     # margin from the screen edge
-      GAP   = 8                     # space between a label and its number
+      COLOR = [80, 255, 120].freeze
+      PAD   = 8
+      GAP   = 8
 
       def initialize
         @visible = false
         @prev_allocated = 0
-        @digit_widths  = Array.new(10) # measured once, then reused
-        @label_widths  = {}            # measured once per label, then reused
+        @digit_widths  = Array.new(10)
+        @label_widths  = {}
       end
 
       def visible? = @visible
 
       def toggle
         @visible = !@visible
-        # Baseline the counter on reveal so the first Δ/f isn't the whole run's history.
         @prev_allocated = GC.stat(:total_allocated_objects) if @visible
       end
 
@@ -70,8 +69,6 @@ module RGame
         @prev_allocated = allocated
 
         line_h  = renderer.text_height
-        # The view's size, not its position: inside a region that has been
-        # translated to its corner, adding `view.x` would offset a second time.
         right_x = view.width - PAD
         top_y   = view.height - PAD - (line_h * 3)
 
@@ -84,14 +81,11 @@ module RGame
 
       private
 
-      # A right-aligned "label  number" row ending at right_x.
       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
 
-      # Draw a non-negative integer right-aligned ending at right_x, digit by digit so no
-      # String is built per frame. Returns the x of the leftmost digit.
       def draw_uint(renderer, value, right_x, y)
         x = right_x
         more = true

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