ee3e4e6 | plum | pyrossh

git clone https://git.pyrossh.dev/plum

A statically typed, imperative programming language inspired by rust, python

ee3e4e6 — Peter John 2026-11-04T14:56:25+05:30

Input steps 1 and 2: shared Input with keys, onInput on actors

Files changed (14) hide show

docs/backlog.md +1 -1
docs/game-scene-styles.md +22 -29
plum-examples/games/functional/game_state_view.plum +70 -34
plum-examples/games/imperative/game.plum +19 -8
plum-examples/games/imperative/game_scene.plum +24 -10
plum-examples/games/imperative/scene.plum +18 -7
plum-examples/games/pure/game_pure_scene.plum +28 -18
plum-game/web-test/fixtures/stress_pure_scene.plum +1 -1
plum-game/web-test/fixtures/stress_state_view.plum +15 -16
plum-std/game/Input.plum +166 -0
plum-std/game/functional/Ui.plum +13 -25
plum-std/game/imperative/Scene.plum +71 -2
plum-std/game/pure/PureScene.plum +83 -79
plum-std/game/pure/SceneInput.plum +118 -65

docs/backlog.md CHANGED Viewed

@@ -39,4 +39,4 @@ Open work, in the order the user queued it, plus smaller items found during buil
 - **Retire PureScene?** — after the component-style functional game, decide whether `std/game/pure` + `games/pure` stay. (Decision record §4b)
 - **`adder(1)(2)`** (calling a returned closure directly) is not supported. (functional-gaps plan)
 - **Fusion past a closure-spec copy on `Nil` miscompiles** — in `drive.rs` `quiet`, resolving `Nil.fold$c0(..)` to `List.fold$c0` (read-only) lets a value move past it, and codegen then fails with `unknown method 'List.fold$c0'` (5 `closure_spec_test` cases). `typeNameMethodKey` skips `$` copies until this is fixed.
-- **Input model** — one shared `Input` (keys included), `onInput` on actors, optional typed `Msg` events; proposal in [game-scene-styles.md](game-scene-styles.md) section 6. Not started.
+- **Input model** — steps 1 (shared `Input`, keys included) and 2 (`onInput` on actors, focus) built 2026-11-04; step 3 (typed `Msg` events) in [game-scene-styles.md](game-scene-styles.md) section 6.

docs/game-scene-styles.md CHANGED Viewed

@@ -55,7 +55,7 @@ Cost: pure updates run in place when the compiler proves uniqueness. Functional
 1. **Fixed timestep.** `plum_bridge.js` passes the real frame time (`dt = (now - last) / 1000`) to `update`. The simulation must instead advance in fixed steps (for example 1/60 s), with the shell accumulating real time and running 0..n steps per frame.
 2. **Recorded seed.** `init` calls `io.randomSeed()`; a replay must record and supply that seed.
-3. **Recorded input.** Keyboard and mouse are read straight from `io` in the game shell (`io.isKeyDown`, `io.mousePos`). Everything the simulation reads from the host must go through one recorded input list per step (see section 6).
+3. **Recorded input.** Done for input: `Input.poll` is the only input read, and the games feed every polled `Input` into their state (section 5). Recording is a matter of saving each step's `Polled.inputs`.
 4. **Host values in state.** The functional game stores the screen size (`sw`, `sh`) and gets `Resize` messages; these must be in the input log too, or kept out of the simulation.
 5. **Checksums.** A per-step hash of the simulation state, to detect desyncs.
@@ -67,25 +67,25 @@ Cost: pure updates run in place when the compiler proves uniqueness. Functional
 **Recommendation:** build deterministic simulation on the functional style first. Its `Msg` stream is already the replay log.
-## 5. Input today
+## 5. Input
-Each style handles input differently:
+Steps 1 and 2 of the proposal below are built (2026-11-04).
+- **One `Input` type** (`std/game/Input`): `PointerDown(x, y) | PointerUp(x, y) | PointerMove(x, y) | KeyDown(key) | KeyUp(key)`. `Input.poll(io, held) -> Polled(inputs, held)` is the only code that reads input from `io`. It compares the host's mouse button and every `Key` code with what was held after the last poll. `Held` (`isDown(key)`, `after(input)`) tracks held keys from the inputs, so games never call `io.isKeyDown`. `input.position()`, `input.through(m)` and `input.isPointer()` are helpers.
+- **One `UiKind`/`UiEvent`**, also in `std/game/Input`, used by both `PureScene` and `Ui`.
 | | Imperative | Pure | Functional |
 |---|---|---|---|
-| Pointer | Game asks `stage.hit(x, y)` and handles the result itself | `Input.poll` -> `stage.frame(dt, inputs)` -> hit path -> `node.route` -> `onPointer` (only `Button` reacts) -> `UiEvent`s | Shell builds a `UiInput` -> `render().hitId(x, y)` -> `Ui.step` -> `UiEvent`s -> `Msg.UiEv` |
-| Keyboard | Read from `io` | Read from `io` in the shell | Read from `io` in the shell, folded into `Tick(dt, ax, ay)` |
-| Event type | none | `UiEvent(id: Int, kind: UiKind)` | its own `UiEvent(id: Int, kind: UiKind)` |
+| Pointer | `stage.input(e)`: the topmost actor under the pointer, then each parent, until one's `onInput` returns true | `stage.input(e)` / `stage.frame(dt, inputs)`: hit path, then `node.route` child first; `Button` reacts, `Custom` asks `actor.onInput` | `state.update(Event(input))` -> `render().hitId(x, y)` -> `Ui.step` -> `UiEvent`s |
+| Keyboard | A press gives the actor the focus; keys go to it, then its parents | A press gives the node the focus; keys go to it (then its ancestors); keys no node consumes come back in `StageHandled.keys` | `Event(KeyDown/KeyUp)` updates `State.held`; the game reads `held.isDown(..)` |
 | Capture (press, drag off, release) | none | yes | yes |
+| Events | `onInput -> Bool` (consumed) | `UiEvent(id, kind)`, `Handled.consumed` | `UiEvent(id, kind)` |
-Problems:
+The example games and fixtures poll once per frame and feed every input in. Nothing else reads input from the host.
-- **Two event types.** `PureScene` and `Ui` each define `UiKind`/`UiEvent`/pointer kinds with the same meaning.
-- **Untyped events.** Games compare integer ids: `if e.id == Id.Restart && e.kind == Click`. Nothing checks that ids are unique or that the game handles every button.
+Remaining problem: events still identify UI elements by integer id (`e.id == Id.Restart && e.kind == Click`); step 3 addresses it.
-- **No input hook for game actors.** In pure, a `Custom` actor has only `act` and `draw`; only the built-in `Button` reacts to the pointer. In imperative, actors have `hit` but no input method.
-- **Keyboard bypasses everything.** It is read directly from `io`, so it is not part of any event stream: there is no focus, and it is not recorded (determinism item 3).
-## 6. Proposal: one input model with `onInput` (not built)
+## 6. Proposal: one input model with `onInput`
 The sketch `scene_graph.pfl` (repo root, not tracked) designs input for a scene2d-style pure scene:
@@ -102,23 +102,17 @@ Its ideas:
 - one `Input` type that includes keys;
 - an overridable `on_input` on every actor;
 - bubbling along the hit path, child first and then each parent, with messages flowing back up;
-- **typed messages**: a button carries the game's own `Msg` value, so the game matches on `StartPressed` instead of comparing ids.
-Plum's pure scene already has the path routing (`route` delivers child first, then each ancestor) and adds pointer capture, which the sketch lacks. The rest maps onto Plum in steps, ordered so each one stands alone.
+- **typed messages**: a button carries the game's own `Msg` value.
-### Step 1: one shared `Input` type, keys included (no generics)
+### Step 1: one shared `Input` type, keys included (built)
-- Move pointer and key input into `std/game/Input.plum`, shared by all styles: `enum Input = PointerDown(x, y) | PointerUp(x, y) | PointerMove(x, y) | KeyDown(key: Int) | KeyUp(key: Int)`. `Input.poll(io, prev) -> Slice[Input]` is the only code that reads input from `io`.
-- Define one shared `UiKind`/`UiEvent`, and delete the duplicates in `PureScene` and `Ui`.
-- Games keep held keys in their state (`Keys`, updated from `KeyDown`/`KeyUp`) instead of calling `io.isKeyDown`.
-- **Gain:** one recorded input list per step (determinism item 3), and one vocabulary across styles.
+`std/game/Input.plum`: see section 5. Gain: one recorded input list per step (determinism item 3), one vocabulary across styles.
-### Step 2: `onInput` for game actors (no generics)
+### Step 2: `onInput` for game actors (built)
-- **Pure:** `trait Actor` gains `fun onInput(self, n: Node, e: Input) -> Handled` (default: unchanged node, no events). `route` calls it on `Custom` nodes along the path, like `onPointer` for `Button`. `Handled` gains `consumed: Bool`, so a child can stop the event reaching its parents (like the DOM's `stopPropagation`).
-- **Imperative:** `trait Actor` gains `fun onInput(self, e: Input) -> Bool` (true = consumed), called child first along the hit path. This is Scene2D's `InputListener` and Flame's `TapCallbacks`.
-- **Functional:** no methods on nodes. Instead, interactive nodes are data, as in Elm: `Tagged(id, child)` stays, and `Ui.step` reports events for it.
-- **Keyboard focus:** `UiState`/`Stage` keep a focused id. `KeyDown` goes to the focused node's `onInput` first; unconsumed keys go to the game.
+- **Pure:** `trait Actor` has `fun onInput(self, n: Node, e: Input, over: Bool) -> Handled` (default: unchanged, nothing raised, not consumed). `Node.onInput` handles `Button` itself and asks a `Custom` node's actor. `Handled` has `consumed: Bool`; `route` skips the ancestors of a node that consumed the input. Only groups have children, so for pointers this matters once groups react; for keys it decides what the game receives.
+- **Imperative:** `trait Actor` has `fun onInput(self, e: Input) -> Bool` (e in the actor's coordinates; true = consumed). `stage.input(e) -> Bool` bubbles from the hit actor through `parent`. A press sets `stage.focus`; keys bubble from the focused actor.
+- **Functional:** no methods on nodes (they are data). Inputs reach `State.update` as `Event(input)` messages.
 ### Step 3 (optional): typed messages instead of ids (needs generics)
@@ -126,11 +120,10 @@ Plum's pure scene already has the path routing (`route` delivers child first, th
 - **Pure:** `Node[Msg]`, `Button(.., onClick: Msg)`, `Actor[Msg]`.
 - **This reopens a decision:** generic `Node[K]`/`Actor[Msg]` was rejected on 2026-11-03 ("Generics can be tried later"), and generic traits are not supported yet. A generic *enum* (`SceneNode[Msg]`) is supported, so the functional style could try it first, but fusion of `render().draw(io)` must be checked on a generic `SceneNode`.
-### Recommendation
+### Next
-1. Do steps 1 and 2: no language work, shared vocabulary, and they unblock deterministic replay.
-2. Try step 3 on the functional style only, once steps 1 and 2 are in, and keep it if fusion still holds.
+1. Step 3 on the functional style only, kept if fusion still holds.
-3. Decide whether PureScene stays (backlog: "Retire PureScene?"). If it is retired, step 2's pure half is not needed.
+2. Decide whether PureScene stays (backlog: "Retire PureScene?").
 ### Open questions

plum-examples/games/functional/game_state_view.plum CHANGED Viewed

@@ -9,15 +9,17 @@
 # nothing is changed in place) and `render(self, ..)` returns its `SceneNode` picture.
 # `State` is the same for the whole game: the components, the score, a `Random` and the
 # screen size. `Msg` is what can happen to it (a tick of time, a resize, a restart, a
-# Ui event); `State.update(msg)` is a short sequence of named steps and
+# player input, a Ui event); `State.update(msg)` is a short sequence of named steps and
 # `State.render()` builds a fresh picture every frame, which `SceneNode.draw` interprets
 # (the compiler fuses the two, so the tree is never built). There is no retained
-# scene: the restart button is a `Ui.button` in the picture; the host turns the mouse
+# scene: the restart button is a `Ui.button` in the picture. The host polls the
+# player's input once a frame (`Input.poll`, its only input read) and sends each
+# `Input` to the state as an `Event`: keys update the held keys that steer the ship,
-# into a `UiInput`, finds what is under it with `SceneNode.hitId` on the picture the
+# and a pointer input finds what is under it with `SceneNode.hitId` on the picture the
 # player is looking at, runs `Ui.step`, and feeds each `UiEvent` to `State.update`.
 # The game-over title and the ship's hurt flash are `Anim`s of time since they began.
-# The `World` record is the host shell: it holds the current `State`, reads the keyboard
+# The `World` record is the host shell: it holds the current `State`, polls the
-# and mouse into messages, and plays sounds.
+# keyboard and mouse into messages, and plays sounds.
 module game_state_view
 import std/Str
 import std/Int
@@ -32,6 +34,7 @@ import std/game/Game
 import std/game/functional/FunctionalScene
 import std/game/functional/Anim
 import std/game/functional/Ui
+import std/game/Input
 import std/Io
 primitive Rules =
@@ -253,6 +256,7 @@ enum Msg =
   | Tick(dt: Float, ax: Float, ay: Float)
   | Resize(w: Float, h: Float)
   | Restart(seed: Int)
+  | Event(input: Input)
   | UiEv(event: UiEvent)
 # Everything that changes during a run. `sheet` and `target` are resource handles
@@ -272,6 +276,7 @@ record State(
   hurtAt: Float,
   overAt: Float,
   ui: UiState,
+  held: Held,
   sw: Float,
   sh: Float,
   sheet: Int,
@@ -295,6 +300,7 @@ record State(
       hurtAt: -1.0,
       overAt: -1.0,
       ui: Ui.init(),
+      held: Held.none(),
       sw: sw,
       sh: sh,
       sheet: sheet,
@@ -307,6 +313,7 @@ record State(
     Tick(dt, ax, ay) => self.tick(dt, ax, ay)
     Resize(w, h) => State(..self, sw: w, sh: h)
     Restart(seed) => self.restarted(seed)
+    Event(input) => self.onInput(input)
     UiEv(event) => self.onUi(event)
   # One frame of time. Once the game is over the actors only animate.
@@ -391,7 +398,24 @@ record State(
   fun restarted(self, seed: Int) -> State =
     fresh := State.start(seed, self.best.max(self.score), self.sheet, self.target, self.sw, self.sh)
-    State(..fresh, ui: self.ui)
+    State(..fresh, ui: self.ui, held: self.held)
+  # A player input: keys update the held keys (Enter or R restarts a finished game),
+  # a pointer input goes through the Ui.
+  fun onInput(self, e: Input) -> State =
+    s := State(..self, held: self.held.after(e))
+    if e.isPointer()
+      return s.feed(e)
+    if s.over && isRestartKey(e)
+      return s.restarted(s.rng.nextInt().value)
+    s
+  # The steering axes from the held arrow or WASD keys.
+  fun axisX(self) -> Float =
+    axis(self.held.isDown(Key.Left) || self.held.isDown(Key.KeyA), self.held.isDown(Key.Right) || self.held.isDown(Key.KeyD))
+  fun axisY(self) -> Float =
+    axis(self.held.isDown(Key.Up) || self.held.isDown(Key.KeyW), self.held.isDown(Key.Down) || self.held.isDown(Key.KeyS))
   # A click on the restart button restarts a finished game; other events change nothing.
   fun onUi(self, e: UiEvent) -> State =
@@ -399,8 +423,9 @@ record State(
   # One pointer input: finds what is under it in the current picture, runs the Ui, and
   # feeds each raised event to `update`.
-  fun feed(self, input: UiInput) -> State =
+  fun feed(self, input: Input) -> State =
+    pos := input.position() ?: return self
-    r := Ui.step(self.ui, input, self.render().hitId(input.x, input.y))
+    r := Ui.step(self.ui, input, self.render().hitId(pos.x, pos.y))
     r.events.fold(State(..self, ui: r.ui), |s, e| s.update(UiEv(event: e)))
   # --- render ---
@@ -481,17 +506,14 @@ record State(
   fun onRestart(self, x: Float, y: Float) -> Bool =
     {self.render().hitId(x, y) ?: -1} == Id.Restart
+# Enter or R going down.
-fun pointerKind(down: Bool, wasDown: Bool) -> UiInputKind =
+fun isRestartKey(e: Input) -> Bool = match e
-  if down && !wasDown
-    PointerDown
-  else if !down && wasDown
+  KeyDown(k) => k == Key.Enter || k == Key.KeyR
-    PointerUp
-  else
-    PointerMove
+  _ => false
 # --- the host shell ---
-record World(mut state: State, mut wasDown: Bool, pickupSound: Int, hitSound: Int, overSound: Int, musicSound: Int)
+record World(mut state: State, mut held: Held, pickupSound: Int, hitSound: Int, overSound: Int, musicSound: Int)
 fun musicVolume() -> Float =
   0.3
@@ -505,7 +527,7 @@ export fun init(io: Io) -> World =
   s := State.start(io.randomSeed(), 0, io.textureLoad("sprites.png"), io.textureCreate(1600, 1200), Rules.ArenaW, Rules.ArenaH)
   w := World(
     state: s,
-    wasDown: false,
+    held: Held.none(),
     pickupSound: io.soundLoad("pickup.wav"),
     hitSound: io.soundLoad("hit.wav"),
     overSound: io.soundLoad("gameover.wav"),
@@ -522,25 +544,20 @@ fun axis(negative: Bool, positive: Bool) -> Float =
   else
     0.0
+# Polls the host once (the only input read), sends every input to the state, then
+# one tick steered by the held keys; plays sounds for what changed.
 export fun update(io: Io, w: World, dt: Float) =
+  polled := Input.poll(io, w.held)
+  w.held = polled.held
   s := w.state.update(Resize(w: io.screenWidth(), h: io.screenHeight()))
+  clicked := s
-  down := io.isMouseDown(0)
+  for i := range polled.inputs.length()
-  m := io.mousePos()
-  clicked := s.feed(UiInput(kind: pointerKind(down, w.wasDown), x: m.x, y: m.y))
+    clicked = clicked.update(Event(input: polled.inputs.at(i)))
-  w.wasDown = down
   if s.over && !clicked.over
     w.state = clicked
     startMusic(io, w)
     return
-  if clicked.over && {io.isKeyPressed(Key.Enter) || io.isKeyPressed(Key.KeyR)}
-    w.state = clicked.update(Restart(seed: clicked.rng.nextInt().value))
-    startMusic(io, w)
-    return
-  left := io.isKeyDown(Key.Left) || io.isKeyDown(Key.KeyA)
-  right := io.isKeyDown(Key.Right) || io.isKeyDown(Key.KeyD)
-  up := io.isKeyDown(Key.Up) || io.isKeyDown(Key.KeyW)
-  downKey := io.isKeyDown(Key.Down) || io.isKeyDown(Key.KeyS)
-  t := clicked.update(Tick(dt: dt, ax: axis(left, right), ay: axis(up, downKey)))
+  t := clicked.update(Tick(dt: dt, ax: clicked.axisX(), ay: clicked.axisY()))
   if t.score > clicked.score
     io.soundPlay(w.pickupSound, 0.8)
   if t.lives < clicked.lives
@@ -807,17 +824,17 @@ test "view_node_count"
 test "restart_click_through_ui"
   e := emptyState()
   s := forceOver(State(..e, score: 90))
-  down := s.feed(UiInput(kind: PointerDown, x: 400.0, y: 364.0))
+  down := s.feed(PointerDown(x: 400.0, y: 364.0))
   assert down.over
   assert Ui.pressed(down.ui, Id.Restart)
-  up := down.feed(UiInput(kind: PointerUp, x: 400.0, y: 364.0))
+  up := down.feed(PointerUp(x: 400.0, y: 364.0))
   assert !up.over
   assert up.score == 0
   assert up.best == 90
   assert up.lives == Rules.StartLives
-  off := s.feed(UiInput(kind: PointerDown, x: 400.0, y: 364.0)).feed(UiInput(kind: PointerUp, x: 100.0, y: 100.0))
+  off := s.feed(PointerDown(x: 400.0, y: 364.0)).feed(PointerUp(x: 100.0, y: 100.0))
   assert off.over
-  miss := s.feed(UiInput(kind: PointerDown, x: 100.0, y: 100.0)).feed(UiInput(kind: PointerUp, x: 100.0, y: 100.0))
+  miss := s.feed(PointerDown(x: 100.0, y: 100.0)).feed(PointerUp(x: 100.0, y: 100.0))
   assert miss.over
 test "hit_flash_pose_at_fixed_times"
@@ -834,3 +851,22 @@ test "title_anim_pose_at_fixed_times"
   assert near(titlePose(0.8).scaleX, 1.17)
   assert near(titlePose(1.3).scaleX, 1.3)
   assert near(titlePose(1.8).scaleY, 1.17)
+test "held keys from input events steer the ship"
+  s := emptyState().update(Event(input: KeyDown(key: Key.Left))).update(Event(input: KeyDown(key: Key.KeyS)))
+  assert s.axisX() == -1.0
+  assert s.axisY() == 1.0
+  t := s.update(Event(input: KeyUp(key: Key.Left)))
+  assert t.axisX() == 0.0
+  assert t.axisY() == 1.0
+test "enter restarts a finished game and nothing else"
+  playing := emptyState().update(Event(input: KeyDown(key: Key.Enter)))
+  assert playing.score == 0
+  assert !playing.over
+  e := emptyState()
+  s := forceOver(State(..e, score: 40))
+  r := s.update(Event(input: KeyDown(key: Key.Enter)))
+  assert !r.over
+  assert r.best == 40
+  assert r.held.isDown(Key.Enter)

plum-examples/games/imperative/game.plum CHANGED Viewed

@@ -16,6 +16,7 @@ import std/Random
 import std/game/Vec2
 import std/game/Color
 import std/game/Game
+import std/game/Input
 import std/Io
 primitive Rules =
@@ -47,6 +48,7 @@ record World(
   mut hurt: Float,
   mut clock: Float,
   mut over: Bool,
+  mut held: Held,
   sheet: Int,
   pickupSound: Int,
   hitSound: Int,
@@ -57,7 +59,7 @@ record World(
     ship := Body(x: Rules.ArenaW / 2.0, y: Rules.ArenaH / 2.0, vx: 0.0, vy: 0.0, angle: 0.0)
     w := World(
       ship: ship, orbs: Slice[Body](), mines: Slice[Body](), rng: Random.seeded(seed), score: 0, best: 0,
-      lives: Rules.StartLives, hurt: 0.0, clock: 0.0, over: false, sheet: sheet,
+      lives: Rules.StartLives, hurt: 0.0, clock: 0.0, over: false, held: Held.none(), sheet: sheet,
       pickupSound: -1, hitSound: -1, overSound: -1, musicSound: -1)
     for i := range Rules.OrbCount
       sp := spawn(w.rng, ship, 120.0, 40.0)
@@ -165,14 +167,23 @@ record World(
       twinkle := 0.25 + 0.2 * Math.sin(self.clock * 2.0 + Float(i))
       io.drawCircle(sx, sy, 1.0 + Float(i % 3) * 0.5, Color(r: 0.7, g: 0.8, b: 1.0, a: twinkle))
+  # Polls the host once (the only input read): Enter or R restarts a finished game,
+  # the held keys steer.
   fun update(self, io: Io, dt: Float) =
+    polled := Input.poll(io, self.held)
+    self.held = polled.held
+    for i := range polled.inputs.length()
+      match polled.inputs.at(i)
+        KeyDown(k) =>
-    if self.over && {io.isKeyPressed(Key.Enter) || io.isKeyPressed(Key.KeyR)}
+          if self.over && {k == Key.Enter || k == Key.KeyR}
-      self.restart()
+            self.restart()
-      self.startMusic(io)
+            self.startMusic(io)
+        _ => 0
+    h := self.held
-    left := io.isKeyDown(Key.Left) || io.isKeyDown(Key.KeyA)
+    left := h.isDown(Key.Left) || h.isDown(Key.KeyA)
-    right := io.isKeyDown(Key.Right) || io.isKeyDown(Key.KeyD)
+    right := h.isDown(Key.Right) || h.isDown(Key.KeyD)
-    up := io.isKeyDown(Key.Up) || io.isKeyDown(Key.KeyW)
+    up := h.isDown(Key.Up) || h.isDown(Key.KeyW)
-    down := io.isKeyDown(Key.Down) || io.isKeyDown(Key.KeyS)
+    down := h.isDown(Key.Down) || h.isDown(Key.KeyS)
     score := self.score
     lives := self.lives
     self.step(axis(left, right), axis(up, down), dt)

plum-examples/games/imperative/game_scene.plum CHANGED Viewed

@@ -31,6 +31,7 @@ import std/game/Vec2
 import std/game/Color
 import std/game/Game
 import std/game/imperative/Scene
+import std/game/Input
 import std/Io
 primitive Rules =
@@ -237,8 +238,13 @@ record Star(Actor(x, y, width, height), seed: Float, mut clock: Float) =
 # The whole game: it embeds the Stage (camera and root) and has its layers, typed handles to the actors the rules
 # touch, and the run's state. `mines` and `orbs` are the layer Groups; `mineList`
 # and `orbList` are the same actors, typed.
+# Enter or R going down.
+fun isRestartKey(e: Input) -> Bool = match e
+  KeyDown(k) => k == Key.Enter || k == Key.KeyR
+  _ => false
 record World(
-  Stage(camX, camY, camScale),
+  Stage(camX, camY, camScale, focus),
   ship: Ship,
   mines: Group,
   orbs: Group,
@@ -254,6 +260,7 @@ record World(
   mut lives: Int,
   mut over: Bool,
   mut clock: Float,
+  mut held: Held,
   sheet: Int,
   pickupSound: Int,
   hitSound: Int,
@@ -290,9 +297,9 @@ record World(
     overlay.add(Text.create("Press Enter to play again", 24.0, Color.White).at(270.0, 316.0))
     hud.add(overlay)
     w := World(
-      camX: 0.0, camY: 0.0, camScale: 1.0, ship: ship, mines: mines, orbs: orbs, mineList: Slice[Mine](), orbList: Slice[Orb](),
+      camX: 0.0, camY: 0.0, camScale: 1.0, focus: null, ship: ship, mines: mines, orbs: orbs, mineList: Slice[Mine](), orbList: Slice[Orb](),
       overlay: overlay, scoreText: scoreText, bestText: bestText, lifeIcons: icons,
-      rng: Random.seeded(seed), score: 0, best: 0, lives: Rules.StartLives, over: false, clock: 0.0, sheet: sheet,
+      rng: Random.seeded(seed), score: 0, best: 0, lives: Rules.StartLives, over: false, clock: 0.0, held: Held.none(), sheet: sheet,
       pickupSound: -1, hitSound: -1, overSound: -1, musicSound: -1)
     w.root.add(Rect.create(Rules.ArenaW, Rules.ArenaH, Color.rgb(0.07, 0.08, 0.16)))
     w.root.add(stars)
@@ -412,14 +419,21 @@ record World(
     io.soundStop(self.musicSound)
     io.soundLoop(self.musicSound, musicVolume())
+  # Polls the host once (the only input read), offers each input to the stage and
+  # handles what no actor consumed: Enter or R restarts a finished game.
   fun update(self, io: Io, dt: Float) =
+    polled := Input.poll(io, self.held)
+    self.held = polled.held
+    for i := range polled.inputs.length()
+      e := polled.inputs.at(i)
-    if self.over && {io.isKeyPressed(Key.Enter) || io.isKeyPressed(Key.KeyR)}
+      if !self.input(e) && self.over && isRestartKey(e)
-      self.restart()
+        self.restart()
-      self.startMusic(io)
+        self.startMusic(io)
+    h := self.held
-    left := io.isKeyDown(Key.Left) || io.isKeyDown(Key.KeyA)
+    left := h.isDown(Key.Left) || h.isDown(Key.KeyA)
-    right := io.isKeyDown(Key.Right) || io.isKeyDown(Key.KeyD)
+    right := h.isDown(Key.Right) || h.isDown(Key.KeyD)
-    up := io.isKeyDown(Key.Up) || io.isKeyDown(Key.KeyW)
+    up := h.isDown(Key.Up) || h.isDown(Key.KeyW)
-    down := io.isKeyDown(Key.Down) || io.isKeyDown(Key.KeyS)
+    down := h.isDown(Key.Down) || h.isDown(Key.KeyS)
     score := self.score
     lives := self.lives
     self.step(axis(left, right), axis(up, down), dt)

plum-examples/games/imperative/scene.plum CHANGED Viewed

@@ -21,6 +21,7 @@ import std/game/Vec2
 import std/game/Color
 import std/game/Game
 import std/game/imperative/Scene
+import std/game/Input
 import std/Io
 primitive Layout =
@@ -102,6 +103,7 @@ record Sky(
   mut selected: Int,
   mut clock: Float,
   mut paused: Bool,
+  mut held: Held,
   map: Int)
 # A body sprite and its (hidden) halo in a group `slot` centred on the group's own
@@ -133,7 +135,7 @@ fun newSky(sheet: Int) -> Sky =
   label.y = 12.0
   sky := Sky(
     stage: stage, bodies: Slice[Actor](), halos: Slice[Actor](), names: Slice[Str](),
-    sun: sun, label: label, crowd: Group(), front: null, selected: -1, clock: 0.0, paused: false, map: -1)
+    sun: sun, label: label, crowd: Group(), front: null, selected: -1, clock: 0.0, paused: false, held: Held.none(), map: -1)
   # faint orbit rings, added first so every body draws (and is hit) above them
   for i := range Layout.Planets
     r := 90.0 + Float(i) * 60.0
@@ -223,15 +225,24 @@ export fun init(io: Io) -> Sky =
   sky.map = io.textureCreate(Layout.MapW, Layout.MapH)
   sky
+# Polls the host once (the only input read): Space pauses, a press selects a body.
 export fun update(io: Io, sky: Sky, dt: Float) =
+  polled := Input.poll(io, sky.held)
+  sky.held = polled.held
+  for i := range polled.inputs.length()
+    match polled.inputs.at(i)
+      KeyDown(k) =>
-  if io.isKeyPressed(Key.Space)
+        if k == Key.Space
-    sky.paused = !sky.paused
+          sky.paused = !sky.paused
+      _ => 0
   tick(sky, dt)
   fit(sky, io.screenWidth(), io.screenHeight())
-  if io.isMousePressed(Mouse.Left)
+  for i := range polled.inputs.length()
-    m := io.mousePos()
+    match polled.inputs.at(i)
+      PointerDown(x, y) =>
-    p := sky.stage.screenToStage(m.x, m.y)
+        p := sky.stage.screenToStage(x, y)
-    clickAt(sky, p.x, p.y)
+        clickAt(sky, p.x, p.y)
+      _ => 0
 # Redraws the minimap texture (every body as a dot, the selected one highlighted)
 # and shows it in the bottom-right corner of the screen.

plum-examples/games/pure/game_pure_scene.plum CHANGED Viewed

@@ -28,6 +28,7 @@ import std/game/Game
 import std/game/pure/Actions
 import std/game/pure/PureScene
 import std/game/pure/SceneInput
+import std/game/Input
 import std/Io
 primitive Rules =
@@ -377,7 +378,7 @@ record World(
   mut lives: Int,
   mut over: Bool,
   mut clock: Float,
-  mut wasDown: Bool,
+  mut held: Held,
   sheet: Int,
   mut pickupSound: Int,
   mut hitSound: Int,
@@ -390,16 +391,16 @@ fun newWorld(seed: Int, sheet: Int) -> World =
   next := spots.rng
   World(
     stage: Stage.create(buildRoot(spots, sheet, 0)), ship: ship, rng: next, mines: mineCount(0), score: 0, best: 0,
-    lives: Rules.StartLives, over: false, clock: 0.0, wasDown: false, sheet: sheet,
+    lives: Rules.StartLives, over: false, clock: 0.0, held: Held.none(), sheet: sheet,
     pickupSound: -1, hitSound: -1, overSound: -1, musicSound: -1)
 fun modifyRoot(st: Stage, id: Int, f: fn(Node) -> Node) -> Stage =
   match st
-    Stage(root, camera, captured) => Stage(root: root.modify(id, f), camera: camera, captured: captured)
+    Stage(root, camera, captured, focus) => Stage(root: root.modify(id, f), camera: camera, captured: captured, focus: focus)
 fun withCamera(st: Stage, camera: Affine) -> Stage =
   match st
-    Stage(root, _, captured) => Stage(root: root, camera: camera, captured: captured)
+    Stage(root, _, captured, focus) => Stage(root: root, camera: camera, captured: captured, focus: focus)
 fun swap(w: World, id: Int, f: fn(Node) -> Node) =
   w.stage = modifyRoot(w.stage, id, f)
@@ -415,7 +416,7 @@ fun restart(w: World) =
   spots := startSpots(w.rng, w.ship)
   next := spots.rng
   w.rng = next
-  w.stage = Stage(root: buildRoot(spots, w.sheet, w.best), camera: w.stage.camera, captured: null)
+  w.stage = Stage(root: buildRoot(spots, w.sheet, w.best), camera: w.stage.camera, captured: null, focus: null)
 # Copies the score, best score, lives and game-over panel into the HUD actors.
 fun syncHud(w: World) =
@@ -569,16 +570,25 @@ fun axis(negative: Bool, positive: Bool) -> Float =
   else
     0.0
+# Enter or R going down.
+fun isRestartKey(e: Input) -> Bool = match e
+  KeyDown(k) => k == Key.Enter || k == Key.KeyR
+  _ => false
+# Polls the host once (the only input read); the held keys steer the ship.
 export fun update(io: Io, w: World, dt: Float) =
+  polled := Input.poll(io, w.held)
+  inputs := polled.inputs
+  w.held = polled.held
+  for i := range inputs.length()
-  if w.over && {io.isKeyPressed(Key.Enter) || io.isKeyPressed(Key.KeyR)}
+    if w.over && isRestartKey(inputs.at(i))
-    restart(w)
+      restart(w)
-    startMusic(io, w)
+      startMusic(io, w)
-  inputs := Input.poll(io, w.wasDown)
-  w.wasDown = io.isMouseDown(0)
+  h := w.held
-  left := io.isKeyDown(Key.Left) || io.isKeyDown(Key.KeyA)
+  left := h.isDown(Key.Left) || h.isDown(Key.KeyA)
-  right := io.isKeyDown(Key.Right) || io.isKeyDown(Key.KeyD)
+  right := h.isDown(Key.Right) || h.isDown(Key.KeyD)
-  up := io.isKeyDown(Key.Up) || io.isKeyDown(Key.KeyW)
+  up := h.isDown(Key.Up) || h.isDown(Key.KeyW)
-  down := io.isKeyDown(Key.Down) || io.isKeyDown(Key.KeyS)
+  down := h.isDown(Key.Down) || h.isDown(Key.KeyS)
   score := w.score
   lives := w.lives
   restarted := advance(w, axis(left, right), axis(up, down), dt, inputs)
@@ -825,8 +835,8 @@ test "restart_button_click_restarts"
   w.score = 30
   forceOver(w)
   assert find(w.stage.root, Id.Restart).visible
-  down := Input(kind: PointerDown, x: 400.0, y: 364.0)
+  down := PointerDown(x: 400.0, y: 364.0)
-  up := Input(kind: PointerUp, x: 400.0, y: 364.0)
+  up := PointerUp(x: 400.0, y: 364.0)
   taps := Slice[Input]()
   taps.push(down)
   taps.push(up)
@@ -841,8 +851,8 @@ test "a click on the restart button while playing does nothing"
   w := emptyWorld()
   w.score = 30
   taps := Slice[Input]()
-  taps.push(Input(kind: PointerDown, x: 400.0, y: 364.0))
+  taps.push(PointerDown(x: 400.0, y: 364.0))
-  taps.push(Input(kind: PointerUp, x: 400.0, y: 364.0))
+  taps.push(PointerUp(x: 400.0, y: 364.0))
   restarted := advance(w, 0.0, 0.0, 0.016, taps)
   assert !restarted
   assert w.score == 30

plum-game/web-test/fixtures/stress_pure_scene.plum CHANGED Viewed

@@ -104,7 +104,7 @@ fun buildWorld(sheet: Int, white: Int) -> World =
     root.push(countLabel(30000 + i, i, Float(i * 30 % Counts.WorldW), Float(i * 17 % Counts.WorldH)))
   top := Node.group(1, 0.0, 0.0, Float(Counts.WorldW), Float(Counts.WorldH), root)
   cam := Affine(a: 0.8, b: 0.0, c: 0.0, d: 0.8, e: 0.0, f: 0.0)
-  World(sheet: sheet, stage: Stage(root: top, camera: cam, captured: null))
+  World(sheet: sheet, stage: Stage(root: top, camera: cam, captured: null, focus: null))
 fun whiteTexture(io: Io) -> Int =
   t := io.textureCreate(1, 1)

plum-game/web-test/fixtures/stress_state_view.plum CHANGED Viewed

@@ -11,7 +11,7 @@
 # plus 200 animated sprites (Pulsers, pose = Anim.at(anim, clock - start)) and
 # 20 Ui.button buttons (tagged ids 40000..40019, screen space, outside the camera).
 # `State.ui` is a Ui.UiState fed by mouse input: update turns the mouse into a
-# UiInput, hit-tests the button layer with SceneNode.hitId, and calls Ui.step.
+# shared Input, hit-tests the button layer with SceneNode.hitId, and calls Ui.step.
 module stress_state_view
 import std/Str
 import std/Int
@@ -24,6 +24,7 @@ import std/game/Game
 import std/game/functional/FunctionalScene
 import std/game/functional/Anim
 import std/game/functional/Ui
+import std/game/Input
 import std/Io
 primitive Counts =
@@ -142,8 +143,9 @@ fun countClicks(es: List[UiEvent]) -> Int = match es
   Cons(e, t) => {if e.kind == Click then 1 else 0} + countClicks(t)
 # Feeds one pointer input through Ui.step against the button layer.
-fun stepUi(s: State, input: UiInput) -> State =
+fun stepUi(s: State, input: Input) -> State =
+  pos := input.position() ?: return s
-  hit := buttonsView(s.ui).hitId(input.x, input.y)
+  hit := buttonsView(s.ui).hitId(pos.x, pos.y)
   r := Ui.step(s.ui, input, hit)
   State(
     sheet: s.sheet, white: s.white, spinners: s.spinners, drifters: s.drifters, counters: s.counters,
@@ -199,21 +201,18 @@ fun whiteTexture(io: Io) -> Int =
   io.renderTarget(-1)
   t
-record World(mut state: State, mut wasDown: Bool)
+record World(mut state: State, mut held: Held)
 export fun init(io: Io) -> World =
-  World(state: newState(io.textureLoad("sprites.png"), whiteTexture(io)), wasDown: false)
+  World(state: newState(io.textureLoad("sprites.png"), whiteTexture(io)), held: Held.none())
 export fun update(io: Io, w: World, dt: Float) =
+  polled := Input.poll(io, w.held)
+  w.held = polled.held
-  m := io.mousePos()
+  s := step(w.state, dt)
-  down := io.isMouseDown(0)
+  for i := range polled.inputs.length()
-  kind := PointerMove
-  if down && !w.wasDown
-    kind = PointerDown
-  else if !down && w.wasDown
+    s = stepUi(s, polled.inputs.at(i))
-    kind = PointerUp
-  w.wasDown = down
+  w.state = s
-  w.state = stepUi(step(w.state, dt), UiInput(kind: kind, x: m.x, y: m.y))
 export fun draw(io: Io, w: World) =
   io.clear(Color.rgb(0.05, 0.06, 0.1))
@@ -249,8 +248,8 @@ test "view has one node per actor"
 test "button click counts and pulsers animate"
   s := newState(0, 0)
-  down := stepUi(s, UiInput(kind: PointerDown, x: 20.0, y: 20.0))
+  down := stepUi(s, PointerDown(x: 20.0, y: 20.0))
-  up := stepUi(down, UiInput(kind: PointerUp, x: 20.0, y: 20.0))
+  up := stepUi(down, PointerUp(x: 20.0, y: 20.0))
   assert up.clicks == 1
   assert Ui.hovered(up.ui, 40000)
   p := newPulser(0)

plum-std/game/Input.plum ADDED Viewed

@@ -0,0 +1,166 @@
+module std
+import std/Int
+import std/Float
+import std/Slice
+import std/game/Vec2
+import std/game/Affine
+import std/game/Game
+import std/Io
+# Player input shared by every scene style. `Input.poll` is the only code that reads
+# input from the host: a game that feeds every polled `Input` into its state reads
+# nothing else, so a recorded list of inputs replays the game exactly (see
+# docs/game-scene-styles.md, "Determinism").
+# One input: a pointer event in screen pixels, or a key going down or up.
+enum Input =
+  | PointerDown(x: Float, y: Float)
+  | PointerUp(x: Float, y: Float)
+  | PointerMove(x: Float, y: Float)
+  | KeyDown(key: Int)
+  | KeyUp(key: Int)
+  # This frame's inputs: the host's mouse button and keys compared with `prev`, what
+  # was held after the last poll. One pointer input (down, up or move) comes first,
+  # then a KeyDown or KeyUp for each key that changed, in key-code order.
+  fun poll(io: Io, prev: Held) -> Polled =
+    out := Slice[Input]()
+    m := io.mousePos()
+    down := io.isMouseDown(Mouse.Left)
+    if down && !prev.mouse
+      out.push(PointerDown(x: m.x, y: m.y))
+    else if !down && prev.mouse
+      out.push(PointerUp(x: m.x, y: m.y))
+    else
+      out.push(PointerMove(x: m.x, y: m.y))
+    keys := Slice[Int]()
+    codes := Input.keyCodes()
+    for i := range codes.length()
+      k := codes.at(i)
+      now := io.isKeyDown(k)
+      was := prev.isDown(k)
+      if now
+        keys.push(k)
+      if now && !was
+        out.push(KeyDown(key: k))
+      if !now && was
+        out.push(KeyUp(key: k))
+    Polled(inputs: out, held: Held(mouse: down, keys: keys))
+  # Every `Key` code in std/game/Game, in increasing order.
+  fun keyCodes() -> Slice[Int] =
+    out := Slice(Key.Space)
+    for i := range 10
+      out.push(Key.Num0 + i)
+    for i := range 26
+      out.push(Key.KeyA + i)
+    for i := range 4
+      out.push(Key.Escape + i)
+    for i := range 4
+      out.push(Key.Right + i)
+    out.push(Key.LeftShift)
+    out.push(Key.LeftControl)
+    out
+  # The pointer position, or null for a key.
+  fun position(self) -> Vec2? = match self
+    PointerDown(x, y) => Vec2(x: x, y: y)
+    PointerUp(x, y) => Vec2(x: x, y: y)
+    PointerMove(x, y) => Vec2(x: x, y: y)
+    _ => null
+  # The input with its position seen through `m` (a key is unchanged).
+  fun through(self, m: Affine) -> Input = match self
+    PointerDown(x, y) => Input.pointerAt(PointerDown(x: x, y: y), m.apply(Vec2(x: x, y: y)))
+    PointerUp(x, y) => Input.pointerAt(PointerUp(x: x, y: y), m.apply(Vec2(x: x, y: y)))
+    PointerMove(x, y) => Input.pointerAt(PointerMove(x: x, y: y), m.apply(Vec2(x: x, y: y)))
+    _ => self
+  # The pointer input `e` (same kind) at `p`.
+  fun pointerAt(e: Input, p: Vec2) -> Input = match e
+    PointerDown(_, _) => PointerDown(x: p.x, y: p.y)
+    PointerUp(_, _) => PointerUp(x: p.x, y: p.y)
+    _ => PointerMove(x: p.x, y: p.y)
+  fun isPointer(self) -> Bool =
+    self.position() != null
+# What is held: the left mouse button and the keys that are down.
+record Held(mouse: Bool, keys: Slice[Int]) =
+  fun none() -> Held =
+    Held(mouse: false, keys: Slice[Int]())
+  fun isDown(self, key: Int) -> Bool =
+    self.keys.contains(key)
+  # What is held after `e`: KeyDown adds its key, KeyUp removes it, a pointer down
+  # or up sets `mouse`.
+  fun after(self, e: Input) -> Held = match e
+    KeyDown(key) => if self.isDown(key) then self else Held(mouse: self.mouse, keys: self.keysWith(key, true))
+    KeyUp(key) => Held(mouse: self.mouse, keys: self.keysWith(key, false))
+    PointerDown(_, _) => Held(mouse: true, keys: self.keys)
+    PointerUp(_, _) => Held(mouse: false, keys: self.keys)
+    _ => self
+  # A fresh copy of the held keys with `key` added (`add`) or removed.
+  fun keysWith(self, key: Int, add: Bool) -> Slice[Int] =
+    out := Slice[Int]()
+    for i := range self.keys.length()
+      if self.keys.at(i) != key
+        out.push(self.keys.at(i))
+    if add
+      out.push(key)
+    out
+# A poll's inputs and what is held after them (pass it to the next poll).
+record Polled(inputs: Slice[Input], held: Held)
+# What happened to a UI element: pressed on it, released after a press on it,
+# clicked (pressed and released on it), or the pointer entered or left it.
+enum UiKind =
+  | Press
+  | Release
+  | Click
+  | Enter
+  | Exit
+record UiEvent(id: Int, kind: UiKind)
+fun inHeld(keys: Slice[Int]) -> Held =
+  Held(mouse: false, keys: keys)
+test "held_after_tracks_keys_and_mouse"
+  h := Held.none().after(KeyDown(key: Key.KeyA)).after(KeyDown(key: Key.Left)).after(PointerDown(x: 1.0, y: 2.0))
+  assert h.isDown(Key.KeyA)
+  assert h.isDown(Key.Left)
+  assert h.mouse
+  h2 := h.after(KeyUp(key: Key.KeyA)).after(PointerUp(x: 1.0, y: 2.0))
+  assert !h2.isDown(Key.KeyA)
+  assert h2.isDown(Key.Left)
+  assert !h2.mouse
+  assert h.isDown(Key.KeyA)
+test "key_down_twice_keeps_one_entry"
+  h := Held.none().after(KeyDown(key: Key.KeyA)).after(KeyDown(key: Key.KeyA))
+  assert h.keys.length() == 1
+test "key_codes_cover_every_key_constant"
+  codes := Input.keyCodes()
+  assert codes.length() == 47
+  assert inHeld(codes).isDown(Key.Space)
+  assert inHeld(codes).isDown(Key.Num9)
+  assert inHeld(codes).isDown(Key.KeyZ)
+  assert inHeld(codes).isDown(Key.Backspace)
+  assert inHeld(codes).isDown(Key.Up)
+  assert inHeld(codes).isDown(Key.LeftControl)
+test "through_moves_pointers_only"
+  m := Affine(a: 1.0, b: 0.0, c: 0.0, d: 1.0, e: 10.0, f: 0.0)
+  if p := PointerDown(x: 1.0, y: 2.0).through(m).position()
+    assert p.x == 11.0
+    assert p.y == 2.0
+  else
+    assert false
+  assert KeyDown(key: 5).through(m).position() == null
+  assert !KeyDown(key: 5).isPointer()
+  assert PointerMove(x: 0.0, y: 0.0).isPointer()

plum-std/game/functional/Ui.plum CHANGED Viewed

@@ -6,6 +6,7 @@ import std/Slice
 import std/List
 import std/game/Color
 import std/game/functional/FunctionalScene
+import std/game/Input
 # A pure UI layer for the functional scene style. `Ui.step` takes the previous
 # UiState, one pointer input and the id under the pointer (from SceneNode.hitId on
@@ -13,22 +14,6 @@ import std/game/functional/FunctionalScene
 # button rules as PureScene: Down captures the pressed id; while captured only
 # that id gets Enter/Exit; Up releases (Click only when still over it).
-enum UiKind =
-  | Press
-  | Release
-  | Click
-  | Enter
-  | Exit
-record UiEvent(id: Int, kind: UiKind)
-enum UiInputKind =
-  | PointerDown
-  | PointerUp
-  | PointerMove
-record UiInput(kind: UiInputKind, x: Float, y: Float)
 record UiState(x: Float, y: Float, down: Bool, hot: Int?, captured: Int?)
 record UiStep(ui: UiState, events: List[UiEvent])
@@ -54,7 +39,9 @@ primitive Ui =
   fun init() -> UiState =
     UiState(x: 0.0, y: 0.0, down: false, hot: null, captured: null)
+  # A key changes nothing here (keys go to the game).
-  fun step(ui: UiState, input: UiInput, hit: Int?) -> UiStep =
+  fun step(ui: UiState, input: Input, hit: Int?) -> UiStep =
+    pos := input.position() ?: return UiStep(ui: ui, events: Nil)
     out := Slice[UiEvent]()
     # a capture left over without a held button is stale
     cap: Int? := ui.captured
@@ -62,8 +49,8 @@ primitive Ui =
       cap = null
     hot: Int? := ui.hot
     down := ui.down
-    match input.kind
+    match input
-      PointerDown =>
+      PointerDown(_, _) =>
         cap = null
         uiHover(out, hot, hit)
         hot = hit
@@ -71,7 +58,7 @@ primitive Ui =
         if h := hit
           out.push(UiEvent(id: h, kind: Press))
           cap = h
-      PointerMove =>
+      PointerMove(_, _) =>
         if c := cap
           now: Int? := null
           if uiSame(hit, cap)
@@ -81,7 +68,7 @@ primitive Ui =
         else
           uiHover(out, hot, hit)
           hot = hit
-      PointerUp =>
+      PointerUp(_, _) =>
         if c := cap
           out.push(UiEvent(id: c, kind: Release))
           if uiSame(hit, cap)
@@ -92,7 +79,8 @@ primitive Ui =
           uiHover(out, hot, hit)
           hot = hit
         down = false
+      _ => 0
-    UiStep(ui: UiState(x: input.x, y: input.y, down: down, hot: hot, captured: cap), events: List.fromSlice(out))
+    UiStep(ui: UiState(x: pos.x, y: pos.y, down: down, hot: hot, captured: cap), events: List.fromSlice(out))
   fun pressed(ui: UiState, id: Int) -> Bool =
     if c := ui.captured
@@ -123,11 +111,11 @@ fun uiPressedColor() -> Color = Color.rgb(0.6, 0.2, 0.2)
 fun uiKinds(s: UiStep) -> List[UiKind] = s.events.map(|e| e.kind)
-fun uiDown(x: Float) -> UiInput = UiInput(kind: PointerDown, x: x, y: 0.0)
+fun uiDown(x: Float) -> Input = PointerDown(x: x, y: 0.0)
-fun uiUp(x: Float) -> UiInput = UiInput(kind: PointerUp, x: x, y: 0.0)
+fun uiUp(x: Float) -> Input = PointerUp(x: x, y: 0.0)
-fun uiMove(x: Float) -> UiInput = UiInput(kind: PointerMove, x: x, y: 0.0)
+fun uiMove(x: Float) -> Input = PointerMove(x: x, y: 0.0)
 fun uiCount(s: UiStep, k: UiKind) -> Int =
   n := 0

plum-std/game/imperative/Scene.plum CHANGED Viewed

@@ -9,6 +9,7 @@ import std/game/Color
 import std/Io
 import std/game/Affine
 import std/game/Game
+import std/game/Input
 # A Scene2D-like scene graph: a tree of actors under a `Stage`. `Actor` is a trait;
 # every kind of actor is a `record` that embeds it (`Group`, `Sprite`, `Rect`,
@@ -100,6 +101,11 @@ trait Actor(
   fun hit(self, p: Vec2) -> Bool =
     self.width > 0.0 && self.height > 0.0 && p.x >= 0.0 && p.x <= self.width && p.y >= 0.0 && p.y <= self.height
+  # Handles `e`, with a pointer position in this actor's own coordinates. Return true
+  # to consume it; otherwise it goes on to the parent. The default ignores it.
+  fun onInput(self, e: Input) -> Bool =
+    false
   fun at(self, x: Float, y: Float) -> Actor =
     self.x = x
     self.y = y
@@ -468,13 +474,13 @@ fun hitNode(n: Actor, p: Vec2) -> Actor? =
 # A root actor plus a camera (the world point at the screen's top-left and the
 # pixels per world unit, as in `setCamera`).
-record Stage(mut camX: Float, mut camY: Float, mut camScale: Float) =
+record Stage(mut camX: Float, mut camY: Float, mut camScale: Float, mut focus: Actor?) =
   fun init(self) =
     self.root: Actor = Group()
   fun create() -> Stage =
-    Stage(camX: 0.0, camY: 0.0, camScale: 1.0)
+    Stage(camX: 0.0, camY: 0.0, camScale: 1.0, focus: null)
   # Runs every actor's `act`, parents before children, in insertion order.
   fun act(self, dt: Float) =
@@ -489,12 +495,48 @@ record Stage(mut camX: Float, mut camY: Float, mut camScale: Float) =
   fun hit(self, x: Float, y: Float) -> Actor? =
     self.root.hitTree(Vec2(x: x, y: y))
+  # Delivers one input and says whether an actor consumed it. A pointer input goes
+  # to the topmost actor under it, then each parent in turn until one's `onInput`
+  # returns true; a press also gives that actor the keyboard focus. A key goes to the
+  # focused actor, then its parents. Unconsumed input is the game's to handle.
+  fun input(self, e: Input) -> Bool =
+    if p := e.position()
+      sp := self.screenToStage(p.x, p.y)
+      target := self.hit(sp.x, sp.y)
+      match e
+        PointerDown(_, _) =>
+          self.focus = target
+        _ => 0
+      if a := target
+        return Stage.bubble(a, Input.pointerAt(e, sp))
+      return false
+    if f := self.focus
+      return Stage.bubble(f, e)
+    false
+  # Offers `e` (in stage coordinates) to `a`, then each parent, until one consumes it.
+  fun bubble(a: Actor, e: Input) -> Bool =
+    cur: Actor? := a
+    while c := cur
+      if c.onInput(e.through(worldMatrix(c).inverse()))
+        return true
+      cur = c.parent
+    false
   # A screen pixel in stage coordinates under this camera.
   fun screenToStage(self, sx: Float, sy: Float) -> Vec2 =
     Vec2(x: sx / self.camScale + self.camX, y: sy / self.camScale + self.camY)
 # --- tests ---
+# Counts the inputs it is offered and the last pointer x it saw; consumes them if `eat`.
+record Catcher(Actor(width, height), mut got: Int, mut lastX: Float, eat: Bool) =
+  override fun onInput(self, e: Input) -> Bool =
+    self.got = self.got + 1
+    if p := e.position()
+      self.lastX = p.x
+    self.eat
 fun sceneNear(a: Float, b: Float) -> Bool =
   {a - b}.abs() < 0.0001
@@ -776,3 +818,30 @@ test "a child without a size is never culled"
   slot.add(Rect.create(10.0, 10.0, Color.Red).at(-890.0, -890.0))
   g.setCullingArea(0.0, 0.0, 100.0, 100.0)
   assert flatten(g).length() == 3
+test "input bubbles from the hit actor to its parents until consumed"
+  stage := Stage.create()
+  outer := Catcher(width: 100.0, height: 100.0, got: 0, lastX: 0.0, eat: true)
+  inner := Catcher(width: 10.0, height: 10.0, got: 0, lastX: 0.0, eat: false)
+  inner.x = 20.0
+  outer.add(inner)
+  stage.root.add(outer)
+  assert stage.input(PointerDown(x: 25.0, y: 5.0))
+  assert inner.got == 1
+  assert inner.lastX == 5.0
+  assert outer.got == 1
+  assert outer.lastX == 25.0
+  assert !stage.input(PointerDown(x: 500.0, y: 5.0))
+test "a press gives the keyboard focus; keys bubble from it"
+  stage := Stage.create()
+  outer := Catcher(width: 100.0, height: 100.0, got: 0, lastX: 0.0, eat: false)
+  inner := Catcher(width: 10.0, height: 10.0, got: 0, lastX: 0.0, eat: false)
+  outer.add(inner)
+  stage.root.add(outer)
+  assert !stage.input(KeyDown(key: Key.KeyA))
+  assert inner.got == 0
+  _ := stage.input(PointerDown(x: 5.0, y: 5.0))
+  assert !stage.input(KeyDown(key: Key.KeyA))
+  assert inner.got == 2
+  assert outer.got == 2

plum-std/game/pure/PureScene.plum CHANGED Viewed

@@ -10,36 +10,22 @@ import std/Io
 import std/game/Affine
 import std/game/Game
 import std/game/pure/Actions
+import std/game/Input
 # A pure scene graph: a node is a record (`Node`) holding a `Transform` and
 # an `enum Kind`. Group, Sprite, Label and Button are built in; games add their
 # own behaviour with `Custom(actor: Actor)`, a behaviour-only trait their records
 # embed (like Rust's `Box<dyn Actor>`). A node is a unique value: `update`,
-# `onPointer`, `modify` and `route` take it, change it in place and hand it back;
+# `onInput`, `modify` and `route` take it, change it in place and hand it back;
 # readers borrow. Only `drawTree` talks to the host, through `std/game/Game`.
+# Input is the shared `Input` of std/game/Input; `route` delivers it along a hit
+# path, child first, then each ancestor, until a node consumes it.
 enum Touchable =
   | Enabled
   | Disabled
   | ChildrenOnly
-enum PointerKind =
-  | Down
-  | Up
-  | Move
-# A pointer event in the actor's own coordinates; `over` says it is on the actor.
-record Pointer(kind: PointerKind, x: Float, y: Float, over: Bool)
-enum UiKind =
-  | Press
-  | Release
-  | Click
-  | Enter
-  | Exit
-record UiEvent(id: Int, kind: UiKind)
 # The node's position, size, origin, scale and rotation.
 record Transform(x: Float, y: Float, width: Float, height: Float, originX: Float, originY: Float, scaleX: Float, scaleY: Float, rotation: Float) =
@@ -264,63 +250,71 @@ record Node(
   # --- input ---
+  # Handles `e` (in the node's own coordinates; `over` says the pointer is on the
-  # Handles a pointer event and returns the new node with the events it raised.
+  # node) and returns the new node, the events it raised and whether it consumed `e`.
-  # Only a Button reacts.
+  # A Button reacts to the pointer; a Custom node asks its actor's `onInput`.
-  fun onPointer(self, e: Pointer) -> Handled =
+  fun onInput(self, e: Input, over: Bool) -> Handled =
     n := self
     ev := Slice[UiEvent]()
     match n.kind
       Button(text, upTex, downTex, wasPressed, wasOver) =>
         pressed := wasPressed
-        over := wasOver
+        now := wasOver
+        match e
-        if e.kind == Down
+          PointerDown(_, _) =>
-          pressed = true
+            pressed = true
-          over = e.over
+            now = over
-          ev.push(UiEvent(id: n.id, kind: Press))
+            ev.push(UiEvent(id: n.id, kind: Press))
-        else if e.kind == Move
+          PointerMove(_, _) =>
-          over = e.over
+            now = over
-          if e.over && !wasOver
+            if over && !wasOver
-            ev.push(UiEvent(id: n.id, kind: Enter))
+              ev.push(UiEvent(id: n.id, kind: Enter))
-          if !e.over && wasOver
+            if !over && wasOver
-            ev.push(UiEvent(id: n.id, kind: Exit))
+              ev.push(UiEvent(id: n.id, kind: Exit))
-        else
+          PointerUp(_, _) =>
-          over = e.over
+            now = over
-          if wasPressed
+            if wasPressed
-            pressed = false
+              pressed = false
-            ev.push(UiEvent(id: n.id, kind: Release))
+              ev.push(UiEvent(id: n.id, kind: Release))
-            if e.over
+              if over
-              ev.push(UiEvent(id: n.id, kind: Click))
+                ev.push(UiEvent(id: n.id, kind: Click))
+          _ => 0
-        n = Node(..n, kind: Button(text: text, upTex: upTex, downTex: downTex, pressed: pressed, over: over))
+        n = Node(..n, kind: Button(text: text, upTex: upTex, downTex: downTex, pressed: pressed, over: now))
+      Custom(actor) =>
+        return actor.onInput(n, e, over)
       _ => 0
-    Handled(node: n, events: ev)
+    Handled(node: n, events: ev, consumed: false)
-  # Delivers `e` (in the coordinates of the parent) along `path`: the child on
+  # Delivers `e` (in the coordinates of the parent) along `path`: the child on the
-  # the path first, then this node. A path that runs out reaches the deepest
+  # path first, then this node, unless a child consumed it. A path that runs out
-  # actor it can.
+  # reaches the deepest actor it can.
-  fun route(self, path: Slice[Int], depth: Int, e: Pointer) -> Handled =
+  fun route(self, path: Slice[Int], depth: Int, e: Input, over: Bool) -> Handled =
     events := Slice[UiEvent]()
-    r := self.routeInto(path, depth, e, events)
+    self.routeInto(path, depth, e, over, events)
-    Handled(node: r, events: events)
-  # `route`, appending the raised events to `events` and returning the node.
+  # `route`, appending the raised events to `events` (the returned Handled holds it).
-  fun routeInto(self, path: Slice[Int], depth: Int, e: Pointer, events: Slice[UiEvent]) -> Node =
+  fun routeInto(self, path: Slice[Int], depth: Int, e: Input, over: Bool, events: Slice[UiEvent]) -> Handled =
-    lp := Vec2(x: e.x, y: e.y)
+    local := e
-    inv := self.localMatrix().invert()
+    if q := self.localMatrix().invert()
-    if q := inv
-      lp = q.apply(lp)
+      local = e.through(q)
-    local := Pointer(kind: e.kind, x: lp.x, y: lp.y, over: e.over)
+    consumed := false
     if depth < path.length()
       match self.kind
         Group(ks) =>
           i := path.at(depth)
           if i >= 0 && i < ks.length()
             c := ks.takeAt(i)
-            ks.putAt(i, c.routeInto(path, depth + 1, local, events))
+            h := c.routeInto(path, depth + 1, local, over, events)
+            consumed = h.consumed
+            ks.putAt(i, h.intoNode())
         _ => 0
+    if consumed
+      return Handled(node: self, events: events, consumed: true)
-    h := self.onPointer(local)
+    h := self.onInput(local, over)
     for j := range h.events.length()
       events.push(h.events.at(j))
-    h.intoNode()
+    used := h.consumed
+    Handled(node: h.intoNode(), events: events, consumed: used)
 enum Kind =
   | Group(children: Slice[Node])
@@ -339,13 +333,20 @@ trait Actor =
   fun draw(self, io: Io, n: Node, m: Affine, tint: Color) =
     return
+  # Handles `e` (in the node's own coordinates; `over` says the pointer is on the
+  # node). Return `consumed: true` to keep it from the node's ancestors. The
+  # default ignores it.
+  fun onInput(self, n: Node, e: Input, over: Bool) -> Handled =
+    Handled(node: n, events: Slice[UiEvent](), consumed: false)
-# The node after handling an event, and the events it raised.
+# The node after handling an input, the events it raised, and whether it consumed
+# the input (its ancestors then do not see it).
-record Handled(node: Node, events: Slice[UiEvent]) =
+record Handled(node: Node, events: Slice[UiEvent], consumed: Bool) =
-  # The node, moved out; read `events` first, they stay behind.
+  # The node, moved out; read `events` and `consumed` first, they stay behind.
   fun intoNode(self) -> Node =
     match self
-      Handled(n, _) => n
+      Handled(n, _, _) => n
 fun psKinds(h: Handled) -> Slice[UiKind] =
   out := Slice[UiKind]()
@@ -365,8 +366,11 @@ fun psClicks(h: Handled) -> Int =
       n = n + 1
   n
+fun psDown() -> Input = PointerDown(x: 1.0, y: 1.0)
+fun psUp() -> Input = PointerUp(x: 1.0, y: 1.0)
-fun psOverPtr(kind: PointerKind, over: Bool) -> Pointer =
+fun psMove() -> Input = PointerMove(x: 1.0, y: 1.0)
-  Pointer(kind: kind, x: 1.0, y: 1.0, over: over)
 # A game actor: counts its draws and moves its node right by 1 on each act.
 record Beacon(Actor, mut draws: Int) =
@@ -492,11 +496,11 @@ test "local_matrix_translates"
 test "button_click_needs_press_and_over"
   b := Node.button(7, "go", 1, 2, 0.0, 0.0, 10.0, 10.0)
-  h1 := b.onPointer(psOverPtr(Down, true))
+  h1 := b.onInput(psDown(), true)
   ks := psKinds(h1)
   n1 := h1.events.length()
   id1 := h1.events.at(0).id
-  h2 := h1.intoNode().onPointer(psOverPtr(Up, true))
+  h2 := h1.intoNode().onInput(psUp(), true)
   ks.push(h2.events.at(0).kind)
   ks.push(h2.events.at(1).kind)
   assert n1 == 1
@@ -509,25 +513,25 @@ test "button_click_needs_press_and_over"
 test "button_release_elsewhere_no_click"
   b := Node.button(7, "go", 1, 2, 0.0, 0.0, 10.0, 10.0)
-  h1 := b.onPointer(psOverPtr(Down, true))
+  h1 := b.onInput(psDown(), true)
-  h2 := h1.intoNode().onPointer(psOverPtr(Up, false))
+  h2 := h1.intoNode().onInput(psUp(), false)
   assert h2.events.length() == 1
   assert h2.events.at(0).kind == Release
   assert !psIsPressed(h2.intoNode())
 test "button_drag_off_and_back_one_click"
   b := Node.button(7, "go", 1, 2, 0.0, 0.0, 10.0, 10.0)
-  a1 := b.onPointer(psOverPtr(Down, true)).intoNode()
+  a1 := b.onInput(psDown(), true).intoNode()
-  h2 := a1.onPointer(psOverPtr(Move, false))
+  h2 := a1.onInput(psMove(), false)
   c2 := psClicks(h2)
-  h3 := h2.intoNode().onPointer(psOverPtr(Move, true))
+  h3 := h2.intoNode().onInput(psMove(), true)
   c3 := psClicks(h3)
-  h4 := h3.intoNode().onPointer(psOverPtr(Up, true))
+  h4 := h3.intoNode().onInput(psUp(), true)
   assert c2 + c3 + psClicks(h4) == 1
 test "on_pointer_hands_back_changed_actor"
   b := Node.button(7, "go", 1, 2, 0.0, 0.0, 10.0, 10.0)
-  h := b.onPointer(psOverPtr(Down, true))
+  h := b.onInput(psDown(), true)
   assert psIsPressed(h.intoNode())
 test "custom_actor_act_and_draw_dispatch"
@@ -554,17 +558,17 @@ test "hit_box_and_children_of"
 test "button_move_raises_enter_then_exit"
   b := Node.button(7, "go", 1, 2, 0.0, 0.0, 10.0, 10.0)
-  h1 := b.onPointer(psOverPtr(Move, true))
+  h1 := b.onInput(psMove(), true)
   assert h1.events.length() == 1
   assert h1.events.at(0).kind == Enter
-  h2 := h1.intoNode().onPointer(psOverPtr(Move, false))
+  h2 := h1.intoNode().onInput(psMove(), false)
   assert h2.events.length() == 1
   assert h2.events.at(0).kind == Exit
   assert !psIsPressed(h2.intoNode())
 test "on_pointer_non_button_raises_nothing"
   s := Node.sprite(1, 0, 0.0, 0.0, 10.0, 10.0)
-  h := s.onPointer(psOverPtr(Down, true))
+  h := s.onInput(psDown(), true)
   assert h.events.length() == 0
   assert h.intoNode().id == 1
@@ -638,10 +642,10 @@ test "modify_changes_first_match_only"
 test "route_child_first_then_group"
   g := ttButtonRoot()
-  h1 := g.route(ttZero(), 0, Pointer(kind: Down, x: 20.0, y: 20.0, over: true))
+  h1 := g.route(ttZero(), 0, PointerDown(x: 20.0, y: 20.0), true)
   n1 := h1.events.length()
   k1 := h1.events.at(0).kind
-  h2 := h1.intoNode().route(ttZero(), 0, Pointer(kind: Up, x: 20.0, y: 20.0, over: true))
+  h2 := h1.intoNode().route(ttZero(), 0, PointerUp(x: 20.0, y: 20.0), true)
   assert n1 == 1
   assert k1 == Press
   assert h2.events.length() == 2
@@ -651,7 +655,7 @@ test "route_child_first_then_group"
 test "stale_path_reaches_group_only"
   nine := Slice(9)
-  h := ttButtonRoot().route(nine, 0, Pointer(kind: Down, x: 20.0, y: 20.0, over: true))
+  h := ttButtonRoot().route(nine, 0, PointerDown(x: 20.0, y: 20.0), true)
   assert h.events.length() == 0
 test "compaction_keeps_order"

plum-std/game/pure/SceneInput.plum CHANGED Viewed

@@ -10,35 +10,16 @@ import std/game/Affine
 import std/game/Game
 import std/game/pure/Actions
 import std/game/pure/PureScene
+import std/game/Input
-# The root of a pure scene tree, its camera and pointer capture. A Stage is an
+# The root of a pure scene tree, its camera, pointer capture and keyboard focus. A
-# unique value: `input` and `frame` take it, change it in place and hand it back
+# Stage is an unique value: `input` and `frame` take it, change it in place and hand
-# inside a StageHandled (`intoStage` moves it out). A press captures the
+# it back inside a StageHandled (`intoStage` moves it out). A press captures the
 # actor it landed on: moves and the release go to that actor until the release,
-# even when the pointer leaves it (scene2d's touch focus). The id stored with
+# even when the pointer leaves it (scene2d's touch focus). The pressed actor also
+# takes the keyboard focus: keys go to it first (then its ancestors), and keys no
+# node consumes come back in `StageHandled.keys` for the game. The id stored with a
-# the path guards against the tree changing under it.
+# path guards against the tree changing under it.
-enum InputKind =
-  | PointerDown
-  | PointerUp
-  | PointerMove
-# A pointer input in screen coordinates.
-record Input(kind: InputKind, x: Float, y: Float) =
-  # This frame's pointer inputs from the host mouse: a press, a release, or a
-  # move. `wasDown` is whether the button was down last frame.
-  fun poll(io: Io, wasDown: Bool) -> Slice[Input] =
-    m := io.mousePos()
-    down := io.isMouseDown(0)
-    out := Slice[Input]()
-    if down && !wasDown
-      out.push(Input(kind: PointerDown, x: m.x, y: m.y))
-    else if !down && wasDown
-      out.push(Input(kind: PointerUp, x: m.x, y: m.y))
-    else
-      out.push(Input(kind: PointerMove, x: m.x, y: m.y))
-    out
 record Capture(path: Slice[Int], id: Int) =
@@ -52,73 +33,96 @@ record Capture(path: Slice[Int], id: Int) =
         return false
     true
+# The stage after some inputs, the UI events raised and the keys no node consumed.
-record StageHandled(stage: Stage, events: Slice[UiEvent]) =
+record StageHandled(stage: Stage, events: Slice[UiEvent], keys: Slice[Input]) =
-  # The stage, moved out; read `events` first, they stay behind.
+  # The stage, moved out; read `events` and `keys` first, they stay behind.
   fun intoStage(self) -> Stage =
     match self
-      StageHandled(s, _) => s
+      StageHandled(s, _, _) => s
-record Stage(root: Node, camera: Affine, captured: Capture?) =
+record Stage(root: Node, camera: Affine, captured: Capture?, focus: Int?) =
-  # A stage over `root` with no camera transform and nothing captured.
+  # A stage over `root` with no camera transform, nothing captured and no focus.
   fun create(root: Node) -> Stage =
-    Stage(root: root, camera: Affine.Identity, captured: null)
+    Stage(root: root, camera: Affine.Identity, captured: null, focus: null)
   # Handles one input: routes it, returns the new stage and the events raised.
   fun input(self, e: Input) -> StageHandled =
+    if !e.isPointer()
+      return self.key(e)
     none := Slice[UiEvent]()
-    inv := self.camera.invert()
-    if inv == null
-      return StageHandled(stage: self, events: none)
+    q := self.camera.invert() ?: return StageHandled(stage: self, events: none, keys: Slice[Input]())
-    world := Vec2(x: e.x, y: e.y)
-    if q := inv
-      world = q.apply(world)
+    world := e.through(q)
+    at := world.position() ?: Vec2(x: 0.0, y: 0.0)
-    hit := self.root.findHit(Affine.Identity, world)
+    hit := self.root.findHit(Affine.Identity, at)
     # A capture is valid only while its path still leads to its actor.
     cap: Capture? := null
     if c := self.captured
       if self.root.idAt(c.path, 0) == c.id
         cap = c
+    match world
-    if e.kind == PointerDown
+      PointerDown(_, _) =>
-      if p := hit
+        if p := hit
-        id := self.root.idAt(p, 0)
+          id := self.root.idAt(p, 0)
-        return self.deliver(p, Pointer(kind: Down, x: world.x, y: world.y, over: true), Capture(path: p, id: id))
+          return Stage(..self, focus: id).deliver(p, world, true, Capture(path: p, id: id))
-      return StageHandled(stage: self.withCapture(null), events: none)
+        return StageHandled(stage: Stage(..self, captured: null, focus: null), events: none, keys: Slice[Input]())
+      _ => 0
     if c := cap
       over := false
       if p := hit
         over = c.within(p)
+      match world
-      if e.kind == PointerUp
+        PointerUp(_, _) =>
-        return self.deliver(c.path, Pointer(kind: Up, x: world.x, y: world.y, over: over), null)
+          return self.deliver(c.path, world, over, null)
+        _ => 0
-      return self.deliver(c.path, Pointer(kind: Move, x: world.x, y: world.y, over: over), c)
+      return self.deliver(c.path, world, over, c)
     # Hover without a press: route to whatever is under the pointer.
+    match world
-    if e.kind == PointerMove
+      PointerMove(_, _) =>
-      if p := hit
+        if p := hit
-        return self.deliver(p, Pointer(kind: Move, x: world.x, y: world.y, over: true), null)
+          return self.deliver(p, world, true, null)
+      _ => 0
-    StageHandled(stage: self.withCapture(null), events: none)
+    StageHandled(stage: self.withCapture(null), events: none, keys: Slice[Input]())
+  # A key goes to the focused actor (then its ancestors); unconsumed, it is returned.
+  fun key(self, e: Input) -> StageHandled =
+    left := Slice(e)
+    if f := self.focus
+      if p := self.root.findPath(f)
+        events := Slice[UiEvent]()
+        match self
+          Stage(root, camera, captured, focus) =>
+            h := root.routeInto(p, 0, e, true, events)
+            if h.consumed
+              left = Slice[Input]()
+            return StageHandled(stage: Stage(root: h.intoNode(), camera: camera, captured: captured, focus: focus), events: events, keys: left)
+    StageHandled(stage: self, events: Slice[UiEvent](), keys: left)
   fun withCapture(self, c: Capture?) -> Stage =
     Stage(..self, captured: c)
-  fun deliver(self, path: Slice[Int], p: Pointer, c: Capture?) -> StageHandled =
+  fun deliver(self, path: Slice[Int], e: Input, over: Bool, c: Capture?) -> StageHandled =
     events := Slice[UiEvent]()
     match self
-      Stage(root, camera, _) =>
+      Stage(root, camera, _, focus) =>
-        r := root.routeInto(path, 0, p, events)
+        h := root.routeInto(path, 0, e, over, events)
-        StageHandled(stage: Stage(root: r, camera: camera, captured: c), events: events)
+        StageHandled(stage: Stage(root: h.intoNode(), camera: camera, captured: c, focus: focus), events: events, keys: Slice[Input]())
   # Handles the inputs in order, then advances the tree by `dt`.
   fun frame(self, dt: Float, inputs: Slice[Input]) -> StageHandled =
     cur := self
     out := Slice[UiEvent]()
+    keys := Slice[Input]()
     for i := range inputs.length()
       h := cur.input(inputs.at(i))
       for j := range h.events.length()
         out.push(h.events.at(j))
+      for j := range h.keys.length()
+        keys.push(h.keys.at(j))
       cur = h.intoStage()
     match cur
-      Stage(root, camera, captured) => StageHandled(stage: Stage(root: root.update(dt), camera: camera, captured: captured), events: out)
+      Stage(root, camera, captured, focus) => StageHandled(stage: Stage(root: root.update(dt), camera: camera, captured: captured, focus: focus), events: out, keys: keys)
   # Paints the tree through the camera.
   fun draw(self, io: Io) =
@@ -146,13 +150,13 @@ fun inOverOf(a: Node) -> Bool =
     _ => false
 fun inDown(x: Float, y: Float) -> Input =
-  Input(kind: PointerDown, x: x, y: y)
+  PointerDown(x: x, y: y)
 fun inUp(x: Float, y: Float) -> Input =
-  Input(kind: PointerUp, x: x, y: y)
+  PointerUp(x: x, y: y)
 fun inMove(x: Float, y: Float) -> Input =
-  Input(kind: PointerMove, x: x, y: y)
+  PointerMove(x: x, y: y)
 fun inClicks(events: Slice[UiEvent]) -> Int =
   n := 0
@@ -169,6 +173,29 @@ fun inXformTree() -> Node =
   me: Node := g2
   me
+# A custom actor that moves its node right on its key and reports presses.
+record KeyMover(Actor, key: Int) =
+  override fun onInput(self, n: Node, e: Input, over: Bool) -> Handled =
+    match e
+      KeyDown(k) =>
+        if k == self.key
+          return Handled(node: Node(..n, x: n.x + 1.0), events: Slice[UiEvent](), consumed: true)
+      PointerDown(_, _) =>
+        return Handled(node: n, events: Slice(UiEvent(id: n.id, kind: Press)), consumed: true)
+      _ => 0
+    Handled(node: n, events: Slice[UiEvent](), consumed: false)
+fun inMoverTree() -> Node =
+  m: Node := Node.custom(8, 10.0, 10.0, 50.0, 50.0, KeyMover(key: Key.KeyA))
+  m2 := Node(..m, touchable: Enabled)
+  g: Node := Node.group(1, 0.0, 0.0, 800.0, 600.0, Slice(m2))
+  g
+fun inFirstX(s: Stage) -> Float =
+  if k := s.root.children()
+    return k.at(0).x
+  0.0 - 1.0
 test "press_sets_capture"
   h := Stage.create(inBtnTree()).input(inDown(20.0, 20.0))
   assert h.events.length() == 1
@@ -201,7 +228,7 @@ test "drag_off_and_back_one_click"
 test "stale_capture_dropped"
   h1 := Stage.create(inBtnTree()).input(inDown(20.0, 20.0))
   empty: Node := Node.group(1, 0.0, 0.0, 800.0, 600.0, Slice[Node]())
-  swapped := Stage(root: empty, camera: h1.stage.camera, captured: h1.stage.captured)
+  swapped := Stage(root: empty, camera: h1.stage.camera, captured: h1.stage.captured, focus: null)
   h2 := swapped.input(inUp(20.0, 20.0))
   assert h2.events.length() == 0
   assert h2.stage.captured == null
@@ -213,7 +240,7 @@ test "hover_without_press_routes_move"
 test "camera_maps_screen_to_world"
   cam := Affine(a: 2.0, b: 0.0, c: 0.0, d: 2.0, e: 0.0, f: 0.0)
-  s := Stage(root: inBtnTree(), camera: cam, captured: null)
+  s := Stage(root: inBtnTree(), camera: cam, captured: null, focus: null)
   h := s.input(inDown(40.0, 40.0))
   assert h.events.length() == 1
   assert h.events.at(0).kind == Press
@@ -243,13 +270,39 @@ test "hit_and_route_agree_for_rotated_scaled_group"
   t := inXformTree()
   hit := t.findHit(Affine.Identity, Vec2(x: 60.0, y: 40.0))
   assert hit != null
-  h := Stage(root: t, camera: Affine.Identity, captured: null).input(Input(kind: PointerDown, x: 60.0, y: 40.0))
+  h := Stage(root: t, camera: Affine.Identity, captured: null, focus: null).input(inDown(60.0, 40.0))
   assert h.events.length() == 1
   assert h.events.at(0).id == 5
-  miss := Stage(root: inXformTree(), camera: Affine.Identity, captured: null).input(Input(kind: PointerDown, x: 20.0, y: 20.0))
+  miss := Stage(root: inXformTree(), camera: Affine.Identity, captured: null, focus: null).input(inDown(20.0, 20.0))
   assert miss.events.length() == 0
 test "input_changes_stage_in_place"
-  h := Stage.create(inBtnTree()).input(Input(kind: PointerDown, x: 20.0, y: 20.0))
+  h := Stage.create(inBtnTree()).input(inDown(20.0, 20.0))
   assert h.stage.captured != null
   assert inBtnPressed(h.stage)
+test "custom_actor_gets_pointer_through_on_input"
+  h := Stage.create(inMoverTree()).input(inDown(20.0, 20.0))
+  assert h.events.length() == 1
+  assert h.events.at(0).id == 8
+  assert {h.stage.focus ?: -1} == 8
+test "focused_actor_consumes_its_key"
+  h1 := Stage.create(inMoverTree()).input(inDown(20.0, 20.0))
+  h2 := h1.intoStage().input(KeyDown(key: Key.KeyA))
+  assert h2.keys.length() == 0
+  assert inFirstX(h2.stage) == 11.0
+test "unconsumed_and_unfocused_keys_go_to_the_game"
+  h1 := Stage.create(inMoverTree()).input(KeyDown(key: Key.KeyA))
+  assert h1.keys.length() == 1
+  assert inFirstX(h1.stage) == 10.0
+  h2 := Stage.create(inMoverTree()).input(inDown(20.0, 20.0))
+  h3 := h2.intoStage().input(KeyDown(key: Key.KeyB))
+  assert h3.keys.length() == 1
+test "frame_collects_unconsumed_keys"
+  ins := Slice(inDown(20.0, 20.0), KeyDown(key: Key.KeyA), KeyDown(key: Key.Space))
+  h := Stage.create(inMoverTree()).frame(0.0, ins)
+  assert h.keys.length() == 1
+  assert inFirstX(h.stage) == 11.0