rgame 0.1.0 → 0.2.0

data/lib/rgame/core/renderer.rb

@@ -3,6 +3,7 @@
 require 'rgame/core_ext'
 require_relative 'font'
 require_relative '../util/color'
+require_relative '../util/z'
 
 module RGame
   module Core
@@ -25,10 +26,22 @@ module RGame
     # raises. That is on purpose: the frame is not open, so the vertices would
     # be silently discarded, and an invisible failure is the worst kind.
     #
-    # Nothing is drawn immediately. Calls accumulate and are z-sorted when the
-    # frame closes, so `z:` decides what ends up on top — not call order. Equal
-    # z keeps call order, which is what stops same-layer sprites flickering
-    # between frames.
+    # Nothing is drawn immediately. Calls accumulate and are sorted when the
+    # frame closes, so what ends up on top is decided by z rather than by call
+    # order. Equal z keeps call order, which is what stops same-layer sprites
+    # flickering between frames.
+    #
+    # ## `z:` is an offset inside the current layer, not a global number
+    #
+    # A `z:` is added to whatever `#layered` most recently pushed, and must be
+    # within RGame::Util::Z::Z_MIN..Z_MAX — one *node's* worth of room. It
+    # orders that node's own drawing (its panel under its label, a shadow under
+    # its sprite) and can reach nothing else. Which node comes before which is
+    # the scene graph's business, resolved by the traversal and handed here as a
+    # layer; see RGame::Util::Z.
+    #
+    # A caller outside any `#layered` block draws at the base layer 0, which is
+    # what a spec or a bare script gets.
     #
     # The C half of this class (ext/rgame_core/ruby/renderer_ext.c) has the `draw_*`
     # and `push_*` primitives; everything here is the comfortable surface over
@@ -43,9 +56,12 @@ module RGame
     class Renderer
       Color = RGame::Util::Color
 
+      Z = RGame::Util::Z
+
       # Shapes default above sprites, so a debug box or a health bar drawn
-      # without a `z:` lands on top of the scene rather than under it. The
-      # values match the layer this replaces.
+      # without a `z:` lands on top of *that node's* sprite rather than under
+      # it. Well inside one slot, so the defaults order a node's own drawing and
+      # nothing further.
       SHAPE_Z = 50
       IMAGE_Z = 0
 
@@ -53,8 +69,7 @@ module RGame
       # draws one, and few enough that a screenful of them is still one batch.
       CIRCLE_SEGMENTS = 64
 
-      # Text defaults above sprites but below shapes, and the size matches what
-      # the layer this replaces used, so ported UI lays out unchanged.
+      # Text defaults above sprites but below shapes, within the same slot.
       TEXT_Z = 10
       FONT_SIZE = 18
 
@@ -117,49 +132,54 @@ module RGame
         lookup(:nine_slice, id).draw(self, x, y, width, height, z: z, color: tint)
       end
 
-      # A tile map's below-the-actor band (ground and same-level detail).
+      # One layer of a tile map — the layer a Tiled `.tmx` lists at `layer`,
+      # counting from the bottom.
+      #
+      # One layer rather than the whole map, because a scene draws its actors
+      # between two of them: trunks under, canopies over. Which is which is the
+      # scene tree's business — `RGame::Engine::TileMapLayer` mounts a node per
+      # layer — so this takes no `z:`.
+      #
+      # **Drawn in world coordinates**: a tile at column 3 lands at
+      # `3 * tile_width`, and getting it onto the screen is the caller's
+      # transform, like every other drawing method here. The rectangle is a
+      # **cull rect** — which part of the world is worth drawing — so a camera
+      # supplies it but does not move the result. That is what lets one map be
+      # drawn through several cameras in a frame.
       #
       # `elapsed` is the seconds its animated tiles have been running for, and
       # is an argument rather than a clock read on purpose — see CLAUDE.md,
       # "`draw` renders state; time enters through `update`". A scene
       # accumulates it in `update`, which is what makes pausing work.
-      def tilemap(id, camera_x, camera_y, viewport_width, viewport_height, elapsed: 0.0)
+      def tilemap(id, layer, cull_x, cull_y, cull_width, cull_height, elapsed: 0.0)
         lookup(:tilemap, id)
-          .draw(self, camera_x, camera_y, viewport_width, viewport_height, elapsed: elapsed)
-      end
-
-      # Its above-the-actor band (canopies, roofs), at a `z` the scene picks so
-      # it lands over the actors.
-      def tilemap_overlay(id, camera_x, camera_y, viewport_width, viewport_height,
-                          z:, elapsed: 0.0)
-        lookup(:tilemap, id).draw_overlay(self, camera_x, camera_y, viewport_width,
-                                          viewport_height, z: z, elapsed: elapsed)
+          .draw_layer(self, layer, cull_x, cull_y, cull_width, cull_height, elapsed: elapsed)
       end
 
       # A filled axis-aligned rectangle.
       def rect(x, y, width, height, z: SHAPE_Z, color: nil)
-        draw_rect(x, y, width, height, z, packed(color))
+        draw_rect(x, y, width, height, Z.offset(z), packed(color))
       end
 
       # Four arbitrary points, in loop order: listing them in Z order gives an
       # hourglass rather than a shape.
       def quad(x1, y1, x2, y2, x3, y3, x4, y4, z: SHAPE_Z, color: nil)
-        draw_quad(x1, y1, x2, y2, x3, y3, x4, y4, z, packed(color))
+        draw_quad(x1, y1, x2, y2, x3, y3, x4, y4, Z.offset(z), packed(color))
       end
 
       def triangle(x1, y1, x2, y2, x3, y3, z: SHAPE_Z, color: nil)
-        draw_triangle(x1, y1, x2, y2, x3, y3, z, packed(color))
+        draw_triangle(x1, y1, x2, y2, x3, y3, Z.offset(z), packed(color))
       end
 
       # A line of real thickness — drawn as a quad, because GL's own line width
       # is a suggestion drivers may ignore above one pixel.
       def line(x1, y1, x2, y2, thickness: 1.0, z: SHAPE_Z, color: nil)
-        draw_line(x1, y1, x2, y2, thickness, z, packed(color))
+        draw_line(x1, y1, x2, y2, thickness, Z.offset(z), packed(color))
       end
 
       # A filled circle, as a fan of triangles around its centre.
       def circle(cx, cy, radius, z: SHAPE_Z, color: nil, segments: CIRCLE_SEGMENTS)
-        draw_circle(cx, cy, radius, segments, z, packed(color))
+        draw_circle(cx, cy, radius, segments, Z.offset(z), packed(color))
       end
 
       # An image centred on (cx, cy), rotated `angle` degrees clockwise about
@@ -168,7 +188,7 @@ module RGame
       #
       # Takes an `Image` or an id for one — see #resolve_image.
       def image(image, cx, cy, angle: 0, scale: 1, z: IMAGE_Z, color: nil)
-        draw_image_rot(resolve_image(image), cx, cy, angle, scale, z, packed(color))
+        draw_image_rot(resolve_image(image), cx, cy, angle, scale, Z.offset(z), packed(color))
       end
 
       # An image with its top-left at (x, y), scaled independently per axis —
@@ -183,14 +203,14 @@ module RGame
       #
       # A zero scale draws nothing.
       def image_at(image, x, y, scale_x: 1, scale_y: 1, z: IMAGE_Z, color: nil)
-        draw_image_scaled(resolve_image(image), x, y, scale_x, scale_y, z, packed(color))
+        draw_image_scaled(resolve_image(image), x, y, scale_x, scale_y, Z.offset(z), packed(color))
       end
 
       # An image with its top-left at (x, y), at its natural size — a
       # full-screen backdrop by default. `image_at` with both scales at 1, kept
       # because "put this at the origin" is worth a name of its own.
       def background(image, x = 0, y = 0, z: IMAGE_Z, color: nil)
-        draw_image(resolve_image(image), x, y, z, packed(color))
+        draw_image(resolve_image(image), x, y, Z.offset(z), packed(color))
       end
 
       # Everything drawn in the block is rotated `angle` degrees about
@@ -239,6 +259,34 @@ module RGame
         end
       end
 
+      # Everything drawn in the block draws in its own layer: a fresh slot in
+      # `band`, which every `z:` inside is then an offset from.
+      #
+      #   renderer.layered(:hud) { renderer.text(score, 12, 10) }
+      #
+      # Two things fall out of it, and they are the whole of draw order.
+      # **Slots are handed out in the order they are asked for**, so nesting
+      # this the way a scene graph is nested makes draw order tree order — a
+      # node drawn later is in front, and its whole subtree with it. And **a
+      # band is a hard partition**: every slot in `:hud` is above every slot in
+      # `:world`, whatever either drew, because they are 2**40 apart and a `z:`
+      # cannot reach out of one slot. See RGame::Util::Z.
+      #
+      # A caller that never uses this draws at layer 0 and gets exactly the z it
+      # passes, which is what a spec or a one-off script wants.
+      def layered(band = Z::DEFAULT)
+        index = Z.index(band)
+        push_layer(Z.slot_base(index, next_layer_slot(index)))
+        begin
+          yield
+        ensure
+          # An ensure for the same reason `rotated` has one: a scene that raises
+          # mid-draw would otherwise leave every later node drawing in its
+          # layer, and the frame would come out interleaved with no clue why.
+          pop
+        end
+      end
+
       # Everything drawn in the block is confined to the given rectangle.
       #
       # A clip only ever narrows: nesting one inside another intersects them, so
@@ -271,7 +319,7 @@ module RGame
       # Newlines are not special. A caller wanting two lines draws two, stepping
       # by #text_height.
       def text(string, x, y, z: TEXT_Z, color: nil, font: nil)
-        draw_text(font || self.font, string, x, y, z, packed(color))
+        draw_text(font || self.font, string, x, y, Z.offset(z), packed(color))
       end
 
       # What #text would occupy, for centring and layout. Unlike the drawing

data/lib/rgame/core/tile_map_renderer.rb

@@ -3,31 +3,53 @@
 module RGame
   module Core
     # Draws a tile map: the static layers baked once, the animated tiles drawn
-    # per frame and culled to the viewport.
+    # per frame, both culled to a rectangle of the world.
     #
     #   tiles = RGame::Core::TileMapRenderer.new(map, tileset_images)
     #
-    #   tiles.draw(renderer, camera_x, camera_y, view_w, view_h, elapsed: seconds)
-    #   tiles.draw_overlay(renderer, camera_x, camera_y, view_w, view_h, z: 20,
+    #   map.layer_count.times do |layer|
+    #     tiles.draw_layer(renderer, layer, cull_x, cull_y, cull_w, cull_h,
     #                      elapsed: seconds)
+    #   end
     #
-    # ## Two bands, with the actors between them
+    # ## It draws in world coordinates
     #
-    # Layers split by the map's own `above_layer?` flag. The **below** band —
-    # ground, and detail on the actors' level — is drawn under them by `#draw`;
-    # the **above** band — tree canopies, roofs — over them by `#draw_overlay`,
-    # at a `z` the scene picks. Two calls rather than one because the scene
-    # draws its actors in between, and collapsing them would put every canopy
-    # behind every character.
+    # A tile at column 3 is drawn at `3 * tile_width`, and getting it onto the
+    # screen is the caller's transform — the same deal every other drawable
+    # gets. The rectangle passed in is therefore a **cull rect** and nothing
+    # else: which part of the world is worth drawing.
+    #
+    # It used to be both, offsetting the output by `-camera` as well as culling
+    # to it, which worked exactly as long as there was one camera. Under
+    # split-screen the same map is drawn through several, so a call that bakes
+    # placement into its output can only be right for one of them. Culling is
+    # genuinely per-camera; placement is the transform stack's job.
+    #
+    # ## One call per layer, because the actors go between them
+    #
+    # A layer is drawn on its own, and the order they are drawn in is the
+    # caller's. That is what lets a scene put its actors between two of them —
+    # tree trunks below, canopies above — which is the whole reason this does
+    # not simply draw the map in one go.
+    #
+    # It is also why nothing here consults the map's `above_layer?` flag any
+    # more: which layers cover the actors is a question about where the actors
+    # are in the scene, and Tiled already answers "in what order do the layers
+    # go" by listing them. `RGame::Engine::TileMapLayer` mounts one node per
+    # layer and the tree does the rest.
     #
     # ## What is baked and what is not
     #
-    # Within each band, every tile that is *not* animated is baked into one
-    # recording, the first time that band is drawn. Scrolling a baked layer is
+    # Within each layer, every tile that is *not* animated is baked into one
+    # recording, the first time that layer is drawn. Scrolling a baked layer is
     # then one call per texture however many thousand tiles went into it. The
     # handful that *are* animated are drawn individually each frame, culled to
     # the viewport — a map far larger than the screen costs only what is on it.
     #
+    # Splitting per layer rather than into two bands bakes the same tiles into
+    # more recordings, not more vertices: the partition changed, the contents
+    # did not.
+    #
     # ## It loads nothing and holds no clock
     #
     # The tiles arrive already sliced, so two maps sharing a tileset share one
@@ -44,9 +66,9 @@ module RGame
     # It never names the map's class — the tile map lives a layer *above* this
     # one and Core may not reach up (CLAUDE.md, "The rule points both ways").
     # What it calls is the 'a tile map' contract in
-    # `spec/support/shared_examples/`: `layer_count`, `above_layer?`, `width`,
-    # `height`, `tile_width`, `tile_height`, `gid`, and a `tileset` answering
-    # `local_id`, `animations` and `frame_local_id`.
+    # `spec/support/shared_examples/`: `layer_count`, `width`, `height`,
+    # `tile_width`, `tile_height`, `gid`, and a `tileset` answering `local_id`,
+    # `animations` and `frame_local_id`.
     class TileMapRenderer
       # The map this was built from. A scene reads it for collision and world
       # bounds, which are its business rather than this class's.
@@ -58,47 +80,53 @@ module RGame
         @map = map
         @tileset = map.tileset
         @tiles = tiles
-        @animated_below, @animated_above = collect_animated_tiles
+        @animated = collect_animated_tiles
         # Baked on first draw, not here: recording needs a live frame, and there
         # is no renderer at construction.
-        @static_below = nil
-        @static_above = nil
+        @static = Array.new(map.layer_count)
       end
 
-      def draw(renderer, camera_x, camera_y, viewport_width, viewport_height, elapsed: 0.0)
-        @static_below ||= bake(renderer) { |layer| !@map.above_layer?(layer) }
-        @static_below.draw(-camera_x, -camera_y, z: BELOW_Z)
-        draw_animated(renderer, @animated_below, camera_x, camera_y,
-                      viewport_width, viewport_height, BELOW_Z, elapsed)
-      end
+      def layer_count = @map.layer_count
+
+      # One layer, culled to `(cull_x, cull_y, cull_width, cull_height)` in world
+      # coordinates and drawn in them.
+      #
+      # The recording is replayed at its own origin, so it lands wherever the
+      # caller's transform puts it. That also makes it **view-independent**: one
+      # bake serves every viewport, which is what keeps split-screen affordable
+      # and is why the bake is not keyed on a camera. Baking happens on the
+      # first draw, and it is safe to do that inside a transform or a clip —
+      # recording runs on its own canvas, begun at identity, and captures
+      # neither.
+      #
+      # No `z:`. A layer is drawn by a node of its own, so where it sits is the
+      # scene tree's answer; everything this issues belongs to that one node and
+      # goes in its slot.
+      def draw_layer(renderer, index, cull_x, cull_y, cull_width, cull_height, elapsed: 0.0)
+        unless index.is_a?(Integer) && index >= 0 && index < @static.size
+          raise ArgumentError, "no layer #{index.inspect} in this map (it has #{@static.size})"
+        end
 
-      def draw_overlay(renderer, camera_x, camera_y, viewport_width, viewport_height,
-                       z:, elapsed: 0.0)
-        @static_above ||= bake(renderer) { |layer| @map.above_layer?(layer) }
-        @static_above.draw(-camera_x, -camera_y, z: z)
-        draw_animated(renderer, @animated_above, camera_x, camera_y,
-                      viewport_width, viewport_height, z, elapsed)
+        @static[index] ||= bake(renderer, index)
+        @static[index].draw
+        draw_animated(renderer, @animated[index], cull_x, cull_y,
+                      cull_width, cull_height, elapsed)
       end
 
-      # The ground band sits at the bottom; the scene chooses where the overlay
-      # goes, because only it knows what its actors are drawn at.
-      BELOW_Z = 0
-
       private
 
-      # [col, row, local_id] for every animated tile, split into the two bands.
-      # Walked once at construction: a map is thousands of tiles and a handful
-      # of animated ones, and finding them again each frame would be the whole
-      # cost this class exists to avoid.
+      # [col, row, local_id] for every animated tile, per layer. Walked once at
+      # construction: a map is thousands of tiles and a handful of animated
+      # ones, and finding them again each frame would be the whole cost this
+      # class exists to avoid.
       def collect_animated_tiles
-        below = []
-        above = []
+        found = Array.new(@map.layer_count) { [] }
         each_tile do |layer, col, row, local|
           next unless @tileset.animations.key?(local)
 
-          (@map.above_layer?(layer) ? above : below) << [col, row, local]
+          found[layer] << [col, row, local]
         end
-        [below, above]
+        found
       end
 
       # Every non-empty tile of every layer, as [layer, col, row, local_id].
@@ -115,22 +143,21 @@ module RGame
         end
       end
 
-      # Bakes the static tiles of the layers the block accepts into one
-      # recording, in layer order so a later layer covers an earlier one.
-      def bake(renderer)
+      # Bakes one layer's static tiles into a recording. An empty layer bakes an
+      # empty recording, which replays as nothing — so a map with a spacer layer
+      # in it needs no special case here or at the call site.
+      def bake(renderer, index)
         renderer.record do
           each_tile do |layer, col, row, local|
-            next unless yield(layer)
+            next unless layer == index
             next if @tileset.animations.key?(local)
 
-            renderer.image_at(@tiles[local], col * @map.tile_width, row * @map.tile_height,
-                              z: BELOW_Z)
+            renderer.image_at(@tiles[local], col * @map.tile_width, row * @map.tile_height)
           end
         end
       end
 
-      def draw_animated(renderer, tiles, camera_x, camera_y, viewport_width, viewport_height,
-                        z, elapsed)
+      def draw_animated(renderer, tiles, cull_x, cull_y, cull_width, cull_height, elapsed)
         tile_width = @map.tile_width
         tile_height = @map.tile_height
 
@@ -143,16 +170,18 @@ module RGame
         # a no-op, leaving the last column of tiles undrawn: a one-tile strip of
         # nothing along the right and bottom edges of the screen, and only when
         # the camera happens to be on a whole pixel.
-        col_start = camera_x.fdiv(tile_width).floor
-        row_start = camera_y.fdiv(tile_height).floor
-        col_end = (camera_x + viewport_width).fdiv(tile_width).ceil
-        row_end = (camera_y + viewport_height).fdiv(tile_height).ceil
+        col_start = cull_x.fdiv(tile_width).floor
+        row_start = cull_y.fdiv(tile_height).floor
+        col_end = (cull_x + cull_width).fdiv(tile_width).ceil
+        row_end = (cull_y + cull_height).fdiv(tile_height).ceil
 
         tiles.each do |col, row, local|
           next if col < col_start || col >= col_end || row < row_start || row >= row_end
 
+          # World coordinates, like the baked band above it: the caller's
+          # transform is what puts either on screen.
           renderer.image_at(@tiles[@tileset.frame_local_id(local, ms)],
-                            (col * tile_width) - camera_x, (row * tile_height) - camera_y, z: z)
+                            col * tile_width, row * tile_height)
         end
       end
     end

data/lib/rgame/engine/camera.rb

@@ -2,29 +2,74 @@
 
 module RGame
   module Engine
-    # A 2D camera: follows a target point and clamps to world bounds so it never
-    # shows past the map edges. Pure; the platform applies (x, y) as a draw offset.
+    # A 2D camera: a point in the world to look at, plus the world bounds it may
+    # not show past. Pure; the offset it produces is applied as a draw-time
+    # transform, never baked into a node.
+    #
+    #   camera = Camera.new(world_width: map.pixel_width, world_height: map.pixel_height)
+    #   camera.center_on(player.abs_x, player.abs_y)   # in update, every tick
+    #   camera.resolve(view_width, view_height)        # at draw, for one viewport
+    #   camera.x, camera.y                             # the offset to translate by
+    #
+    # ## Why the viewport size is an argument and not state
+    #
+    # A camera used to be built with its viewport size and clamp against it in
+    # `center_on`. That cannot survive split-screen: the same world is drawn
+    # through several viewports whose rects come from the layout and change when
+    # a player joins or the window resizes. Clamping has to happen against the
+    # rect actually being drawn into, and the difference is visible rather than
+    # theoretical — near a world edge, the same target sits at a different place
+    # on screen in a half-width viewport than in a full-width one.
+    #
+    # So `center_on` records *intent* and `resolve` computes the offset. Nothing
+    # calls `resolve` by hand: the platform resolves each camera against the
+    # viewport it is about to draw, which is what keeps the two from drifting.
+    #
+    # ## The camera belongs to a player, not to a scene
+    #
+    # A scene may have any number of viewers, so it cannot own "the" camera.
+    # RGame::Engine::Player owns one; a scene sets its world bounds when it
+    # loads a map, and a CameraFollow component in the world points it.
     class Camera
-      attr_reader :x, :y, :viewport_width, :viewport_height
+      attr_reader :x, :y, :target_x, :target_y
+      attr_accessor :world_width, :world_height
 
-      def initialize(viewport_width:, viewport_height:, world_width:, world_height:)
-        @viewport_width = viewport_width
-        @viewport_height = viewport_height
+      # `world_width` / `world_height` bound what the camera may show. Left nil
+      # the camera is unbounded and follows its target exactly — which is the
+      # right default: a game that has not declared its world yet gets a camera
+      # that visibly works, rather than one silently pinned to the origin.
+      def initialize(world_width: nil, world_height: nil)
         @world_width = world_width
         @world_height = world_height
+        @target_x = 0.0
+        @target_y = 0.0
         @x = 0.0
         @y = 0.0
       end
 
+      # Look at this world point. Records the target; the offset is worked out
+      # by #resolve, which is the only place that knows how big the view is.
       def center_on(world_x, world_y)
-        @x = clamp(world_x - @viewport_width / 2.0, @world_width - @viewport_width)
-        @y = clamp(world_y - @viewport_height / 2.0, @world_height - @viewport_height)
+        @target_x = world_x
+        @target_y = world_y
+        self
+      end
+
+      # Work out the draw offset for a viewport of this size, clamped so the
+      # view never shows past the world's edges.
+      def resolve(view_width, view_height)
+        @x = clamp(@target_x - (view_width / 2.0), @world_width, view_width)
+        @y = clamp(@target_y - (view_height / 2.0), @world_height, view_height)
+        self
       end
 
       private
 
-      def clamp(value, max)
-        return 0.0 if max <= 0 # world smaller than the viewport → pin to origin
+      def clamp(value, world_size, view_size)
+        return value.to_f if world_size.nil? # unbounded: follow exactly
+
+        max = world_size - view_size
+        return 0.0 if max <= 0 # world smaller than the view -> pin to origin
 
         value.clamp(0.0, max.to_f)
       end

data/lib/rgame/engine/component.rb

@@ -20,11 +20,21 @@ module RGame
 
       def control(actions); end
       def update(dt); end
-      def draw(renderer); end
+      def draw(renderer, view); end
 
       # Container components (e.g. SceneStack) that hold nodes off the normal child
       # list override this to forward the deferred-free sweep into them.
       def sweep_freed; end
+
+      # `control` above receives **one player's** Actions — the actions of
+      # whoever owns this component's node — which is what a component wants,
+      # since it belongs to exactly one node.
+      #
+      # A container component holding a whole subtree needs the input *source*
+      # instead, so the nodes inside it can each resolve their own owner. There
+      # is no hook for that on purpose: it is a system lookup like any other, so
+      # such a component pulls `node.system(Players)` in `on_attach` and passes
+      # that down. SceneStack is the worked example.
     end
   end
 end

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

@@ -9,10 +9,10 @@ module RGame
       # AnimationSet built from the sheet's animation table.
       #
       # Like Sprite, it passes NO angle and draws at the node's *world* origin
-      # (node.abs_x/abs_y): a CameraView ancestor wraps the draw in renderer.translated to
+      # (node.abs_x/abs_y): a WorldView ancestor wraps the draw in renderer.translated to
       # map world → screen, so this component never touches the camera. `z` is the render
       # layer (kept as @layer, distinct from the node's transform z); it must sit between
-      # the tile world's ground band and its overlay band so canopies draw in front.
+      # the tile map's ground and canopy z bands, so canopies draw in front.
       #
       # `sheet` is the asset's relative path. The component resolves it from the game's
       # asset manager on attach — via node.root.context.assets (the platform seam) — to
@@ -20,6 +20,8 @@ module RGame
       # like CharacterBody can read node.width/height. The renderer resolves the same
       # symbol when drawing, so nothing is registered or passed in by hand.
       class AnimatedSprite < Engine::Component
+        include Engine::Culling
+
         def initialize(sheet:, z: 0)
           super()
           @sheet = sheet
@@ -39,7 +41,11 @@ module RGame
           @animator.update(dt)
         end
 
-        def draw(renderer)
+        # Top-left anchored, and sized by the sheet's frame — so the footprint
+        # to cull against is exactly the node's box.
+        def draw(renderer, view)
+          return if culled?(view, node.abs_x, node.abs_y, node.width, node.height)
+
           # Read row/col/flip_x separately (not @animator.frame, which allocates an Array
           # every call) to keep the draw path allocation-free.
           renderer.sprite(@sheet, @animator.row, @animator.col, node.abs_x, node.abs_y,

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Points a camera at the node it is attached to.
+      #
+      #   player_node.add_component(CameraFollow.new(camera: players.primary.camera))
+      #
+      # ## Ownership and behaviour are different questions
+      #
+      # The camera cannot be *owned* by a node in the world — with several
+      # viewers there are several cameras, and a world that holds one has to know
+      # how many times it is being drawn. But deciding *where a camera points* is
+      # exactly a per-node concern, so it belongs here: the player owns the
+      # camera, and a component in the world moves it.
+      #
+      # That also makes "player two's camera follows player two" nothing more
+      # than attaching this to their node with their camera.
+      #
+      # `offset_x` / `offset_y` shift the point being centred on, for a node
+      # whose origin is not what should be in the middle of the screen — a
+      # bottom-anchored sprite usually wants its feet, not its head.
+      class CameraFollow < Engine::Component
+        def initialize(camera:, offset_x: 0.0, offset_y: 0.0)
+          super()
+          @camera = camera
+          @offset_x = offset_x
+          @offset_y = offset_y
+        end
+
+        # Reads the absolute origin resolved at the top of this node's update,
+        # so the camera trails the node's own movement by one step (a couple of
+        # pixels at walking speed). That is deliberate and uniform: everything
+        # drawn through this camera trails equally, so nothing drifts apart on
+        # screen, and the alternative — re-resolving here — would put this
+        # component's ordering among its siblings on show.
+        def update(_dt)
+          @camera.center_on(node.abs_x + @offset_x, node.abs_y + @offset_y)
+        end
+      end
+    end
+  end
+end

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

@@ -30,11 +30,17 @@ module RGame
           @collision_box = nil
         end
 
+        # The feet box, derived from the node's sprite size and memoised.
+        #
+        # **Only valid once the node is in the tree**, and it says so rather than
+        # letting you find out later. The size comes from AnimatedSprite#on_attach,
+        # so a read from a constructor sees a 0x0 node and bakes a box anchored to
+        # nothing — permanently, because this memoises, and for the collision
+        # system too, because it reads the same box. The symptom is an actor that
+        # walks through walls it should not, a long way from the call that caused
+        # it. Guarding costs one comparison, once.
         def collision_box
-          @collision_box ||= Engine::CollisionBox.bottom_anchored(
-            sprite_width: node.width, sprite_height: node.height,
-            width: @feet_width, height: @feet_height
-          )
+          @collision_box ||= build_collision_box
         end
 
         # The TileWorld is a scene-scoped system, reachable once we're in the tree.
@@ -64,6 +70,21 @@ module RGame
         def y=(value)
           node.y = value
         end
+
+        private
+
+        def build_collision_box
+          if node.width.zero? || node.height.zero?
+            raise "collision_box needs the node's sprite size, but it is " \
+                  "#{node.width}x#{node.height}. AnimatedSprite sets that when it attaches, so " \
+                  'read this after the node is in the tree, not while building it.'
+          end
+
+          Engine::CollisionBox.bottom_anchored(
+            sprite_width: node.width, sprite_height: node.height,
+            width: @feet_width, height: @feet_height
+          )
+        end
       end
     end
   end