Fixing tests and comments

kiln-core/src/action.rs

@@ -1,8 +1,9 @@
-//! The [`Action`] enum and its Rhai-facing conversions.
+//! The [`Action`] enum and supporting types.
 //!
 //! This module owns the `Action` type (which scripts enqueue via write host
-//! functions), the rate-limiting delay constant, and [`action_to_map`] which
-//! converts an `Action` to a Rhai map for `Queue.peek()` / `Queue.pop()`.
+//! functions), the rate-limiting delay constant [`MOVE_COST`], the [`ScrollLine`]
+//! and [`SendArg`] payload types, and [`BoardAction`] (an action tagged with the
+//! object that issued it).
 
 use std::fmt::Debug;
 use crate::log::LogLine;

kiln-core/src/api/queue.rs

@@ -1,6 +1,6 @@
 //! ## Queue API
 //!
-//! `queue.length`, `queue.clear()`, `queue.peek()`, `queue.pop()`, `queue.delay()`
+//! `queue.length`, `queue.clear()`, `queue.delay()`
 
 use std::cell::RefCell;
 use std::collections::VecDeque;

kiln-core/src/script.rs

@@ -28,7 +28,7 @@
 //! `move(dir)`, `delay(secs)`, `now()`, `set_tile(n)`, `log(msg)`, `say(msg)`,
 //! `set_fg(fg)`, `set_bg(bg)`, `set_color(fg, bg)`, `set_tag(target, tag, present)`,
 //! `send(target_id, fn_name [, arg])`, `teleport(x, y)`, `push(x, y, dir)`,
-//! `swap([[src_x, src_y, dst_x, dst_y], …])`, `add_gems(n)`, `alter_health(dh)`, `set_key(color, present)`, `die()`
+//! `shift([[x, y], …])`, `add_gems(n)`, `alter_health(dh)`, `set_key(color, present)`, `die()`
 
 use crate::action::{Action, BoardAction, ScrollLine, SendArg, MOVE_COST};
 use crate::game::SAY_DURATION;
@@ -691,8 +691,9 @@ fn register_global_constants(engine: &mut Engine) {
     engine.register_global_module(m.into());
 }
 
-/// Builds a fresh per-object scope containing only the object-specific handles:
-/// the Board view, the object's Queue, and the Me self-reference.
+/// Builds a fresh per-object scope containing only the `Registry` handle. The
+/// per-object `me` (an [`ObjectInfo`]) and `state` (a [`ScriptState`]) views are
+/// passed as hook parameters, not scope constants.
 fn new_object_scope(board: &BoardRef) -> Scope<'static> {
     let mut scope = Scope::new();
     scope.push_constant("Registry", Registry { board: board.clone() });

kiln-core/src/scripts/pusher.rhai

@@ -11,8 +11,8 @@ fn tick(me, state, dt) {
     // and is a no-op when blocked; the delay pads each step out to ~0.5s (move
     // itself costs 0.25s), matching the old global pusher heartbeat.
     //
-    // The direction is read here, at the top level of the hook, because `Me` is a
-    // per-object scope constant and is not visible inside other script functions.
+    // The direction is read from `me` (the hook's first parameter); to use it in a
+    // helper function you would pass `me` down explicitly.
     if !me.waiting {
         let dir = if me.has_tag("BUILTIN_pusher_north") { North }
                   else if me.has_tag("BUILTIN_pusher_south") { South }

kiln-core/src/scripts/spinner.rhai

@@ -1,13 +1,10 @@
-// Rotates this object's 8 neighbours one step around a ring every 0.5s, shoving
-// each pushable into the next ring slot via a single simultaneous `swap`. The spin
-// direction comes from the `BUILTIN_spinner_*` tag the map loader attaches (it
-// defaults to clockwise when no tag is present).
-//
-// A neighbour may only rotate if its destination slot will actually be free: the
-// slot is a hole (`passable`), or that slot's own occupant also rotates out. We
-// can't decide that with `can_shift` alone — `can_shift(j) == false` is ambiguous
-// between "j is empty" and "j is a blocked solid" — so we seed with `can_shift`
-// and then cascade-demote using `passable` to spot the genuine holes.
+// Rotates this object's 8 neighbours one step around a ring every 0.5s via a single
+// `shift()` of the ring coordinates. `shift` moves each pushable to the next slot,
+// skips non-pushables, and won't move anything into a cell that isn't vacant (or
+// vacated by this same rotation) — so the "is the slot free?" decision lives in the
+// engine and the script just hands it the ring. The spin direction comes from the
+// `BUILTIN_spinner_*` tag the map loader attaches (it defaults to clockwise when no
+// tag is present).
 fn tick(me, state, dt) {
     // Only start a new rotation when the previous one (and its delay) has drained,
     // exactly like the built-in pusher's pacing.