rgame 0.2.0 → 0.3.0

data/examples/timer/main.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+# Timer — things that happen on a clock, with nobody pressing anything.
+#
+# Run it:
+#
+#   ruby examples/timer/main.rb
+#
+# Watch the race; **Space** sets off the one-shot. It exercises:
+#   - Components::Timer — a repeating interval that rides the node's tick;
+#   - `repeating: false` — the same component as a one-shot that arms itself;
+#   - `as:` — two cadences on one node, because a node holds one per slot;
+#   - Engine::Timer — the pure accumulator underneath all of that.
+#
+# ## A spawner is not waiting for a key
+#
+# Every example before this one moved when something was pressed. A wave clock, a
+# turret's rate of fire and an enemy every few seconds are none of them input, and
+# they are what this is for.
+#
+# ## The race is the point, and the loser is the obvious implementation
+#
+# Both bars count beats at the same interval. The top one is a
+# `Components::Timer`; the bottom one is four lines anybody would write:
+#
+#     @elapsed += dt
+#     if @elapsed >= INTERVAL
+#       @elapsed = 0.0      # <- this
+#       beat
+#     end
+#
+# The top bar wins every lap, and that line is why. A frame almost never lands
+# exactly on an interval boundary, so `@elapsed` is a little *past* it when the
+# beat fires — and zeroing throws that overshoot away. Every beat starts late by
+# whatever was discarded, and the error adds up for as long as the program runs.
+#
+# `Engine::Timer#consume` subtracts the interval instead of zeroing, so the
+# remainder carries into the next beat and the cadence stays true to the clock
+# rather than to the frame it happened to be noticed on:
+#
+#     def consume
+#       @elapsed -= @interval
+#     end
+#
+# One character of difference, and the gap it opens is on screen. The interval
+# here is deliberately not a whole number of frames — at a fixed sixtieth of a
+# second and an interval of 0.07, a beat is 4.2 frames, and rounding that up to 5
+# costs the naive bar about one lap in six.
+#
+# ## The catch-up half of the same idea
+#
+# `Components::Timer#update` fires `on_timeout` *once per whole interval* that
+# elapsed, in a loop, rather than once per call. A step long enough to cover
+# three intervals emits three times. Nothing in this example produces one — the
+# loop is fixed-timestep — but a game that ever sees a long step wants the
+# spawner to owe it three enemies rather than one.
+#
+# ## One component per slot, which is what `as:` is for
+#
+# A node holds one component per slot, and a slot defaults to the component's
+# class — so a second `Components::Timer` added plainly would be refused. The top
+# runner carries two: a fast `:beat` and a slow `:chime` that flips the marker
+# beside it. Naming them is the whole of making that legal, and it is also how
+# either is found again.
+#
+# ## The one-shot arms itself, which matters more than it sounds
+#
+# `repeating: false` fires once and goes inert, and `reset` re-arms it. The
+# component calls `reset` from `on_attach`, so a node that leaves the tree and
+# comes back gets a fresh countdown rather than inheriting a spent one. That line
+# is what makes a pooled projectile with a lifetime work — see `examples/pooling`,
+# where the same component retires what the pool hands out.
+#
+# ## What it does not solve
+#
+# Pausing a timer on its own. A `Components::Timer` stops when its node stops,
+# because `paused` halts the node's whole update — which is usually what is
+# wanted, and is not the same as a timer with its own switch.
+
+$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
+
+# 4.2 frames at a fixed sixtieth of a second, chosen so that rounding it up to a
+# whole frame is a mistake with a visible size.
+BEAT = 0.07
+CHIME = 1.5
+FUSE = 1.2 # how long the one-shot banner stays
+
+TRACK_X = 60
+TRACK_W = 480
+LAP = 70 # beats to the end of the track
+
+# The two runners share this, so the only difference between them is how each
+# decides a beat has happened.
+module Runner
+  BAR_H = 26
+  TRACK = RGame::Util::Color.new(44, 50, 64)
+
+  def beats = @beats ||= 0
+
+  def draw_track(renderer, color)
+    renderer.rect(0, 0, TRACK_W, BAR_H, color: TRACK)
+    renderer.rect(0, 0, TRACK_W * (beats.to_f / LAP), BAR_H, color: color)
+  end
+end
+
+# Beats on a Components::Timer, which carries the remainder forward.
+class TrueRunner < RGame::Engine::Node2D
+  include Runner
+
+  BAR = RGame::Util::Color.new(120, 210, 150)
+  MARK_ON = RGame::Util::Color.new(255, 226, 130)
+  MARK_OFF = RGame::Util::Color.new(70, 78, 96)
+  MARK = 18
+
+  def initialize(**)
+    super
+    @beats = 0
+    @chimed = false
+  end
+
+  # Two timers, two slots. Without the names the second would be refused, and
+  # `get_component(Components::Timer)` would have no single answer to give.
+  def on_add
+    add_component(RGame::Engine::Components::Timer.new(BEAT), as: :beat)
+      .on_timeout { @beats += 1 }
+    add_component(RGame::Engine::Components::Timer.new(CHIME), as: :chime)
+      .on_timeout { @chimed = !@chimed }
+  end
+
+  # Resetting the lap is this node's business rather than the timer's: the timer
+  # counts time and the owner decides what a count means.
+  def lap? = @beats >= LAP
+
+  def restart = @beats = 0
+
+  def on_draw(renderer, _view)
+    draw_track(renderer, BAR)
+    renderer.rect(TRACK_W + 14, 4, MARK, MARK, color: @chimed ? MARK_ON : MARK_OFF)
+  end
+end
+
+# The same cadence, written the way it comes out first. It is slower, and the
+# only reason is the line that throws the overshoot away.
+class NaiveRunner < RGame::Engine::Node2D
+  include Runner
+
+  BAR = RGame::Util::Color.new(235, 120, 100)
+  MARK = RGame::Util::Color.new(255, 255, 255)
+  MARK_W = 3
+
+  def initialize(**)
+    super
+    @beats = 0
+    @elapsed = 0.0
+    @shortfall = 0
+  end
+
+  def on_update(dt)
+    @elapsed += dt
+    return if @elapsed < BEAT
+
+    # Discarding the overshoot is the bug. `@elapsed -= BEAT` here and the two
+    # bars finish level.
+    @elapsed = 0.0
+    @beats += 1
+  end
+
+  # Remembered before it is cleared, because how far this bar had got when the
+  # other one finished *is* the size of the error. The marker lands in the same
+  # place every lap, which is the other half of the point: the gap is a steady
+  # rate, not a one-off stumble.
+  def restart
+    @shortfall = @beats
+    @beats = 0
+    @elapsed = 0.0
+  end
+
+  def on_draw(renderer, _view)
+    draw_track(renderer, BAR)
+    return if @shortfall.zero?
+
+    renderer.rect(TRACK_W * (@shortfall.to_f / LAP), 0, MARK_W, BAR_H, color: MARK)
+  end
+end
+
+# A banner that takes itself away. Nothing removes it from outside.
+class Fuse < RGame::Engine::Node2D
+  BANNER = RGame::Util::Color.new(120, 200, 255)
+  INK = RGame::Util::Color.new(20, 26, 34)
+  BANNER_W = 260
+  BANNER_H = 30
+
+  def initialize(**)
+    super
+    @label = RGame::Engine::Text.new('fuse.banner')
+  end
+
+  def on_add
+    add_component(RGame::Engine::Components::Timer.new(FUSE, repeating: false))
+      .on_timeout { queue_free }
+  end
+
+  def on_draw(renderer, _view)
+    renderer.rect(0, 0, BANNER_W, BANNER_H, color: BANNER)
+    renderer.text(@label, 10, 8, z: 1, color: INK)
+  end
+end
+
+class Scene < RGame::Engine::Node2D
+  BACKDROP = RGame::Util::Color.new(28, 32, 42)
+  FUSE_X = 60
+  FUSE_Y = 370
+
+  def initialize
+    super
+    @help = RGame::Engine::Text.new('help.beat')
+    @true_caption = RGame::Engine::Text.new('captions.timer')
+    @naive_caption = RGame::Engine::Text.new('captions.naive')
+    @mark_caption = RGame::Engine::Text.new('captions.mark')
+    @blink_caption = RGame::Engine::Text.new('captions.blink')
+    @fuse_caption = RGame::Engine::Text.new('captions.fuse')
+  end
+
+  def on_add
+    @truth = add_node(TrueRunner.new(x: TRACK_X, y: 150))
+    @naive = add_node(NaiveRunner.new(x: TRACK_X, y: 210))
+  end
+
+  # The lap is settled here, where both runners are visible, so that neither of
+  # them needs to know the other exists.
+  def on_update(_dt)
+    return unless @truth.lap?
+
+    @truth.restart
+    @naive.restart
+  end
+
+  def on_control(actions)
+    return unless actions.pressed?(:fire)
+    # One at a time: a second banner would sit exactly on top of the first.
+    return if @fuse&.in_tree?
+
+    @fuse = add_node(Fuse.new(x: FUSE_X, y: FUSE_Y))
+  end
+
+  def on_draw(renderer, view)
+    renderer.rect(0, 0, view.width, view.height, color: BACKDROP)
+
+    renderer.text(@help, 12, 12)
+    renderer.text(@true_caption, TRACK_X, 126)
+    renderer.text(@naive_caption, TRACK_X, 244)
+    renderer.text(@mark_caption, TRACK_X, 264)
+    renderer.text(@blink_caption, TRACK_X, 296)
+    renderer.text(@fuse_caption, TRACK_X, 336)
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Timer',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES
+)
+
+game.start

data/examples/velocity/locales/en.yml

@@ -0,0 +1,6 @@
+# The English table: every string this example draws.
+en:
+  help:
+    walk: Arrows / WASD walk the pale circle — the rectangles need nobody
+    wrap: They wrap at the edge of the world, which stops above this text
+    spin: "Two of them spin: one component adding to angle, no shape the wiser"

data/examples/velocity/main.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+# Velocity — movement with nobody driving.
+#
+# Run it:
+#
+#   ruby examples/velocity/main.rb
+#
+# Arrow keys, WASD or a stick walk the pale circle. The rectangles are not
+# waiting for you. It exercises:
+#   - Components::Velocity — a velocity integrated into the node each step;
+#   - Components::ScreenWrap — leaving one edge and arriving at the opposite one;
+#   - Components::World — how big the world is, as a service the scene mounts;
+#   - Components::WorldBounds — the contract that lets one wrap fit two worlds.
+#
+# ## Two ways to move, and the difference is who decides
+#
+# Every example before this one moved things with `CharacterBody`, which takes an
+# *intent* — each axis in -1..1 — and turns it into a step at a fixed speed. Let
+# go of the key and the intent is zero and the node stops. That is what a walking
+# character wants, and it is why the circle here behaves the way you expect.
+#
+# A rock has no intent. It has a velocity, and something integrates it:
+#
+#     node.x += vx * dt
+#     node.y += vy * dt
+#     node.angle += spin * dt
+#
+# That is the whole of Components::Velocity. Nothing writes to it after the
+# rectangles are built, nothing reads input, and they drift for as long as the
+# program runs. The two components are siblings rather than rivals —
+# `ThrustController` is the third of the family, and it *accelerates* a velocity
+# rather than setting one, which is how a ship differs from both.
+#
+# ## `spin` is an angle, and the shape does not know
+#
+# Two of the rectangles turn as they drift, and the drawing code is the same
+# single `renderer.rect` the still ones use, at the same coordinates. `Node2D#draw`
+# has already pushed the node's rotation, so a component that adds to `angle` is
+# enough to make a shape spin — the same reason the sprite in `examples/sprite`
+# turns without Components::Sprite knowing that angles exist.
+#
+# ## The world is not the window
+#
+# The world stops short of the bottom of the window, where the text is, and the
+# rectangles wrap at its edge rather than the screen's. Ask the `view` a draw is
+# handed how big the **window** is, and `node.system(WorldBounds)` how big the
+# **world** is. `examples/scroll_map` is where the two differ in earnest.
+#
+# ## Why the wrap asks for a contract rather than a class
+#
+# `ScreenWrap` never mentions `World`. It calls `WorldBounds.resolve`, and what
+# answers is whichever system the scene mounted — the plain rectangle here, or a
+# `TileWorld` that works its bounds out from a parsed map. `Node2D#get_component`
+# matches with `is_a?`, which matches an included module as readily as a class,
+# and that is the whole mechanism.
+#
+# It resolves in `on_attach` rather than `initialize`, because a node has no
+# scene to ask until it is in the tree — and it resolves again on every entry, so
+# an entity pooled out of one scene and into a smaller one wraps against the
+# smaller one.
+#
+# ## What it does not solve
+#
+# Collision. These pass straight through each other, because a velocity is only
+# a position changing over time and nothing here is watching for overlaps.
+# `examples/collision` is where that is the subject.
+
+$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 world is the window minus a band along the bottom for the text. It is
+# shorter by more than the wrap margin, so a shape leaving through the bottom edge
+# is put back before it reaches the text.
+WORLD_W = WIDTH
+WORLD_H = 360
+TEXT_Y  = 410
+
+# How far past the edge a shape travels before it is put back on the other side.
+# Without it a rectangle jumps while half of it is still showing.
+WRAP_MARGIN = 40.0
+
+WALK_SPEED = 140.0
+
+# A rectangle that moves because it was given a velocity, and for no other
+# reason. Everything that makes it move is a component; this class is a shape.
+class Drifter < RGame::Engine::Node2D
+  BOX_W = 38
+  BOX_H = 20
+
+  def initialize(color:, vx:, vy:, spin: 0.0, **)
+    super(width: BOX_W, height: BOX_H, **)
+    @color = color
+    @vx = vx
+    @vy = vy
+    @spin = spin
+  end
+
+  def on_add
+    add_component(RGame::Engine::Components::Velocity.new(vx: @vx, vy: @vy, spin: @spin))
+    add_component(RGame::Engine::Components::ScreenWrap.new(margin: WRAP_MARGIN))
+  end
+
+  # Centred on the node's own origin, which is where the traversal has already
+  # put the renderer — so a spinning node turns this rectangle about its middle
+  # and this method never learns of it.
+  def on_draw(renderer, _view)
+    renderer.rect(-BOX_W / 2, -BOX_H / 2, BOX_W, BOX_H, color: @color)
+  end
+end
+
+# The one with an intent. Same wrap, same world, different reason to move.
+class Walker < RGame::Engine::Node2D
+  BODY = RGame::Util::Color.new(236, 233, 220)
+  RADIUS = 13
+
+  def initialize(**)
+    super(width: RADIUS * 2, height: RADIUS * 2, **)
+  end
+
+  # CharacterBody first: PlayerController drives a sibling body and asks for it
+  # by class when it attaches, and a component added from `on_add` can only see
+  # the ones already there.
+  def on_add
+    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
+
+  def on_draw(renderer, _view) = renderer.circle(0, 0, RADIUS, color: BODY)
+end
+
+class Scene < RGame::Engine::Node2D
+  BACKDROP = RGame::Util::Color.new(28, 32, 42)
+  FLOOR    = RGame::Util::Color.new(44, 50, 64)
+  EDGE     = RGame::Util::Color.new(120, 200, 255)
+  THICK    = 2
+
+  # vx, vy, spin (degrees per second), colour. Fixed rather than random: two runs
+  # of this example should be able to be compared without a seed.
+  DRIFTERS = [
+    [90.0, 34.0, 0.0, [235, 145, 90]],
+    [-70.0, 58.0, 110.0, [130, 210, 150]],
+    [48.0, -76.0, 0.0, [225, 205, 110]],
+    [-104.0, -26.0, -150.0, [190, 150, 235]],
+    [62.0, 90.0, 0.0, [120, 200, 255]]
+  ].freeze
+
+  # Mounted here rather than in `on_add` for a reason worth knowing: a node
+  # assembled outside the tree collects every component before any of them
+  # attaches, so nothing depends on the order. Added from `on_add` the node is
+  # already live, each component attaches as it arrives, and the wraps below
+  # would resolve their bounds before this existed.
+  def initialize
+    super
+    @help_walk = RGame::Engine::Text.new('help.walk')
+    @help_wrap = RGame::Engine::Text.new('help.wrap')
+    @help_spin = RGame::Engine::Text.new('help.spin')
+    add_component(RGame::Engine::Components::World.new(width: WORLD_W, height: WORLD_H))
+  end
+
+  def on_add
+    DRIFTERS.each_with_index do |(vx, vy, spin, rgb), index|
+      add_node(Drifter.new(color: RGame::Util::Color.new(*rgb), vx: vx, vy: vy, spin: spin,
+                           x: 60 + (index * 120), y: 40 + (index * 60)))
+    end
+
+    add_node(Walker.new(x: WORLD_W / 2, y: WORLD_H / 2))
+  end
+
+  def on_draw(renderer, view)
+    renderer.rect(0, 0, view.width, view.height, color: BACKDROP)
+    renderer.rect(0, 0, WORLD_W, WORLD_H, color: FLOOR)
+    renderer.rect(0, WORLD_H - THICK, WORLD_W, THICK, color: EDGE)
+
+    renderer.text(@help_walk, 12, TEXT_Y)
+    renderer.text(@help_wrap, 12, TEXT_Y + 22)
+    renderer.text(@help_spin, 12, TEXT_Y + 44)
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Velocity',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES
+)
+
+game.start

data/examples/walk/locales/en.yml

@@ -0,0 +1,4 @@
+# The English table: every string this example draws.
+en:
+  help:
+    walk: Arrow keys / WASD / gamepad to walk

data/examples/walk/main.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# Walk — a player-controlled sprite, and the smallest complete game there is.
+#
+# Run it:
+#
+#   ruby examples/walk/main.rb
+#
+# Arrow keys, WASD, a d-pad or a left stick; they all work and none of them are
+# mentioned below. It exercises:
+#   - Node2D — the scene tree, and `on_update`/`on_draw` as blank hooks;
+#   - Components::AnimatedSprite — directional animation off a sprite sheet;
+#   - Components::CharacterBody — an intent in -1..1 becomes a step at a speed;
+#   - Components::PlayerController — input axes become that intent;
+#   - InputMap.default — physical keys become the :move_x / :move_y actions.
+#
+# ## The shape to take away
+#
+# The hero is a plain Node2D with three components on it. Nothing subclasses a
+# "player" class, and the three components do not know about each other: the
+# controller writes a movement intent, the body turns intent into a step, and
+# the sprite reads the same intent back to pick which way to face. Swapping the
+# controller for Components::WanderController is the whole of turning this into
+# an NPC.
+#
+# The one subclass here is Hero, and it exists only to keep the walker on
+# screen — see the comment on `on_update`.
+
+# lib/ on the load path, so `require 'rgame/game'` resolves the same way it
+# would from an installed gem. examples/ and lib/ are siblings in both, so this
+# line is correct either way.
+$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 # pixels per second
+
+# A Node2D that stays inside the window.
+#
+# Clamping is not something the engine does for you here: a plain CharacterBody
+# moves the node wherever the intent points, because it is meant for an actor in
+# a world with nothing to bump into. Giving it edges is one `on_update` — and in
+# a real game it is usually Components::TileWorld doing it instead, which is
+# what `examples/scroll_map` shows.
+class Hero < RGame::Engine::Node2D
+  # `on_update` is the blank hook: Node2D#update does the bookkeeping and calls
+  # this, so there is no `super` to forget.
+  def on_update(_dt)
+    self.x = x.clamp(0, WIDTH - width)
+    self.y = y.clamp(0, HEIGHT - height)
+  end
+end
+
+# The root. It builds the hero in `initialize`, before anything is in the tree.
+#
+# That matters and is easy to get wrong the other way round: `add_component`
+# attaches immediately once its node is live, and AnimatedSprite's attach looks
+# for a CharacterBody sibling. Build the node whole, then add it — then the
+# order components go on in cannot matter.
+class Root < RGame::Engine::Node2D
+  def initialize
+    super
+    @help = RGame::Engine::Text.new('help.walk')
+    add_node(build_hero)
+  end
+
+  def on_draw(renderer, _view)
+    renderer.text(@help, 12, 12)
+  end
+
+  private
+
+  def build_hero
+    hero = Hero.new(x: (WIDTH - 16) / 2, y: (HEIGHT - 22) / 2)
+    # The sheet is a path relative to the asset manager's root, resolved on
+    # attach — nothing is loaded or registered by hand. hero.json names its own
+    # image and its animations; AnimatedSprite picks between them by reading the
+    # body's intent, so :walk_left and friends are looked up by name.
+    hero.add_component(RGame::Engine::Components::AnimatedSprite.new(sheet: 'hero.json'))
+    hero.add_component(RGame::Engine::Components::CharacterBody.new(speed: SPEED))
+    hero.add_component(RGame::Engine::Components::PlayerController.new)
+    hero
+  end
+end
+
+game = RGame::Game.new(
+  root: Root.new,
+  caption: 'Walk',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES
+)
+
+game.start

data/exe/rgame

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+
+require 'rgame/cli'
+
+exit RGame::CLI.run(ARGV)

data/ext/rgame_core/app/app.c

@@ -95,7 +95,11 @@ struct rgame_app {
     int drawing;
 };
 
-rgame_app *rgame_app_create(int width, int height, const char *title) {
+/* Desktop fullscreen, never a mode change — see the header for why. Named once
+ * so the creation flags and the runtime toggle cannot disagree. */
+#define RGAME_FULLSCREEN_FLAG SDL_WINDOW_FULLSCREEN_DESKTOP
+
+rgame_app *rgame_app_create(int width, int height, const char *title, int fullscreen) {
     if (SDL_Init(SDL_INIT_VIDEO | SDL_INIT_GAMECONTROLLER) != 0) {
         SDL_Log("SDL_Init failed: %s", SDL_GetError());
         return NULL;
@@ -114,7 +118,8 @@ rgame_app *rgame_app_create(int width, int height, const char *title) {
         title,
         SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_CENTERED,
         width, height,
-        SDL_WINDOW_OPENGL | SDL_WINDOW_SHOWN);
+        SDL_WINDOW_OPENGL | SDL_WINDOW_SHOWN |
+            (fullscreen ? RGAME_FULLSCREEN_FLAG : 0u));
     if (!app->window) {
         SDL_Log("SDL_CreateWindow failed: %s", SDL_GetError());
         free(app);
@@ -467,7 +472,13 @@ static void rgame_app_poll_events(rgame_app *app, const rgame_app_callbacks *cb)
             break;
         }
         case SDL_WINDOWEVENT:
-            if (event.window.event == SDL_WINDOWEVENT_RESIZED) {
+            /* SIZE_CHANGED rather than RESIZED, and the difference matters:
+             * SDL sends RESIZED only when something *outside* the program
+             * resized the window, and SIZE_CHANGED for that case as well as for
+             * a size this program asked for. Toggling fullscreen is the second
+             * kind, so a listener on RESIZED alone never hears about it and the
+             * game carries on laying out for the old size. */
+            if (event.window.event == SDL_WINDOWEVENT_SIZE_CHANGED) {
                 /* The viewport is set from the current size every frame, in the
                  * backend's begin_frame, so there is nothing to update here. */
                 if (cb->resize) {
@@ -865,6 +876,25 @@ void rgame_app_set_title(rgame_app *app, const char *title) {
     SDL_SetWindowTitle(app->window, title);
 }
 
+void rgame_app_set_fullscreen(rgame_app *app, int fullscreen) {
+    if (!app) {
+        return;
+    }
+    SDL_SetWindowFullscreen(app->window, fullscreen ? RGAME_FULLSCREEN_FLAG : 0u);
+}
+
+int rgame_app_fullscreen(const rgame_app *app) {
+    if (!app) {
+        return 0;
+    }
+    /* Tested against the whole mask rather than for any bit in it:
+     * SDL_WINDOW_FULLSCREEN_DESKTOP is SDL_WINDOW_FULLSCREEN plus one more,
+     * so `flags & FLAG` is also true of an exclusive-fullscreen window — which
+     * this engine never asks for, but a caller could have set behind our back. */
+    Uint32 flags = SDL_GetWindowFlags(app->window);
+    return (flags & RGAME_FULLSCREEN_FLAG) == RGAME_FULLSCREEN_FLAG;
+}
+
 int rgame_app_input_down(const rgame_app *app, int device, int button_id) {
     return rgame_input_state_down(&app->input, device, button_id);
 }