rgame 0.2.0 → 0.3.0

data/examples/pathfinding/main.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+# Pathfinding — pick a tile, and the hero works out how to get there.
+#
+# Run it:
+#
+#   ruby examples/pathfinding/main.rb
+#
+# The arrow keys or a d-pad move the tile cursor, and holding one keeps it moving.
+# Return, Space or the pad's A button sends the hero there. The trees and the fence
+# are solid, and the fence has one gap. It exercises:
+#   - Components::Navigator — `go_to(world_x, world_y)`: a route over the map,
+#     smoothed against the hero's own feet box, and walked;
+#   - Components::TileWorld#nav_grid — the search grid, built from the same
+#     solidity the collision uses, and asked whether a tile can be stood on;
+#   - Components::AnimatedSprite — facing the way the route goes, with nobody
+#     pressing a direction;
+#   - Components::ActionTrigger — the cursor's held-key repeat;
+#   - Components::CameraFollow — on the cursor rather than on the hero;
+#   - Engine::Text.computed — a status line assembled from several translations,
+#     with plurals, and built only when the route or the language changes;
+#   - the TileWorld, FeetCollider and TileMapLayer scene from `examples/collision_tiles`.
+#
+# ## Two drawings of one route
+#
+# The small dots are the route the search found: one per tile, start to target,
+# each a step to a neighbouring tile. The lines are the route the hero walks. They
+# are the same route, and the difference between them is the point of this file.
+#
+# A tile-by-tile route walked as it stands zig-zags. It turns wherever the grid
+# does, which is at every tile a diagonal meets a straight, and a character doing
+# that looks like it is being steered by a spreadsheet. So the navigator pulls the
+# route tight: from each corner it keeps going straight for as long as it can, and
+# turns only where it has to. Send the hero across open ground and there is one
+# line; send it through the fence and there are a handful, against dozens of dots.
+#
+# ## "As long as it can" means as long as the feet fit
+#
+# A straight line is kept only if the hero's feet box — the red box in
+# `examples/collision_tiles`, twelve by six — can travel it without touching a
+# solid tile, and the thing asked is the same `TileWorld` that stops the hero when
+# it walks. A line tested against tiles alone would cut past a tree's corner that a
+# point clears and a feet box clips. The hero does not slide along the tree the way
+# a player-steered character would: it is on a route, so it would stand at that
+# corner pressing into it. The search and the collision cannot disagree about what
+# fits, because they are asking one map.
+#
+# ## The cursor, and where the camera looks
+#
+# The camera follows the cursor, not the hero. A target is picked by looking at it,
+# and a cursor that could be walked off the screen would be lost; the hero is the
+# thing that is allowed to leave the view, and it walks back into it on its way to
+# the tile you picked.
+#
+# The outline is green on a tile the hero can stand on and red on a solid one. That
+# is read from the grid once each time the cursor moves, not every frame. Confirming
+# on a red tile does nothing to the hero — there is no route to a tree, and the
+# navigator says so by returning `false` — so a hero already walking carries on.
+#
+# ## What this scene does not solve
+#
+# The hero plans against the map and nothing else. Give it `blocked_by: %i[tiles
+# npc]` and it waits behind a villager standing on its route rather than going
+# round; a game that wants it to go round calls `go_to` again. The map never
+# changes, so the grid is built once, the first time it is asked for — a door that
+# opens would need a grid that is told. And there is one hero: many walkers heading
+# for one place want a different search from many separate ones.
+
+$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
+
+MAP   = 'town.tmx'
+TILE  = 16
+SPEED = 90.0 # px/s
+
+FEET_WIDTH  = 12
+FEET_HEIGHT = 6
+
+# The tile the hero starts on: north of the fence and well east of its gap, so any
+# route south goes the long way.
+START_COL = 24
+START_ROW = 18
+
+# The middle of the feet box, from the hero's origin: centred across the 16px-wide
+# sprite, and half the box up from the bottom of its 22px height. Standing the hero
+# with this point on a tile's centre is standing it on that tile.
+FEET_CENTRE_X = 8
+FEET_CENTRE_Y = 19
+
+# How often a held direction moves the cursor another tile.
+CURSOR_REPEAT = 0.12 # s
+
+# A sprite, a feet box and a navigator. Where `examples/collision_tiles` has a
+# CharacterBody and a PlayerController, this hero has one component that plans
+# its own movement, and nothing reads the keyboard on its behalf.
+class Hero < RGame::Engine::Node2D
+  attr_reader :navigator, :collider
+
+  def initialize(**)
+    super
+    add_component(RGame::Engine::Components::AnimatedSprite.new(sheet: 'hero.json'))
+    @collider = add_component(RGame::Engine::Components::FeetCollider.new(
+                                width: FEET_WIDTH, height: FEET_HEIGHT
+                              ))
+    @navigator = add_component(RGame::Engine::Components::Navigator.new(
+                                 speed: SPEED, blocked_by: [:tiles]
+                               ))
+  end
+end
+
+# A tile outline, moved a tile at a time. It knows which tile it is on and whether
+# that tile can be stood on; what confirming *means* is the scene's business, so it
+# only reports the tile's centre.
+class Cursor < RGame::Engine::Node2D
+  WALKABLE = RGame::Util::Color.rgba(120, 230, 120, 255)
+  SOLID = RGame::Util::Color.rgba(240, 90, 90, 255)
+  STEPS = { ui_left: [-1, 0], ui_right: [1, 0], ui_up: [0, -1], ui_down: [0, 1] }.freeze
+
+  signal :on_confirmed, RGame::Engine::Signal.define(:world_x, :world_y)
+
+  def initialize(col:, row:, camera:)
+    super(x: col * TILE, y: row * TILE)
+    @col = col
+    @row = row
+    # ActionTrigger fires on the tick a direction goes down and again every
+    # CURSOR_REPEAT while it stays down — which is a key repeat, per action.
+    repeat = add_component(RGame::Engine::Components::ActionTrigger.new(
+                             STEPS.keys.to_h { |action| [action, CURSOR_REPEAT] }
+                           ))
+    repeat.on_triggered { |action| step(*STEPS.fetch(action)) }
+    add_component(RGame::Engine::Components::CameraFollow.new(
+                    camera: camera, offset_x: TILE / 2, offset_y: TILE / 2
+                  ))
+  end
+
+  def on_add
+    @world = system(RGame::Engine::Components::TileWorld)
+    step(0, 0)
+  end
+
+  def on_control(actions)
+    return unless actions.pressed?(:ui_confirm)
+
+    on_confirmed_signal.emit(world_x: (@col + 0.5) * TILE, world_y: (@row + 0.5) * TILE)
+  end
+
+  def on_draw(renderer, _view)
+    renderer.line(0, 0, TILE, 0, thickness: 2.0, color: @color)
+    renderer.line(TILE, 0, TILE, TILE, thickness: 2.0, color: @color)
+    renderer.line(TILE, TILE, 0, TILE, thickness: 2.0, color: @color)
+    renderer.line(0, TILE, 0, 0, thickness: 2.0, color: @color)
+  end
+
+  private
+
+  def step(dcol, drow)
+    grid = @world.nav_grid
+    @col = (@col + dcol).clamp(0, grid.width - 1)
+    @row = (@row + drow).clamp(0, grid.height - 1)
+    self.x = @col * TILE
+    self.y = @row * TILE
+    @color = grid.walkable?(@col, @row) ? WALKABLE : SOLID
+  end
+end
+
+# Both drawings of the hero's current route, in world space: a dot per tile the
+# search returned, and a line per segment of the path being walked.
+#
+# The path's waypoints are where the hero's *origin* goes — its sprite's top-left
+# corner — while the route was planned for the middle of its feet. Adding the feet
+# box's centre back puts the lines on the ground the dots are on.
+class Route < RGame::Engine::Node2D
+  DOT = RGame::Util::Color.rgba(255, 255, 255, 200)
+  LINE = RGame::Util::Color.rgba(255, 220, 60, 255)
+  DOT_SIZE = 4
+
+  def initialize(hero:)
+    super()
+    @hero = hero
+  end
+
+  def on_draw(renderer, _view)
+    navigator = @hero.navigator
+    draw_cells(renderer, navigator.cells) if navigator.cells
+    draw_path(renderer, navigator.path) if navigator.path
+  end
+
+  private
+
+  def draw_cells(renderer, cells)
+    offset = (TILE - DOT_SIZE) / 2
+    index = 0
+    while index < cells.length
+      col, row = cells[index]
+      renderer.rect((col * TILE) + offset, (row * TILE) + offset, DOT_SIZE, DOT_SIZE, color: DOT)
+      index += 1
+    end
+  end
+
+  def draw_path(renderer, path)
+    box = @hero.collider.box
+    feet_x = box.offset_x + (box.width / 2.0)
+    feet_y = box.offset_y + (box.height / 2.0)
+    index = 1
+    while index < path.count
+      renderer.line(path.x_at(index - 1) + feet_x, path.y_at(index - 1) + feet_y,
+                    path.x_at(index) + feet_x, path.y_at(index) + feet_y,
+                    thickness: 2.0, color: LINE)
+      index += 1
+    end
+  end
+end
+
+# The scene: the map and its world, the hero, the route drawn under the hero and
+# the cursor over it — and the one line that connects a confirmed tile to a walk.
+class Scene < RGame::Engine::Node2D
+  def on_add
+    map = root.context.assets.tilemap(MAP).map
+    players = root.system(RGame::Engine::Players)
+    add_component(RGame::Engine::Components::TileWorld.new(
+                    map: map, tilemap_id: MAP, cameras: players.map(&:camera)
+                  ))
+
+    view = add_node(RGame::Engine::WorldView.new)
+    actors = RGame::Engine::TileMapLayer.mount(view)
+    @hero = Hero.new(x: ((START_COL + 0.5) * TILE) - FEET_CENTRE_X,
+                     y: ((START_ROW + 0.5) * TILE) - FEET_CENTRE_Y)
+    actors.add_node(Route.new(hero: @hero))
+    actors.add_node(@hero)
+    cursor = actors.add_node(Cursor.new(col: START_COL, row: START_ROW, camera: players.primary.camera))
+
+    cursor.on_confirmed { |world_x, world_y| send_hero(world_x, world_y) }
+    @hero.navigator.on_finished do
+      @arrived = true
+      report
+    end
+
+    @arrived = false
+    @status = nil
+    @status_label = RGame::Engine::Text.computed(:status) { |status:| describe(status) }
+    @help_cursor = RGame::Engine::Text.new('help.cursor')
+    @help_route = RGame::Engine::Text.new('help.route')
+  end
+
+  def on_draw(renderer, _view)
+    renderer.text(@help_cursor, 12, 12)
+    renderer.text(@help_route, 12, 34)
+    renderer.text(@status_label.with(status: @status), 12, 56)
+  end
+
+  private
+
+  def send_hero(world_x, world_y)
+    routed = @hero.navigator.go_to(world_x, world_y)
+    @arrived = false if routed
+    report(refused: !routed)
+  end
+
+  # The status is rebuilt on an event, never per frame, so the label's value only
+  # changes when there is something new to say.
+  def report(refused: false)
+    navigator = @hero.navigator
+    @status = [navigator.cells&.length, navigator.path&.count, @arrived, refused].freeze
+  end
+
+  # The status line, in whatever language is current. It is several keys rather
+  # than one, because a count needs its own plural and a refusal can wrap a
+  # route: `computed` is for text put together like this, and its block runs
+  # only when the status or the language changes.
+  def describe(status)
+    i18n = RGame::Engine::I18n
+    return i18n.t('status.idle') unless status
+
+    cells, waypoints, arrived, refused = status
+    route = cells && i18n.t(arrived ? 'status.arrived' : 'status.walking',
+                            waypoints: i18n.t('status.waypoints', count: waypoints),
+                            cells: i18n.t('status.cells', count: cells))
+    return route unless refused
+
+    route ? i18n.t('status.refused_after', route: route) : i18n.t('status.refused')
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Pathfinding',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES
+)
+
+game.start

data/examples/pooling/locales/en.yml

@@ -0,0 +1,7 @@
+# The English table: every string this example draws.
+en:
+  status:
+    pooled: pooled — Space builds a fresh mote instead
+    fresh: fresh objects — Space goes back to the pool
+  hud:
+    allocated: "objects allocated per second: %{count}"

data/examples/pooling/main.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+# Pooling — spawning a lot of things without building any of them.
+#
+# Run it:
+#
+#   ruby examples/pooling/main.rb
+#
+# **Space** switches between taking motes from a pool and building a fresh one
+# every time. Watch the number. It exercises:
+#   - Components::Pool — acquire, add as a child, reclaim on free;
+#   - Engine::Pool — the free list underneath it;
+#   - Components::DespawnOffscreen — retiring a mote that has left the world;
+#   - Components::Timer — the spawn cadence, from `examples/timer`;
+#   - Engine::Text — a readout with a variable that changes once a second, not per frame.
+#
+# ## The number on screen is the whole argument
+#
+# Everything else here is prose. The readout samples
+# `GC.stat(:total_allocated_objects)` once a second and shows the difference, and
+# switching modes moves it within a second or two of the press. Measured over a
+# steady eighty motes a second:
+#
+#   pooled   about 140 objects a second
+#   fresh    about 750
+#
+# Same spawn rate, same motes on screen, same draw calls. The gap is around seven
+# and a half objects per mote — the node, its two components, and the few arrays
+# and hashes a node keeps for them — and it is *entirely* what the pool removes.
+#
+# A steady sixty-frame-per-second loop that allocates is a GC pause waiting to
+# happen, and a pause is not a slow frame: it is a visible hitch at a moment
+# nobody chose. Bullets and particles are where it starts, because they are the
+# things there are suddenly two hundred of.
+#
+# **The readout only means anything in a plain run.** Under
+# `tools/drive_test_project.rb` both numbers land near eighty-five thousand,
+# because the harness records every draw call it sees and that recording dwarfs
+# everything the game does. Measure the thing you changed, in the configuration
+# you care about.
+#
+# ## A game writes two lines and no bookkeeping
+#
+#     @pool.spawn { |mote| mote.reset(...) }   # acquire, initialise, add as a child
+#     mote.queue_free                          # → back on the free list
+#
+# There is no acquire/add/reclaim bridge to write, because
+# `Components::Pool#update` rides the tick and reclaims everything freed since
+# the last one. Nothing in this file asks for a mote back, and
+# `Components::DespawnOffscreen` — which knows nothing about pools — retires them
+# by calling the same `queue_free` any other node would.
+#
+# ## A pooled node is an ordinary child
+#
+# It is in the tree, the traversal updates and draws it, its components run. The
+# pool manages membership and nothing else. Pooling is not a parallel world with
+# its own rules — which is worth saying, because the one rule it *does* add is
+# easy to miss.
+#
+# ## The one rule: components go in `initialize`, not `on_add`
+#
+# `on_add` fires on **every** entry into the tree, and a pooled node enters it
+# again on each spawn. A component added there is added a second time, and
+# `add_component` refuses a slot that is already taken — so a pool that worked
+# for one lifetime raises on the next. Mote below adds its components in
+# `initialize`, where a node built by a factory outside the tree collects them
+# once.
+#
+# The mirror of that rule is what makes reuse safe: `Components::Timer` re-arms
+# itself in `on_attach`, and `Components::DespawnOffscreen` re-resolves its world
+# bounds there, so a recycled node inherits neither a spent countdown nor the
+# dimensions of the scene it came from.
+#
+# ## `reset` is the other half of a factory that builds blanks
+#
+# `Engine::Pool.new { Mote.new }` builds a blank, because it has no idea where the
+# next mote will be or where it is going. `spawn` takes a block and runs it
+# *before* the node enters the tree, which is where those answers get filled in.
+#
+# ## What it does not solve
+#
+# A cap. The pool grows to the high-water mark of how many are live at once and
+# never shrinks, which is the intent — the memory is the point of the exercise —
+# but a spawner that can outrun its despawn has no brake here.
+
+$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
+
+SPAWN_EVERY = 0.05 # seconds
+PER_BURST   = 4
+SPEED_MIN   = 70.0
+SPEED_MAX   = 210.0
+SAMPLE      = 1.0 # how often the allocation readout is taken
+DEFAULT_SEED = 0x9001
+
+# Far enough out that a mote is well off the screen before it is retired, so the
+# despawn is never something you can see happening.
+DESPAWN_MARGIN = 30.0
+
+# A blank when the factory builds it, a particular mote when `reset` is done with
+# it. Both of its components are added here rather than in `on_add`, because a
+# pooled node re-enters the tree on every spawn and `on_add` fires every time.
+class Mote < RGame::Engine::Node2D
+  SIZE = 7
+
+  def initialize
+    super(width: SIZE, height: SIZE)
+    @velocity = add_component(RGame::Engine::Components::Velocity.new)
+    add_component(RGame::Engine::Components::DespawnOffscreen.new(margin: DESPAWN_MARGIN))
+    @color = RGame::Util::Color.new(255, 255, 255)
+  end
+
+  # Run by the spawner before this node enters the tree, which is the seam a
+  # factory that builds blanks needs. Returns self so a fresh mote can be built
+  # and placed in one expression.
+  def reset(x, y, vx, vy, color)
+    self.x = x
+    self.y = y
+    @velocity.vx = vx
+    @velocity.vy = vy
+    @color = color
+    self
+  end
+
+  def on_draw(renderer, _view) = renderer.rect(-SIZE / 2, -SIZE / 2, SIZE, SIZE, color: @color)
+end
+
+# Emits motes on a cadence, either from a pool or by building each one, and the
+# only difference between the two paths is the line that gets the node.
+class Spawner < RGame::Engine::Node2D
+  POOLED = RGame::Util::Color.new(120, 210, 150)
+  FRESH  = RGame::Util::Color.new(235, 120, 100)
+
+  def initialize(rng:, **)
+    super(**)
+    @rng = rng
+    @pooled = true
+  end
+
+  def pooled? = @pooled
+  def toggle = @pooled = !@pooled
+  # Children, not `@pool.size`: both paths attach the mote as a child of this
+  # node, and only one of them involves a pool. Counting the pool would make the
+  # bar vanish in fresh mode and hide the thing being compared.
+  def live = children.size
+
+  def on_add
+    @pool = add_component(RGame::Engine::Components::Pool.new { Mote.new })
+    add_component(RGame::Engine::Components::Timer.new(SPAWN_EVERY))
+      .on_timeout { PER_BURST.times { emit } }
+  end
+
+  private
+
+  def emit
+    if @pooled
+      # Acquire, initialise, attach — one call, and the reclaim is already
+      # arranged for.
+      @pool.spawn { |mote| place(mote) }
+    else
+      # The same three steps written out, and a new object every single time.
+      # Nothing else about the mote or the frame differs.
+      add_node(place(Mote.new))
+    end
+  end
+
+  def place(mote)
+    angle = @rng.rand * Math::PI * 2
+    speed = SPEED_MIN + (@rng.rand * (SPEED_MAX - SPEED_MIN))
+    mote.reset(0, 0, Math.cos(angle) * speed, Math.sin(angle) * speed,
+               @pooled ? POOLED : FRESH)
+  end
+end
+
+# Samples the allocation counter once a second and shows the difference.
+#
+# A per-frame readout is the one thing a cached Text cannot help with — a value
+# that changes every frame has to be rebuilt every frame. Sampling on a slow
+# timer makes it a value that changes once a second, which is exactly what the
+# cache is for, and it is also the only way the number means anything: a single
+# frame's allocations are noise.
+class Meter < RGame::Engine::Node2D
+  INK = RGame::Util::Color.new(255, 255, 255)
+
+  def initialize(**)
+    super
+    @label = RGame::Engine::Text.new('hud.allocated', :count)
+    @count = 0
+    @last = 0
+  end
+
+  def on_add
+    @last = GC.stat(:total_allocated_objects)
+    add_component(RGame::Engine::Components::Timer.new(SAMPLE)).on_timeout { sample }
+  end
+
+  def on_draw(renderer, _view) = renderer.text(@label.with(count: @count), 0, 0, color: INK)
+
+  private
+
+  def sample
+    now = GC.stat(:total_allocated_objects)
+    @count = now - @last
+    @last = now
+  end
+end
+
+class Scene < RGame::Engine::Node2D
+  BACKDROP = RGame::Util::Color.new(26, 30, 38)
+  BAR = RGame::Util::Color.new(90, 100, 124)
+  BAR_X = 12
+  BAR_Y = 86
+  BAR_H = 14
+  BAR_SCALE = 2.4 # pixels per live mote
+
+  MODE = { true => RGame::Engine::Text.new('status.pooled'),
+           false => RGame::Engine::Text.new('status.fresh') }.freeze
+
+  def initialize
+    super
+    @rng = Random.new(ENV.fetch('RGAME_SEED', DEFAULT_SEED).to_i)
+    # Mounted outside the tree, so every DespawnOffscreen that attaches later
+    # finds it — the same ordering the wrap in `examples/velocity` depends on.
+    add_component(RGame::Engine::Components::World.new(width: WIDTH, height: HEIGHT))
+  end
+
+  def on_add
+    @spawner = add_node(Spawner.new(rng: @rng, x: WIDTH / 2, y: HEIGHT / 2))
+    @meter = add_node(Meter.new(x: 12, y: 34))
+  end
+
+  def on_control(actions)
+    @spawner.toggle if actions.pressed?(:fire)
+  end
+
+  def on_draw(renderer, view)
+    renderer.rect(0, 0, view.width, view.height, color: BACKDROP)
+    renderer.text(MODE.fetch(@spawner.pooled?), 12, 12)
+    # The live count as a bar rather than a number: it changes most frames, and
+    # a label rebuilt every frame is the allocation this example is about.
+    renderer.rect(BAR_X, BAR_Y, @spawner.live * BAR_SCALE, BAR_H, color: BAR)
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Pooling',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES
+)
+
+game.start

data/examples/quick_wheel/locales/en.yml

@@ -0,0 +1,16 @@
+# The English table: every string this example draws.
+en:
+  help:
+    wheel: Hold Tab (or LB), point with the arrows (or stick), let go to choose
+  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