rgame 0.2.0 → 0.3.0

data/examples/quick_wheel/main.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+# Quick wheel — a radial menu held open by a button, and chosen by letting go.
+#
+# Run it:
+#
+#   ruby examples/quick_wheel/main.rb
+#
+# Hold Tab (or the left shoulder button), point with the arrow keys (or the left
+# stick), and let go of Tab to choose. Let go with nothing pointed at to choose
+# nothing. It exercises:
+#   - UI::RadialMenu with `trigger:` — the wheel is closed until the trigger goes
+#     down and chooses what is focused when it comes up;
+#   - UI::Pointing's grace window — a stick that springs back a moment before
+#     the trigger still chooses what it pointed at;
+#   - UI::Menu#on_opened / #on_closed — what the game does while the wheel is
+#     open, here slowing the world to a quarter of its speed;
+#   - InputMap.default.merge — declaring the trigger on Tab and the left shoulder.
+#
+# ## Letting go is the choice
+#
+# There is no confirm button here, and pressing one does nothing: the player's
+# thumb is on the stick and a finger is on the shoulder, and releasing the
+# shoulder is the only thing left to do. `examples/radial_menu` is the other
+# style of the same wheel — always open, point, then press A — and is the same
+# classes without `trigger:`.
+#
+# ## The stick springs back first
+#
+# Letting go of a stick and a shoulder button at once is not at once: the stick
+# is back in the middle a frame or two before the button comes up. With nothing
+# to account for that, the release would find the stick at rest and choose
+# nothing almost every time. So focus survives the dead zone for
+# `Pointing::GRACE`, 0.15 s, which a wheel with a trigger gets without asking.
+# On a keyboard the same thing happens between letting go of an arrow key and
+# letting go of Tab. Hold the arrow at rest for longer than that, and the
+# release chooses nothing — which is how a player changes their mind.
+#
+# ## The world is the game's business
+#
+# The wheel says when it opens and closes. Whether the world pauses, slows or
+# carries on is a decision about the game, not about menus, so it is made here:
+# the dots drift at a quarter speed while the wheel is open.
+#
+# ## What this example does not solve
+#
+# Captions on the wheel, and a wheel centred on the view — see
+# `examples/radial_menu`. A stick that overshoots the middle as it springs back
+# can briefly point at the opposite icon, which the grace window does not
+# cover.
+
+$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 part of the scene the wheel slows down. A time scale applied to `dt` on
+# the way in is the whole of slow motion, because time only enters through
+# `update`.
+class World < RGame::Engine::Node2D
+  SLOWED = 0.25
+
+  attr_accessor :time_scale
+
+  def initialize(**)
+    super
+    @time_scale = 1.0
+  end
+
+  def update(dt) = super(dt * @time_scale)
+end
+
+# A square that drifts and bounces off the window's edges.
+class Dot < RGame::Engine::Node2D
+  SIZE = 12
+  COLOR = RGame::Util::Color.new(120, 180, 150)
+
+  def initialize(speed_x:, speed_y:, **)
+    super(**)
+    @speed_x = speed_x
+    @speed_y = speed_y
+  end
+
+  def on_update(dt)
+    self.x += @speed_x * dt
+    self.y += @speed_y * dt
+    @speed_x = -@speed_x unless x.between?(0, WIDTH - SIZE)
+    @speed_y = -@speed_y unless y.between?(0, HEIGHT - SIZE)
+  end
+
+  def on_draw(renderer, _view) = renderer.rect(0, 0, SIZE, SIZE, color: COLOR)
+end
+
+# The wheel, held open by `:quick_menu`, and what it last chose.
+class QuickWheel < RGame::Engine::Node2D
+  UI = RGame::Engine::UI
+
+  RADIUS = 150
+  SLOT = 64
+
+  # Clockwise from the top. Each image names an entry of icons.json's `images`.
+  ICONS = [
+    %i[home home],
+    %i[settings gear],
+    %i[save save],
+    %i[favourite star],
+    %i[trophies trophy],
+    %i[sound audio_on],
+    %i[music music_on],
+    %i[locked locked]
+  ].freeze
+
+  DISC = UI::ShapeStyle.new(shape: :disc)
+
+  attr_reader :chosen
+
+  def initialize(world:, **)
+    super(**)
+    @chosen = nil
+    @menu = add_node(UI::RadialMenu.new(radius: RADIUS, button_width: SLOT, trigger: :quick_menu))
+    ICONS.each { |key, image| add_icon(key, image) }
+    @menu.on_opened { world.time_scale = World::SLOWED }
+    @menu.on_closed { world.time_scale = 1.0 }
+  end
+
+  private
+
+  def add_icon(key, image)
+    button = @menu.add(UI::IconButton.new(image: image, style: DISC, enabled: image != :locked))
+    button.on_activated { @chosen = key }
+  end
+end
+
+# The captions. Added last, so its final line is the last text of every frame —
+# which is what the drive script reads.
+class Caption < RGame::Engine::Node2D
+  NAMES = QuickWheel::ICONS.to_h { |key, _| [key, RGame::Engine::Text.new(key, scope: 'items')] }.freeze
+
+  def initialize(wheel:, **)
+    super(**)
+    @wheel = wheel
+    @help = RGame::Engine::Text.new('help.wheel')
+    @nothing = RGame::Engine::Text.new('status.nothing')
+    @chosen = RGame::Engine::Text.new('status.chosen', :item)
+  end
+
+  def on_draw(renderer, _view)
+    renderer.text(@help, 12, 12)
+    chosen = @wheel.chosen
+    renderer.text(chosen ? @chosen.with(item: NAMES.fetch(chosen).to_s) : @nothing, 12, HEIGHT - 30)
+  end
+end
+
+class Scene < RGame::Engine::Node2D
+  DOTS = [[60, 80, 90, 40], [400, 120, -70, 60], [200, 360, 50, -80], [520, 300, -100, -30]].freeze
+
+  def on_add
+    world = add_node(World.new)
+    DOTS.each { |x, y, speed_x, speed_y| world.add_node(Dot.new(x: x, y: y, speed_x: speed_x, speed_y: speed_y)) }
+    wheel = add_node(QuickWheel.new(world: world, x: WIDTH / 2, y: (HEIGHT / 2) + 6))
+    add_node(Caption.new(wheel: wheel))
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Quick wheel',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES,
+  input_map: RGame::Engine::InputMap.default.merge(
+    quick_menu: { buttons: [Controls::KEY_TAB, Controls::PAD_LEFT_SHOULDER] }
+  )
+)
+
+# The icons are registered by name, once: the atlas cuts each from the strip.
+game.renderer.register_ui_atlas(game.assets.ui_atlas('icons.json'))
+
+game.start

data/examples/radial_menu/locales/en.yml

@@ -0,0 +1,16 @@
+# The English table: every string this example draws.
+en:
+  help:
+    point: Point the stick (or arrow keys) at an icon, then press A (or Enter)
+  status:
+    nothing: "Chosen: nothing yet"
+    chosen: "Chosen: %{item}"
+  items:
+    home: Home
+    settings: Settings
+    save: Save
+    favourite: Favourite
+    trophies: Trophies
+    sound: Sound
+    music: Music
+    locked: Locked

data/examples/radial_menu/main.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+# Radial menu — a quick menu of icons, chosen by pointing rather than by stepping
+# through a list.
+#
+# Run it:
+#
+#   ruby examples/radial_menu/main.rb
+#
+# Point the left stick at an icon and press A. On a keyboard, hold the arrow
+# keys — two at once for a diagonal — and press Enter or Space. The chosen icon
+# appears, doubled, in the middle of the wheel. It exercises:
+#   - UI::RadialMenu — a UI::Menu that builds its own UI::Ring and
+#     UI::Pointing, and draws the backdrop, the dead zone and the pointer;
+#   - UI::IconButton — each entry, a picture tinted by its state;
+#   - UI::ShapeStyle — the disc behind every icon, outlined while focused;
+#   - `ui_radial_x` / `ui_radial_y` — the two axes Pointing reads, from the
+#     universal set every InputMap carries, so nothing here declares an action;
+#   - a UI atlas's `images` — the eight icons, cut from one strip and registered
+#     by name in one call.
+#
+# ## The direction is the selection
+#
+# A list menu moves focus *relative* to where it already is: down means "the
+# next one". A stick is bad at that and good at pointing, so here nothing is
+# stepped through at all. Whichever button lies closest to the direction the
+# stick points in is focused, which on a ring cuts the circle into one sector per
+# button, centred on it. Eight buttons is the number that makes a keyboard a
+# first-class input too: the arrow keys, alone and in pairs, produce exactly
+# eight directions, one per icon.
+#
+# That is the only thing that makes this a wheel rather than a list. The menu,
+# its buttons and what confirming does are the same classes `examples/game_menu`
+# uses; a RadialMenu is a UI::Menu handed a UI::Ring where that one has a
+# UI::Column, and UI::Pointing where that one keeps the default UI::Stepping.
+#
+# `examples/quick_wheel` is the other common style of the same wheel: closed until
+# a button is held, and chosen by letting that button go.
+#
+# ## Letting go selects nothing
+#
+# The lighter disc around the middle is the **dead zone**, drawn to scale: the
+# pointer's tip inside it means the stick is not deflected far enough to mean
+# anything, and no button is focused. That is what makes the obvious mistake
+# impossible — a player who lets the stick spring back and then presses A has
+# not asked for whatever the stick passed over on its way home, and gets nothing.
+#
+# It is a length on the combined vector, and much bigger than the per-axis dead
+# zone every action already has. That one only stops a worn stick drifting; it
+# would let a stick barely off centre choose.
+#
+# **Locked** is disabled, and pointing at it focuses nothing — the same rule a
+# list follows by skipping it.
+#
+# ## White art, coloured by a tint
+#
+# The icons are white, and IconButton draws each one multiplied by a colour for
+# its state — grey at rest, white while focused, dim while disabled — so one
+# picture serves all four looks. Dark art would take none of them. While pressed
+# the disc is gold, and the disc's ShapeStyle says the icon goes dark on it: what
+# reads on a fill is the style's to decide, since it chose the fill.
+#
+# The icons are 50 pixels in 64-pixel slots and the chosen one is drawn at scale
+# 2: images sample nearest-neighbour, so only a whole-number scale stays sharp.
+#
+# ## What this example does not solve
+#
+# Captions. The icons carry no text, so the wheel says what was chosen only in
+# the line along the bottom. The wheel is also at a fixed position rather than
+# centred on the view, because its buttons are placed when they are added and the
+# view's size only exists at draw time — the same limit `examples/game_menu`
+# names.
+
+$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
+
+# The wheel and what it chooses. The wheel itself — backdrop, dead zone, pointer
+# and buttons — is a UI::RadialMenu; the chosen icon is a node added after it,
+# because between nodes the tree decides what lands on top, and anything this
+# node drew itself would sit under the menu's backdrop.
+class QuickMenu < RGame::Engine::Node2D
+  UI = RGame::Engine::UI
+
+  RADIUS = 150
+  SLOT = 64
+
+  # Clockwise from the top. Each image names an entry of icons.json's `images`.
+  ICONS = [
+    %i[home home],
+    %i[settings gear],
+    %i[save save],
+    %i[favourite star],
+    %i[trophies trophy],
+    %i[sound audio_on],
+    %i[music music_on],
+    %i[locked locked]
+  ].freeze
+
+  DISC = UI::ShapeStyle.new(shape: :disc)
+
+  attr_reader :chosen, :chosen_image
+
+  def initialize(**)
+    super
+    @chosen = nil
+    @chosen_image = nil
+    @menu = add_node(UI::RadialMenu.new(radius: RADIUS, button_width: SLOT))
+    ICONS.each { |key, image| add_icon(key, image) }
+    add_node(ChosenIcon.new(menu: self))
+  end
+
+  private
+
+  def add_icon(key, image)
+    button = @menu.add(UI::IconButton.new(image: image, style: DISC, enabled: image != :locked))
+    button.on_activated do
+      @chosen = key
+      @chosen_image = image
+    end
+  end
+end
+
+# The chosen icon, doubled, in the middle of the wheel.
+class ChosenIcon < RGame::Engine::Node2D
+  SCALE = 2
+
+  def initialize(menu:, **)
+    super(**)
+    @menu = menu
+  end
+
+  def on_draw(renderer, _view)
+    image = @menu.chosen_image
+    renderer.image(image, 0, 0, scale: SCALE) if image
+  end
+end
+
+# The captions. Added after the wheel, so it draws last and its final line is
+# the last text of every frame — which is what the drive script reads.
+class Caption < RGame::Engine::Node2D
+  NAMES = QuickMenu::ICONS.to_h { |key, _| [key, RGame::Engine::Text.new(key, scope: 'items')] }.freeze
+
+  def initialize(menu:, **)
+    super(**)
+    @menu = menu
+    @help = RGame::Engine::Text.new('help.point')
+    @nothing = RGame::Engine::Text.new('status.nothing')
+    @chosen = RGame::Engine::Text.new('status.chosen', :item)
+  end
+
+  def on_draw(renderer, _view)
+    renderer.text(@help, 12, 12)
+    chosen = @menu.chosen
+    renderer.text(chosen ? @chosen.with(item: NAMES.fetch(chosen).to_s) : @nothing, 12, HEIGHT - 30)
+  end
+end
+
+class Scene < RGame::Engine::Node2D
+  def on_add
+    menu = add_node(QuickMenu.new(x: WIDTH / 2, y: (HEIGHT / 2) + 6))
+    add_node(Caption.new(menu: menu))
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Radial menu',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES
+)
+
+# An image id that is a Symbol is a name rather than a path, so the icons are
+# registered once, by hand: the atlas cuts each from the strip and registers it
+# under its name.
+game.renderer.register_ui_atlas(game.assets.ui_atlas('icons.json'))
+
+game.start

data/examples/save_load/locales/en.yml

@@ -0,0 +1,11 @@
+# The English table: every string this example draws.
+en:
+  help:
+    walk: Arrows walk the dog
+    keys: F5 saves   F9 loads   Delete discards the save
+  status:
+    saved: saved — quit and run again, or press F9
+    loaded: loaded
+    deleted: save deleted
+    fresh: no save yet — walk the dog, then press F5
+    restored: loaded the save from last time

data/examples/save_load/main.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+# Save and load — writing game state to disk, and putting it back.
+#
+# Run it:
+#
+#   ruby examples/save_load/main.rb
+#
+# Arrow keys walk the dog. **F5** saves, **F9** loads, **Delete** throws the save
+# away. Quit and run it again: the dog and the sheep are where you left them,
+# because a save found at startup is loaded before the first frame. It
+# exercises:
+#   - Util::SaveFile — one JSON file, written atomically, read forgivingly;
+#   - the same Node2D + CharacterBody + controller composition as
+#     `examples/walk`, with the flock on a WanderController instead;
+#   - `RGAME_SEED`, so a run without a save is reproducible.
+#
+# ## The tree is not saved, and nothing here tries
+#
+# This is the shape every comparable engine settles on: **a scene is a recipe
+# and a save file is state.** The scene builds itself the same way every time,
+# and the save supplies the handful of facts that differ between runs. Godot's
+# own guidance is this, and it is why an rgame node has no name, no path and no
+# id — nothing needs one.
+#
+# Two kinds of thing are being restored here, and they need different answers.
+#
+# **The dog is singular, so a variable is its identity.** `@dog` is set where the
+# dog is built, and `load_state` writes straight to it. There is no lookup, no
+# name, nothing to match up — the code that made the dog is the code that puts
+# it back, and it never lost track of which one it was.
+#
+# **The sheep are interchangeable, so their order is their identity.** The save
+# holds an array of positions; loading walks the flock and the array together.
+# If sheep three and seven swapped places nothing observable would change, which
+# is exactly what "interchangeable" means, and it is the property that makes an
+# array enough.
+#
+# ## What would break this, and what to do about it
+#
+# The flock is a fixed size and no sheep can die. That is what lets an array
+# index stand in for identity — and it is the assumption to check before copying
+# this shape. The moment sheep can be killed, and the survivors must keep their
+# own hunger and name across a save, the array stops meaning anything and each
+# sheep needs an id of its own.
+#
+# `Components::Identity` is that id, and `examples/save_load_ids` is where it is
+# shown: sheep that can be lost, and a dog chasing one particular sheep — a
+# reference between two saved things, which is what genuinely forces a name.
+# Unreal's save libraries bolt a GUID onto every actor for the same reason, and
+# Unity's community does the same.
+#
+# ## Position is not the whole of where something is
+#
+# The sheep resume standing still, because a WanderController's timer is not
+# saved. That is a deliberate simplification and worth naming, because the real
+# version of this bug is not funny: a game that saves a falling player's position
+# and not their velocity restores them hanging in the air.
+
+$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
+
+DOG_SPEED   = 150.0
+SHEEP_SPEED = 40.0
+SHEEP_COUNT = 8
+
+# Seeded, so a fresh run with no save always lays the flock out the same way and
+# two driven runs can be compared.
+DEFAULT_SEED = 0x5EED
+
+class Pasture < RGame::Engine::Node2D
+  GRASS = RGame::Util::Color.new(96, 140, 84)
+  DOG   = RGame::Util::Color.new(70, 50, 40)
+  SHEEP = RGame::Util::Color.new(240, 240, 235)
+  DOG_R = 11
+  SHEEP_R = 9
+
+  STATUS = { saved: RGame::Engine::Text.new('status.saved'),
+             loaded: RGame::Engine::Text.new('status.loaded'),
+             deleted: RGame::Engine::Text.new('status.deleted'),
+             fresh: RGame::Engine::Text.new('status.fresh'),
+             restored: RGame::Engine::Text.new('status.restored') }.freeze
+
+  def initialize(save:, **)
+    super(**)
+    @save = save
+    @help = RGame::Engine::Text.new('help.walk')
+    @keys = RGame::Engine::Text.new('help.keys')
+    @rng = Random.new(ENV.fetch('RGAME_SEED', DEFAULT_SEED).to_i)
+    @flock = []
+    @status = :fresh
+  end
+
+  def on_add
+    # Built first, always, and identically. The save does not decide what exists
+    # — only where it is.
+    @dog = add_node(build_walker(RGame::Engine::Components::PlayerController.new,
+                                 DOG_SPEED, WIDTH / 2, HEIGHT / 2))
+    SHEEP_COUNT.times do
+      @flock << add_node(build_walker(
+                           RGame::Engine::Components::WanderController.new(rng: @rng),
+                           SHEEP_SPEED, @rng.rand(WIDTH - 40) + 20, @rng.rand(HEIGHT - 80) + 60
+                         ))
+    end
+
+    return unless @save.exist?
+
+    load_state
+    @status = :restored
+  end
+
+  def on_control(actions)
+    save_state if actions.pressed?(:save)
+    load_state if actions.pressed?(:load)
+    drop_save if actions.pressed?(:drop)
+  end
+
+  def on_draw(renderer, view)
+    renderer.rect(0, 0, view.width, view.height, color: GRASS)
+    @flock.each { |sheep| renderer.circle(sheep.x, sheep.y, SHEEP_R, color: SHEEP) }
+    renderer.circle(@dog.x, @dog.y, DOG_R, color: DOG)
+
+    renderer.text(@help, 12, 12)
+    renderer.text(@keys, 12, 34)
+    renderer.text(STATUS.fetch(@status), 12, 56)
+  end
+
+  private
+
+  # The whole save: two facts, written as plain numbers.
+  #
+  # Reading `sheep.x` from outside the node is fine here and is not the thing
+  # Game/DrawInLocalSpace forbids — that rule is about a node reading its *own*
+  # position while drawing, when its transform has already been applied.
+  def save_state
+    @save.write(dog: [@dog.x, @dog.y], sheep: @flock.map { |sheep| [sheep.x, sheep.y] })
+    @status = :saved
+  end
+
+  def load_state
+    state = @save.read
+    place(@dog, state[:dog])
+    # `zip` stops at the shorter of the two, so a save written when the flock
+    # was a different size restores what it can instead of raising. That is the
+    # cheap half of the versioning problem; the expensive half is a save whose
+    # *shape* changed, which needs a version number in the file.
+    @flock.zip(state.fetch(:sheep, [])) { |sheep, position| place(sheep, position) }
+    @status = :loaded
+  end
+
+  def drop_save
+    @save.delete
+    @status = :deleted
+  end
+
+  def place(node, position)
+    return if position.nil?
+
+    node.x, node.y = position
+  end
+
+  def build_walker(controller, speed, x, y)
+    node = RGame::Engine::Node2D.new(x: x, y: y)
+    node.add_component(RGame::Engine::Components::CharacterBody.new(speed: speed))
+    node.add_component(controller)
+    node
+  end
+end
+
+# `dir:` is normally left out, and the file lands in the platform's own data
+# directory — ~/.local/share, Application Support or %APPDATA%. It is overridable
+# here so a driven run can write somewhere disposable instead of into the home
+# directory of whoever happens to be running it.
+save = RGame::Util::SaveFile.new('pasture.json', game: 'rgame-examples',
+                                                 dir: ENV.fetch('RGAME_SAVE_DIR', nil))
+
+game = RGame::Game.new(
+  root: Pasture.new(save: save),
+  caption: 'Save and load',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES,
+  # F5 and F9 rather than S and L, and the reason is worth knowing: **a key
+  # already in the default map keeps doing its default job too.** `move_y` is
+  # bound to W and S, so an action added on S saves *and* walks the dog
+  # downwards — both fire, because two actions may read one key. Nothing is
+  # broken and nothing warns; the game just moves when you asked it to save.
+  #
+  # F5 and F9 are free, and are what a player already expects quicksave and
+  # quickload to be. F1 and F2 are not free: RGame::Game keeps those for the
+  # debug overlay and quit.
+  input_map: RGame::Engine::InputMap.default.merge(
+    save: { buttons: [Controls::KEY_F5] },
+    load: { buttons: [Controls::KEY_F9] },
+    drop: { buttons: [Controls::KEY_DELETE] }
+  )
+)
+
+game.start

data/examples/save_load_ids/locales/en.yml

@@ -0,0 +1,11 @@
+# The English table: every string this example draws.
+en:
+  help:
+    keys: Arrows walk   Tab targets   Space shears   N adds a sheep
+    save: F5 saves   F9 loads   Delete discards the save
+  status:
+    fresh: no save yet — shear a few, add one, then press F5
+    restored: loaded the save from last time
+    saved: saved — quit, run again, then press N for a fresh id
+    loaded: loaded
+    deleted: save deleted