rgame 0.2.0 → 0.3.1

data/examples/assets/icons.json

@@ -0,0 +1,13 @@
+{
+  "image": "icons.png",
+  "images": {
+    "home":      { "x":   0, "y": 0, "w": 50, "h": 50 },
+    "gear":      { "x":  50, "y": 0, "w": 50, "h": 50 },
+    "save":      { "x": 100, "y": 0, "w": 50, "h": 50 },
+    "star":      { "x": 150, "y": 0, "w": 50, "h": 50 },
+    "trophy":    { "x": 200, "y": 0, "w": 50, "h": 50 },
+    "audio_on":  { "x": 250, "y": 0, "w": 50, "h": 50 },
+    "music_on":  { "x": 300, "y": 0, "w": 50, "h": 50 },
+    "locked":    { "x": 350, "y": 0, "w": 50, "h": 50 }
+  }
+}

data/examples/assets/skills.json

@@ -0,0 +1,10 @@
+{
+  "image": "skills.png",
+  "images": {
+    "wand":         { "x":   0, "y": 0, "w": 64, "h": 64 },
+    "wrench":       { "x":  64, "y": 0, "w": 64, "h": 64 },
+    "torch":        { "x": 128, "y": 0, "w": 64, "h": 64 },
+    "hammer":       { "x": 192, "y": 0, "w": 64, "h": 64 },
+    "watering_can": { "x": 256, "y": 0, "w": 64, "h": 64 }
+  }
+}

data/examples/assets/tileset.tsx

@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Kenney "Tiny Town" (CC0) sliced as a Tiled tileset. See README.md.
+
+     A tile is solid to RGame::Engine::Tileset because it carries a collision
+     shape here — an <objectgroup> with at least one object — not because of
+     anything in code. The trees and fences below are the obstacles the examples
+     use; every other tile is walkable. -->
+<tileset version="1.10" tiledversion="1.10.2" name="tiny_town" tilewidth="16" tileheight="16" tilecount="132" columns="12">
+ <image source="tileset.png" width="192" height="176"/>
+ <tile id="3">
+  <objectgroup draworder="index">
+   <object id="1" x="0" y="0" width="16" height="16"/>
+  </objectgroup>
+ </tile>
+ <tile id="4">
+  <objectgroup draworder="index">
+   <object id="1" x="0" y="0" width="16" height="16"/>
+  </objectgroup>
+ </tile>
+ <tile id="5">
+  <objectgroup draworder="index">
+   <object id="1" x="0" y="0" width="16" height="16"/>
+  </objectgroup>
+ </tile>
+ <tile id="15">
+  <objectgroup draworder="index">
+   <object id="1" x="0" y="0" width="16" height="16"/>
+  </objectgroup>
+ </tile>
+ <tile id="16">
+  <objectgroup draworder="index">
+   <object id="1" x="0" y="0" width="16" height="16"/>
+  </objectgroup>
+ </tile>
+ <tile id="27">
+  <objectgroup draworder="index">
+   <object id="1" x="0" y="0" width="16" height="16"/>
+  </objectgroup>
+ </tile>
+ <tile id="28">
+  <objectgroup draworder="index">
+   <object id="1" x="0" y="0" width="16" height="16"/>
+  </objectgroup>
+ </tile>
+ <tile id="44">
+  <objectgroup draworder="index">
+   <object id="1" x="0" y="0" width="16" height="16"/>
+  </objectgroup>
+ </tile>
+ <tile id="45">
+  <objectgroup draworder="index">
+   <object id="1" x="0" y="0" width="16" height="16"/>
+  </objectgroup>
+ </tile>
+ <tile id="46">
+  <objectgroup draworder="index">
+   <object id="1" x="0" y="0" width="16" height="16"/>
+  </objectgroup>
+ </tile>
+ <tile id="47">
+  <objectgroup draworder="index">
+   <object id="1" x="0" y="0" width="16" height="16"/>
+  </objectgroup>
+ </tile>
+</tileset>

data/examples/assets/town.tmx

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Authored for the examples; edit it in Tiled. See README.md.
+
+     60x40 tiles at 16px = 960x640 pixels, larger than the 640x480 window on
+     both axes so the camera has somewhere to scroll. Two layers: the ground is
+     entirely walkable, and everything solid lives in "obstacles" - a tree
+     border, a fence right across the middle, and scattered trees.
+
+     The fence has exactly one gap, at x=12..14, and it is deliberately far
+     west of both clearings. A gap sitting between them would be no obstacle at
+     all: the shortest route through it would cost exactly the straight-line
+     distance, and a pathfinder would have nothing to show. Placed out here, a
+     walker starting in the north clearing has to head away from the south one
+     to get through - a route you can watch being taken. The fence runs the full
+     interior width for the same reason: stopping it a tile short of the border
+     leaves a second gap nobody planned, and the route quietly uses that
+     instead. -->
+<map version="1.10" tiledversion="1.10.2" orientation="orthogonal" renderorder="right-down" width="60" height="40" tilewidth="16" tileheight="16" infinite="0" nextlayerid="3" nextobjectid="1">
+ <tileset firstgid="1" source="tileset.tsx"/>
+ <layer id="1" name="ground" width="60" height="40">
+  <data encoding="base64" compression="zlib">eJztWU1vwzAIzexzt3O7czdNyv//fU0PlqwM8/EAJ5t6eFIbJ5gHGGNclmV5Y1CIZ6vwjQaU3Jokl3qmBaXTyoxpwdmwjXn0fgGLg9E7lRkrDtmF+Z6bcx8viN57GVabcfF/2fAO4EOpr1aPWbhuuAH4TNInK283W0fzPSLXVcP8mf7N4u6R6+UbEWvZHGf5F9VTY8MCzpG1fnsdpLys3TettqTGI/hWwid18Dubj4T7hi8A34QsjrMXlhyM2jRrL7TKzOKXFXdRep/hHOOpz/v/Px3655wPPHaOsB13Nmjjo3dGfDm9VuV7lDxtLGfFVM+XyyGe+bm1O/ssM/LvX4WU91G+M/apjDkovmfIx1mIimdN7WqV9/xGqhGs4/9t/SL+1dZynE/X5XevLGIv0vbfrPpK83LjSJ1K5VXN2VPq82flVUkHT3/Sq+/IJl5bUH5ttZ3n/JtVk2TJ9fJFfWj1XWS9P6Nfx9XAkXdsfX4ZyT0inr35Sbpj4XxwxvU7sgvFw9pviV6/1rpK+h8dG0feH6F38Uj90ezo6U/u90qvniiQHqLmm6N7ICg3DaJykaYGReKaGkd7PxFcuT0jIs9KXK2cZ8VDlD57e0XJ1fJ6AGJxLzQ=</data>
+ </layer>
+ <layer id="2" name="obstacles" width="60" height="40">
+  <data encoding="base64" compression="zlib">eJztmU0OAiEMhdnofg7gEdT7385xQVIJP4X2wZvgl5DZOGD7WiidI4RwO8ex0XMXos278Ah1fe/KOXrfXxVXUt+abTWbWjDFT0lfja5XhDF/kb5u5a830pbV+YuanwmEvmw2SqS+KJ1lDFv2eQ9SfVt7xehe0vLlDF9/8crflm6rdY2g92e2s857f/bUERF3JX2tazHomrMr1ddiu0f9jfC9XL9WP/fGpsUmy3w9v7fmr1wjnccyb+2MtNTXs+vn1UR9n+d4KYdE+w7DeAc/fa9yX2a8/0ZG/pemztsxf5lA6RqfnvquugflyPlAo++M+ysqp7T1c0rJJ4h+FPLuyJi/SKS+I98JUnK+Y9r/U31z8R7xjAPp45m1isf3oxFW5dCs/hULyPqK0QdafUd9wta3RPWvWPmfv796e/ZoJJ49mh521Xen5wfjJRxI</data>
+ </layer>
+</map>

data/examples/assets/ui.json

@@ -0,0 +1,11 @@
+{
+  "image": "ui.png",
+  "scale": 1,
+  "nine_slices": {
+    "panel":           { "x": 0,   "y": 0, "w": 32, "h": 32, "border": 8 },
+    "button_idle":     { "x": 32,  "y": 0, "w": 32, "h": 32, "border": 8 },
+    "button_focus":    { "x": 64,  "y": 0, "w": 32, "h": 32, "border": 8 },
+    "button_pressed":  { "x": 96,  "y": 0, "w": 32, "h": 32, "border": 8 },
+    "button_disabled": { "x": 128, "y": 0, "w": 32, "h": 32, "border": 8 }
+  }
+}

data/examples/collision/locales/en.yml

@@ -0,0 +1,8 @@
+# The English table: every string this example draws.
+en:
+  help:
+    walk: Arrows / WASD walk the pale circle — the other two need nobody
+    crate: "Enter a crate: it blinks once and counts you, you stay lit inside"
+    circles: Circle into circle does nothing — same layer, one line ignoring it
+  hud:
+    visits: "visits: %{count}"

data/examples/collision/main.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+# Collision — two shapes touching.
+#
+# Run it:
+#
+#   ruby examples/collision/main.rb
+#
+# Arrow keys or WASD walk the pale circle. The other circles need nobody. Drive
+# into a crate and both of you light up; drive into another circle and neither
+# of you does. It exercises:
+#   - Components::CollisionWorld — the scene-scoped system that pairs shapes up
+#     each step and tells them when they start and stop overlapping;
+#   - Components::CircleCollider — a round shape on a node;
+#   - Components::BoxCollider — the rectangular one, and the two mix freely;
+#   - Components::Velocity — from `examples/velocity`, so that things move into
+#     each other without anybody pressing a key;
+#   - Engine::Text — a crate's counter, a key with a variable, rendered again
+#     only on a contact.
+#
+# The pale circle stays lit for as long as it is inside a crate, and the crate
+# blinks once and adds one to its counter. Two readings of the same pair of
+# signals: one brackets a contact, the other marks the moment it began.
+#
+# ## The system is on the scene, the shapes are on the nodes
+#
+# `CollisionWorld` is a component mounted on the scene node, so it is born with
+# the scene and torn down with it, and it rides the ordinary update traversal
+# rather than needing a step of its own. The shapes are components on the things
+# that have shapes.
+#
+# Nothing connects the two by hand. A collider registers with
+# `node.system(CollisionWorld)` when its node enters the tree and unregisters
+# when it leaves, and the engine fires both hooks — so a spawned or despawned
+# entity cannot leak a registration, and no game code is asked to remember.
+#
+# That is also why every component here is added in `initialize` rather than in
+# `on_add`: a node assembled outside the tree collects all of its components
+# before any of them attaches, so the order they go on in never matters.
+#
+# ## A contact is reported to both sides, and neither is asked what it means
+#
+# Each step, the system buckets every collider, finds the overlapping pairs, and
+# tells both colliders of each pair about the other. It stops there. It does not
+# know what a crate is, and it never looks at `layer`.
+#
+# `layer` is an opaque tag, and the whole of the rule in this example is one
+# line in `Mover`:
+#
+#     collider.on_hit { |other| @touching += 1 unless other.layer == :mover }
+#
+# The two circles that drift through each other *are* reported, and that line is
+# what makes it look like nothing happened. Pushing the test up into the system
+# would mean the system deciding that same-layer things never interact — which is
+# wrong the moment one kind of thing has to hurt another of its own kind.
+#
+# ## A contact is two edges, not a state
+#
+# `on_hit` fires on the step a pair starts overlapping. `on_separated` fires on
+# the step it stops. Nothing fires on the steps in between, however long the two
+# sit inside each other, and a pair is reported once however many broadphase
+# cells it happens to span.
+#
+# That is what lets a handler do something that must happen exactly once —
+# `@score += 100`, play a sound, spend a life — with nothing to remember and
+# nothing to guard. `Crate` below counts arrivals in one line because of it.
+#
+# The two signals also come in balanced pairs, which is the other thing to see on
+# screen. `Mover` keeps a count: up on `on_hit`, down on `on_separated`, lit
+# while it is above zero. That count is right no matter how many crates the
+# circle is inside at once, because the edges are **per pair** — a second crate
+# is a second `on_hit`, not a louder version of the first.
+#
+# A contact also ends when the other side is destroyed or leaves the tree, and
+# `on_separated` fires then too. Nothing here dies, but a shooter whose bullets
+# vanish on impact depends on it: without it a ship could stay "in contact" with
+# a rock that no longer exists.
+#
+# ## A box and a circle collide with each other
+#
+# `CircleCollider` and `BoxCollider` are not two separate worlds. Both answer the
+# same broadphase question (the bounding box to bucket me in) and the same
+# narrowphase one (`overlap?`), and the pair settles the actual test between
+# themselves by handing each other their numbers. So one world holds both, and
+# every circle here collides with every crate.
+#
+# ## An AABB does not turn with its node
+#
+# The drifting circles spin — the spoke is drawn so you can see it — and their
+# collision shape is unaffected, because a circle is the same circle at every
+# angle. The crates carry an axis-aligned box and do not spin, and that is a
+# choice rather than a preference: a box that turned with its node would have to
+# be recomputed into a wider box every frame, and the wider box is wrong in a
+# different way. A thing that spins wants a circle.
+#
+# ## `cell_size` is the one number this system asks a game to pick
+#
+# The broadphase is a spatial hash: a lattice of square cells, each collider
+# dropped into the cells its bounding box covers, and only colliders sharing a
+# cell ever tested against each other. The faint grid on the backdrop is drawn at
+# that size, so the number is visible rather than a constant at the top of a
+# file.
+#
+# Pick it at about the size of the things being bucketed. Much smaller and one
+# collider spans a block of cells and is tested from every one of them; much
+# larger and everything lands in the same cell and the hash has quietly become
+# the loop over all pairs it exists to avoid.
+#
+# ## What it does not solve
+#
+# Response. Nothing here is pushed out of anything: a contact is a notification,
+# and these shapes overlap and carry on. Stopping a body at a wall is a different
+# problem with different machinery, and `examples/collision_tiles` is where it
+# lives.
+
+$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 broadphase cell, and the grid drawn on the backdrop. Everything bucketed
+# here is 32 to 96 pixels across, so the cell is one of those.
+CELL_SIZE = 64
+
+WALK_SPEED = 150.0
+
+# How long a crate stays lit after a circle arrives. Long enough to see at a
+# glance, short enough that two arrivals read as two.
+FLASH_TIME = 0.3
+
+# A round thing that lights up while it is inside a crate. Its two subclasses
+# differ only in what moves them — the shape, the layer and the rule are the same
+# for both.
+#
+# `@touching` is the balanced pair of edges, kept as a count rather than a flag
+# because a circle can be inside two crates at once: the two in the middle of the
+# field overlap, and driving into the pair is two `on_hit` calls before either
+# `on_separated` arrives. A flag would go dark on leaving the first of them.
+class Mover < RGame::Engine::Node2D
+  RADIUS = 16
+  BODY  = RGame::Util::Color.new(236, 233, 220)
+  HIT   = RGame::Util::Color.new(255, 214, 92)
+  SPOKE = RGame::Util::Color.new(60, 66, 82)
+
+  def initialize(**)
+    super(width: RADIUS * 2, height: RADIUS * 2, **)
+    @touching = 0
+    collider = add_component(RGame::Engine::Components::CircleCollider.new(radius: RADIUS, layer: :mover))
+    # Both edges are reported to both colliders, each handed the other, so this is
+    # written entirely from this node's side. The guard is the example's subject:
+    # same-layer pairs are reported and these lines drop them. It has to be the
+    # same guard on both, or the count would not come back to zero.
+    collider.on_hit { |other| @touching += 1 unless other.layer == :mover }
+    collider.on_separated { |other| @touching -= 1 unless other.layer == :mover }
+  end
+
+  # The centre is where the traversal has already put the renderer, and the
+  # circle's collision centre is the node's origin — the same point.
+  def on_draw(renderer, _view)
+    renderer.circle(0, 0, RADIUS, color: @touching.positive? ? HIT : BODY)
+    # Drawn at the node's own angle, which is what makes the spin visible at all:
+    # a spinning circle looks like a still one without a mark on it.
+    renderer.line(0, 0, RADIUS, 0, thickness: 3, color: SPOKE)
+  end
+end
+
+# Moves because it was given a velocity, and for no other reason.
+class Drifter < Mover
+  def initialize(vx:, vy:, spin: 0.0, **)
+    super(**)
+    add_component(RGame::Engine::Components::Velocity.new(vx: vx, vy: vy, spin: spin))
+    add_component(RGame::Engine::Components::ScreenWrap.new(margin: RADIUS))
+  end
+end
+
+# The one with a hand on it. Same shape, same layer, same rule.
+class Walker < Mover
+  def initialize(**)
+    super
+    add_component(RGame::Engine::Components::CharacterBody.new(speed: WALK_SPEED))
+    add_component(RGame::Engine::Components::PlayerController.new)
+    add_component(RGame::Engine::Components::ScreenWrap.new(margin: RADIUS))
+  end
+end
+
+# A rectangle that never moves and counts the circles that have arrived.
+#
+# Two of them overlap on purpose, in the middle of the field. That pair is in
+# contact from the first step to the last, the system reports it exactly once,
+# and neither counter moves — which is the same one-line rule `Mover` uses, seen
+# from the other side.
+#
+# A visit is one circle arriving, and it is counted by adding one in the handler,
+# because `on_hit` is the arrival rather than the overlap. Two circles standing
+# in this crate at once is two visits: the edges are per pair, so each of them
+# announced itself.
+class Crate < RGame::Engine::Node2D
+  BODY = RGame::Util::Color.new(88, 104, 136)
+  HIT  = RGame::Util::Color.new(150, 196, 255)
+  INK  = RGame::Util::Color.new(180, 190, 210)
+
+  def initialize(width:, height:, **)
+    super
+    @flash = 0.0
+    @touches = 0
+    @label = RGame::Engine::Text.new('hud.visits', :count)
+    # The box is offset to sit around the node's origin, which is where a circle's
+    # centre already is — so both shapes here are drawn and collide about the
+    # same point. A sprite that wants a small box at its feet moves the offset
+    # instead; nothing says the box has to be centred.
+    collider = add_component(RGame::Engine::Components::BoxCollider.new(
+                               width: width, height: height,
+                               offset_x: -width / 2, offset_y: -height / 2, layer: :wall
+                             ))
+    collider.on_hit do |other|
+      next if other.layer == :wall
+
+      @touches += 1
+      @flash = FLASH_TIME
+    end
+  end
+
+  # Only the flash, which is a cosmetic timer and the one thing here that has to
+  # be advanced rather than announced. The counter is not touched: it moves on the
+  # edge, in the handler above.
+  def on_update(dt) = @flash -= dt
+
+  def on_draw(renderer, _view)
+    renderer.rect(-width / 2, -height / 2, width, height, color: @flash.positive? ? HIT : BODY)
+    renderer.text(@label.with(count: @touches), -width / 2, (-height / 2) - 22, color: INK)
+  end
+end
+
+class Scene < RGame::Engine::Node2D
+  BACKDROP = RGame::Util::Color.new(26, 30, 38)
+  GRID     = RGame::Util::Color.new(38, 44, 56)
+
+  # Centre x, centre y, width, height. The first two overlap.
+  CRATES = [
+    [300, 200, 96, 40],
+    [336, 244, 40, 96],
+    [520, 140, 72, 56],
+    [150, 340, 64, 64]
+  ].freeze
+
+  # Centre x, centre y, vx, vy, spin in degrees per second. Fixed rather than
+  # random, so two runs of this example can be compared without a seed.
+  DRIFTERS = [
+    [40, 200, 120.0, 0.0, 90.0],
+    [600, 140, -95.0, 0.0, -140.0],
+    [150, 104, 0.0, 105.0, 0.0]
+  ].freeze
+
+  # Both systems are mounted here rather than in `on_add`, so they exist before
+  # any child's collider attaches and goes looking for them.
+  def initialize
+    super
+    @help_walk = RGame::Engine::Text.new('help.walk')
+    @help_crate = RGame::Engine::Text.new('help.crate')
+    @help_circles = RGame::Engine::Text.new('help.circles')
+    add_component(RGame::Engine::Components::World.new(width: WIDTH, height: HEIGHT))
+    add_component(RGame::Engine::Components::CollisionWorld.new(cell_size: CELL_SIZE))
+  end
+
+  def on_add
+    CRATES.each { |x, y, w, h| add_node(Crate.new(x: x, y: y, width: w, height: h)) }
+    DRIFTERS.each do |x, y, vx, vy, spin|
+      add_node(Drifter.new(x: x, y: y, vx: vx, vy: vy, spin: spin))
+    end
+    add_node(Walker.new(x: 80, y: 430))
+  end
+
+  def on_draw(renderer, view)
+    renderer.rect(0, 0, view.width, view.height, color: BACKDROP)
+    draw_cells(renderer, view)
+
+    renderer.text(@help_walk, 12, 12)
+    renderer.text(@help_crate, 12, 34)
+    renderer.text(@help_circles, 12, 56)
+  end
+
+  private
+
+  # The broadphase's own lattice, so `cell_size` is something you can look at.
+  # A while loop rather than a Range: this runs every frame, and a fresh Range
+  # every frame is the allocation the hot-path cops exist to refuse.
+  #
+  # hot-path
+  def draw_cells(renderer, view)
+    x = CELL_SIZE
+    while x < view.width
+      renderer.rect(x, 0, 1, view.height, color: GRID)
+      x += CELL_SIZE
+    end
+
+    y = CELL_SIZE
+    while y < view.height
+      renderer.rect(0, y, view.width, 1, color: GRID)
+      y += CELL_SIZE
+    end
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Collision',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES
+)
+
+game.start

data/examples/collision_tiles/locales/en.yml

@@ -0,0 +1,9 @@
+# The English table: every string this example draws.
+en:
+  help:
+    walk: Arrows / WASD / gamepad to walk — trees and the fence are solid
+    slide: "Hold down and left against the fence: you slide to its one gap"
+    box: The red box is what collides. The rest of the sprite is a picture
+    ball: "Walk east into the spiky ball: it stops you, and it costs a life"
+  hud:
+    lives: "Lives: %{lives}"