refactor

kiln-core/CLAUDE.md

@@ -30,7 +30,7 @@ The core types that were formerly monolithic in `game.rs` are now split into foc
 - `Behavior` — plain data struct from `Archetype::behavior()`: `solid: bool`, `opaque: bool`, `pushable: Pushable`, `grab: bool` (the player walking onto a `solid + grab` thing isn't blocked — it moves onto it and the thing's `grab()` hook fires; this is the *only* grab trigger; `Gem` and `Heart` both set the flag).
 - `ObjectId = u32` — stable identifier for board objects.
 - `Solid` — the single solid occupant of a cell, returned by `Board::solid_at`: `Player`, `Cell(Archetype)`, or `Object(ObjectId)`.
-- `Player { x: i32, y: i32 }` — current player position.
+- `PlayerPos { x: i32, y: i32 }` — the player's current position on a board (held as `Board::player`). The broader player *state* (health, gems, keys) lives in [`player::Player`], not here.
 - `PortalDef { x, y, target_map, target_entry }` — parsed from map files, not yet runtime-wired.
 
 **`kiln-core/src/object_def.rs`** — scripted objects (`pub(crate)`):
@@ -59,16 +59,23 @@ The core types that were formerly monolithic in `game.rs` are now split into foc
 - `in_bounds((i32, i32))` — bounds-checks a possibly-negative coord.
 - `is_valid()` / `load_errors()` / `report_error(msg)` — nonfatal load-error surface.
 
+**`kiln-core/src/player.rs`** — game-global player state (`pub`):
+- `Player { health: i64, max_health: i64, keys: Keyring, gems: i64 }` — the player's persistent stats, owned by `GameState::player` (separate from the per-board `PlayerPos` position in `utils.rs`). `Default` starts `health = max_health = 5`, `gems = 0`, no keys. `alter_gems(delta) -> bool` adds to `gems` but refuses (returns `false`, no change) if it would go negative. `alter_health(delta)` adds to `health` clamped to `[0, max_health]`. A `Copy` snapshot is handed to each script hook and exposed to Rhai (read-only) as the `Player` constant.
+
+**`kiln-core/src/keys.rs`** — key inventory and colors (`pub`):
+- `KeyType` (`Red`/`Orange`/`Yellow`/`Green`/`Blue`/`Cyan`/`Purple`/`White`) — the eight key colors. `glyph() -> Glyph` returns the key tile (12, `♀`) in that color's fg — the single source of truth for key colors, used by `Keyring::colors` and by kiln-tui's editor menu. (Moved here from `game.rs`; `archetype.rs`'s `Key` builtin aliases must match these glyphs — see its `key_aliases_have_distinct_fg_colors` test.)
+- `Keyring { red, orange, yellow, green, blue, cyan, purple, white: bool }` — the player's key inventory (one bool per color), held by `Player::keys`. `set_by_name(name, value) -> bool` sets a slot by color name (returns `false` for an unknown name); `colors() -> [(bool, Rgba8); 8]` lists all eight in display order paired with their render color.
+
 **`kiln-core/src/game.rs`** — game-loop logic only:
 - `SpeechBubble { object_id, text, remaining }` — an active speech bubble created by a script's `say(s)` call. `remaining` counts down in `GameState::tick`; when it reaches zero the bubble is removed. At most one bubble per object (a new `say()` replaces the old one).
 - `SAY_DURATION: f64` — how long a bubble lives (3.0 seconds).
 - `Scroll { source: ObjectId, lines: Vec<ScrollLine> }` — an active scroll overlay opened by a script's `scroll(lines)` call. Lives on `GameState::active_scroll: Option<Scroll>`; front-ends pause ticks while it's `Some` and close it via `close_scroll(choice)`. `ScrollLine` is re-exported from `action.rs` through `game.rs` so front-ends import both from `kiln_core::game`.
-- `GameState` — owns `world: World` (all boards as `Rc<RefCell<Board>>` + world scripts) and `current_board_name: String` (key of the active board). `pub log: Vec<LogLine>`, `scripts: ScriptHost`, `pub speech_bubbles: Vec<SpeechBubble>`, `pub active_scroll: Option<Scroll>`, `pub player_health: u32` (starts 5), `pub max_health: u32` (default 5), and `pub player_gems: u32` (starts 0) — game-global player stats that persist across board transitions. `player_gems` is changed at runtime by the `add_gems(n)` script fn (e.g. grabbing a gem); `player_health` is changed by `alter_health(dh)` (clamped to `[0, max_health]`, e.g. grabbing a heart). Front-ends reach the active board through `board() -> Ref<Board>` / `board_mut() -> RefMut<Board>` (both look up `world.boards[current_board_name]`). `current_board_name() -> &str` returns the active key. **`from_world(world: World) -> Self`** is the primary constructor: clones the start board's `Rc<RefCell<Board>>` for the `ScriptHost`, compiles scripts from `world.scripts`. `new(board)` and `with_scripts(board, scripts)` are `#[cfg(test)]`-only sugar that build a minimal single-board `World`. `try_move(dir)` moves the player (pushing if possible) and fires `bump(-1)` on any solid object walked into; walking onto a `grab` thing (via `Board::grab_object_at`) instead moves onto it and fires `grab()` + an immediate `resolve()` so its `die()`/`add_gems()`/`alter_health()` apply before the call returns (no player+object overlap). **`try_move` is the only grab trigger** — a grab thing pushed or swapped into the player is an ordinary solid (it slides/blocks/refuses like any other). `run_init()` runs object `init()` hooks once at startup. `tick(dt)` advances cooldowns, expires speech bubbles, and runs `tick(dt)` hooks every frame. Both end by calling `resolve()`, which drains the board queue and applies each `Action` (`Log` → `log`, `SetTile` → source glyph, `Move(dir)` → `step_object`, `Say` → `speech_bubbles`, `Scroll` → `active_scroll`, `AddGems(n)` → `player_gems`, `AlterHealth(dh)` → `player_health` clamped to `[0, max_health]`, `Die` → `remove_object(source)`). Resolution is two-phase: mutate the board collecting `(bumped, bumper)` pairs, drop the borrow, then fire `run_bump` for each pair. `drain_errors()` moves script errors into `log`. `close_scroll(choice)` clears `active_scroll` and optionally fires `run_send(source, choice, None)` to dispatch the player's selection back to the object.
+- `GameState` — owns `world: World` (all boards as `Rc<RefCell<Board>>` + world scripts) and `current_board_name: String` (key of the active board). `pub log: Vec<LogLine>`, `scripts: ScriptHost`, `pub speech_bubbles: Vec<SpeechBubble>`, `pub active_scroll: Option<Scroll>`, and `pub player: Player` — the game-global player state ([`player::Player`]: `health`/`max_health`/`gems`/`keys`) that persists across board transitions (it is *not* per-board; `Board::player` holds only the per-board `PlayerPos`). `player.gems` is changed at runtime by the `add_gems(n)` script fn (e.g. grabbing a gem); `player.health` is changed by `alter_health(dh)` (clamped to `[0, max_health]`, e.g. grabbing a heart); `player.keys` is changed by `set_key(color, present)`. Each script-hook call is handed a snapshot of `player` wrapped in a `ScriptState` bundle (read-only, exposed to Rhai as the `Player` constant — see `script.rs`). Front-ends reach the active board through `board() -> Ref<Board>` / `board_mut() -> RefMut<Board>` (both look up `world.boards[current_board_name]`). `current_board_name() -> &str` returns the active key. **`from_world(world: World) -> Self`** is the primary constructor: clones the start board's `Rc<RefCell<Board>>` for the `ScriptHost`, compiles scripts from `world.scripts`. `new(board)` and `with_scripts(board, scripts)` are `#[cfg(test)]`-only sugar that build a minimal single-board `World`. `try_move(dir)` moves the player (pushing if possible) and fires `bump(-1)` on any solid object walked into; walking onto a `grab` thing (via `Board::grab_object_at`) instead moves onto it and fires `grab()` + an immediate `resolve()` so its `die()`/`add_gems()`/`alter_health()` apply before the call returns (no player+object overlap). **`try_move` is the only grab trigger** — a grab thing pushed or swapped into the player is an ordinary solid (it slides/blocks/refuses like any other). `run_init()` runs object `init()` hooks once at startup. `tick(dt)` advances cooldowns, expires speech bubbles, and runs `tick(dt)` hooks every frame. Both end by calling `resolve()`, which drains the board queue and applies each `Action` (`Log` → `log`, `SetTile` → source glyph, `Move(dir)` → `step_object`, `Say` → `speech_bubbles`, `Scroll` → `active_scroll`, `AddGems(n)` → `player.gems`, `AlterHealth(dh)` → `player.health` clamped to `[0, max_health]`, `Die` → `remove_object(source)`). Resolution is two-phase: mutate the board collecting `(bumped, bumper)` pairs, drop the borrow, then fire `run_bump` for each pair. `drain_errors()` moves script errors into `log`. `close_scroll(choice)` clears `active_scroll` and optionally fires `run_send(source, choice, None)` to dispatch the player's selection back to the object.
 
 **`kiln-core/src/action.rs`** — the `Action` enum and its Rhai-facing conversion:
 - `MOVE_COST: f64` — how long a move occupies an object before it can act again (0.25 s).
 - `ScrollLine` (`pub`) — one line of content in a `Scroll` action: `Text(String)` (plain, word-wrapped) or `Choice { choice, display }` (selectable; `choice` is sent back to the source object when the player picks it).
-- `Action` (`pub(crate)`) — deferred mutation emitted by a script and applied by `GameState` after promotion onto the board queue: `Move(Direction)`, `SetTile(u32)`, `Log(LogLine)`, `SetTag { target, tag, present }`, `Say(String)`, `Delay(f64)` (never reaches the board queue — consumed by `ScriptHost::drain` to pace the object), `SetColor { fg, bg }`, `Send { target, fn_name, arg }`, `Scroll(Vec<ScrollLine>)`, `Teleport { x, y }`, `Push { x, y, dir }` (shove a chain at arbitrary coords; zero time cost), `Swap(Vec<(i32,i32,i32,i32)>)` (batch of simultaneous one-way solid moves; zero time cost), `AddGems(i64)` (change `GameState::player_gems`, clamped at 0; zero cost), `AlterHealth(i64)` (change `GameState::player_health`, clamped to `[0, max_health]`; zero cost), `Die` (remove the source object; zero cost).
+- `Action` (`pub(crate)`) — deferred mutation emitted by a script and applied by `GameState` after promotion onto the board queue: `Move(Direction)`, `SetTile(u32)`, `Log(LogLine)`, `SetTag { target, tag, present }`, `Say(String)`, `Delay(f64)` (never reaches the board queue — consumed by `ScriptHost::drain` to pace the object), `SetColor { fg, bg }`, `Send { target, fn_name, arg }`, `Scroll(Vec<ScrollLine>)`, `Teleport { x, y }`, `Push { x, y, dir }` (shove a chain at arbitrary coords; zero time cost), `Swap(Vec<(i32,i32,i32,i32)>)` (batch of simultaneous one-way solid moves; zero time cost), `AddGems(i64)` (change `GameState::player.gems`, clamped at 0; zero cost), `AlterHealth(i64)` (change `GameState::player.health`, clamped to `[0, max_health]`; zero cost), `Die` (remove the source object; zero cost).
 - `action_to_map(action) -> rhai::Map` — converts an `Action` to a Rhai map for `Queue.peek()` / `Queue.pop()`. The map always has a `"type"` key; other keys carry the payload. `Scroll`/`Swap` emit `type` only (their payloads are not inspectable via the map API). `Log` is flattened to its first span's text.
 
 **`kiln-core/src/floor.rs`** — procedural floor generators:
@@ -80,8 +87,8 @@ The core types that were formerly monolithic in `game.rs` are now split into foc
 
 **`kiln-core/src/script.rs`** — Rhai scripting runtime:
 - `ScriptHost` — owns the Rhai `Engine`, the compiled scripts referenced by a board's objects, a per-object persistent `Scope` + output queue + ready timer, and the shared board queue. Built with `ScriptHost::new(&Rc<RefCell<Board>>, &HashMap<String, String>)`: the first arg is a shared ref to the active board (used by read-API closures), the second is the world-level script pool. Each object resolves to a `(key, source)` compiled once per key: the key is the object's `script_name` (a world-pool name for a named script, or a synthetic `BUILTIN_*` name assigned by `expand_builtin_archetypes` so identical built-ins, e.g. all pushers, share one AST); the source is the pool entry for that name, or the object's embedded `builtin_script` when present. Reports compile/unknown-script failures onto the error sink; runs nothing.
-- Lifecycle hooks per object: `init()` (zero-arg), `tick(dt)` (elapsed seconds as `f64`), `bump(id)` (the bumper's `ObjectId`, or `-1` for the player), and `grab()` (zero-arg; fired when the player walks onto a `grab` thing — the only grab trigger), all optional — detected via `AST::iter_functions()` by name and arity. Driven by `run_init()` / `run_tick(dt)` / `run_bump(object_id, bumper)` / `run_grab(object_id)`; runtime errors go to the error sink (drained to the log), not fatal.
-- **Reads (direct):** read getters (`player_x`, `player_y`, `width`, `height`) are registered on `Rc<RefCell<Board>>` (the `BoardRef` alias, exposed to Rhai under the type name `Board`) — getters only, so read-only by construction. A clone of the handle is pushed into each scope as the constant `Board`. `blocked(dir) -> bool` is also a read fn: true if the caller's target cell is off-board, already solid, or the destination of a pending move on the board queue (an object never sees its *own* move, which is pumped only after its script returns). `can_push(x, y, dir) -> bool` is a read fn mirroring `Board::can_push`: true if `(x, y)` holds a pushable whose chain can be shoved in `dir` (false off-board). `can_shift(x, y, dir) -> bool` mirrors `Board::can_shift`: like `can_push` but only checks the single cell ahead (pushable source + an empty-or-pushable next cell), the right gate for a simultaneous shift/rotation via `swap`. `passable(x, y) -> bool` mirrors `Board::is_passable`: true if `(x, y)` is on-board and holds no solid (off-board → false), letting a script tell a hole apart from a blocked solid (which `can_shift`/`can_push` alone cannot). `has_tag(s) -> bool` and `get_tags() -> Array` read the calling object's tag set; `objects_with_tag(s) -> Array` returns all object ids carrying that tag. `my_name() -> String` returns the calling object's name (or `""` if unnamed); `object_id_for_name(s) -> i64` looks up an object by name and returns its id, or `0` if not found. Each getter briefly borrows the shared `Board`.
+- Lifecycle hooks per object: `init()` (zero-arg), `tick(dt)` (elapsed seconds as `f64`), `bump(id)` (the bumper's `ObjectId`, or `-1` for the player), and `grab()` (zero-arg; fired when the player walks onto a `grab` thing — the only grab trigger), all optional — detected via `AST::iter_functions()` by name and arity. Driven by `run_init(state)` / `run_tick(state, dt)` / `run_bump(state, object_id, bumper)` / `run_grab(state, object_id)` — each takes a `ScriptState(pub Player)` bundle (a `Copy` wrapper that exists so more host context can be threaded through later without re-touching every signature); the host pulls its `Player` out and sets it into the object's scope as the `Player` constant before the call; runtime errors go to the error sink (drained to the log), not fatal.
+- **Reads (direct):** read getters (`player_x`, `player_y`, `width`, `height`) are registered on `Rc<RefCell<Board>>` (the `BoardRef` alias, exposed to Rhai under the type name `Board`) — getters only, so read-only by construction. A clone of the handle is pushed into each scope as the constant `Board`. The player's game-global stats are likewise exposed read-only as the `Player` constant (a `Copy` snapshot, carried in by the `ScriptState` bundle and set into scope before each hook call; getters `Player.gems`, `Player.health`, `Player.max_health` — keys not yet exposed), via `register_player_type`. `blocked(dir) -> bool` is also a read fn: true if the caller's target cell is off-board, already solid, or the destination of a pending move on the board queue (an object never sees its *own* move, which is pumped only after its script returns). `can_push(x, y, dir) -> bool` is a read fn mirroring `Board::can_push`: true if `(x, y)` holds a pushable whose chain can be shoved in `dir` (false off-board). `can_shift(x, y, dir) -> bool` mirrors `Board::can_shift`: like `can_push` but only checks the single cell ahead (pushable source + an empty-or-pushable next cell), the right gate for a simultaneous shift/rotation via `swap`. `passable(x, y) -> bool` mirrors `Board::is_passable`: true if `(x, y)` is on-board and holds no solid (off-board → false), letting a script tell a hole apart from a blocked solid (which `can_shift`/`can_push` alone cannot). `has_tag(s) -> bool` and `get_tags() -> Array` read the calling object's tag set; `objects_with_tag(s) -> Array` returns all object ids carrying that tag. `my_name() -> String` returns the calling object's name (or `""` if unnamed); `object_id_for_name(s) -> i64` looks up an object by name and returns its id, or `0` if not found. Each getter briefly borrows the shared `Board`.
 - **Actions & rate limiting (two-tier queues):** host fns `move(dir)`, `set_tile(n)`, `log(s)`, `say(s)`, `scroll(lines)`, `push(x, y, dir)`, `swap(pairs)`, `add_gems(n)` (adjust the player's gem count), `alter_health(dh)` (adjust the player's health, clamped to `[0, max_health]`), `die()` (remove the calling object) append an `Action` (`Move`/`SetTile`/`Log`/`Say`/`Scroll`/`Push`/`Swap`; `MOVE_COST = 0.25` s for `Move`, else 0 — `push`/`swap` add no delay) to the *issuing object's* output queue (routed by the per-call tag via a `HashMap<usize, ObjQueue>`). `scroll(lines)` takes a Rhai array where each element is a string (text line) or a two-element array `[choice_key, display_text]` (selectable choice). `push(x, y, dir)` shoves the pushable chain at arbitrary coords `(x, y)`. `swap(pairs)` takes an array of four-int `[src_x, src_y, dst_x, dst_y]` arrays (a malformed entry is skipped + logged) and moves all the named solids simultaneously (see `Board::apply_swap`). `ScriptHost::pump(i)` promotes ready actions onto the shared **board queue** (`Vec<BoardAction { source, action }>`): the leading run of zero-cost actions plus at most one timed action, which arms that object's **ready timer** and ends the pump. While a ready timer is `> 0` nothing is pulled (this caps object speed); `advance_timers(dt)` counts them down each frame. `GameState` drains the board queue with `take_board_queue()` and applies it after the batch — so scripts mutate without a `&mut GameState` borrow. Errors (compile/runtime) bypass the queues via the error sink (`take_errors()`).
 - The `Queue` object (a handle to the calling object's output queue) is pushed into each scope; scripts call `Queue.length()`, `Queue.clear()`, `Queue.peek()` (front action as a Rhai map, or `()` if empty), and `Queue.pop()` (same, removes the front). Safe to mutate from script because the host only touches output queues between calls (during `pump`).
 - **Sender identity:** `source` (which object issued an action) rides the per-call **tag** — `run` calls `call_fn_with_options(...with_tag(object_id)...)` and the host fns read it via `NativeCallContext::tag()` (decoded back to an `ObjectId` by `source_of`). Scripts write `move(North)` without naming themselves; `North`/`South`/`East`/`West` are `Direction` constants in scope, and `impl From<Direction> for (i32,i32)` gives the delta.

kiln-core/src/action.rs

@@ -77,16 +77,16 @@ pub(crate) enum Action {
     /// Zero time cost.
     Shift(Vec<(i32, i32)>),
     /// Add `n` to the player's gem count (negative subtracts; the count is
-    /// clamped at 0). Zero time cost. Applied to `GameState::player_gems`.
+    /// clamped at 0). Zero time cost. Applied to `GameState::player.gems`.
     AddGems(i64),
     /// Add `dh` to the player's health (clamped to `[0, max_health]`). Zero time
-    /// cost. Applied to `GameState::player_health`.
+    /// cost. Applied to `GameState::player.health`.
     AlterHealth(i64),
     /// Give (`true`) or take (`false`) the named key color from the player.
     ///
     /// Color must be one of `"blue"`, `"green"`, `"cyan"`, `"red"`, `"purple"`,
     /// `"orange"`, `"yellow"`, `"white"`. An unrecognized name is logged and
-    /// ignored. Zero time cost. Applied to `GameState::player_keys`.
+    /// ignored. Zero time cost. Applied to `GameState::player.keys`.
     SetKey(String, bool),
     /// Remove the source object from the board. Zero time cost. Used by grab
     /// things (e.g. gems) to despawn themselves from their `grab()` hook.

kiln-core/src/board.rs

@@ -43,7 +43,8 @@ pub struct Board {
     /// top-down; solidity ([`Board::solid_at`]) scans every layer. Access a single
     /// cell with [`Board::get`]/[`Board::get_mut`] by `(z, x, y)`.
     pub(crate) layers: Vec<Layer>,
-    /// Current player position. See [`Player`] for caveats about its future.
+    /// Current player position on this board. See [`PlayerPos`] for caveats
+    /// about its future. Game-global player *stats* live in [`crate::player::Player`].
     pub player: PlayerPos,
     /// Scripted objects on this board, keyed by stable [`ObjectId`]. A `BTreeMap`
     /// (not a `Vec`) so an object can be removed without invalidating other

kiln-core/src/game.rs

@@ -1,7 +1,7 @@
 use crate::action::Action;
 use crate::board::Board;
 use crate::log::LogLine;
-use crate::script::ScriptHost;
+use crate::script::{ScriptHost, ScriptState};
 use crate::utils::{Direction, ObjectId, PlayerPos, ScriptArg};
 use crate::world::World;
 use std::cell::{Ref, RefMut};
@@ -67,7 +67,10 @@ pub struct GameState {
     /// by [`enter_board`](GameState::enter_board). Front-ends tick this down and
     /// may block input or show a visual effect while it is `Some(t)` where `t > 0`.
     pub board_transition: Option<f64>,
-    /// The player's state
+    /// The game-global player state (health, gems, keys) — see [`Player`]. Not
+    /// per-board: it persists across board transitions, unlike the per-board
+    /// position in [`Board::player`](crate::board::Board::player). Scripts mutate
+    /// it via `add_gems`/`alter_health`/`set_key` and read a snapshot of it.
     pub player: Player,
 }
 
@@ -159,7 +162,7 @@ impl GameState {
     /// the game is about to start — never during map deserialization, since a script
     /// may inspect the board.
     pub fn run_init(&mut self) {
-        self.scripts.run_init(self.player);
+        self.scripts.run_init(ScriptState(self.player));
         self.resolve();
     }
 
@@ -173,7 +176,7 @@ impl GameState {
         // this runs exactly once per player interaction with a scroll.
         self.handle_scroll();
         let secs = dt.as_secs_f64();
-        self.scripts.run_tick(self.player, secs);
+        self.scripts.run_tick(ScriptState(self.player), secs);
         // Expire speech bubbles before resolving new actions so a fresh say()
         // this frame isn't immediately culled.
         self.speech_bubbles.retain_mut(|b| {
@@ -308,11 +311,11 @@ impl GameState {
                     Action::Shift(cells) => {
                         logs.extend(board.apply_shift(&cells));
                     }
-                    // Accumulated and applied to `self.player_gems` after the borrow drops.
+                    // Accumulated and applied to `self.player.gems` after the borrow drops.
                     Action::AddGems(n) => gem_delta += n,
-                    // Accumulated and applied to `self.player_health` after the borrow drops.
+                    // Accumulated and applied to `self.player.health` after the borrow drops.
                     Action::AlterHealth(dh) => health_delta += dh,
-                    // Collected and applied to `self.player_keys` after the borrow drops.
+                    // Collected and applied to `self.player.keys` after the borrow drops.
                     Action::SetKey(color, present) => key_changes.push((color, present)),
                     // A grab thing despawns itself from its grab() hook.
                     Action::Die => {
@@ -345,10 +348,10 @@ impl GameState {
             }
         }
         for (bumped, bumper) in bumps {
-            self.scripts.run_bump(self.player, bumped, bumper);
+            self.scripts.run_bump(ScriptState(self.player), bumped, bumper);
         }
         for (target, fn_name, arg) in sends {
-            self.scripts.run_send(self.player, target, &fn_name, arg);
+            self.scripts.run_send(ScriptState(self.player), target, &fn_name, arg);
         }
         self.drain_errors();
     }
@@ -364,7 +367,7 @@ impl GameState {
         if let Some(scroll) = self.active_scroll.take()
             && let Some(choice) = scroll.choice
         {
-            self.scripts.run_send(self.player, scroll.source, &choice, None);
+            self.scripts.run_send(ScriptState(self.player), scroll.source, &choice, None);
             self.drain_errors();
         }
     }
@@ -471,11 +474,11 @@ impl GameState {
         // Fire the grab hook and resolve it immediately so the grabbed thing's
         // die()/add_gems() apply now — no player+object overlap survives this call.
         if let Some(id) = grabbed {
-            self.scripts.run_grab(self.player, id);
+            self.scripts.run_grab(ScriptState(self.player), id);
             self.resolve();
         }
         if let Some(idx) = bumped {
-            self.scripts.run_bump(self.player, idx, -1);
+            self.scripts.run_bump(ScriptState(self.player), idx, -1);
             self.drain_errors();
         }
     }

kiln-core/src/player.rs

@@ -1,5 +1,12 @@
 use crate::keys::Keyring;
 
+/// The game-global player state: stats that follow the player across boards.
+///
+/// Owned by [`GameState::player`](crate::game::GameState) (a single value, not
+/// per-board), so health, gems, and keys persist through board transitions.
+/// Distinct from [`PlayerPos`](crate::utils::PlayerPos), which is the player's
+/// position *on a particular board*. A `Copy` snapshot is handed to each script
+/// hook and exposed to Rhai (read-only) as the `Player` constant.
 #[derive(Copy, Clone)]
 pub struct Player {
     /// The player's current health. Game-global (not per-board), so it persists
@@ -15,7 +22,7 @@ pub struct Player {
     pub keys: Keyring,
 
     /// The number of gems the player has collected. Game-global like
-    /// [`player_health`](GameState::player_health); starts at `0`.
+    /// [`health`](Player::health); starts at `0`.
     pub gems: i64,
 }
 

kiln-core/src/script.rs

@@ -81,6 +81,12 @@ use std::collections::{HashMap, HashSet, VecDeque};
 use std::rc::Rc;
 use crate::player::Player;
 
+/// The host-provided context handed to every script hook for the duration of one
+/// call. Currently just the player snapshot, but it exists so more host state can
+/// be threaded through the `run_*` methods without changing each signature again.
+#[derive(Copy, Clone)]
+pub struct ScriptState(pub Player);
+
 /// An action promoted from an object's output queue onto the board queue, tagged
 /// with the object that issued it.
 pub(crate) struct BoardAction {
@@ -318,18 +324,18 @@ impl ScriptHost {
     }
 
     /// Calls `init()` on every scripted object that defines it and drains each queue.
-    pub fn run_init(&mut self, player: Player) {
-        self.run("init", |c| c.has_init, (), 0.0, player);
+    pub fn run_init(&mut self, state: ScriptState) {
+        self.run("init", |c| c.has_init, (), 0.0, state);
     }
 
     /// Calls `tick(dt)` on every scripted object that defines it, then drains queues.
-    pub fn run_tick(&mut self, player: Player, dt: f64) {
-        self.run("tick", |c| c.has_tick, (dt,), dt, player);
+    pub fn run_tick(&mut self, state: ScriptState, dt: f64) {
+        self.run("tick", |c| c.has_tick, (dt,), dt, state);
     }
 
     /// Calls `bump(id)` on the object with [`ObjectId`] `object_id`, if it defines
     /// the hook. After the hook, drains the object's queue with `dt = 0`.
-    pub fn run_bump(&mut self, player: Player, object_id: ObjectId, bumper: i64) {
+    pub fn run_bump(&mut self, state: ScriptState, object_id: ObjectId, bumper: i64) {
         let Some(i) = self.objects.iter().position(|o| o.object_id == object_id) else {
             return;
         };
@@ -349,7 +355,7 @@ impl ScriptHost {
                 return;
             }
             let options = CallFnOptions::default().with_tag(object_id as i64);
-            obj.scope.set_or_push("Player", player);
+            obj.scope.set_or_push("Player", state.0);
             if let Err(err) = engine.call_fn_with_options::<()>(
                 options,
                 &mut obj.scope,
@@ -372,7 +378,7 @@ impl ScriptHost {
     /// Fired when the player walks onto a grab object or a grab object is pushed
     /// into the player (see [`GameState`](crate::game::GameState)). The hook
     /// typically increments a player stat and removes the object via `die()`.
-    pub fn run_grab(&mut self, player: Player, object_id: ObjectId) {
+    pub fn run_grab(&mut self, state: ScriptState, object_id: ObjectId) {
         let Some(i) = self.objects.iter().position(|o| o.object_id == object_id) else {
             return;
         };
@@ -392,7 +398,7 @@ impl ScriptHost {
                 return;
             }
             let options = CallFnOptions::default().with_tag(object_id as i64);
-            obj.scope.set_or_push("Player", player);
+            obj.scope.set_or_push("Player", state.0);
             if let Err(err) = engine.call_fn_with_options::<()>(
                 options,
                 &mut obj.scope,
@@ -415,7 +421,7 @@ impl ScriptHost {
     /// If the function accepts zero parameters (or arg is `None`), it is called with
     /// no args. If neither arity exists, the call is silently skipped.
     /// After the call, drains the object's queue with `dt = 0`.
-    pub(crate) fn run_send(&mut self, player: Player, target_id: ObjectId, fn_name: &str, arg: Option<ScriptArg>) {
+    pub(crate) fn run_send(&mut self, state: ScriptState, target_id: ObjectId, fn_name: &str, arg: Option<ScriptArg>) {
         let Some(i) = self.objects.iter().position(|o| o.object_id == target_id) else {
             return;
         };
@@ -442,7 +448,7 @@ impl ScriptHost {
                 .any(|f| f.name == fn_name && f.params.is_empty());
 
             let options = CallFnOptions::default().with_tag(obj.object_id as i64);
-            obj.scope.set_or_push("Player", player);
+            obj.scope.set_or_push("Player", state.0);
             let result = if has_1 {
                 // Call with arg (or unit if arg is absent).
                 let dyn_arg: Dynamic = match &arg {
@@ -530,7 +536,7 @@ impl ScriptHost {
         defined: fn(&CompiledScript) -> bool,
         args: A,
         drain_dt: f64,
-        player: Player
+        state: ScriptState,
     ) {
         for i in 0..self.objects.len() {
             {
@@ -546,7 +552,7 @@ impl ScriptHost {
                     && defined(compiled)
                 {
                     let options = CallFnOptions::default().with_tag(obj.object_id as i64);
-                    obj.scope.set_or_push("Player", player);
+                    obj.scope.set_or_push("Player", state.0);
                     if let Err(err) = engine.call_fn_with_options::<()>(
                         options,
                         &mut obj.scope,