rgame 0.1.0 → 0.3.0

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

@@ -20,7 +20,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
@@ -71,7 +71,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 +80,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 +133,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

@@ -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

data/lib/rgame/engine/tileset.rb

@@ -15,7 +15,7 @@ module RGame
       Frame = Struct.new(:tile_id, :duration)
 
       attr_reader :firstgid, :columns, :tile_width, :tile_height, :image_source, :animations
-      attr_accessor :solid_ids # Set of *local* tile ids treated as solid
+      attr_accessor :solid_ids
 
       def self.parse(tsx_string, firstgid:)
         root = REXML::Document.new(tsx_string).root
@@ -40,7 +40,6 @@ module RGame
         )
       end
 
-      # Frames for an animated tile, or nil (compacted away) for a static one.
       def self.parse_animation(tile_el)
         anim = tile_el.elements['animation']
         return unless anim
@@ -50,12 +49,11 @@ module RGame
         end
       end
 
-      # A tile is solid if it carries a Tiled collision shape — an `<objectgroup>`
-      # with at least one object (the per-tile collision editor's output).
       def self.collision_shape?(tile_el)
         group = tile_el.elements['objectgroup']
         !group.nil? && !group.elements['object'].nil?
       end
+      private_class_method :parse_animation, :collision_shape?
 
       def initialize(firstgid:, columns:, tile_width:, tile_height:, image_source:, animations:, solid_ids: Set.new)
         @firstgid = firstgid

data/lib/rgame/engine/timer.rb

@@ -3,12 +3,12 @@
 module RGame
   module Engine
     # A repeating interval timer for periodic events that aren't driven by input — a
-    # spawner emitting an enemy every N seconds, a tower's fire rate, a wave clock.
+    # spawner emitting an enemy every N seconds, a turret's fire rate, a wave clock.
     #
     # It only accumulates time; the owner decides what each elapsed interval means. That
     # split lets one primitive serve both styles: "act automatically" (consume every ready
     # interval) and "stay loaded until conditions allow" (check `ready?`, but `consume`
-    # only when actually acting — so a tower with no target keeps its shot ready instead of
+    # only when actually acting — so a turret with no target keeps its shot ready instead of
     # wasting it). Pure and allocation-free, so it ticks on the per-frame path.
     #
     #   timer = Engine::Timer.new(0.8)

data/lib/rgame/engine/ui/button.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # Anything a Menu can hold: the state a button has — enabled, focused,
+      # pressed — and a signal for when it is chosen, with no look at all.
+      #
+      #   class Swatch < UI::Button
+      #     def initialize(color:, **)
+      #       super(**)
+      #       @color = color
+      #     end
+      #
+      #     def on_draw(renderer, _view)
+      #       inset = state == :focused ? 0 : 4
+      #       renderer.rect(inset, inset, width - (inset * 2), height - (inset * 2), color: @color)
+      #     end
+      #   end
+      #
+      # The look is a subclass's `on_draw`, and it reads `state` to decide what
+      # to draw. Everything the menu needs from a button — being told it is
+      # focused or pressed, being activated, being asked to `adjust` — lives
+      # here, so a subclass that only draws cannot leave any of it out.
+      #
+      # There is no hover, because there is no pointer: what a mouse-driven
+      # control would get from the cursor being over it, this gets from the Menu
+      # telling it it is the focused one.
+      #
+      # Its position is its own, resolved through the tree like any node's, so a
+      # Menu inside a PlayerLayer puts its buttons inside that player's region
+      # without either of them arranging it.
+      #
+      # A Button with no `on_draw` of its own draws nothing.
+      #
+      # ## The label is a translation key
+      #
+      # `label: 'play'` is a key, and the button holds it as an Engine::Text, so
+      # what is drawn follows `I18n.locale` without the button being rebuilt.
+      # Text that must not be translated — a player's name — is passed as one:
+      #
+      #   UI::TextButton.new(label: 'play')                        # the key 'play'
+      #   UI::TextButton.new(label: Engine::Text.literal(name))    # the name, in every language
+      #
+      # A label is drawn as it reads, so a `Text` with variables shows the values
+      # its last `with` was given. The node that owns them calls `with` in
+      # `update`, and the label follows:
+      #
+      #   @continue = Engine::Text.new('continue', :saves)
+      #   menu.add(UI::PanelButton.new(label: @continue))
+      #   def on_update(_dt) = @continue.with(saves: @save_count)
+      #
+      # One given no `with` yet raises on the first draw, naming the keywords.
+      #
+      # `label_scope` puts a scope in front of a label given as a key, and
+      # UI::Menu sets it from its own `scope:` as the button is added. A label
+      # given as a `Text` is the caller's, scope and all, and nothing changes it.
+      #
+      # ## When a press activates
+      #
+      # `activate_on:` is `:release` by default: confirm draws the button pressed
+      # while it is held and activates it when it is let go, so a player who
+      # moves focus away while still holding cancels. `:press` activates on the
+      # way down — what a skill bar wants — and keeps the button drawn pressed
+      # for at least `PRESS_FEEDBACK` seconds, because a tap is otherwise a
+      # single frame of pressed that nobody sees. Its 0.1 s is Unity's, which
+      # holds a submitted button pressed that long; Godot holds a shortcut's for
+      # 0.2 s.
+      #
+      # Either way a button only acts on a press it saw start. A press whose
+      # release it did not see — its menu was paused or covered in between — is
+      # dropped rather than finished, so a menu that closes itself from
+      # `on_activated` and is opened again does not come back pressed. See
+      # UI::Menu for the other half, a menu that has not yet seen confirm up.
+      #
+      # ## A hotkey
+      #
+      # `hotkey:` names an action that presses this button whether or not it is
+      # focused, and without moving focus — a skill bar's number keys:
+      #
+      #   UI::IconButton.new(image: :torch, hotkey: :skill3)
+      #
+      # A hotkey always activates on the press, whatever `activate_on:` says,
+      # and draws pressed for `PRESS_FEEDBACK` or while held. Its release
+      # activates nothing. The menu reads it, so the action has to be declared
+      # in the player's InputMap; an undeclared one raises on the first frame.
+      #
+      # **A press belongs to the source that started it.** The menu passes
+      # `:confirm` or `:hotkey` to `press`, `release` and `cancel_press`, and
+      # while one source holds the button a press from the other is ignored and
+      # its release ends nothing. So a player holding confirm on a `:release`
+      # button who taps that button's hotkey activates it once, when confirm is
+      # let go; and losing focus ends a confirm hold but not a hotkey one.
+      class Button < Node2D
+        signal :on_activated
+
+        PRESS_FEEDBACK = 0.1
+        STATES = %i[idle focused pressed disabled].freeze
+        ACTIVATE_ON = %i[release press].freeze
+        SOURCES = %i[confirm hotkey].freeze
+
+        attr_accessor :enabled
+        # The Engine::Text drawn for this button, or nil.
+        attr_reader :label
+        # The scope a label given as a key resolves under, or nil.
+        attr_reader :label_scope
+        # `hotkey` is an action name, or nil.
+        attr_reader :activate_on, :hotkey
+
+        def initialize(label: nil, enabled: true, activate_on: :release, hotkey: nil, **)
+          super(**)
+          unless ACTIVATE_ON.include?(activate_on)
+            raise ArgumentError, "activate_on: must be :release or :press, not #{activate_on.inspect}"
+          end
+
+          @label_scope = nil
+          self.label = label
+          @enabled = enabled
+          @activate_on = activate_on
+          @hotkey = hotkey
+          @focused = false
+          @holder = nil
+          @feedback = 0.0
+        end
+
+        # Sets the label: a key String or Symbol, which the button makes an
+        # Engine::Text of under `label_scope`; a `Text`, used as it is; or nil.
+        def label=(label)
+          @label = label && text_for(label)
+          @label_from_key = !(label.nil? || label.is_a?(Text))
+        end
+
+        # Sets the scope a label given as a key resolves under — `'title_menu'`
+        # makes the key `'play'` read `'title_menu.play'` — and resolves it again
+        # on the next draw.
+        def label_scope=(scope)
+          @label_scope = scope&.to_s
+          @label.scope = @label_scope if @label_from_key
+        end
+
+        def enabled? = @enabled
+        def focused? = @focused
+        def pressed? = !@holder.nil? || @feedback.positive?
+
+        # What to draw: `:disabled` whenever the button is disabled, whatever
+        # else is true; then `:pressed`, `:focused`, and otherwise `:idle`.
+        # Pressed does not require focus: a press can outlast the focus that
+        # started it by its `PRESS_FEEDBACK`.
+        def state
+          return :disabled unless @enabled
+          return :pressed if pressed?
+
+          @focused ? :focused : :idle
+        end
+
+        # Called by the Menu. Calls `on_focus_changed` when the value actually
+        # changes, and never for a repeated assignment, so a menu that reasserts
+        # focus every frame does not replay a focus sound every frame. Losing
+        # focus lets go of a confirm press without activating it; a hotkey press
+        # was never about focus, and is kept.
+        def focused=(value)
+          return if @focused == value
+
+          @focused = value
+          @holder = nil if !value && @holder == :confirm
+          on_focus_changed(value)
+        end
+
+        # Called by the Menu when a press from `source` — `:confirm` or
+        # `:hotkey` — starts on this button. A hotkey press, or any press under
+        # `activate_on: :press`, activates at once and returns what `activate`
+        # did; a confirm press under `:release` holds and returns nil. Ignored,
+        # returning nil, while disabled or while any source already holds it.
+        def press(source = :confirm)
+          unless SOURCES.include?(source)
+            raise ArgumentError, "source must be :confirm or :hotkey, not #{source.inspect}"
+          end
+          return nil unless @enabled && @holder.nil?
+
+          @holder = source
+          return nil unless source == :hotkey || @activate_on == :press
+
+          activate_with_feedback
+        end
+
+        # Called by the Menu when a press `source` started is let go. Activates
+        # a confirm press under `activate_on: :release`, and returns what
+        # `activate` did; ends nothing another source started.
+        def release(source = :confirm)
+          return nil unless @holder == source
+
+          @holder = nil
+          activate if source == :confirm && @activate_on == :release
+        end
+
+        # Called by the Menu for a press from `source` whose release this button
+        # never saw. Drops it, and the feedback with it, activating nothing.
+        def cancel_press(source = :confirm)
+          return unless @holder == source
+
+          @holder = nil
+          @feedback = 0.0
+        end
+
+        # The instant press: activates, and shows pressed for `PRESS_FEEDBACK`
+        # though nothing holds the button. What a hotkey press and a
+        # `:press` confirm do, available on its own for a press that ends
+        # somewhere other than on this button. Returns what `activate` did.
+        def activate_with_feedback
+          return nil unless @enabled
+
+          @feedback = PRESS_FEEDBACK
+          activate
+        end
+
+        # What the focused button does with `ui_left` / `ui_right`, which the
+        # menu hands down without knowing what kind of button it is talking to.
+        # A plain button has nothing to change, and answers nil the way a
+        # disabled `activate` does. UI::OptionButton is the one that overrides it.
+        def adjust(_delta) = nil
+
+        # Fires the signal and returns the button, or nil if it is disabled — so
+        # a caller never has to check first, and a disabled button cannot be
+        # activated by any route.
+        def activate
+          return nil unless @enabled
+
+          on_activated_signal.emit
+          self
+        end
+
+        # Counts down the pressed feedback, then does what every node does.
+        def update(dt)
+          @feedback -= dt if @feedback.positive? && !@paused
+          super
+        end
+
+        # Hook: override to react to gaining or losing focus — a sound, the
+        # start of an animation. Called only on a change.
+        def on_focus_changed(focused); end
+
+        private
+
+        def text_for(shown) = shown.is_a?(Text) ? shown : Text.new(shown, scope: @label_scope)
+      end
+    end
+  end
+end

data/lib/rgame/engine/ui/column.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # A Menu layout: buttons stacked downwards from the menu's origin, all the
+      # same size, `spacing` pixels apart. A UI::Stack on the vertical axis, so
+      # UI::Stepping moves through it with `ui_up` and `ui_down`.
+      #
+      #   UI::Menu.new(layout: UI::Column.new(item_width: 220, item_height: 44))
+      #
+      # It takes no `axis:` — a column that is not vertical is a UI::Row.
+      class Column < Stack
+        def initialize(item_width:, item_height:, spacing: 8)
+          super(axis: :vertical, item_width: item_width, item_height: item_height, spacing: spacing)
+        end
+      end
+    end
+  end
+end