rgame 0.2.0 → 0.3.1

data/examples/input_glyphs/locales/en.yml

@@ -0,0 +1,14 @@
+# The English table: every string this example draws.
+en:
+  help:
+    seat: Press A on a controller to hand it the seat
+    back: Enter or Space on the keyboard takes it back
+  devices:
+    keyboard: Keyboard
+    controller: Controller
+  # What this game calls each action. The button shown beside it changes with
+  # the device; the word does not.
+  actions:
+    ui_confirm: Confirm
+    ui_cancel: Cancel
+    fire: Wave

data/examples/input_glyphs/main.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+# Input glyphs — the prompt matches the thing in your hand.
+#
+# Run it:
+#
+#   ruby examples/input_glyphs/main.rb
+#
+# Arrow keys, WASD or a stick walk the hero. Press **A** on a controller and the
+# panel switches to controller prompts; press **Enter** or **Space** on the
+# keyboard and it switches back. It exercises:
+#   - Controls.gamepad? — is the device in the player's hands a controller;
+#   - InputMap#button_for — which of an action's ids that device can press;
+#   - Engine::Players with one seat — `on_unassigned_input` defaulting to
+#     `:takeover`, which is what keyboard-to-controller switching *is*;
+#   - renderer.sprite — a glyph sheet indexed by button id.
+#
+# ## Nothing here listens for a controller being plugged in
+#
+# A game with one seat treats an unassigned device that somebody uses as *that
+# player* picking it up, rather than as a second player arriving. So plugging a
+# pad in does nothing at all, and pressing A on it hands the seat over: the
+# player's `device` changes, and every prompt below follows it on the next frame.
+#
+# That is the engine's `:takeover` policy, and a one-seat game gets it without
+# asking. `examples/split_screen` is the other setting of the same dial.
+#
+# **It switches back, through `ui_confirm` and nothing else.** Once the pad has
+# the seat the keyboard is unassigned, so Enter or Space hands it back — but W
+# does not, and neither does any other key. One action rather than "any input" is
+# deliberate: a stick resting a little off centre must never count as somebody
+# picking up a controller, and the rule is the same rule in both directions. A
+# game that genuinely wants any key to return to the keyboard sets
+# `players.on_unassigned_input = :ignore` and calls `players.seat(device)` on its
+# own terms.
+#
+# ## One entry lists both, and a prompt has to undo that
+#
+# An `InputMap` entry names the key *and* the pad button for one action:
+#
+#     fire: { buttons: [Controls::KEY_SPACE, Controls::PAD_A] }
+#
+# That is right for reading input — a device only answers for its own kind of id,
+# so polling needs no branch — and exactly wrong for showing it. A prompt saying
+# "press Space or A" tells the player about hardware they are not holding.
+#
+# `InputMap#button_for(action, device)` is the question the other way round: of
+# the ids bound to this action, which one can *this* device press? It compares
+# `Controls.pad_button?(id)` against `Controls.gamepad?(device)` — two id spaces
+# that were made disjoint for exactly this — and gives back the first that
+# matches, or nil.
+#
+# The first match is not arbitrary: `ui_confirm` lists Return before Space, so
+# the panel says Return. The order an entry is written in is the order a prompt
+# prefers.
+#
+# ## A glyph is a button id rendered as a picture
+#
+# Which makes the whole of it a lookup keyed by that id:
+#
+#     GLYPH_COLUMN = { Controls::KEY_SPACE => 0, ... }.freeze
+#
+# The sheet is one row of 64x64 frames, drawn with `renderer.sprite`, and the
+# table says which column belongs to which id. There is no cleverness to it, and
+# that is the point — the hard part was deciding *which* id to draw, and that
+# happened above.
+#
+# The table covers the five ids this example's three actions can produce. A game
+# with a rebinding screen needs one entry per id it lets a player bind, or a text
+# fallback for the ones it has no art for; here a missing glyph draws nothing and
+# leaves the label to speak for itself.
+#
+# ## What it does not solve
+#
+# **Axes.** Walking is bound to `move_x`/`move_y`, which are a stick and pairs of
+# keys rather than buttons, so `button_for` gives nil for them and the panel does
+# not try: the picture for "the left stick" or "the arrow keys" is one image
+# standing for several ids, which is a different question with a different
+# answer. The three prompts here are all single buttons.
+#
+# **Which controller.** The pad glyphs are Xbox-shaped because SDL's button names
+# are (`PAD_A`, `PAD_B`), and a PlayStation pad reports the same ids under
+# different labels. Shipping a second sheet and choosing between them by
+# controller name is a real thing games do, and it is another table keyed by the
+# same ids.
+
+$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
+
+SPEED = 90.0
+
+# The glyph sheet: one row of 64x64 frames, in the order examples/assets/README.md
+# lists them.
+SHEET  = 'glyphs.json'
+GLYPH  = 64
+
+# A prompt is a picture of a button, so the table is keyed by button id. These
+# five are what this example's three actions resolve to on the two kinds of
+# device.
+GLYPH_COLUMN = {
+  RGame::Util::Controls::KEY_SPACE => 0,
+  RGame::Util::Controls::KEY_RETURN => 1,
+  RGame::Util::Controls::KEY_ESCAPE => 2,
+  RGame::Util::Controls::PAD_A => 3,
+  RGame::Util::Controls::PAD_B => 4
+}.freeze
+
+# The panel: three actions, and the button each one is on for the device the
+# player is holding right now.
+class Prompts < RGame::Engine::Node2D
+  PANEL = RGame::Util::Color.new(18, 22, 30, 220)
+  INK   = RGame::Util::Color.new(228, 232, 240)
+  DIM   = RGame::Util::Color.new(150, 158, 172)
+
+  # The action to ask about, and what this game calls it. Both fixed: the label
+  # is the game's word for the action, and the button is what changes.
+  ROWS = { ui_confirm: RGame::Engine::Text.new('actions.ui_confirm'),
+           ui_cancel: RGame::Engine::Text.new('actions.ui_cancel'),
+           fire: RGame::Engine::Text.new('actions.fire') }.freeze
+
+  # A text chosen by state rather than built from it: one Text per state, so there
+  # is nothing to render again but a language switch.
+  DEVICE_NAME = { false => RGame::Engine::Text.new('devices.keyboard'),
+                  true => RGame::Engine::Text.new('devices.controller') }.freeze
+
+  WIDTH_PX = 300
+  ROW_H    = 72
+  PAD      = 14
+  HEADER_H = 34
+
+  def on_add
+    # One seat, so the player is the primary one. Held rather than looked up per
+    # frame: which player this is cannot change, while the device they hold can.
+    @player = system(RGame::Engine::Players).primary
+  end
+
+  def on_draw(renderer, _view)
+    device = @player.device
+    renderer.rect(0, 0, WIDTH_PX, HEADER_H + (ROWS.size * ROW_H), color: PANEL)
+    renderer.text(DEVICE_NAME.fetch(RGame::Util::Controls.gamepad?(device)), PAD, PAD, color: INK)
+
+    ROWS.each_with_index do |(action, label), index|
+      draw_row(renderer, action, label, device, HEADER_H + (index * ROW_H))
+    end
+  end
+
+  private
+
+  # hot-path
+  def draw_row(renderer, action, label, device, y)
+    id = @player.input_map.button_for(action, device)
+    column = GLYPH_COLUMN[id]
+    renderer.sprite(SHEET, 0, column, PAD, y) unless column.nil?
+    renderer.text(label, PAD + GLYPH + PAD, y + ((GLYPH - 16) / 2), color: id.nil? ? DIM : INK)
+  end
+end
+
+# Something to walk, so that picking up a controller has a reason to happen.
+# `examples/walk`'s hero, kept inside the window.
+class Hero < RGame::Engine::Node2D
+  def initialize(**)
+    super
+    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)
+  end
+
+  def on_update(_dt)
+    self.x = x.clamp(0, WIDTH - width)
+    self.y = y.clamp(0, HEIGHT - height)
+  end
+end
+
+class Scene < RGame::Engine::Node2D
+  BACKDROP = RGame::Util::Color.new(30, 36, 46)
+  MARGIN   = 16
+
+  # The hero first, so the panel is drawn over them rather than under: a node
+  # draws before its later siblings, and the two do overlap once the hero is
+  # walked into the corner.
+  def initialize
+    super
+    @help_seat = RGame::Engine::Text.new('help.seat')
+    @help_back = RGame::Engine::Text.new('help.back')
+  end
+
+  def on_add
+    add_node(Hero.new(x: 470, y: 300))
+    add_node(Prompts.new(x: MARGIN, y: MARGIN))
+  end
+
+  def on_draw(renderer, view)
+    renderer.rect(0, 0, view.width, view.height, color: BACKDROP)
+    renderer.text(@help_seat, MARGIN, view.height - 52)
+    renderer.text(@help_back, MARGIN, view.height - 30)
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Input glyphs',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES
+)
+
+game.start

data/examples/jump_topdown/locales/en.yml

@@ -0,0 +1,9 @@
+# The English table: every string this example draws.
+en:
+  help:
+    walk: Arrows / WASD / gamepad to walk, Space / A to hop
+    box: The red box stays on the ground. So does everything it collides with
+    fence: "Walk south into the fence and hop: the picture clears it, the feet do not"
+  status:
+    airborne: In the air
+    grounded: On the ground

data/examples/jump_topdown/main.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+# Jump top-down — a hop that leaves the ground without leaving its spot on it.
+#
+# Run it:
+#
+#   ruby examples/jump_topdown/main.rb
+#
+# Arrow keys, WASD, a d-pad or a left stick walk the hero; Space or the pad's A
+# button hops. The trees and the fence are solid. It exercises:
+#   - Components::Hop — a parabola in time, written to the node's elevation;
+#   - Node2D#elevation — how far a node's picture is drawn above where it stands;
+#   - Components::AnimatedSprite — the picture that rises with it;
+#   - Components::FeetCollider and Components::CharacterBody — the shape and the
+#     steps that stay on the ground, from `examples/collision_tiles`;
+#   - Components::TileWorld and Components::CameraFollow — the map and a camera
+#     that does not bob;
+#   - InputMap.default.merge — the :jump action this game declares.
+#
+# ## A jump is a drawing offset
+#
+# In a top-down view, "up" on the screen is *north*. So a jump cannot move the
+# node up the screen: that would be walking north, and the feet box would go with
+# it, into whatever is north of the hero. What leaves the ground is the picture.
+#
+# `Hop` writes its height to `node.elevation`, and `elevation` is not part of the
+# transform: `y` does not change, `world_y` does not change, the feet box does not
+# move, and neither does the camera following them. `AnimatedSprite` is the one
+# thing that reads it, and draws the sprite that far above the spot. Watch the red
+# box during a hop — it never leaves the floor, and the shadow sits on it, getting
+# smaller as the hero gets further away from it.
+#
+# ## So a hop does not clear a fence
+#
+# Walk up to the fence and hop over it. The sprite rises well above it, and the
+# hero stops exactly where walking stopped them, because what collides never
+# left the ground. That is correct for a hop and would be wrong for a vault, and
+# the difference is a decision about the map rather than about the jump.
+#
+# ## What this does not solve
+#
+# **Crossing anything.** `hop.airborne?` is the seam for that: a game whose
+# chasm tiles should be passable in the air reads it where it decides what is
+# solid. `TileWorld` does not consult it, and `Hop` knows nothing about tiles.
+# Which tiles a jump clears, and what happens to a hero who lands on one, are
+# rules of a particular game, and a jump component that had an opinion about
+# them would be wrong for the next game.
+#
+# **Height against the scenery.** The lifted sprite keeps the draw order it has
+# on the ground, so a hop next to a tree still passes behind the canopy that
+# would hide the hero walking there. A game with tall jumps would sort by the
+# feet and draw the lifted part over the scenery.
+
+$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'
+SPEED = 80.0 # px/s
+
+# A hop about as tall as the hero's head, over half a second: enough to read as a
+# jump at this sprite size, short enough that it is over before the next press.
+HOP_PEAK = 18.0
+HOP_DURATION = 0.5
+
+FEET_WIDTH  = 12
+FEET_HEIGHT = 6
+
+CAMERA_OFFSET_X = 8
+CAMERA_OFFSET_Y = 19
+
+# North of the fence, two tiles above it: one walk down reaches it.
+START_X = 384.0
+START_Y = 264.0
+
+Controls = RGame::Util::Controls
+
+# A walker from `examples/collision_tiles` with one more component. The only
+# drawing it does itself is what stays on the ground: the shadow and the feet box.
+class Hero < RGame::Engine::Node2D
+  FEET = RGame::Util::Color.rgba(255, 110, 110, 120)
+  SHADOW = RGame::Util::Color.rgba(0, 0, 0, 90)
+
+  # The shadow on the ground is an ellipse this wide and tall, and shrinks to half
+  # its size once the hero is this far above it.
+  SHADOW_RADIUS_X = 7.0
+  SHADOW_RADIUS_Y = 3.0
+  SHADOW_HALF_AT = 18.0
+
+  attr_reader :hop
+
+  def initialize(camera:, **)
+    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
+                              ))
+    add_component(RGame::Engine::Components::CharacterBody.new(speed: SPEED, blocked_by: [:tiles]))
+    add_component(RGame::Engine::Components::PlayerController.new)
+    # The one line that differs from `examples/collision_tiles`. It needs nothing
+    # from its siblings and none of them know it is here: it writes the node's
+    # elevation, and the sprite already draws lifted by whatever that is.
+    @hop = add_component(RGame::Engine::Components::Hop.new(peak: HOP_PEAK, duration: HOP_DURATION))
+    add_component(RGame::Engine::Components::CameraFollow.new(
+                    camera: camera, offset_x: CAMERA_OFFSET_X, offset_y: CAMERA_OFFSET_Y
+                  ))
+  end
+
+  # Both drawn at the feet, and neither reads the node's elevation: this is the
+  # part of the hero that is on the ground. The shadow is a circle squashed into an
+  # ellipse, so it is placed first and squashed second — squashing first would
+  # squash the placement too. It shrinks through the circle's radius rather than
+  # the squash, which keeps the ellipse's proportions. `z: -1` puts it under the
+  # sprite, which draws at 0.
+  def on_draw(renderer, _view)
+    box = @collider.box
+    shrink = 1.0 / (1.0 + (@hop.height / SHADOW_HALF_AT))
+    renderer.translated(box.offset_x + (box.width / 2.0), box.offset_y + (box.height / 2.0)) do
+      renderer.scaled(SHADOW_RADIUS_X, SHADOW_RADIUS_Y) do
+        renderer.circle(0, 0, shrink, color: SHADOW, z: -1)
+      end
+    end
+    renderer.rect(box.offset_x, box.offset_y, box.width, box.height, color: FEET)
+  end
+end
+
+# The scene from `examples/collision_tiles`, less the spiky ball.
+class Scene < RGame::Engine::Node2D
+  STATE = { true => RGame::Engine::Text.new('status.airborne'),
+            false => RGame::Engine::Text.new('status.grounded') }.freeze
+
+  def initialize
+    super
+    @help_walk = RGame::Engine::Text.new('help.walk')
+    @help_box = RGame::Engine::Text.new('help.box')
+    @help_fence = RGame::Engine::Text.new('help.fence')
+  end
+
+  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 = actors.add_node(Hero.new(camera: players.primary.camera, x: START_X, y: START_Y))
+  end
+
+  def on_draw(renderer, _view)
+    renderer.text(@help_walk, 12, 12)
+    renderer.text(@help_box, 12, 34)
+    renderer.text(@help_fence, 12, 56)
+    renderer.text(STATE[@hero.hop.airborne?], 12, 78)
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Jump top-down',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES,
+  # :jump is this game's own action. Space is also in the default map as :fire and
+  # :ui_confirm, which nothing in this scene reads.
+  input_map: RGame::Engine::InputMap.default.merge(
+    jump: { buttons: [Controls::KEY_SPACE, Controls::PAD_A] }
+  )
+)
+
+game.start

data/examples/localization/locales/de.yml

@@ -0,0 +1,12 @@
+# The German table. It has no `zero:`, because German says "0 Äpfel", and it
+# lacks `hud.hint` on purpose: main.rb's header says what that shows.
+de:
+  title: Lokalisierung
+  hud:
+    apples:
+      one: "%{count} Apfel"
+      other: "%{count} Äpfel"
+    locale: "Aktuelles Gebietsschema: %{locale}"
+  language:
+    title: Sprache
+    system: Systemsprache verwenden

data/examples/localization/locales/en.yml

@@ -0,0 +1,13 @@
+# The English table, and the default: a key German lacks shows this text.
+en:
+  title: Localization
+  hud:
+    apples:
+      zero: No apples
+      one: "%{count} apple"
+      other: "%{count} apples"
+    locale: "Current locale: %{locale}"
+    hint: Left and right change the count
+  language:
+    title: Language
+    system: Use the system language

data/examples/localization/main.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# Localization — the same screen in two languages.
+#
+# Run it:
+#
+#   ruby examples/localization/main.rb
+#
+# Left and right change the number of apples. Up and down move through the
+# language menu, and Enter picks one. Quit and run it again: the language you
+# picked is still the one on screen. It exercises:
+#   - Engine::I18n — tables in locales/, a fallback to English, CLDR plurals;
+#   - Engine::Text — a key built once, with a `count` and with a variable;
+#   - UI::Menu's `scope:`, and `Text.literal` for text that is never translated;
+#   - RGame::Game's `locales:`, and the language it picks from the OS;
+#   - Util::SaveFile, holding the language a player picked.
+#
+# ## Nothing is looked up while drawing
+#
+# Every string on screen is an Engine::Text built in `initialize`. Reading one
+# compares its variables and `I18n.generation` with what it last rendered, and
+# returns the same String while nothing changed. Picking a language moves the
+# generation, so every Text and every button renders again on its next read,
+# and nothing here tells them to.
+#
+# ## The tables sit beside this file
+#
+# `Game.new(locales: File.join(__dir__, 'locales'))` loads `en.yml` and `de.yml`
+# from here. Every example shares `examples/assets/` as its media root, so a
+# table there would be loaded into every example.
+#
+# ## German lacks a key, on purpose
+#
+# `de.yml` has no `hud.hint`. In German the hint shows the English text, because
+# German's fallback chain ends at the default locale, English. A player reads a
+# sentence in a language the game ships rather than `hud.hint`. That is the right
+# failure for a game, and the wrong one to ship on purpose: a project from
+# `rgame new` has a locales spec that fails until German has the key.
+#
+# German also has no `zero:` for the apples. English says "No apples", German
+# says "0 Äpfel": an explicit `zero:` belongs to the table that has it.
+#
+# ## Language names are literals
+#
+# "English" and "Deutsch" are `Text.literal`, not keys. A language is named in
+# its own language whichever one is current, so its name must not translate.
+# The third button is a key, and the menu's `scope: 'language'` makes `system`
+# read `language.system`. A literal has no key, so the scope does not touch it.
+#
+# ## What this does not solve
+#
+# The engine layer cannot measure text yet, so the buttons are a fixed width,
+# chosen wide enough for the longer label in either language: "Use the system
+# language". A third language with longer words would need a wider slot.
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'rgame/game'
+
+UI = RGame::Engine::UI
+I18n = RGame::Engine::I18n
+Text = RGame::Engine::Text
+
+WIDTH  = 640
+HEIGHT = 360
+ASSETS = File.expand_path('../assets', __dir__)
+LOCALES = File.expand_path('locales', __dir__)
+
+# The language on screen, and the file that remembers a player's choice.
+#
+# `RGame::Game` picks a language from the OS before `start`. A choice saved
+# here wins over that, and "use the system language" forgets the choice again.
+class Language
+  def initialize(save, preferred)
+    @save = save
+    @preferred = preferred
+  end
+
+  # Called between `Game.new`, which loaded the tables, and `start`. `choose`
+  # takes the saved locale if a table covers it, and the OS's otherwise, so a
+  # hand-edited file holding a language this game lacks changes nothing.
+  def restore
+    saved = @save.read[:language]
+    I18n.locale = I18n.choose([saved, *@preferred]) if saved.is_a?(String) && !saved.empty?
+  end
+
+  def pick(locale)
+    I18n.locale = locale
+    @save.write(language: locale.name)
+  end
+
+  def follow_system
+    @save.delete
+    I18n.locale = I18n.choose(@preferred)
+  end
+end
+
+# The whole screen: a heading, three lines of text and the language menu.
+class Screen < RGame::Engine::Node2D
+  MARGIN = 40
+  MENU_Y = 196
+  ITEM_WIDTH = 280
+  ITEM_HEIGHT = 34
+
+  def initialize(language:, **)
+    super(**)
+    @language = language
+    @apples_held = 3
+    @title = Text.new('title')
+    @apples = Text.new('hud.apples', :count)
+    @locale = Text.new('hud.locale', :locale)
+    @hint = Text.new('hud.hint')
+    @heading = Text.new('language.title')
+  end
+
+  def on_add
+    menu = add_node(UI::Menu.new(x: MARGIN, y: MENU_Y, scope: 'language',
+                                 layout: UI::Column.new(item_width: ITEM_WIDTH, item_height: ITEM_HEIGHT)))
+    menu.add(UI::PanelButton.new(label: Text.literal('English'))).on_activated { @language.pick(:en) }
+    menu.add(UI::PanelButton.new(label: Text.literal('Deutsch'))).on_activated { @language.pick(:de) }
+    menu.add(UI::PanelButton.new(label: 'system')).on_activated { @language.follow_system }
+  end
+
+  def on_control(actions)
+    @apples_held += 1 if actions.pressed?(:ui_right)
+    @apples_held -= 1 if actions.pressed?(:ui_left) && @apples_held.positive?
+  end
+
+  def on_draw(renderer, _view)
+    renderer.text(@title, MARGIN, 24)
+    renderer.text(@apples.with(count: @apples_held), MARGIN, 72)
+    renderer.text(@locale.with(locale: I18n.locale.name), MARGIN, 96)
+    renderer.text(@hint, MARGIN, 120)
+    renderer.text(@heading, MARGIN, MENU_Y - 30)
+  end
+end
+
+# `dir:` is normally left out and the file lands in the platform's own data
+# directory. It is overridable so a driven run writes somewhere disposable.
+save = RGame::Util::SaveFile.new('language.json', game: 'rgame-examples',
+                                                  dir: ENV.fetch('RGAME_SAVE_DIR', nil))
+language = Language.new(save, RGame::Core.preferred_locales)
+
+game = RGame::Game.new(
+  root: Screen.new(language: language),
+  caption: 'Localization',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES
+)
+
+language.restore
+
+# The buttons draw nine-slices, which name elements of an atlas rather than
+# files, so the atlas is registered before the first frame.
+game.renderer.register_ui_atlas(game.assets.ui_atlas('ui.json'))
+
+game.start

data/examples/menu_navigation/locales/en.yml

@@ -0,0 +1,23 @@
+# The English table: every string this example draws.
+en:
+  title:
+    heading: Menu navigation
+    help: Up and down to move, Enter to choose
+    play: Play
+    settings: Settings
+    quit: Quit
+  settings:
+    heading: Settings — left and right change a value
+    fullscreen: Fullscreen
+    scale: Scale mode
+    volume: Volume
+    back: Back
+    # Quoted: YAML reads a bare on and off as true and false.
+    'on': "on"
+    'off': "off"
+    disabled: disabled
+    stretch: stretch
+    letterbox: letterbox
+    integer: integer
+  play:
+    help: Enter makes a noise — Escape returns to the title