rgame 0.4.0-x86_64-linux-gnu

data/lib/rgame/engine/signal.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Signal
+      IDENTIFIER = /\A[a-z_][a-zA-Z0-9_]*\z/
+
+      # Class-level DSL for declaring signal "slots" so a host class need not hand-write
+      # the connect-forwarding boilerplate. `extend Engine::Signal::DSL`, then:
+      #
+      #   signal :on_clicked               # a no-arg signal
+      #   signal :on_changed, ChangeSignal # a typed signal (Signal.define(:index, :value))
+      #
+      # For :on_clicked this generates:
+      #   def on_clicked(&block) = on_clicked_signal.connect(&block) # public: subscribe, returns handle
+      #   def on_clicked_signal = (@on_clicked ||= type.new)         # private: the Signal, to emit on
+      #
+      # The Signal is built lazily on first use, so the host wires nothing in #initialize;
+      # emit from inside the host via the private `<name>_signal` reader.
+      module DSL
+        def signal(name, type = Signal.define)
+          ivar = :"@#{name}"
+          reader = :"#{name}_signal"
+
+          define_method(reader) do
+            instance_variable_get(ivar) || instance_variable_set(ivar, type.new)
+          end
+          private reader
+
+          define_method(name) { |&block| send(reader).connect(&block) }
+        end
+      end
+
+      def self.define(*fields)
+        fields.each do |field|
+          raise ArgumentError, "invalid field name: #{field.inspect}" unless field.to_s.match?(IDENTIFIER)
+        end
+
+        params = fields.size == 1 ? fields.first : fields.map { |f| "#{f}:" }.join(', ')
+        args = fields.join(', ')
+
+        Class.new do
+          class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+            # For fields [:x, :y] this generates:
+            #   def initialize
+            #     @listeners = []
+            #   end
+            #   def connect(&callback)
+            #     @listeners << callback
+            #     callback
+            #   end
+            #   def disconnect(handle) = @listeners.delete(handle)
+            #   def emit(x:, y:)
+            #     @listeners.each { it.call(x, y) }
+            #   end
+
+            def initialize
+              @listeners = []
+            end
+
+            def connect(&callback)
+              @listeners << callback
+              callback
+            end
+
+            def disconnect(handle) = @listeners.delete(handle)
+            def emit(#{params})
+              @listeners.each { it.call(#{args}) }
+            end
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/spatial_hash.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # A uniform-grid spatial hash for broadphase collision: bucket colliders into
+    # fixed-size cells, then test only candidates that share a cell instead of every
+    # pair. Pure logic; no graphics.
+    #
+    # Typical per-frame use: `clear`, `insert` every collider of the static set
+    # (here: rocks), then `query` around each moving collider (bullets, the ship).
+    #
+    #   hash.clear
+    #   rocks.each { |r| hash.insert(r, *r.aabb) }
+    #   hash.query(*bullet.aabb) { |rock| ...narrowphase... }
+    class SpatialHash
+      OFFSET = 1 << 13
+      STRIDE = 1 << 14
+
+      def initialize(cell_size:)
+        @cell_size = cell_size
+        @buckets = Hash.new { |h, key| h[key] = [] }
+      end
+
+      # Reuse the bucket arrays across frames (clear contents, keep capacity).
+      def clear
+        @buckets.each_value(&:clear)
+      end
+
+      def insert(item, x, y, w, h)
+        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,
+      # so we skip a per-query visited set and stay allocation-free.
+      def query(x, y, w, h, &)
+        each_cell(x, y, w, h) do |key|
+          bucket = @buckets[key]
+          bucket.each(&) unless bucket.empty?
+        end
+      end
+
+      # Broadphase a circle: yield every item bucketed in a cell the circle's bounding
+      # box covers — the radial counterpart to #query, for range/nearest lookups. Same
+      # dedup contract (an item may be yielded more than once; the narrowphase caller
+      # refines by true distance). Allocation-free.
+      def query_circle(cx, cy, r, &)
+        d = r * 2
+        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 = last_cell(x + w, col0)
+        row1 = last_cell(y + h, row0)
+        row0.upto(row1) do |row|
+          col0.upto(col1) do |col|
+            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

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'rexml/document'
+require 'zlib'
+
+require_relative '../util'
+require_relative 'tileset'
+
+module RGame
+  module Engine
+    # An orthogonal tile map parsed from a Tiled .tmx. Holds the per-layer gid
+    # arrays and geometry, and answers collision queries via its Tileset.
+    #
+    # `parse` takes a *string*, so the parsing itself needs no filesystem at all;
+    # `load` adds the file plumbing on top — reading the .tmx, following it to the
+    # .tsx it names, and working out where the tileset image sits relative to
+    # that. Both belong here. What does *not* is the image: a texture is a GPU
+    # handle, and the renderer that owns one lives a layer below and may not name
+    # this class (see CLAUDE.md, "The rule points both ways"). So `load` hands
+    # back a path and stops there.
+    class TileMap
+      FLIP_MASK = 0x1FFFFFFF
+
+      attr_reader :width, :height, :tile_width, :tile_height,
+                  :pixel_width, :pixel_height, :tileset_source, :firstgid
+      attr_accessor :tileset
+
+      # Reads a .tmx and everything it points at, returning `[map, image_path]`.
+      #
+      # Two values rather than one because they are two kinds of thing: the map is
+      # the grid, and the path is where its pixels happen to live. Keeping the
+      # second off the map means a stand-in map in a spec has one less method to
+      # answer, and the renderer's protocol stays "things about the grid".
+      #
+      # Every path is resolved relative to the file that named it — the .tsx
+      # relative to the .tmx, the image relative to the .tsx — which is what Tiled
+      # itself writes and what lets a map be moved as a set.
+      def self.load(tmx_path)
+        map = parse(File.read(tmx_path))
+
+        tsx_path = File.join(File.dirname(tmx_path), map.tileset_source)
+        map.tileset = Tileset.parse(File.read(tsx_path), firstgid: map.firstgid)
+
+        [map, File.join(File.dirname(tsx_path), map.tileset.image_source)]
+      end
+
+      def self.parse(tmx_string)
+        root = REXML::Document.new(tmx_string).root
+        tileset_el = root.elements['tileset']
+
+        layers = []
+        above = []
+        root.each_element('layer') do |layer_el|
+          raw = layer_el.elements['data'].text.strip.unpack1('m')
+          gids = Zlib::Inflate.inflate(raw).unpack('V*')
+          gids.map! { |g| g & FLIP_MASK }
+          layers << gids
+          above << layer_flag?(layer_el, 'above')
+        end
+
+        new(
+          width: root.attributes['width'].to_i,
+          height: root.attributes['height'].to_i,
+          tile_width: root.attributes['tilewidth'].to_i,
+          tile_height: root.attributes['tileheight'].to_i,
+          tileset_source: tileset_el.attributes['source'],
+          firstgid: tileset_el.attributes['firstgid'].to_i,
+          layers: layers,
+          above: above
+        )
+      end
+
+      def self.layer_flag?(layer_el, name)
+        props = layer_el.elements['properties']
+        return false unless props
+
+        props.each_element('property') do |property|
+          return property.attributes['value'] == 'true' if property.attributes['name'] == name
+        end
+        false
+      end
+      private_class_method :layer_flag?
+
+      def initialize(width:, height:, tile_width:, tile_height:, tileset_source:, firstgid:, layers:, above: [])
+        @width = width
+        @height = height
+        @tile_width = tile_width
+        @tile_height = tile_height
+        @pixel_width = width * tile_width
+        @pixel_height = height * tile_height
+        @tileset_source = tileset_source
+        @firstgid = firstgid
+        @above = above
+        @tileset = nil
+        @tiles = build_tiles(layers)
+      end
+
+      def layer_count
+        @tiles.depth
+      end
+
+      # Whether a layer is drawn *above* the actors (a tree canopy, roof, etc.) rather
+      # than beneath them. Marked in Tiled with a bool layer property `above`; layers
+      # without it default to below. Purely a rendering distinction (collision still
+      # considers every layer).
+      def above_layer?(index)
+        @above[index] || false
+      end
+
+      def in_bounds?(col, row)
+        col >= 0 && row >= 0 && col < @width && row < @height
+      end
+
+      def gid(layer_index, col, row)
+        return 0 unless in_bounds?(col, row)
+
+        @tiles[col, row, layer_index]
+      end
+
+      # Solid if any layer has a solid tile at (col, row). Out of bounds is not solid
+      # — the camera/bounds clamp keeps the player inside the map.
+      def solid_tile?(col, row)
+        return false unless in_bounds?(col, row)
+
+        @tiles.depth.times { |layer| return true if @tileset.solid?(@tiles[col, row, layer]) }
+        false
+      end
+
+      def solid_at?(world_x, world_y)
+        solid_tile?((world_x / @tile_width).floor, (world_y / @tile_height).floor)
+      end
+
+      private
+
+      def build_tiles(layers)
+        tiles = Util::Tensor.new(@width, @height, layers.length, initial: 0)
+        layers.each_with_index do |gids, layer|
+          @height.times do |row|
+            base = row * @width
+            @width.times { |col| tiles[col, row, layer] = gids[base + col] }
+          end
+        end
+        tiles
+      end
+    end
+  end
+end

data/lib/rgame/engine/tile_map_layer.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # One layer of the scene's tile map, drawn in world space, once per viewport.
+    #
+    #   world  = scene.add_node(WorldView.new)
+    #   actors = TileMapLayer.mount(world)
+    #   actors.add_node(player)
+    #
+    # A node per layer, and the layers Tiled lists are the layers you get. The
+    # scene tree is then what says what covers what: everything mounted before
+    # the actors draws under them, everything after draws over them, and the
+    # gap `mount` leaves is where the actors go.
+    #
+    # It belongs **inside a WorldView**, which is the whole point of it existing
+    # separately from Components::TileWorld. The map is world content: it
+    # scrolls under a camera and every player sees their own part of it, so it
+    # has to be drawn where the rest of the world is drawn rather than once for
+    # the frame.
+    #
+    # It carries no state. The map id and the animation clock come from the
+    # scene's TileWorld system, and the region worth drawing comes from the view.
+    #
+    # ## Why a node per layer, rather than two passes
+    #
+    # There used to be one of these, drawing a "below" band and an "above" band
+    # in one go and relying on a global z to slot the actors between them. Draw
+    # order is tree order now (see RGame::Util::Z), so a node's drawing is
+    # contiguous and "between them" has to mean "between two nodes".
+    #
+    # That turned out to be the better shape anyway. A designer already orders
+    # layers in Tiled and can see the result there; content can go between *any*
+    # two of them rather than at one flagged boundary; and the `above` property
+    # stops being something to remember on every layer — it is read once, by
+    # `mount`, to decide where the gap goes.
+    class TileMapLayer < Node2D
+      # Mounts one node per layer of the scene's map under `parent`, and returns
+      # an empty node sitting in the gap between them — what the scene hangs its
+      # actors on. Nothing here picks a z by hand, and neither does the caller.
+      #
+      # `under` names the first layer that should cover the actors, as a layer
+      # index. It defaults to the first layer the map flags `above` in Tiled, so
+      # a map that already marks its canopies needs nothing said; a map that
+      # marks none puts the actors on top of everything.
+      #
+      # `parent` must be inside a WorldView, like the nodes themselves.
+      def self.mount(parent, under: nil)
+        world = parent.system(Components::TileWorld)
+        gap = under || world.first_above_layer
+
+        world.layer_count.times do |index|
+          parent.add_node(new(layer: index, z: index < gap ? index : index + 1))
+        end
+        parent.add_node(Node2D.new(z: gap))
+      end
+
+      def initialize(layer:, **)
+        super(**)
+        @layer = layer
+      end
+
+      def on_add = @world = system(Components::TileWorld)
+
+      # The view supplies the cull rect: which part of the world this viewport
+      # can see. The map draws in world coordinates and the WorldView's
+      # translate puts it on screen, so nothing here does camera arithmetic —
+      # which is exactly what lets the same map serve every viewport.
+      #
+      # A screen-space view has no camera and nothing to cull against, so
+      # there is nothing sensible to draw; that is a misplaced layer rather than
+      # a state to handle, and it says so.
+      def on_draw(renderer, view)
+        camera = view.camera
+        raise 'TileMapLayer must be inside a WorldView — this view has no camera' if camera.nil?
+
+        renderer.tilemap(@world.tilemap_id, @layer, camera.x, camera.y,
+                         view.width, view.height, elapsed: @world.elapsed)
+      end
+    end
+  end
+end