@crowdedkingdoms/ckx-kit 0.2.0 → 0.4.0-dev.1

package/crates/ckx-sdk/src/kit/play/timing.rs

@@ -0,0 +1,218 @@
+//! Race timing: ordered checkpoint/gate evaluation from pose streams,
+//! lap/split timing, best-lap books, and compact ghost recording (pose
+//! track capture + interpolated replay). Pure state machines fed by the
+//! race hub's tick samples — gates are proximity circles, so tick-rate
+//! sampling with generous radii is the tolerance model (documented for
+//! course designers).
+
+use serde::{Deserialize, Serialize};
+
+/// One ordered gate on a course.
+#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq)]
+pub struct Gate {
+    pub x: f32,
+    pub z: f32,
+    pub radius: f32,
+}
+
+/// A course: ordered gates; a lap = passing every gate in order (gate 0 is
+/// the start/finish line).
+#[derive(Serialize, Deserialize, Clone, Debug, Default)]
+pub struct Course {
+    pub gates: Vec<Gate>,
+    pub laps: u32,
+}
+
+/// Events produced by feeding poses through a run timer.
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub enum TimingEvent {
+    Started { at_ms: u64 },
+    Checkpoint { gate: usize, split_ms: u64 },
+    LapCompleted { lap: u32, lap_ms: u64, best: bool },
+    Finished { total_ms: u64, best_lap_ms: u64 },
+}
+
+/// One racer's live run state.
+#[derive(Serialize, Deserialize, Clone, Debug, Default)]
+pub struct RunTimer {
+    pub next_gate: usize,
+    pub lap: u32,
+    pub started_at_ms: u64,
+    pub lap_started_at_ms: u64,
+    pub splits_ms: Vec<u64>,
+    pub best_lap_ms: u64,
+    pub finished: bool,
+    pub total_ms: u64,
+}
+
+impl RunTimer {
+    /// Feed one pose sample; returns the timing events it produced. The run
+    /// starts when the racer first touches gate 0.
+    pub fn feed(&mut self, course: &Course, pos: (f32, f32), now_ms: u64) -> Vec<TimingEvent> {
+        if self.finished || course.gates.is_empty() {
+            return Vec::new();
+        }
+        let mut events = Vec::new();
+        let gate = course.gates[self.next_gate];
+        let (dx, dz) = (pos.0 - gate.x, pos.1 - gate.z);
+        if (dx * dx + dz * dz).sqrt() > gate.radius {
+            return events;
+        }
+
+        if self.started_at_ms == 0 {
+            // Touching the start line arms the run.
+            if self.next_gate == 0 {
+                self.started_at_ms = now_ms;
+                self.lap_started_at_ms = now_ms;
+                self.lap = 1;
+                self.next_gate = 1 % course.gates.len();
+                events.push(TimingEvent::Started { at_ms: now_ms });
+            }
+            return events;
+        }
+
+        let split = now_ms.saturating_sub(self.lap_started_at_ms);
+        self.splits_ms.push(split);
+        events.push(TimingEvent::Checkpoint { gate: self.next_gate, split_ms: split });
+        self.next_gate = (self.next_gate + 1) % course.gates.len();
+
+        // Wrapped back to the start line: lap complete.
+        if self.next_gate == 1 % course.gates.len() && self.splits_ms.len().is_multiple_of(course.gates.len()) {
+            let lap_ms = now_ms.saturating_sub(self.lap_started_at_ms);
+            let best = self.best_lap_ms == 0 || lap_ms < self.best_lap_ms;
+            if best {
+                self.best_lap_ms = lap_ms;
+            }
+            events.push(TimingEvent::LapCompleted { lap: self.lap, lap_ms, best });
+            if self.lap >= course.laps.max(1) {
+                self.finished = true;
+                self.total_ms = now_ms.saturating_sub(self.started_at_ms);
+                events.push(TimingEvent::Finished { total_ms: self.total_ms, best_lap_ms: self.best_lap_ms });
+            } else {
+                self.lap += 1;
+                self.lap_started_at_ms = now_ms;
+            }
+        }
+        events
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Ghosts
+// ---------------------------------------------------------------------------
+
+/// A compact recorded pose track: (offset ms, x, y, z, yaw). Sampled at the
+/// recorder's cadence, replayed with linear interpolation.
+#[derive(Serialize, Deserialize, Clone, Debug, Default)]
+pub struct GhostTrack {
+    pub frames: Vec<(u32, f32, f32, f32, f32)>,
+    pub started_at_ms: u64,
+}
+
+/// Ghost tracks are capped so a long run cannot blow the state budget.
+pub const GHOST_MAX_FRAMES: usize = 600;
+
+impl GhostTrack {
+    /// Record one frame (call per sample while the run is live).
+    pub fn record(&mut self, now_ms: u64, x: f32, y: f32, z: f32, yaw: f32) {
+        if self.started_at_ms == 0 {
+            self.started_at_ms = now_ms;
+        }
+        if self.frames.len() >= GHOST_MAX_FRAMES {
+            return;
+        }
+        let offset = now_ms.saturating_sub(self.started_at_ms) as u32;
+        self.frames.push((offset, x, y, z, yaw));
+    }
+
+    pub fn duration_ms(&self) -> u32 {
+        self.frames.last().map(|f| f.0).unwrap_or(0)
+    }
+
+    /// Interpolated pose at `offset_ms` into the replay (clamped to ends).
+    pub fn frame_at(&self, offset_ms: u32) -> Option<(f32, f32, f32, f32)> {
+        if self.frames.is_empty() {
+            return None;
+        }
+        let last = *self.frames.last().unwrap();
+        if offset_ms >= last.0 {
+            return Some((last.1, last.2, last.3, last.4));
+        }
+        let after_index = self.frames.iter().position(|f| f.0 >= offset_ms)?;
+        if after_index == 0 {
+            let f = self.frames[0];
+            return Some((f.1, f.2, f.3, f.4));
+        }
+        let before = self.frames[after_index - 1];
+        let after = self.frames[after_index];
+        let span = (after.0 - before.0).max(1) as f32;
+        let t = (offset_ms - before.0) as f32 / span;
+        Some((
+            before.1 + (after.1 - before.1) * t,
+            before.2 + (after.2 - before.2) * t,
+            before.3 + (after.3 - before.3) * t,
+            before.4 + (after.4 - before.4) * t,
+        ))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn triangle() -> Course {
+        Course {
+            gates: vec![Gate { x: 0.0, z: 0.0, radius: 2.0 }, Gate { x: 10.0, z: 0.0, radius: 2.0 }, Gate { x: 5.0, z: 8.0, radius: 2.0 }],
+            laps: 2,
+        }
+    }
+
+    #[test]
+    fn ordered_gates_laps_and_finish() {
+        let course = triangle();
+        let mut timer = RunTimer::default();
+        // Touching gate 1 before starting does nothing.
+        assert!(timer.feed(&course, (10.0, 0.0), 500).is_empty());
+        // Start at gate 0.
+        let events = timer.feed(&course, (0.5, 0.0), 1_000);
+        assert_eq!(events, vec![TimingEvent::Started { at_ms: 1_000 }]);
+        // Skipping a gate is ignored (gate 2 while gate 1 is next).
+        assert!(timer.feed(&course, (5.0, 8.0), 2_000).is_empty());
+        // Gate 1 -> checkpoint split.
+        let events = timer.feed(&course, (10.0, 0.5), 3_000);
+        assert_eq!(events, vec![TimingEvent::Checkpoint { gate: 1, split_ms: 2_000 }]);
+        timer.feed(&course, (5.0, 8.0), 5_000); // gate 2
+        // Back to start: lap 1 done (best).
+        let events = timer.feed(&course, (0.0, 0.5), 7_000);
+        assert!(events.contains(&TimingEvent::LapCompleted { lap: 1, lap_ms: 6_000, best: true }));
+        assert_eq!(timer.lap, 2);
+        // Lap 2, faster: finish with best lap = lap 2.
+        timer.feed(&course, (10.0, 0.0), 8_000);
+        timer.feed(&course, (5.0, 8.0), 9_000);
+        let events = timer.feed(&course, (0.0, 0.0), 11_000);
+        assert!(events.contains(&TimingEvent::LapCompleted { lap: 2, lap_ms: 4_000, best: true }));
+        assert!(events.contains(&TimingEvent::Finished { total_ms: 10_000, best_lap_ms: 4_000 }));
+        assert!(timer.finished);
+        assert!(timer.feed(&course, (10.0, 0.0), 12_000).is_empty(), "finished runs ignore input");
+    }
+
+    #[test]
+    fn ghost_records_and_interpolates() {
+        let mut ghost = GhostTrack::default();
+        ghost.record(1_000, 0.0, 0.0, 0.0, 0.0);
+        ghost.record(2_000, 10.0, 0.0, 0.0, 90.0);
+        ghost.record(3_000, 10.0, 0.0, 10.0, 180.0);
+        assert_eq!(ghost.duration_ms(), 2_000);
+        let mid = ghost.frame_at(500).unwrap();
+        assert!((mid.0 - 5.0).abs() < 1e-3);
+        assert!((mid.3 - 45.0).abs() < 1e-3);
+        let end = ghost.frame_at(9_999).unwrap();
+        assert_eq!(end.2, 10.0);
+        // Frame cap holds.
+        let mut big = GhostTrack::default();
+        for i in 0..(GHOST_MAX_FRAMES + 50) {
+            big.record(i as u64 * 100, i as f32, 0.0, 0.0, 0.0);
+        }
+        assert_eq!(big.frames.len(), GHOST_MAX_FRAMES);
+    }
+}

package/crates/ckx-sdk/src/kit/play/turns.rs

@@ -0,0 +1,315 @@
+//! Turns: initiative ordering, turn/round advance, per-turn timers
+//! with timeout policies, and simultaneous reveal. Pure state machine over
+//! `now_ms` — a hub keeps it in its state and drives it from
+//! timers and calls; it never talks to the platform itself.
+
+use serde::{Deserialize, Serialize};
+
+/// What happens when a turn timer expires.
+#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Default)]
+pub enum TimeoutPolicy {
+    /// The actor's turn is skipped (turn passes on).
+    #[default]
+    Skip,
+    /// The actor forfeits and is removed from the order.
+    Forfeit,
+    /// Nothing happens automatically (a human host decides).
+    Wait,
+}
+
+/// One participant in the order.
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct TurnActor {
+    /// Stable id (a player id, a unit's id, ...).
+    pub id: String,
+    /// Higher acts first; ties keep insertion order (stable sort).
+    pub initiative: i64,
+    /// Forfeited/dead actors stay recorded but are skipped.
+    pub active: bool,
+}
+
+/// An event the hub should announce (turn changed, round advanced, ...).
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub enum TurnEvent {
+    TurnStarted {
+        actor_id: String,
+        round: u32,
+        turn_in_round: u32,
+    },
+    RoundStarted {
+        round: u32,
+    },
+    ActorSkipped {
+        actor_id: String,
+    },
+    ActorForfeited {
+        actor_id: String,
+    },
+    /// One (or zero) active actors remain.
+    OrderExhausted,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, Default)]
+pub struct TurnOrder {
+    pub actors: Vec<TurnActor>,
+    /// Index into `actors` of the current turn holder.
+    pub current: usize,
+    pub round: u32,
+    pub turn_in_round: u32,
+    /// Current turn deadline (0 = no timer).
+    pub deadline_ms: u64,
+    pub turn_duration_ms: u64,
+    pub timeout_policy: TimeoutPolicy,
+    started: bool,
+}
+
+impl TurnOrder {
+    /// Build an order from (id, initiative) pairs; sorts by initiative
+    /// descending (stable — ties keep the given order).
+    pub fn new(actors: impl IntoIterator<Item = (String, i64)>, turn_duration_ms: u64, timeout_policy: TimeoutPolicy) -> Self {
+        let mut list: Vec<TurnActor> = actors.into_iter().map(|(id, initiative)| TurnActor { id, initiative, active: true }).collect();
+        list.sort_by_key(|b| std::cmp::Reverse(b.initiative));
+        Self { actors: list, current: 0, round: 0, turn_in_round: 0, deadline_ms: 0, turn_duration_ms, timeout_policy, started: false }
+    }
+
+    pub fn active_count(&self) -> usize {
+        self.actors.iter().filter(|a| a.active).count()
+    }
+
+    /// The current turn holder (None before start / after exhaustion).
+    pub fn current_actor(&self) -> Option<&TurnActor> {
+        if !self.started {
+            return None;
+        }
+        self.actors.get(self.current).filter(|a| a.active)
+    }
+
+    /// Begin round 1, turn 1. Returns the announce events.
+    pub fn start(&mut self, now_ms: u64) -> Vec<TurnEvent> {
+        if self.started || self.active_count() == 0 {
+            return Vec::new();
+        }
+        self.started = true;
+        self.round = 1;
+        self.turn_in_round = 1;
+        self.current = self.first_active_from(0);
+        self.arm_timer(now_ms);
+        vec![
+            TurnEvent::RoundStarted { round: 1 },
+            TurnEvent::TurnStarted { actor_id: self.actors[self.current].id.clone(), round: 1, turn_in_round: 1 },
+        ]
+    }
+
+    /// Advance to the next active actor (call when the current turn ends).
+    pub fn advance(&mut self, now_ms: u64) -> Vec<TurnEvent> {
+        if !self.started {
+            return Vec::new();
+        }
+        let mut events = Vec::new();
+        if self.active_count() <= 1 {
+            events.push(TurnEvent::OrderExhausted);
+            return events;
+        }
+        let mut index = self.current;
+        loop {
+            index += 1;
+            if index >= self.actors.len() {
+                index = 0;
+                self.round += 1;
+                self.turn_in_round = 0;
+                events.push(TurnEvent::RoundStarted { round: self.round });
+            }
+            if self.actors[index].active {
+                break;
+            }
+        }
+        self.current = index;
+        self.turn_in_round += 1;
+        self.arm_timer(now_ms);
+        events.push(TurnEvent::TurnStarted {
+            actor_id: self.actors[index].id.clone(),
+            round: self.round,
+            turn_in_round: self.turn_in_round,
+        });
+        events
+    }
+
+    /// Apply the timeout policy if the current turn's deadline passed.
+    pub fn tick(&mut self, now_ms: u64) -> Vec<TurnEvent> {
+        if !self.started || self.deadline_ms == 0 || now_ms < self.deadline_ms {
+            return Vec::new();
+        }
+        let actor_id = match self.current_actor() {
+            Some(actor) => actor.id.clone(),
+            None => return Vec::new(),
+        };
+        match self.timeout_policy {
+            TimeoutPolicy::Wait => Vec::new(),
+            TimeoutPolicy::Skip => {
+                let mut events = vec![TurnEvent::ActorSkipped { actor_id }];
+                events.extend(self.advance(now_ms));
+                events
+            }
+            TimeoutPolicy::Forfeit => {
+                let mut events = vec![TurnEvent::ActorForfeited { actor_id: actor_id.clone() }];
+                events.extend(self.forfeit(&actor_id, now_ms));
+                events
+            }
+        }
+    }
+
+    /// Remove an actor from the running order (death, rage-quit). Advances
+    /// the turn when it was theirs.
+    pub fn forfeit(&mut self, actor_id: &str, now_ms: u64) -> Vec<TurnEvent> {
+        let Some(index) = self.actors.iter().position(|a| a.id == actor_id && a.active) else {
+            return Vec::new();
+        };
+        self.actors[index].active = false;
+        if self.active_count() <= 1 {
+            return vec![TurnEvent::OrderExhausted];
+        }
+        if index == self.current && self.started {
+            // Their turn: pass it on. advance() skips inactive actors.
+            return self.advance(now_ms);
+        }
+        Vec::new()
+    }
+
+    /// Milliseconds left on the current turn (None = no timer / not started).
+    pub fn remaining_ms(&self, now_ms: u64) -> Option<u64> {
+        (self.started && self.deadline_ms > 0).then(|| self.deadline_ms.saturating_sub(now_ms))
+    }
+
+    fn arm_timer(&mut self, now_ms: u64) {
+        self.deadline_ms = if self.turn_duration_ms > 0 { now_ms + self.turn_duration_ms } else { 0 };
+    }
+
+    fn first_active_from(&self, start: usize) -> usize {
+        (start..self.actors.len()).find(|&i| self.actors[i].active).unwrap_or(0)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Simultaneous reveal: everyone commits a move, then all resolve at once.
+// ---------------------------------------------------------------------------
+
+/// Collects one hidden submission per actor, then resolves when everyone
+/// (or the deadline) is in. Submissions stay in the hub until the reveal.
+#[derive(Serialize, Deserialize, Clone, Debug, Default)]
+pub struct RevealRound {
+    pub expected: Vec<String>,
+    pub submissions: Vec<(String, serde_json::Value)>,
+    pub deadline_ms: u64,
+}
+
+impl RevealRound {
+    pub fn new(expected: Vec<String>, now_ms: u64, window_ms: u64) -> Self {
+        Self { expected, submissions: Vec::new(), deadline_ms: if window_ms > 0 { now_ms + window_ms } else { 0 } }
+    }
+
+    /// Record a submission. Duplicates and strangers are rejected.
+    pub fn submit(&mut self, actor_id: &str, payload: serde_json::Value) -> Result<(), &'static str> {
+        if !self.expected.iter().any(|id| id == actor_id) {
+            return Err("not a participant");
+        }
+        if self.submissions.iter().any(|(id, _)| id == actor_id) {
+            return Err("already submitted");
+        }
+        self.submissions.push((actor_id.to_string(), payload));
+        Ok(())
+    }
+
+    pub fn complete(&self) -> bool {
+        self.submissions.len() == self.expected.len()
+    }
+
+    /// Ready to reveal: everyone submitted, or the window closed.
+    pub fn ready(&self, now_ms: u64) -> bool {
+        self.complete() || (self.deadline_ms > 0 && now_ms >= self.deadline_ms)
+    }
+
+    /// Consume and return all submissions (the reveal).
+    pub fn reveal(self) -> Vec<(String, serde_json::Value)> {
+        self.submissions
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn order3() -> TurnOrder {
+        TurnOrder::new([("slow".into(), 3), ("fast".into(), 9), ("mid".into(), 5)], 10_000, TimeoutPolicy::Skip)
+    }
+
+    #[test]
+    fn initiative_orders_and_rounds_advance() {
+        let mut order = order3();
+        let events = order.start(1_000);
+        assert!(matches!(&events[1], TurnEvent::TurnStarted { actor_id, round: 1, .. } if actor_id == "fast"));
+        assert_eq!(order.current_actor().unwrap().id, "fast");
+
+        order.advance(2_000);
+        assert_eq!(order.current_actor().unwrap().id, "mid");
+        order.advance(3_000);
+        assert_eq!(order.current_actor().unwrap().id, "slow");
+        // Wrap: new round.
+        let events = order.advance(4_000);
+        assert!(events.iter().any(|e| matches!(e, TurnEvent::RoundStarted { round: 2 })));
+        assert_eq!(order.current_actor().unwrap().id, "fast");
+        assert_eq!(order.round, 2);
+    }
+
+    #[test]
+    fn timeout_skips_and_forfeit_policy_removes() {
+        let mut order = order3();
+        order.start(0);
+        assert!(order.tick(9_999).is_empty(), "before the deadline");
+        let events = order.tick(10_000);
+        assert!(matches!(&events[0], TurnEvent::ActorSkipped { actor_id } if actor_id == "fast"));
+        assert_eq!(order.current_actor().unwrap().id, "mid");
+
+        let mut hard = TurnOrder::new([("a".into(), 2), ("b".into(), 1)], 5_000, TimeoutPolicy::Forfeit);
+        hard.start(0);
+        let events = hard.tick(5_000);
+        assert!(matches!(&events[0], TurnEvent::ActorForfeited { actor_id } if actor_id == "a"));
+        assert!(events.iter().any(|e| matches!(e, TurnEvent::OrderExhausted)));
+        assert_eq!(hard.active_count(), 1);
+    }
+
+    #[test]
+    fn forfeit_mid_order_passes_turn() {
+        let mut order = order3();
+        order.start(0);
+        // "mid" (not current) forfeits: current turn unaffected.
+        assert!(order.forfeit("mid", 1_000).is_empty());
+        assert_eq!(order.current_actor().unwrap().id, "fast");
+        // Current forfeits: turn passes to the next active ("slow").
+        let events = order.forfeit("fast", 2_000);
+        assert!(events.iter().any(|e| matches!(e, TurnEvent::OrderExhausted)));
+    }
+
+    #[test]
+    fn reveal_round_collects_then_reveals() {
+        let mut round = RevealRound::new(vec!["a".into(), "b".into()], 0, 30_000);
+        assert_eq!(round.submit("x", json!(1)).unwrap_err(), "not a participant");
+        round.submit("a", json!("rock")).unwrap();
+        assert_eq!(round.submit("a", json!("paper")).unwrap_err(), "already submitted");
+        assert!(!round.ready(1_000), "waiting on b");
+        assert!(round.ready(30_000), "window closed");
+        round.submit("b", json!("scissors")).unwrap();
+        assert!(round.complete() && round.ready(1_000));
+        let submissions = round.reveal();
+        assert_eq!(submissions.len(), 2);
+    }
+
+    #[test]
+    fn serde_roundtrip() {
+        let mut order = order3();
+        order.start(0);
+        let json = serde_json::to_string(&order).unwrap();
+        let restored: TurnOrder = serde_json::from_str(&json).unwrap();
+        assert_eq!(restored.current_actor().unwrap().id, "fast");
+    }
+}

package/crates/ckx-sdk/src/kit/presence.rs

@@ -0,0 +1,142 @@
+//! Where players are, for hubs that referee space (an arena, a race, a ball, a capture point, a
+//! shrinking zone): the actors near a place, read with the node API (`world.read`), each
+//! player's position as precise as their actor's state allows.
+//!
+//! Positions are in chunks, fractional. An actor whose state is an [`ActorState`] map or the
+//! 48-byte engine pose (`f32` x, y, z in blocks first, 16 blocks a chunk) is placed exactly;
+//! any other is placed at its chunk's centre, so a game that wants the hub to see more than
+//! which chunk a player is in replicates its players with one of those two.
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+use super::wire::ActorState;
+use crate::node::{Actor, ChunkPos};
+use crate::{CallError, Ctx, decode};
+
+/// Blocks in a chunk's edge, for the engine pose's world coordinates.
+pub const CHUNK_BLOCKS: f64 = 16.0;
+/// The engine pose's length.
+pub const POSE_BYTES: usize = 48;
+
+/// One player near the place, as last seen.
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub struct Seen {
+    pub player: u64,
+    pub uuid: String,
+    pub x: f64,
+    pub y: f64,
+    pub z: f64,
+    /// Placed from the actor's state, not its chunk's centre.
+    pub precise: bool,
+}
+
+/// Where an actor is, in chunks, and whether that came from its state.
+pub fn position_of(actor: &Actor) -> (f64, f64, f64, bool) {
+    if let Some(state) = actor.state.as_deref() {
+        if let Ok(s) = decode::<ActorState>(state) {
+            return (s.x, s.y, s.z, true);
+        }
+        if state.len() >= POSE_BYTES {
+            let f = |i: usize| f32::from_le_bytes([state[i], state[i + 1], state[i + 2], state[i + 3]]) as f64;
+            let (x, y, z) = (f(0), f(4), f(8));
+            if x.is_finite() && y.is_finite() && z.is_finite() {
+                return (x / CHUNK_BLOCKS, y / CHUNK_BLOCKS, z / CHUNK_BLOCKS, true);
+            }
+        }
+    }
+    (actor.chunk.x as f64 + 0.5, actor.chunk.y as f64 + 0.5, actor.chunk.z as f64 + 0.5, false)
+}
+
+/// Every player among `actors`, once each (the first actor a player has).
+pub fn players_among(actors: &[Actor]) -> Vec<Seen> {
+    let mut out: Vec<Seen> = Vec::new();
+    for a in actors {
+        let Some(player) = a.player else { continue };
+        if out.iter().any(|s| s.player == player) {
+            continue;
+        }
+        let (x, y, z, precise) = position_of(a);
+        out.push(Seen { player, uuid: a.uuid.clone(), x, y, z, precise });
+    }
+    out
+}
+
+/// The players within `radius` chunks (at most 3 across, 1 up and down) of `center`.
+pub fn nearby(ctx: &Ctx, center: ChunkPos, radius: u8) -> Result<Vec<Seen>, CallError> {
+    Ok(players_among(&ctx.world().actors_near(center, radius, 1)?))
+}
+
+/// Distance on the ground (x and z), in chunks.
+pub fn ground_distance(a: (f64, f64), b: (f64, f64)) -> f64 {
+    ((a.0 - b.0).powi(2) + (a.1 - b.1).powi(2)).sqrt()
+}
+
+/// Players' recent positions and speeds, from one scan to the next.
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq)]
+pub struct Tracker {
+    #[serde(default)]
+    pub last: BTreeMap<u64, Track>,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub struct Track {
+    pub x: f64,
+    pub z: f64,
+    pub at: u64,
+    /// Chunks a second between the last two scans; 0 for the first.
+    pub speed: f64,
+}
+
+impl Tracker {
+    /// Takes a scan at `now`; players not in it are forgotten. Returns each player's speed.
+    pub fn update(&mut self, seen: &[Seen], now: u64) -> BTreeMap<u64, f64> {
+        let mut next = BTreeMap::new();
+        for s in seen {
+            let speed = match self.last.get(&s.player) {
+                Some(t) if now > t.at => ground_distance((t.x, t.z), (s.x, s.z)) / ((now - t.at) as f64 / 1_000.0),
+                _ => 0.0,
+            };
+            next.insert(s.player, Track { x: s.x, z: s.z, at: now, speed });
+        }
+        self.last = next;
+        self.last.iter().map(|(p, t)| (*p, t.speed)).collect()
+    }
+
+    pub fn position(&self, player: u64) -> Option<(f64, f64)> {
+        self.last.get(&player).map(|t| (t.x, t.z))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::encode;
+
+    fn actor(player: Option<u64>, chunk: (i64, i64, i64), state: Option<Vec<u8>>) -> Actor {
+        Actor { uuid: format!("a{player:?}"), player, chunk: ChunkPos::new(chunk.0, chunk.1, chunk.2), state }
+    }
+
+    #[test]
+    fn a_kit_state_or_an_engine_pose_places_a_player_exactly_and_anything_else_at_the_chunk_centre() {
+        let kit = encode(&ActorState::new("player", 1, 2.25, -3.5)).unwrap();
+        assert_eq!(position_of(&actor(Some(1), (2, 0, -4), Some(kit))), (2.25, 0.0, -3.5, true));
+        let mut pose = vec![0u8; POSE_BYTES];
+        pose[0..4].copy_from_slice(&40.0f32.to_le_bytes());
+        pose[8..12].copy_from_slice(&(-8.0f32).to_le_bytes());
+        assert_eq!(position_of(&actor(Some(2), (2, 0, -1), Some(pose))), (2.5, 0.0, -0.5, true));
+        assert_eq!(position_of(&actor(Some(3), (1, 0, 1), Some(b"opaque".to_vec()))), (1.5, 0.5, 1.5, false));
+        let seen = players_among(&[actor(None, (0, 0, 0), None), actor(Some(4), (0, 0, 0), None), actor(Some(4), (9, 0, 9), None)]);
+        assert_eq!(seen.len(), 1, "an NPC is not a player, and a player counts once");
+    }
+
+    #[test]
+    fn a_tracker_tells_each_players_speed() {
+        let mut t = Tracker::default();
+        let s = |x: f64| vec![Seen { player: 1, uuid: "u".into(), x, y: 0.0, z: 0.0, precise: true }];
+        assert_eq!(t.update(&s(0.0), 1_000)[&1], 0.0);
+        assert_eq!(t.update(&s(3.0), 2_000)[&1], 3.0);
+        assert!(t.update(&[], 3_000).is_empty(), "gone from the scan, forgotten");
+    }
+}