rgame 0.2.0 → 0.3.1

data/examples/split_screen/main.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+# Split screen — two players, one world.
+#
+# Run it:
+#
+#   ruby examples/split_screen/main.rb
+#
+# Player one walks with the arrow keys or WASD. Press **A** on a controller and
+# player two joins: the screen splits, a second walker appears, and each half
+# follows its own player. Space (or A) waves, and only the waver's own badge
+# counts it. It exercises:
+#   - Game.new(players: 2) — two seats, the second of them empty at the start;
+#   - Engine::Players — who is playing, and the `on_joined` signal that says
+#     somebody now is;
+#   - Engine::WorldView — the world, drawn once per viewport through that
+#     viewport's camera;
+#   - Engine::PlayerLayer — one player's own corner of the screen;
+#   - Engine::Camera and Components::CameraFollow — one camera per player;
+#   - `input_owner` — which player a subtree answers to, inherited like a
+#     transform.
+#
+# ## The world does not know how many times it is drawn
+#
+# That is the sentence the whole design exists to make true, and this example is
+# the only place it can be shown rather than asserted. `Ground` draws the floor
+# once in its `on_draw`; with two players that method runs twice a frame, with
+# one it runs once, and nothing in it can tell. The walkers are the same: each is
+# a node in the world, so each is drawn in every viewport that can see it —
+# player two walks around inside player one's view, because there is one world
+# and two windows onto it.
+#
+# The update is not doubled. A frame is one `update(dt)` over the whole tree and
+# then one `draw` per viewport, so nothing moves twice when the screen splits.
+#
+# ## What a viewport cannot see, it does not draw
+#
+# The two walkers start side by side and each appears in both halves. Walk them
+# apart and each half is down to one sprite, because `AnimatedSprite` compares
+# the node's world box against the view's camera rectangle and skips the draw —
+# `Engine::Culling`, which split-screen is the reason for: with one viewport a
+# skipped draw saved a little, and with one per player it saves that much per
+# player.
+#
+# Only components that know a node's footprint cull. The banner `Walker` draws
+# itself is not culled, just clipped away with the rest of what is outside the
+# region — at one rectangle a check would cost more than the draw, and that is
+# the trade rather than an oversight.
+#
+# ## Three kinds of content, and a node's place decides which it is
+#
+# A frame here holds all three, and no node is told which it is in:
+#
+#   - **world content** — under the `WorldView`, drawn once per viewport, through
+#     that viewport's camera, so its coordinates are places in the world;
+#   - **a player's own screen space** — under a `PlayerLayer`, drawn once for that
+#     player, clipped to their region and laid out from *its* corner, so a badge
+#     at (16, 16) is sixteen pixels inside whichever half they were given;
+#   - **a global overlay** — a plain child of the scene, like the two lines of
+#     instructions at the bottom. Drawn once across the whole window whatever the
+#     split is doing.
+#
+# ## The screen splits when somebody joins, not when a pad is plugged in
+#
+# The game opens with two seats and one player. The second seat is empty, so
+# there is one viewport and it is the whole window — an ordinary single-player
+# game, which is what a two-player game should look like until the second player
+# turns up.
+#
+# A device is seated when somebody *uses* it. Pressing A on an unassigned
+# controller fills the empty seat, `Players#on_joined` fires with the player who
+# got it, and this scene spawns their walker and their badge in the handler. The
+# split follows from there: `Viewports` gives a region to each active player, and
+# one more active player is one more region. Nothing here counts anything or
+# asks how the screen is divided.
+#
+# ## Ownership is inherited, so neither subtree mentions players
+#
+# `walker.input_owner = player` is the only line about ownership in this file,
+# and `PlayerLayer` sets the same thing for its subtree. Everything below either
+# one reads that player's device: `PlayerController` moves the right walker,
+# `Badge#on_control` counts the right waves, and neither class names a player or
+# knows that there is more than one.
+#
+# That is what keeps a HUD written for one player working for two. The badge
+# under player two's layer is the same class, with nothing configured, drawn in
+# their half because their layer is where it hangs.
+#
+# ## What it does not solve
+#
+# Anything about the world itself — there is a floor, some landmarks and two
+# walkers, and they pass through each other. Every other example puts its subject
+# in the world; this one's subject is the plumbing around it, and a busier world
+# would only hide the thing being shown.
+#
+# `Ground` also draws the whole floor every time, which is thirty-eight
+# rectangles and not worth thinking about. A world big enough for that to matter
+# draws what the `view` it is handed can actually show — the same camera
+# rectangle the sprites are culled against.
+
+$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
+
+# Bigger than the window on both axes, so a camera has somewhere to go and the
+# two halves can be looking at genuinely different places.
+WORLD_W = 1280
+WORLD_H = 960
+
+SPEED = 120.0
+
+# Where the camera looks: the middle of the 16x22 sprite rather than its
+# top-left origin.
+CAMERA_OFFSET_X = 8
+CAMERA_OFFSET_Y = 11
+
+# One player, one colour. Their walker carries it as a banner and their badge
+# prints their name in it, which is the only way to tell two halves apart at a
+# glance.
+TINTS = [RGame::Util::Color.new(255, 190, 90), RGame::Util::Color.new(120, 200, 255)].freeze
+
+# Where each player's walker starts: side by side, so each of them is in the
+# other's half of the screen until the two of them walk apart.
+STARTS = [[520.0, 460.0], [700.0, 500.0]].freeze
+
+# The world: a floor, a grid to make movement visible, and landmarks to tell one
+# part of it from another. It is a single node under the WorldView, so this
+# `on_draw` runs once per viewport and knows nothing about that.
+class Ground < RGame::Engine::Node2D
+  FLOOR = RGame::Util::Color.new(38, 54, 44)
+  GRID  = RGame::Util::Color.new(50, 70, 58)
+  CELL  = 64
+
+  # x, y and a colour: four blocks in four quarters of the world, so which half
+  # of the screen is looking where is obvious.
+  LANDMARKS = [
+    [200, 200, RGame::Util::Color.new(196, 92, 72)],
+    [980, 240, RGame::Util::Color.new(92, 148, 196)],
+    [260, 700, RGame::Util::Color.new(214, 196, 96)],
+    [1000, 740, RGame::Util::Color.new(140, 110, 196)]
+  ].freeze
+  BLOCK = 64
+
+  def on_draw(renderer, _view)
+    renderer.rect(0, 0, WORLD_W, WORLD_H, color: FLOOR)
+    draw_grid(renderer)
+    LANDMARKS.each { |x, y, color| renderer.rect(x, y, BLOCK, BLOCK, color: color) }
+  end
+
+  private
+
+  # While loops rather than ranges: this runs once per viewport per frame, and a
+  # fresh Range every time is the allocation the hot-path cops refuse.
+  #
+  # hot-path
+  def draw_grid(renderer)
+    x = CELL
+    while x < WORLD_W
+      renderer.rect(x, 0, 1, WORLD_H, color: GRID)
+      x += CELL
+    end
+
+    y = CELL
+    while y < WORLD_H
+      renderer.rect(0, y, WORLD_W, 1, color: GRID)
+      y += CELL
+    end
+  end
+end
+
+# A player's avatar: `examples/walk`'s hero with a camera on it and a banner in
+# their colour. Nothing in it refers to a player — the scene sets `input_owner`
+# once, and the controller below reads whatever that resolves to.
+class Walker < RGame::Engine::Node2D
+  BANNER_H = 4
+
+  def initialize(tint:, camera:, **)
+    super(**)
+    @tint = tint
+    add_component(RGame::Engine::Components::AnimatedSprite.new(sheet: 'hero.json'))
+    add_component(RGame::Engine::Components::CharacterBody.new(speed: SPEED))
+    add_component(RGame::Engine::Components::PlayerController.new)
+    add_component(RGame::Engine::Components::CameraFollow.new(
+                    camera: camera, offset_x: CAMERA_OFFSET_X, offset_y: CAMERA_OFFSET_Y
+                  ))
+  end
+
+  # Keep them on the floor. A plain CharacterBody walks wherever the intent
+  # points; the cameras stop at the world's edges on their own, and a walker that
+  # kept going would leave its half of the screen showing a player pushing a key
+  # with nothing happening.
+  def on_update(_dt)
+    self.x = x.clamp(0, WORLD_W - width)
+    self.y = y.clamp(0, WORLD_H - height)
+  end
+
+  def on_draw(renderer, _view) = renderer.rect(0, -BANNER_H - 2, width, BANNER_H, color: @tint)
+end
+
+# One player's badge, in their own corner of the screen.
+#
+# Written as though there were one player, because from in here there is. It
+# hangs under a PlayerLayer, so it is drawn inside that player's region, laid out
+# from that region's corner, and `on_control` is handed that player's actions.
+class Badge < RGame::Engine::Node2D
+  PANEL = RGame::Util::Color.new(20, 26, 34, 190)
+  INK   = RGame::Util::Color.new(226, 230, 238)
+  W = 108
+  H = 46
+
+  def initialize(number:, tint:, **)
+    super(**)
+    @name = RGame::Engine::Text.new('hud.player', :number)
+    @name.with(number: number)
+    @tint = tint
+    @waves = 0
+    @label = RGame::Engine::Text.new('hud.waves', :count)
+  end
+
+  def on_control(actions)
+    @waves += 1 if actions.pressed?(:fire)
+  end
+
+  def on_draw(renderer, _view)
+    renderer.rect(0, 0, W, H, color: PANEL)
+    renderer.rect(0, 0, W, 3, color: @tint)
+    renderer.text(@name, 8, 8, color: @tint)
+    renderer.text(@label.with(count: @waves), 8, 26, color: INK)
+  end
+end
+
+class Scene < RGame::Engine::Node2D
+  MARGIN = 16
+
+  def initialize
+    super
+    @help_keys = RGame::Engine::Text.new('help.keys')
+    @help_join = RGame::Engine::Text.new('help.join')
+  end
+
+  def on_add
+    @players = root.system(RGame::Engine::Players)
+    # Every camera, including the empty seat's: a camera that does not know how
+    # big the world is will happily show the void past its edge, and the seat is
+    # filled later by somebody who should not have to remember this.
+    @players.each { |player| bound(player.camera) }
+
+    # World space begins here. Everything under it is drawn once per viewport,
+    # through that viewport's camera.
+    @view = add_node(RGame::Engine::WorldView.new)
+    @view.add_node(Ground.new)
+
+    # One walker and one badge per player who is already playing, and one more
+    # when somebody joins. The scene never asks whether anybody has — the
+    # registry tells it.
+    @players.each_active { |player| spawn(player) }
+    @players.on_joined { |player| spawn(player) }
+  end
+
+  # A plain child of the scene, so this is the global overlay: once across the
+  # whole window, wherever the split is.
+  def on_draw(renderer, view)
+    renderer.text(@help_keys, MARGIN, view.height - 52)
+    renderer.text(@help_join, MARGIN, view.height - 30)
+  end
+
+  private
+
+  def bound(camera)
+    camera.world_width = WORLD_W
+    camera.world_height = WORLD_H
+  end
+
+  def spawn(player)
+    x, y = STARTS[player.id]
+    walker = Walker.new(x: x, y: y, tint: TINTS[player.id], camera: player.camera)
+    # The only line in this file about who owns what. It is inherited by the
+    # whole subtree, which is why nothing under it needs telling.
+    walker.input_owner = player
+    @view.add_node(walker)
+
+    layer = add_node(RGame::Engine::PlayerLayer.new(player: player))
+    layer.add_node(Badge.new(number: player.id + 1, tint: TINTS[player.id],
+                             x: MARGIN, y: MARGIN))
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Split screen',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES,
+  # Two seats. The second stays empty until somebody picks up a controller and
+  # presses confirm, and until then this is an ordinary one-player game.
+  players: 2
+)
+
+game.start

data/examples/sprite/locales/en.yml

@@ -0,0 +1,8 @@
+# The English table: every string this example draws.
+en:
+  help:
+    keys: Left / right turn it — up / down resize it
+  captions:
+    whole: "hero.png whole: a String id is a path"
+    frame: one registered frame — the node holds the angle and the scale
+    above: the sprite asks for a z above the panel its own node draws

data/examples/sprite/main.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+# Sprite — one frame, drawn at a node, with no animation behind it.
+#
+# Run it:
+#
+#   ruby examples/sprite/main.rb
+#
+# Left and right turn the middle sprite; up and down resize it. It exercises:
+#   - Components::Sprite — a picture drawn at the node it is attached to;
+#   - Image#subimage — one cell of a sheet, as a view costing no second decode;
+#   - renderer.register_image — binding a Symbol to an image the game chose;
+#   - the two id spaces, a String path and a registered Symbol, in one file.
+#
+# ## Most things in a game are this
+#
+# `examples/walk` uses Components::AnimatedSprite, which carries an AnimationSet,
+# a current animation name and an elapsed time. Take all of that away and what is
+# left is this: a picture, at a node. A crate, a pickup, a rock and a tree want
+# exactly that and nothing more.
+#
+# ## It passes no position and no angle, and that is the whole trick
+#
+# The component's draw is one line, and both coordinates in it are zero:
+#
+#     renderer.image(@id, 0, 0, scale: @scale, z: @layer)
+#
+# `Node2D#draw` has already pushed this node's transform onto the renderer, so
+# drawing at the origin *is* drawing at the node, turned by however much the node
+# is turned. Hold left and watch: nothing inside Components::Sprite knows that an
+# angle exists, and the sprite turns anyway.
+#
+# Writing `node.x` there would apply the position a second time, which is what
+# `Game/DrawInLocalSpace` refuses — `world_x` included, and for the same reason.
+#
+# ## Two numbers called z, and the bottom row separates them
+#
+# A **node's** `z` orders it against its siblings: which of two nodes is drawn
+# first. A **component's** `z:` is an offset inside that one node's own slot, so
+# it can only ever settle the order of what a single node draws — against its own
+# other components, and against its own `on_draw`. It cannot reach the next node.
+#
+# The bottom node draws a panel from `on_draw` and hangs a sprite on itself, and
+# they land in one slot together. The default offsets are not equal: a shape is
+# drawn at 50 and an image at 0, so the panel covers the sprite unless the sprite
+# asks for more. `z: ABOVE_PANEL` is that ask, and the node did not move.
+#
+# ## What this does not show
+#
+# Culling, though Components::Sprite does it. It skips a draw whose footprint is
+# outside the view — but this scene is screen space with everything well inside
+# the window, so the check answers "draw" every frame. `examples/scroll_map` has
+# the camera that makes the other answer visible.
+
+$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
+
+SHEET = 'hero.png'
+# The grid examples/assets/hero.json describes, which is what makes cell (0, 0)
+# the standing frame. Written out rather than parsed: this example is about the
+# image, and reading the descriptor would be borrowing AnimatedSprite's job.
+FRAME_W = 16
+FRAME_H = 22
+
+STILL = :hero_still # the Symbol the frame is registered under, below
+
+TURN_SPEED = 120.0 # degrees per second
+GROW_SPEED = 3.0   # scale steps per second
+MIN_SCALE  = 1.0
+MAX_SCALE  = 9.0
+START_SCALE = 4.0
+
+# The one you can play with. It holds an angle and a scale, and hands neither to
+# the renderer — the component draws at the origin and the transform does the
+# rest.
+class Turntable < RGame::Engine::Node2D
+  def initialize(**)
+    super(width: FRAME_W, height: FRAME_H, **)
+    @turn = 0.0
+    @resize = 0.0
+  end
+
+  def on_add
+    @sprite = add_component(RGame::Engine::Components::Sprite.new(id: STILL, scale: START_SCALE))
+  end
+
+  # Axes, not buttons: `move_x` and `move_y` come from the default map already
+  # bound to the arrows, WASD and a left stick, so this example declares no input
+  # of its own. Screen y grows downward, so up reads negative and is subtracted.
+  def on_control(actions)
+    @turn = actions.axis(:move_x)
+    @resize = actions.axis(:move_y)
+  end
+
+  def on_update(dt)
+    self.angle += @turn * TURN_SPEED * dt
+    @sprite.scale = (@sprite.scale - (@resize * GROW_SPEED * dt)).clamp(MIN_SCALE, MAX_SCALE)
+  end
+end
+
+# The bottom row: one node, two things drawn, and a z that decides which wins.
+class Layered < RGame::Engine::Node2D
+  PANEL = RGame::Util::Color.new(196, 92, 64)
+  PANEL_W = 132
+  PANEL_H = 78
+  SCALE = 3.0
+  # Above the 50 a shape is drawn at, inside this node's slot. Drop it to 0 and
+  # the sprite disappears behind the panel; nothing else about the frame changes.
+  ABOVE_PANEL = 60
+
+  def initialize(**)
+    super(width: FRAME_W, height: FRAME_H, **)
+  end
+
+  def on_add
+    add_component(RGame::Engine::Components::Sprite.new(id: STILL, scale: SCALE, z: ABOVE_PANEL))
+  end
+
+  # Centred on this node's own origin, which is where the traversal has already
+  # put the renderer — the same reason the component draws at (0, 0).
+  def on_draw(renderer, _view)
+    renderer.rect(-PANEL_W / 2, -PANEL_H / 2, PANEL_W, PANEL_H, color: PANEL)
+  end
+end
+
+class Scene < RGame::Engine::Node2D
+  BACKDROP = RGame::Util::Color.new(38, 42, 52)
+  SHEET_X = 24
+  SHEET_Y = 60
+
+  def initialize
+    super
+    @help = RGame::Engine::Text.new('help.keys')
+    @whole = RGame::Engine::Text.new('captions.whole')
+    @frame = RGame::Engine::Text.new('captions.frame')
+    @above = RGame::Engine::Text.new('captions.above')
+  end
+
+  def on_add
+    add_node(Turntable.new(x: WIDTH / 2, y: 230))
+    add_node(Layered.new(x: WIDTH / 2, y: 400))
+  end
+
+  def on_draw(renderer, view)
+    renderer.rect(0, 0, view.width, view.height, color: BACKDROP)
+
+    # A String is a path, resolved through the asset manager on first use and
+    # remembered. Drawn at its natural size, so this is the file itself — six
+    # columns of walk frames over three rows, and the frame below is the first
+    # cell of it.
+    renderer.image_at(SHEET, SHEET_X, SHEET_Y)
+
+    renderer.text(@help, 12, 12)
+    renderer.text(@whole, SHEET_X, SHEET_Y - 18)
+    renderer.text(@frame, SHEET_X, 170)
+    renderer.text(@above, SHEET_X, 330)
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Sprite',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES
+)
+
+# The other id space. A Symbol is a name this game chose, so nothing can resolve
+# it and it has to be bound — and what it is bound to here is not a file at all
+# but a *view* into one. `subimage` shares the uploaded texture rather than
+# decoding the PNG again, so slicing a sheet into frames costs nothing.
+game.renderer.register_image(STILL, game.assets.image(SHEET).subimage(0, 0, FRAME_W, FRAME_H))
+
+game.start

data/examples/timer/locales/en.yml

@@ -0,0 +1,12 @@
+# The English table: every string this example draws.
+en:
+  help:
+    beat: Both bars beat every 0.07s. One of them is right
+  captions:
+    timer: Components::Timer — the remainder carries forward
+    naive: "@elapsed = 0.0 — the overshoot is thrown away"
+    mark: the white mark is where this bar was when the other finished
+    blink: The square blinks on a second, slower timer on the same node
+    fuse: Space sets off a one-shot
+  fuse:
+    banner: one-shot — this removes itself