rgame 0.2.0 → 0.3.1

data/lib/rgame/engine/presentation.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # How a game's own resolution is presented on a window that may be a
+    # different size. Pure arithmetic: a size, a mode, and the scale and offset
+    # they imply. No renderer, no window, nothing to draw with.
+    #
+    #   presentation = Presentation.new(width: 640, height: 480, mode: :integer)
+    #   presentation.fit(1920, 1080)
+    #   presentation.scale_x   # => 2.0
+    #   presentation.offset_x  # => 320   (1920 - 640*2, halved)
+    #
+    # ## The problem it exists for
+    #
+    # A game laid out against fixed numbers — a 500x500 board centred by writing
+    # `x: 150` in a 800x600 window — keeps those numbers when the window grows.
+    # It does not re-centre; it sits in the top-left corner with the new space
+    # piled up to its right. Fullscreen makes that happen to every game that has
+    # not thought about it, because fullscreen is the screen's resolution and
+    # never the one the game asked for.
+    #
+    # There are two honest answers, and this is the second one:
+    #
+    # - **Re-layout.** Read the size you are drawing into and place things
+    #   relative to its edges. Right for a HUD or a menu, where extra space is
+    #   extra room. `examples/fullscreen` does this.
+    # - **Scale.** Keep the design size, and map it onto whatever the window is.
+    #   Right for a play area, where extra space should mean a bigger picture of
+    #   the same thing rather than more world. This class.
+    #
+    # A game usually wants both at once, which works: the scale applies to
+    # everything, and nodes still read their view's size — that size is just the
+    # *logical* one now, so it stops changing.
+    #
+    # ## The modes
+    #
+    # | | |
+    # |---|---|
+    # | `:disabled` | No scaling. The logical size *is* the window size, so it changes as the window does. |
+    # | `:stretch` | Fill the window exactly, distorting if the aspect ratios differ. |
+    # | `:letterbox` | Largest scale that fits, equal on both axes, centred. Bars on two sides. |
+    # | `:integer` | The same, rounded down to a whole number. |
+    #
+    # `:integer` is the one pixel art wants. A sprite drawn at 1.875x with nearest
+    # filtering has some source pixels covering two screen pixels and some
+    # covering one, and the unevenness crawls as anything moves. A whole-number
+    # factor makes every source pixel exactly the same square, which is what
+    # "pixel perfect" means.
+    #
+    # **It costs screen, sometimes a lot of it.** The factor is bounded by the
+    # tighter axis, and rounding that down can throw away most of a window. A
+    # 640x480 design measured against real screens:
+    #
+    # | window | `:integer` | `:letterbox` |
+    # |---|---|---|
+    # | 1920x1080 | 2x, 320px border | 2.25x |
+    # | 2560x1440 | 3x, 320px border | 3x |
+    # | 1600x900 | **1x**, 480px border | 1.875x |
+    # | 1280x720 | **1x**, 320px border | 1.5x |
+    #
+    # The 16:9 rows are the ones to look at before choosing this mode: 900 and
+    # 720 pixels of height are both short of the 960 that 2x needs, so the whole
+    # window drops to 1x and the game sits in a small island. A design height
+    # that divides common screen heights — 360 rather than 480 — is what avoids
+    # that, and it is a decision about the game's art, not about this class.
+    #
+    # ## What `:integer` does when the window is too small
+    #
+    # It scales by 1 and lets the content overrun, rather than dropping below a
+    # whole number. So the design size is a **minimum**: shrink the window under
+    # it and you see part of the game rather than all of it, smaller.
+    #
+    # That is the same choice SDL makes, and the alternative is worse for the
+    # case the mode exists for — falling back to a fractional scale would
+    # reintroduce exactly the uneven pixels the game asked to avoid, at the
+    # moment nobody is looking. Nothing here enforces a minimum window size;
+    # that would need SDL, and this class is pure.
+    class Presentation
+      MODES = %i[disabled stretch letterbox integer].freeze
+
+      # The logical size a game draws in. Under `:disabled` these follow the
+      # window; under every other mode they are fixed and the window does not
+      # matter to anything above this class.
+      attr_reader :width, :height
+
+      attr_reader :mode, :scale_x, :scale_y, :offset_x, :offset_y
+
+      def initialize(width:, height:, mode: :disabled)
+        raise ArgumentError, "unknown scale mode #{mode.inspect} — one of #{MODES.inspect}" \
+          unless MODES.include?(mode)
+        raise ArgumentError, 'a logical size needs a positive width and height' \
+          unless width.positive? && height.positive?
+
+        @logical_width = width
+        @logical_height = height
+        @mode = mode
+        fit(width, height)
+      end
+
+      # Switches mode and refits against the window it last saw, so a settings
+      # screen can change this while the game runs.
+      #
+      # The window size is remembered for exactly this: a caller changing the
+      # mode knows which mode it wants and has no reason to also know how big
+      # the window currently is, and asking it to pass one would be asking it to
+      # keep a copy of something this object already has.
+      def mode=(mode)
+        raise ArgumentError, "unknown scale mode #{mode.inspect} — one of #{MODES.inspect}" \
+          unless MODES.include?(mode)
+
+        @mode = mode
+        fit(@window_width, @window_height)
+      end
+
+      # Whether anything is being scaled. `:disabled` means the caller can skip
+      # pushing a transform at all rather than pushing an identity one.
+      #
+      # @api private
+      def scaled? = @mode != :disabled
+
+      # Recomputes for a window of this size. Mutates rather than returning a
+      # new object: it is read every frame and recomputed only on a resize, so
+      # there is no reason to allocate.
+      def fit(window_width, window_height)
+        @window_width = window_width
+        @window_height = window_height
+        case @mode
+        when :disabled then fit_disabled(window_width, window_height)
+        when :stretch then fit_stretch(window_width, window_height)
+        else fit_uniform(window_width, window_height)
+        end
+        self
+      end
+
+      private
+
+      def fit_disabled(window_width, window_height)
+        @width = window_width
+        @height = window_height
+        @scale_x = @scale_y = 1.0
+        @offset_x = @offset_y = 0.0
+      end
+
+      def fit_stretch(window_width, window_height)
+        @width = @logical_width
+        @height = @logical_height
+        @scale_x = window_width.to_f / @logical_width
+        @scale_y = window_height.to_f / @logical_height
+        @offset_x = @offset_y = 0.0
+      end
+
+      def fit_uniform(window_width, window_height)
+        @width = @logical_width
+        @height = @logical_height
+
+        fitting = [window_width.to_f / @logical_width, window_height.to_f / @logical_height].min
+        scale = @mode == :integer ? integer_scale(fitting) : fitting
+
+        @scale_x = @scale_y = scale
+        @offset_x = ((window_width - (@logical_width * scale)) / 2.0).floor
+        @offset_y = ((window_height - (@logical_height * scale)) / 2.0).floor
+      end
+
+      def integer_scale(fitting)
+        floored = fitting.floor
+        floored < 1 ? 1.0 : floored.to_f
+      end
+    end
+  end
+end

data/lib/rgame/engine/scene/scene_stack.rb

@@ -16,9 +16,9 @@ module RGame
 
         def push(scene)
           @stack.push(scene)
-          scene.parent = node          # so scene.root resolves up to the host
-          scene.scene = scene          # mark the scene as its subtree's scene boundary
-          scene.enter_tree             # cascades on_attach/on_add through the scene
+          scene.parent = node
+          scene.scene = scene
+          scene.enter_tree
           self
         end
 
@@ -26,7 +26,7 @@ module RGame
           scene = @stack.pop
           return self unless scene
 
-          scene.exit_tree              # cascades on_remove/on_detach, releasing systems
+          scene.exit_tree
           scene.scene = nil
           scene.parent = nil
           self

data/lib/rgame/engine/sealed_privates.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # The rule for the two classes a game subclasses, Node2D and Component: a
+    # non-public method whose name starts with `_` is the engine's machinery, and
+    # a subclass defining a method of the same name raises where it is defined.
+    #
+    #   class Hop < RGame::Engine::Node2D
+    #     def _draw_content(renderer, view) = ...   # NameError: would replace Node2D#_draw_content
+    #     def draw_children(renderer, view) = ...   # fine: no underscore, meant to be overridden
+    #   end
+    #
+    # `private` in Ruby says who may *call* a method, not who may *replace* one: a
+    # subclass method of the same name is found first, and the base class quietly
+    # stops doing what that method did — for that subclass only, with the failure
+    # somewhere else entirely. So the underscore is the opt-in. A private or
+    # protected method *without* one is a seam, meant to be overridden with
+    # `super`, and nothing guards it.
+    #
+    # Only the base class's own methods are sealed. A private hook an engine
+    # subclass writes for its own subclasses — Components::Mover's `take_step` —
+    # is not covered, and the underscore convention does not apply outside these
+    # two classes.
+    #
+    # What it cannot see: a method arriving through `include` or `prepend` of a
+    # module, which does not pass through `method_added`.
+    module SealedPrivates
+      def self.extended(base)
+        base.define_singleton_method(:sealed_base) { base }
+        base.singleton_class.send(:private, :sealed_base)
+      end
+
+      # Every method a subclass may not define: the base's non-public methods
+      # whose names start with `_`.
+      def sealed_methods
+        base = sealed_base
+        (base.private_instance_methods(false) + base.protected_instance_methods(false))
+          .select { |name| name.start_with?('_') }
+      end
+
+      def method_added(name)
+        super
+        base = sealed_base
+        return if equal?(base) || !name.start_with?('_')
+        return unless base.private_method_defined?(name, false) || base.protected_method_defined?(name, false)
+
+        raise NameError.new("#{self}##{name} would replace #{base}##{name}, which #{base} calls " \
+                            "itself, and #{base} would silently stop doing its job for this class. " \
+                            'Give the method another name.', name)
+      end
+    end
+  end
+end

data/lib/rgame/engine/spatial_hash.rb

@@ -13,22 +13,6 @@ module RGame
     #   rocks.each { |r| hash.insert(r, *r.aabb) }
     #   hash.query(*bullet.aabb) { |rock| ...narrowphase... }
     class SpatialHash
-      # Cell (col, row) → one integer key. The offset keeps negative cells (objects
-      # off-screen / mid-wrap) non-negative; the stride keeps pairs unique. Both are
-      # sized to keep every packed key inside a tagged Fixnum, so keying allocates
-      # nothing on the query path (CLAUDE.md: never allocate on the per-frame path).
-      #
-      # The ceiling that sizes them is Windows, not Linux/macOS: CRuby's immediate
-      # Fixnum range comes from a C `long`, which is 64 bits on LP64 (Linux, macOS)
-      # but stays 32 bits on Windows' LLP64 even in a 64-bit process — so a value
-      # comfortably inside Fixnum range on Linux (this packing used to run up to
-      # ~2**42) silently becomes a heap-allocated Bignum on Windows instead, one
-      # allocation per cell per query. OFFSET/STRIDE here keep the largest possible
-      # packed key (both coordinates at the far corner) under 2**28 — well inside
-      # Windows' ~2**30 Fixnum ceiling — while still allowing cell coordinates out
-      # to +/-8192, i.e. a world some sixteen million pixels wide at this file's own
-      # cell_size: 64 example. A game whose world exceeds that wraps into a
-      # neighbouring cell's key instead of raising; see #each_cell below.
       OFFSET = 1 << 13
       STRIDE = 1 << 14
 
@@ -46,6 +30,24 @@ module RGame
         each_cell(x, y, w, h) { |key| @buckets[key] << item }
       end
 
+      # Un-bucket an item from the cells the given box covers — the exact inverse of
+      # #insert, so the caller passes the box the item was **inserted at**, not where it
+      # is now. That is what keeps this stateless: nothing here remembers where anything
+      # was bucketed, and a mover that knows where it started can undo its own insert.
+      #
+      # An item that was never inserted (or a box that covers none of its cells) is a
+      # no-op rather than an error — removing something twice, or removing something that
+      # left the tree between two steps, is ordinary rather than a mistake.
+      #
+      # Allocation-free: `fetch` sidesteps the bucket Hash's default block, which would
+      # *create* an empty bucket for every cell walked.
+      def remove(item, x, y, w, h)
+        each_cell(x, y, w, h) do |key|
+          bucket = @buckets.fetch(key, nil)
+          bucket&.delete(item)
+        end
+      end
+
       # Yield every item whose buckets overlap the region. Dedup contract: an item
       # spanning several cells may be yielded more than once. Narrowphase callers
       # must already guard with `next if a.dead? || b.dead?` to make hits idempotent,
@@ -66,19 +68,49 @@ module RGame
         query(cx - r, cy - r, d, d, &)
       end
 
+      # Is the one cell containing the point (x, y) holding nothing? A point, not a
+      # region: pass any coordinate inside the cell you mean.
+      #
+      # An item is bucketed by its *bounding box*, and the cell walk is half-open on the
+      # far edge (see #last_cell), so "bucketed here" means "overlaps this cell's area"
+      # exactly: a box filling one cell fills that cell's bucket and no other, and one
+      # covering four cells fills four. So this answers occupancy, not just candidacy —
+      # it is true when nothing overlaps the cell at all. What it cannot know is whether
+      # an occupant still counts; `CollisionWorld#cell_empty?` adds that, skipping
+      # colliders whose node is queued for removal.
+      #
+      # Reads whatever the most recent inserts left behind: after `clear` every cell is
+      # empty until something is inserted again. Allocation-free — `fetch` deliberately
+      # sidesteps the bucket Hash's default block, which would *create* the bucket.
+      def cell_empty?(x, y)
+        bucket = @buckets.fetch(cell_key((x / @cell_size).floor, (y / @cell_size).floor), nil)
+        bucket.nil? || bucket.empty?
+      end
+
       private
 
+      def cell_key(col, row) = (col + OFFSET) * STRIDE + (row + OFFSET)
+
       def each_cell(x, y, w, h)
         col0 = (x / @cell_size).floor
         row0 = (y / @cell_size).floor
-        col1 = ((x + w) / @cell_size).floor
-        row1 = ((y + h) / @cell_size).floor
+        col1 = last_cell(x + w, col0)
+        row1 = last_cell(y + h, row0)
         row0.upto(row1) do |row|
           col0.upto(col1) do |col|
-            yield (col + OFFSET) * STRIDE + (row + OFFSET)
+            yield cell_key(col, row)
           end
         end
       end
+
+      def last_cell(edge, first)
+        cell = (edge / @cell_size).floor
+        cell -= 1 if (edge % @cell_size).zero?
+        # rubocop:disable Style/MinMaxComparison -- the [cell, first].max it asks for is
+        # what the project's own Game/NoNeedlessAllocation rejects on a per-frame path.
+        cell < first ? first : cell
+        # rubocop:enable Style/MinMaxComparison
+      end
     end
   end
 end

data/lib/rgame/engine/text.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require_relative 'i18n'
+
+module RGame
+  module Engine
+    # The string a node draws: a translation key, resolved through `I18n` and
+    # kept until one of its inputs changes — a variable, or the language.
+    #
+    #   @score = Engine::Text.new('hud.score', :score)       # built once, e.g. in initialize
+    #   renderer.text(@score.with(score: @points), 12, 10)   # every frame: cached, no allocation
+    #
+    # The names a `Text` is built with become the keywords of its `with`, so a
+    # forgotten or misspelt variable is Ruby's own `ArgumentError`. `to_s` reads
+    # a `Text` with the values its last `with` was given — so whatever draws it,
+    # a button's label among them, needs no values of its own — and raises
+    # before the first `with`. A `Text` with no names is read with `to_s`
+    # alone. Reading one whose variables and
+    # `I18n.generation` are unchanged returns the same frozen String and
+    # allocates nothing; otherwise it renders again. A `Text` never subscribes to
+    # `I18n`: it compares one Integer, so it holds nothing that could keep it
+    # alive.
+    #
+    # A `Text` answers `to_str`, so a renderer takes one where it takes a String,
+    # and it is `==` to the String it reads.
+    #
+    # `Text.literal` is a string that is never translated, and `Text.computed` a
+    # string a block builds. Both answer `with` and `to_s` the same way, so
+    # whatever draws a `Text` never asks which kind it holds.
+    class Text
+      NAME = /\A[a-z_][A-Za-z0-9_]*\z/
+      private_constant :NAME
+
+      class << self
+        # A `Text` that shows `string` in every language.
+        def literal(string) = Literal.new(string)
+
+        # A `Text` whose string the block builds from the keywords `names`, for
+        # text that is formatted rather than looked up. The block runs when a
+        # keyword or `I18n.generation` changes, never on an unchanged read, so a
+        # block that calls `I18n.t` follows the language too:
+        #
+        #   @clock = Engine::Text.computed(:seconds) { |seconds:| format_clock(seconds) }
+        def computed(*names, &block) = Computed.new(names, block)
+      end
+
+      # Generates the module that gives a `Text` its `with` for one list of
+      # names, the first time that list is seen, and shares it after.
+      module Accessors
+        @cache = {}
+
+        def self.for(names)
+          @cache[names] ||= generate(names)
+        end
+
+        class << self
+          private
+
+          def generate(names)
+            names.each do |name|
+              raise ArgumentError, "#{name.inspect} cannot be a variable name" unless NAME.match?(name)
+            end
+
+            Module.new.tap { |mod| mod.module_eval(accessor_source(names), __FILE__, __LINE__) }
+          rescue SyntaxError
+            raise ArgumentError, "#{names.inspect} cannot all be variable names"
+          end
+
+          def accessor_source(names)
+            return <<~RUBY if names.empty?
+              def with = to_s
+
+              def to_s
+                return @string if @generation == ::RGame::Engine::I18n.generation
+
+                refresh({})
+              end
+            RUBY
+
+            <<~RUBY
+              def with(#{names.map { "#{it}:" }.join(', ')})
+                if @generation == ::RGame::Engine::I18n.generation && #{names.map { "@_var_#{it} == #{it}" }.join(' && ')}
+                  return @string
+                end
+
+                #{names.map { "@_var_#{it} = #{it}" }.join('; ')}
+                refresh({ #{names.map { "#{it}: #{it}" }.join(', ')} })
+              end
+
+              def to_s
+                return @string if @generation == ::RGame::Engine::I18n.generation
+                unless defined?(@_var_#{names.first})
+                  raise ArgumentError, "\#{describe} needs #{names.map { "#{it}:" }.join(', ')}; call with first"
+                end
+
+                refresh({ #{names.map { "#{it}: @_var_#{it}" }.join(', ')} })
+              end
+            RUBY
+          end
+        end
+      end
+      private_constant :Accessors
+
+      # The key as given, without its scope.
+      attr_reader :key
+
+      # The variable names `with` takes, sorted.
+      attr_reader :names
+
+      attr_reader :scope
+
+      # A `Text` for `key`, whose translation prints the variables `names`.
+      # `scope: 'title_menu'` with key `'play'` resolves `'title_menu.play'`.
+      def initialize(key, *names, scope: nil)
+        @key = key.to_s.freeze
+        self.scope = scope
+        declare(names)
+      end
+
+      # Changes the scope the key resolves under; the next read resolves again.
+      def scope=(scope)
+        @scope = scope&.to_s&.freeze
+        @path = (@scope ? "#{@scope}.#{@key}" : @key).freeze
+        @generation = nil
+      end
+
+      # The same String as `to_s`, so a `Text` goes wherever a String is
+      # expected: `renderer.text(@title, 12, 10)`. Before the first `with`, a
+      # `Text` with names raises `ArgumentError` here too.
+      def to_str = to_s
+
+      # Equal to a String that reads the same, from either side, so a spy that
+      # recorded a `Text` matches the String it drew. Against anything else,
+      # including another `Text`, it compares by identity.
+      def ==(other) = other.is_a?(String) ? to_s == other : super
+
+      private
+
+      def declare(names)
+        @names = names.map(&:to_sym).sort.freeze
+        raise ArgumentError, "#{describe} declares a variable twice" if @names.uniq.size != @names.size
+
+        extend(Accessors.for(@names))
+      end
+
+      def refresh(vars)
+        generation = I18n.generation
+        @string = render(vars)
+        @generation = generation
+        @string
+      end
+
+      def render(vars) = I18n.render(@path, @names, vars).freeze
+
+      def describe = "Text #{@path.inspect}"
+
+      # A `Text` that is not translated: the same `with` and `to_s`, answering
+      # with one String.
+      class Literal < Text
+        def initialize(string) # rubocop:disable Lint/MissingSuper -- a literal has no key to resolve
+          @string = -string.to_s
+          @names = [].freeze
+        end
+
+        def with = @string
+        def to_s = @string
+
+        # A literal ignores a scope: there is no key to put one in front of.
+        def scope=(_scope); end
+      end
+      private_constant :Literal
+
+      # A `Text` built by a block from its keywords instead of from a key.
+      class Computed < Text
+        def initialize(names, block) # rubocop:disable Lint/MissingSuper -- a computed text has no key to resolve
+          raise ArgumentError, 'Text.computed needs a block' unless block
+
+          @block = block
+          declare(names)
+        end
+
+        # A computed text ignores a scope: there is no key to put one in front of.
+        def scope=(_scope); end
+
+        private
+
+        def render(vars) = @block.call(**vars)
+
+        def describe = 'Text.computed'
+      end
+      private_constant :Computed
+    end
+  end
+end

data/lib/rgame/engine/tile_blockers.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # The tile grid as a blocker source: axis-separated AABB-vs-tile collision
+    # resolution over a Util::SolidGrid, at a tile size. Assumes per-step movement smaller
+    # than a tile (no tunneling), which holds for our speeds.
+    #
+    # It answers the blocker-source question — "where does this box land moving dx" —
+    # which CollisionSystem asks of every source it holds; see its header for the
+    # protocol. Resolving X then Y (with the X result) is what gives wall-sliding, and
+    # that ordering lives in the system rather than here, so every source shares it.
+    #
+    # It also answers the protocol's optional fourth question, #travel? — whether a box can
+    # move along a segment without any resolve falling short — which is how a route is
+    # checked against the resolver that will stop the walker on it. It is the only source
+    # that answers it today.
+    #
+    # The arithmetic for both is Util::TileSweep's, in C: this class is its blocker-source
+    # face, adding what the protocol asks beyond the numbers. The grid is read, never copied,
+    # so a cell changed with SolidGrid#set_solid stops the next step.
+    class TileBlockers
+      # What a TileBlockers reports as having stopped a step. One object for the life of
+      # the process, answering the same two questions a collider does — so a handler reads
+      # `by.layer` whatever stopped it and never branches on what kind of thing it was. A
+      # tile has no node, so `node` is nil.
+      #
+      # It holds no state at all, which is what makes one TileBlockers safe to share
+      # between every body on the map: there is nothing here for two of them to race over.
+      class Tiles
+        def layer = :tiles
+        def node = nil
+      end
+
+      TILES = Tiles.new.freeze
+
+      def initialize(grid:, tile_width:, tile_height:)
+        @sweep = Util::TileSweep.new(grid, tile_width, tile_height)
+      end
+
+      def grid = @sweep.grid
+
+      # Move an AABB (top-left x, y; size w, h) by dx, snapping flush against solids. A Float.
+      def resolve_x(x, y, w, h, dx) = @sweep.resolve_x(x, y, w, h, dx)
+
+      def resolve_y(x, y, w, h, dy) = @sweep.resolve_y(x, y, w, h, dy)
+
+      # Whether the box travels (dx, dy) without any resolve along the way falling short of
+      # where it was heading — so a walker resolving its own steps against this source, each
+      # under a quarter tile, is never stopped on that segment. A landing *past* the intended
+      # one does not count as stopped, which is how CollisionSystem reads every source.
+      def travel?(x, y, w, h, dx, dy) = @sweep.travel?(x, y, w, h, dx, dy)
+
+      # The grid stopped it, and the grid is the same for everybody — so this is a
+      # constant rather than a record of the last step. See TILES.
+      def blocker = TILES
+
+      # A grid does not move, so there is nothing to re-index. Part of the blocker-source
+      # protocol Engine::CollisionSystem calls after every step; see its header.
+      def moved(_actor, _from_x, _from_y, _w, _h) = nil
+    end
+  end
+end

data/lib/rgame/engine/tile_map.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'rexml/document'
-require 'base64'
 require 'zlib'
 
 require_relative '../util'
@@ -20,7 +19,7 @@ module RGame
     # this class (see CLAUDE.md, "The rule points both ways"). So `load` hands
     # back a path and stops there.
     class TileMap
-      FLIP_MASK = 0x1FFFFFFF # strip Tiled's flip/rotation flags from a gid
+      FLIP_MASK = 0x1FFFFFFF
 
       attr_reader :width, :height, :tile_width, :tile_height,
                   :pixel_width, :pixel_height, :tileset_source, :firstgid
@@ -52,7 +51,7 @@ module RGame
         layers = []
         above = []
         root.each_element('layer') do |layer_el|
-          raw = Base64.decode64(layer_el.elements['data'].text.strip)
+          raw = layer_el.elements['data'].text.strip.unpack1('m')
           gids = Zlib::Inflate.inflate(raw).unpack('V*')
           gids.map! { |g| g & FLIP_MASK }
           layers << gids
@@ -71,7 +70,6 @@ module RGame
         )
       end
 
-      # True if a layer carries a Tiled bool custom property `name` set to "true".
       def self.layer_flag?(layer_el, name)
         props = layer_el.elements['properties']
         return false unless props
@@ -81,6 +79,7 @@ module RGame
         end
         false
       end
+      private_class_method :layer_flag?
 
       def initialize(width:, height:, tile_width:, tile_height:, tileset_source:, firstgid:, layers:, above: [])
         @width = width
@@ -133,7 +132,6 @@ module RGame
 
       private
 
-      # Pack the parsed per-layer gid rows into one flat Tensor ([col, row, layer]).
       def build_tiles(layers)
         tiles = Util::Tensor.new(@width, @height, layers.length, initial: 0)
         layers.each_with_index do |gids, layer|

data/lib/rgame/engine/tile_map_layer.rb

@@ -50,8 +50,6 @@ module RGame
         gap = under || world.first_above_layer
 
         world.layer_count.times do |index|
-          # A layer at or past the gap sits above the actors; z is only ever
-          # compared to a sibling's, so the +1 is a gap, not a magnitude.
           parent.add_node(new(layer: index, z: index < gap ? index : index + 1))
         end
         parent.add_node(Node2D.new(z: gap))