rgame 0.2.0 → 0.3.0

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

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # A picture, tinted by state, with an optional caption: the round,
+      # image-only entry of a quick-select wheel, or a skill with its name
+      # underneath.
+      #
+      #   disc = UI::ShapeStyle.new(shape: :disc)
+      #   wheel.add(UI::IconButton.new(image: :home, style: disc)).on_activated { go_home }
+      #   bar.add(UI::IconButton.new(image: :torch, label: 'torch', style: disc))
+      #
+      # `image:` is an image id — a registered Symbol or a path String — drawn at
+      # its natural size, centred in the slot, or centred in the space above the
+      # caption when there is one. The caption is centred along the bottom edge,
+      # inside the slot, so the slot is still the button's whole extent.
+      #
+      # **A caption sits under the style, not on it.** With a caption the style
+      # is handed the space above it, so a disc is drawn round the picture and the
+      # caption reads on whatever is behind the button, in the button's own label
+      # colours. A caption wider than the disc — "Watering can" under a tool — is
+      # the ordinary case in a skill bar, and one drawn across a disc's edge would
+      # be half on the fill and half off it, legible on neither.
+      #
+      # `image: nil` draws no picture and leaves the caption, for an entry whose
+      # art is not in yet. An id nobody registered is a mistake rather than that
+      # case, and fails on the first draw like any other image.
+      #
+      # **Tint is a multiply**, so the art should be white: white takes each
+      # colour in `tints:` exactly, and dark art takes none of them. Scales
+      # default to 1 in every state because images sample nearest-neighbour, so
+      # any scale but a whole number doubles some pixel rows and not others; focus
+      # shows through the tint and the style instead. `tints:` and `scales:` need
+      # every state, checked here rather than the first frame one is reached.
+      #
+      # No style by default: an icon on its own is a complete look. The style is
+      # drawn at `z: 0` or below, the picture and the caption at `z: 1`. A style
+      # answering `content_color(state)` — UI::ShapeStyle does — replaces the tint
+      # in any state it names, because what reads on its fill is the style's to
+      # say: the pressed tint is the same gold as a ShapeStyle's pressed fill. It
+      # does not touch the caption, which is not on the fill.
+      class IconButton < Button
+        TINTS = {
+          idle: Util::Color.new(200, 200, 212),
+          focused: Util::Color.new(255, 255, 255),
+          pressed: Util::Color.new(240, 200, 96),
+          disabled: Util::Color.new(90, 88, 100)
+        }.freeze
+        SCALES = { idle: 1, focused: 1, pressed: 1, disabled: 1 }.freeze
+
+        attr_reader :image, :style, :tints, :scales, :label_color, :disabled_label_color
+
+        def initialize(image:, style: nil, tints: TINTS, scales: SCALES,
+                       label_color: TextButton::LABEL_COLOR,
+                       disabled_label_color: TextButton::DISABLED_LABEL_COLOR, **)
+          super(**)
+          @image = image
+          @style = style
+          @style_names_content = style.respond_to?(:content_color)
+          @tints = STATES.to_h { |state| [state, Util::Color.coerce(tints.fetch(state))] }.freeze
+          @scales = STATES.to_h { |state| [state, scales.fetch(state)] }.freeze
+          @label_color = Util::Color.coerce(label_color)
+          @disabled_label_color = Util::Color.coerce(disabled_label_color)
+        end
+
+        def on_draw(renderer, _view)
+          current = state
+          caption_height = @label ? renderer.text_height : 0
+          @style&.draw(renderer, current, width, height - caption_height)
+          content = @style_names_content ? @style.content_color(current) : nil
+          draw_image(renderer, current, content, (height - caption_height) / 2.0)
+          draw_caption(renderer, caption_height) if @label
+        end
+
+        private
+
+        def draw_image(renderer, current, content, cy)
+          return unless @image
+
+          renderer.image(@image, width / 2.0, cy,
+                         scale: @scales.fetch(current), z: 1, color: content || @tints.fetch(current))
+        end
+
+        def draw_caption(renderer, caption_height)
+          text = @label.to_s
+          renderer.text(text, (width - renderer.text_width(text)) / 2, height - caption_height,
+                        z: 1, color: @enabled ? @label_color : @disabled_label_color)
+        end
+      end
+    end
+  end
+end