rgame 0.2.0 → 0.3.0

data/examples/signals/main.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+# Signals — a node announcing that something happened, to nobody in particular.
+#
+# Run it:
+#
+#   ruby examples/signals/main.rb
+#
+# **Enter** stands on the plate. Hold **Space** and hold **E**: both feed one
+# component, at different rates. It exercises:
+#   - Signal::DSL — `signal :on_pressed` on a node of your own;
+#   - Signal.define(:field) — a signal that carries a payload;
+#   - Components::ActionTrigger — one component, several actions, one signal;
+#   - the connect handle, and the one place in the engine that can use it.
+#
+# ## The plate does not know what a door is
+#
+# That sentence is the whole reason signals exist. A plate that opened a door
+# would have to be handed a door, which means whatever built the plate would have
+# to know about doors, and a plate with nothing to open would be a special case
+# to write. Instead the plate says *that it was pressed* and stops:
+#
+#     on_pressed_signal.emit
+#
+# The door and the lamp connect to it, and neither appears anywhere in the
+# plate. Adding a third thing that reacts is one line, in the third thing.
+#
+# ## Declaring one is a single line
+#
+#     class Plate < RGame::Engine::Node2D
+#       signal :on_pressed
+#     end
+#
+# `Node2D` extends `Signal::DSL`, so every node and every component has this
+# available. That one line generates two methods:
+#
+#   `on_pressed { ... }`   public — subscribe, and get a handle back
+#   `on_pressed_signal`    private — the Signal itself, to emit on
+#
+# **Emitting is private on purpose.** Only the plate can say the plate was
+# pressed. That is the same "give the user a blank hook, keep the machinery
+# separate" rule that makes `on_draw` overridable while `draw` is not: the thing
+# a stranger is invited to do is the safe one.
+#
+# ## A payload, for signals that have something to say
+#
+# `signal :on_pressed` carries nothing, because "it happened" is all there is.
+# `Signal.define(:action)` builds one that carries a field, and
+# `Components::ActionTrigger` uses exactly that:
+#
+#     signal :on_triggered, Engine::Signal.define(:action)
+#
+# The engine allows one component of a class per node, so a node that wanted a
+# separate component per action could not have one. Emitting the action name
+# instead lets a single trigger serve `fire` and `poke` together, and the
+# listener filters. Hold both keys here and watch the two counters move at
+# different rates: one component, two cooldowns.
+#
+# ## The handle, and why almost nothing uses it
+#
+# `on_pressed { ... }` hands back a handle, and there is no public way to give it
+# back — `on_pressed_signal` is private, and `disconnect` lives on the Signal.
+# That is deliberate rather than missing. **A node's listeners die with the
+# node**, so a subtree that goes away takes its subscriptions with it and there
+# is nothing to leak.
+#
+# The exception is the one signal that outlives everything. `Engine::AudioBus` is
+# a *module*, so it is built the other way round — it exposes its Signals
+# publicly rather than through the DSL — and `Engine::AudioDirector` disconnects
+# from them when it is released:
+#
+#     @bus.on_play_sound.disconnect(@handles[0])
+#
+# It has to. A module-level hub holds its listeners for as long as the process
+# runs, and the one that was forgotten there held the audio device, which held
+# the asset manager, which held the window. Reach for the public-Signal shape
+# when a hub outlives its subscribers, and for the DSL everywhere else.
+#
+# ## What it does not solve
+#
+# Ordering. Listeners are called in the order they connected, and nothing here
+# offers a priority — if two reactions must happen in a particular order, the
+# thing that cares should own both rather than connecting twice.
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'rgame/game'
+
+Controls = RGame::Util::Controls
+
+WIDTH  = 640
+HEIGHT = 480
+ASSETS = File.expand_path('../assets', __dir__)
+LOCALES = File.expand_path('locales', __dir__) # the text on screen: locales/en.yml
+
+# A plate that announces presses. It has no idea anything is listening, and
+# nothing below it in this file is named anywhere inside it.
+class Plate < RGame::Engine::Node2D
+  signal :on_pressed
+
+  PLATE_W = 150
+  PLATE_H = 34
+  UP   = RGame::Util::Color.new(110, 120, 140)
+  DOWN = RGame::Util::Color.new(210, 190, 110)
+
+  def initialize(**)
+    super(width: PLATE_W, height: PLATE_H, **)
+    @down = false
+  end
+
+  def on_control(actions)
+    @down = actions.held?(:stand_on_plate)
+    # An edge, not the held state: one press is one event, however long the key
+    # stays down. The Signal has no opinion on that — deciding when a thing has
+    # happened is the emitter's job.
+    on_pressed_signal.emit if actions.pressed?(:stand_on_plate)
+  end
+
+  def on_draw(renderer, _view)
+    renderer.rect(0, 0, PLATE_W, PLATE_H, color: @down ? DOWN : UP)
+  end
+end
+
+# Reacts by opening. It knows about the plate; the plate does not know about it.
+class Door < RGame::Engine::Node2D
+  FRAME = RGame::Util::Color.new(70, 78, 96)
+  LEAF  = RGame::Util::Color.new(180, 140, 96)
+  DOOR_W = 64
+  DOOR_H = 96
+  SPEED = 2.2 # fractions of the doorway per second
+
+  def initialize(plate:, **)
+    super(width: DOOR_W, height: DOOR_H, **)
+    @plate = plate
+    @open = false
+    @openness = 0.0
+  end
+
+  # Connecting is the whole of the wiring, and it happens here rather than in
+  # `initialize` because the plate has to exist first — which in this scene it
+  # does, but a listener built outside the tree would not be able to rely on it.
+  def on_add = @plate.on_pressed { @open = !@open }
+
+  def on_update(dt)
+    target = @open ? 1.0 : 0.0
+    step = SPEED * dt
+    @openness += (target - @openness).clamp(-step, step)
+  end
+
+  def on_draw(renderer, _view)
+    renderer.rect(0, 0, DOOR_W, DOOR_H, color: FRAME)
+    # The leaf slides up into the frame, so an open door is a short one.
+    leaf = DOOR_H * (1.0 - @openness)
+    renderer.rect(0, DOOR_H - leaf, DOOR_W, leaf, color: LEAF) if leaf > 1.0
+  end
+end
+
+# Reacts by lighting, and knows nothing about the door reacting to the same
+# thing. Two listeners on one signal, neither aware of the other.
+class Lamp < RGame::Engine::Node2D
+  OFF = RGame::Util::Color.new(64, 62, 56)
+  ON  = RGame::Util::Color.new(255, 226, 130)
+  RADIUS = 22
+  FADE = 1.6
+
+  def initialize(plate:, **)
+    super(width: RADIUS * 2, height: RADIUS * 2, **)
+    @plate = plate
+    @glow = 0.0
+  end
+
+  def on_add = @plate.on_pressed { @glow = 1.0 }
+
+  # The glow is state advanced by dt, not a clock read while drawing — the
+  # standing rule, and the reason pausing this node would freeze it mid-fade.
+  def on_update(dt)
+    @glow -= dt * FADE
+    @glow = 0.0 if @glow.negative?
+  end
+
+  def on_draw(renderer, _view)
+    renderer.circle(0, 0, RADIUS, color: @glow.positive? ? ON : OFF)
+    renderer.circle(0, 0, RADIUS * @glow, color: ON) if @glow.positive?
+  end
+end
+
+# One component, two actions, one signal carrying which. The counters are
+# separate so the two cooldowns are visible as different rates rather than
+# described as them.
+class Repeater < RGame::Engine::Node2D
+  FIRE_COOLDOWN = 0.20
+  POKE_COOLDOWN = 0.55
+  PIP = 12
+  GAP = 5
+  ROW = 26
+  FIRE_COLOR = RGame::Util::Color.new(235, 120, 100)
+  POKE_COLOR = RGame::Util::Color.new(120, 200, 255)
+  MAX_PIPS = 28
+
+  def initialize(**)
+    super
+    @counts = { fire: 0, poke: 0 }
+  end
+
+  def on_add
+    trigger = add_component(
+      RGame::Engine::Components::ActionTrigger.new(fire: FIRE_COOLDOWN, poke: POKE_COOLDOWN)
+    )
+    # The payload is what makes one listener enough. Without it this would need
+    # a signal per action, and the component is allowed only one of itself per
+    # node to hang them on.
+    trigger.on_triggered { |action| @counts[action] += 1 }
+  end
+
+  def on_draw(renderer, _view)
+    draw_row(renderer, @counts[:fire], 0, FIRE_COLOR)
+    draw_row(renderer, @counts[:poke], ROW, POKE_COLOR)
+  end
+
+  private
+
+  # Counted in rectangles rather than in text, because a row makes two rates
+  # comparable at a glance in a way two numbers do not.
+  # hot-path
+  def draw_row(renderer, count, y, color)
+    [count, MAX_PIPS].min.times do |i|
+      renderer.rect(i * (PIP + GAP), y, PIP, PIP, color: color)
+    end
+  end
+end
+
+class Scene < RGame::Engine::Node2D
+  BACKDROP = RGame::Util::Color.new(30, 34, 44)
+
+  def initialize
+    super
+    @help_plate = RGame::Engine::Text.new('help.plate')
+    @help_unnamed = RGame::Engine::Text.new('help.unnamed')
+    @help_cooldowns = RGame::Engine::Text.new('help.cooldowns')
+  end
+
+  def on_add
+    plate = add_node(Plate.new(x: 60, y: 150))
+    # Both are handed the plate and connect themselves. The plate is handed
+    # nothing at all.
+    add_node(Door.new(plate: plate, x: 300, y: 110))
+    add_node(Lamp.new(plate: plate, x: 480, y: 158))
+    add_node(Repeater.new(x: 60, y: 330))
+  end
+
+  def on_draw(renderer, view)
+    renderer.rect(0, 0, view.width, view.height, color: BACKDROP)
+
+    renderer.text(@help_plate, 12, 12)
+    renderer.text(@help_unnamed, 12, 34)
+    renderer.text(@help_cooldowns, 12, 290)
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Signals',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES,
+  # `stand_on_plate` rather than reading `ui_confirm` directly, and the reason is
+  # the trap that costs an afternoon: **a key already in the default map keeps
+  # doing its old job too.** `ui_confirm` is Enter *and* Space, and Space is
+  # `fire`, which the ActionTrigger below reads — so a plate on `ui_confirm`
+  # would also be pressed by the key that is supposed to only feed the repeater.
+  # Two actions may read one key, both fire, and nothing warns.
+  input_map: RGame::Engine::InputMap.default.merge(
+    stand_on_plate: { buttons: [Controls::KEY_RETURN] },
+    poke: { buttons: [Controls::KEY_E] }
+  )
+)
+
+game.start

data/examples/skill_bar/locales/en.yml

@@ -0,0 +1,14 @@
+# The English table: every string this example draws.
+en:
+  help:
+    bar: Left and right move, Enter (or A) uses — or press 1 to 5
+  status:
+    focused: "Focused: %{skill}"
+    used: "Used: %{skill}"
+    nothing_used: "Used: nothing yet"
+  skills:
+    wand: Wand
+    wrench: Wrench
+    torch: Torch
+    hammer: Hammer
+    watering_can: Watering can

data/examples/skill_bar/main.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+# Skill bar — a row of tools, stepped through like a menu and fired by hotkey.
+#
+# Run it:
+#
+#   ruby examples/skill_bar/main.rb
+#
+# Left and right (or the d-pad) move along the bar, and Enter or Space (or A)
+# uses the focused tool. The number keys 1 to 5 use a tool directly, wherever the
+# focus is. Every use clicks. It exercises:
+#   - UI::Row — a UI::Menu layout that lines its buttons up side by side;
+#   - UI::Stepping — the default navigation, which takes its axis from the
+#     layout, so a Row steps with left and right with nothing else said;
+#   - UI::Button's `hotkey:` — an action that presses one button, focused or not;
+#   - `activate_on: :press` — a use happens on the way down, as a skill should;
+#   - UI::IconButton with a caption, on a disc UI::ShapeStyle — a picture with
+#     its name underneath;
+#   - InputMap.default.merge — declaring the five hotkey actions;
+#   - a UI atlas's `images` — the five tools, cut from one strip by name.
+#
+# ## Two ways to press one button
+#
+# A farming sim's tool bar and a combat game's arts are the same menu: a row of
+# buttons, one of them focused. What makes it a *bar* is that each button can
+# also be reached without moving the focus at all. Press 5 with the Torch
+# focused and the Watering can is used, drawn pressed for a moment, and the
+# focus stays on the Torch — a hotkey is a second way to press a button, not a
+# way to move to it.
+#
+# The two ways do not add up. Holding a number key uses the tool once, not once a
+# frame; pressing a tool's number while Enter is already pressing it uses it
+# once. The button remembers which of them started the press, so neither can end
+# the other's.
+#
+# `activate_on: :press` is what a skill wants: the tool is used the frame the key
+# goes down. A settings menu keeps the default, `:release`, where a player can
+# still move away before letting go. Pressed stays visible for
+# `UI::Button::PRESS_FEEDBACK` after a tap, because a single pressed frame is
+# too short to see.
+#
+# ## The caption sits under the disc
+#
+# A captioned IconButton draws its style only in the space above the caption, so
+# "Watering can", wider than the disc, reads on the background in every state.
+#
+# ## What this example does not solve
+#
+# Cooldowns — a sweep over a used tool needs an arc the renderer does not have —
+# and a glyph on each button saying which key uses it. `examples/input_glyphs`
+# draws the glyph for an action, if a bar wants one. The bar is also at a fixed
+# position rather than centred on the view: its buttons are placed when they are
+# added, and the view's size exists only at draw time.
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'rgame/game'
+
+WIDTH  = 640
+HEIGHT = 480
+ASSETS = File.expand_path('../assets', __dir__)
+LOCALES = File.expand_path('locales', __dir__) # the text on screen: locales/en.yml
+Controls = RGame::Util::Controls
+
+# The bar, and what was last used from it.
+class SkillBar < RGame::Engine::Node2D
+  UI = RGame::Engine::UI
+
+  SLOT_WIDTH = 100
+  SLOT_HEIGHT = 104
+
+  # Left to right, with the action that uses each without moving focus. Each
+  # image names an entry of skills.json's `images`.
+  SKILLS = [
+    %i[wand wand skill1],
+    %i[wrench wrench skill2],
+    %i[torch torch skill3],
+    %i[hammer hammer skill4],
+    %i[watering_can watering_can skill5]
+  ].freeze
+
+  DISC = UI::ShapeStyle.new(shape: :disc)
+  CLICK = 'blip.ogg'
+
+  attr_reader :menu, :used
+
+  def initialize(**)
+    super
+    @used = nil
+    @menu = add_node(UI::Menu.new(layout: UI::Row.new(item_width: SLOT_WIDTH, item_height: SLOT_HEIGHT),
+                                  scope: 'skills'))
+    SKILLS.each { |key, image, hotkey| add_skill(key, image, hotkey) }
+  end
+
+  # The name of the focused tool, as its button draws it.
+  def focused_name = @menu.focused.label
+
+  private
+
+  def add_skill(key, image, hotkey)
+    button = UI::IconButton.new(image: image, label: key, hotkey: hotkey, activate_on: :press, style: DISC)
+    @menu.add(button).on_activated do
+      @used = button.label
+      RGame::Engine::AudioBus.play_sound(CLICK)
+    end
+  end
+end
+
+# The captions. Added after the bar, so its last line is the last text of every
+# frame — which is what the drive script reads. Each sentence is one key with the
+# tool's name as a variable, and the name is the button's own label, so a
+# translator writes each name once and drawing an unchanged caption allocates
+# nothing.
+class Caption < RGame::Engine::Node2D
+  def initialize(bar:, **)
+    super(**)
+    @bar = bar
+    @help = RGame::Engine::Text.new('help.bar')
+    @focused = RGame::Engine::Text.new('status.focused', :skill)
+    @used = RGame::Engine::Text.new('status.used', :skill)
+    @nothing_used = RGame::Engine::Text.new('status.nothing_used')
+  end
+
+  def on_draw(renderer, _view)
+    renderer.text(@help, 12, 12)
+    renderer.text(@focused.with(skill: @bar.focused_name.to_s), 12, HEIGHT - 52)
+    used = @bar.used
+    renderer.text(used ? @used.with(skill: used.to_s) : @nothing_used, 12, HEIGHT - 30)
+  end
+end
+
+class Scene < RGame::Engine::Node2D
+  def on_add
+    bar = add_node(SkillBar.new(y: 300))
+    bar.x = (WIDTH - bar.menu.bounds_width) / 2
+    add_node(Caption.new(bar: bar))
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Skill bar',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES,
+  input_map: RGame::Engine::InputMap.default.merge(
+    skill1: { buttons: [Controls::KEY_1] },
+    skill2: { buttons: [Controls::KEY_2] },
+    skill3: { buttons: [Controls::KEY_3] },
+    skill4: { buttons: [Controls::KEY_4] },
+    skill5: { buttons: [Controls::KEY_5] }
+  )
+)
+
+# An image id that is a Symbol is a name rather than a path, so the tools are
+# registered once: the atlas cuts each from the strip and registers it by name.
+game.renderer.register_ui_atlas(game.assets.ui_atlas('skills.json'))
+
+game.start

data/examples/sound/locales/en.yml

@@ -0,0 +1,6 @@
+# The English table: every string this example draws.
+en:
+  help:
+    press: Press Space (or A on a controller) — fast, to hear them overlap
+  hud:
+    plays: "plays: %{plays}"

data/examples/sound/main.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# Sound — a sound effect fired by a button, and the seam it travels through.
+#
+# Run it:
+#
+#   ruby examples/sound/main.rb
+#
+# Space (or A on a pad) plays a blip. Press it fast: each press is another
+# voice, so they overlap rather than cutting each other off. It exercises:
+#   - Core::Sample — a decoded, fire-and-forget effect, named by its path;
+#   - Engine::AudioBus — where gameplay says *what happened*;
+#   - Engine::AudioDirector — what turns that into playback, subscribed by
+#     RGame::Game;
+#   - Engine::Text — a count on screen, from a key, that costs no String per frame.
+#
+# ## Why a node does not just call the audio device
+#
+# It cannot. A node lives in `RGame::Engine`, and that layer may not name
+# `RGame::Core` at all — not a require, not a constant. So `Scene#on_control`
+# below emits on `AudioBus`, a global signal hub that knows nothing about sound,
+# and an `AudioDirector` forwards it to the real device. `RGame::Game` subscribes
+# that director when it starts and releases it when the loop ends, so this file
+# wires nothing.
+#
+# That looks like ceremony until you notice what it buys: the same scene runs in
+# a headless spec with a recording fake substituted for the device, and the spec
+# asserts on *what was asked for* rather than on what came out of a speaker.
+# `spec/support/shared_examples/an_audio_server.rb` is the contract both sides
+# are held to.
+#
+# ## A Sample is not a Song
+#
+# There are two types on purpose. This is a `Sample`: decoded up front, and every
+# `play_sound` starts a **new voice** layered over whatever is already sounding.
+# It has no `playing?`, because the question has no answer for a sound that may
+# be going five times at once. `examples/music` is the other type.
+#
+# ## Naming a sound is naming a file
+#
+# `'blip.ogg'` is a path, resolved through the asset manager on first use and
+# remembered — the same thing `examples/walk` does with `'hero.json'`. Nothing is
+# registered anywhere in this file.
+#
+# The other id space is a Symbol, which `audio.register_sound(:hit, ...)` binds
+# to a sound the game chose the name for, or assembled rather than loaded. Audio
+# and the renderer take the same two, so one rule covers both: a String is a
+# file, a Symbol is a name.
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'rgame/game'
+
+WIDTH  = 640
+HEIGHT = 480
+ASSETS = File.expand_path('../assets', __dir__)
+LOCALES = File.expand_path('locales', __dir__) # the text on screen: locales/en.yml
+
+class Scene < RGame::Engine::Node2D
+  RING = RGame::Util::Color.new(120, 200, 255)
+  FADE = 3.0        # how fast the flash decays, in units per second
+  MIN_R = 18.0      # radius at rest
+  GROW  = 90.0      # extra radius at full flash
+
+  def initialize
+    super
+    @flash = 0.0
+    @plays = 0
+    # Built once, here, and that is the whole trick: the key's text renders when
+    # the count changes rather than when a frame is drawn. See the note above
+    # on_draw.
+    @plays_label = RGame::Engine::Text.new('hud.plays', :plays)
+    @help = RGame::Engine::Text.new('help.press')
+  end
+
+  def on_control(actions)
+    return unless actions.pressed?(:fire)
+
+    # The whole of "make a noise": a fact, emitted. Nothing here knows whether
+    # anything is listening, or what it would play it on.
+    RGame::Engine::AudioBus.play_sound('blip.ogg')
+
+    @flash = 1.0
+    @plays += 1
+  end
+
+  # The flash is state, advanced by dt — not a clock read at draw time. That is
+  # the standing rule (CLAUDE.md, "`draw` renders state"), and it is why pausing
+  # this node would freeze the ring mid-fade instead of letting it run on.
+  def on_update(dt)
+    @flash -= dt * FADE
+    @flash = 0.0 if @flash.negative?
+  end
+
+  # A count, drawn as text, allocating nothing.
+  #
+  # `"plays: #{@plays}"` written here would build a String on every frame
+  # forever, and `Game/NoInterpolationInHotPath` is right to refuse it: a steady
+  # 60fps frame that allocates is a GC pause waiting to happen.
+  # `Engine::Text` holds the last string and renders `plays: %{plays}` from the
+  # table again only when the value changes, so pressing the key costs one
+  # allocation and the thousand frames between presses cost none.
+  #
+  # **Reach for it rather than inventing a way round the rule.** A label built
+  # from something that changes is common enough that the engine owns the
+  # answer — see CLAUDE.md, "A label built from a changing value".
+  def on_draw(renderer, _view)
+    renderer.circle(WIDTH / 2, HEIGHT / 2, MIN_R + (GROW * @flash), color: RING)
+    renderer.text(@help, 12, 12)
+    renderer.text(@plays_label.with(plays: @plays), 12, 44)
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Sound',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES
+)
+
+game.start

data/examples/split_screen/locales/en.yml

@@ -0,0 +1,9 @@
+# The English table: every string this example draws.
+en:
+  help:
+    keys: "Player one: arrows or WASD. Space waves"
+    join: Press A on a controller to join player two
+  hud:
+    # The number is given once, when the badge is built, and the Text keeps it.
+    player: "Player %{number}"
+    waves: "waves: %{count}"