@crowdedkingdoms/ckx-kit 0.3.0-dev.1 → 0.5.0-dev.1

package/crates/ckx-sdk/src/kit/sim/daycycle.rs

@@ -0,0 +1,71 @@
+//! The deterministic day/night clock: a pure function of wall-clock ms, so
+//! hubs and clients agree without any synchronization message.
+//! A 20-minute day is the
+//! default; games pick their own length.
+
+use serde::{Deserialize, Serialize};
+
+pub const DEFAULT_DAY_LENGTH_MS: u64 = 1_200_000; // 20 minutes
+
+#[derive(Serialize, Deserialize, Clone, Copy, Debug)]
+pub struct DayCycle {
+    pub day_length_ms: u64,
+}
+
+impl Default for DayCycle {
+    fn default() -> Self {
+        Self { day_length_ms: DEFAULT_DAY_LENGTH_MS }
+    }
+}
+
+impl DayCycle {
+    pub fn new(day_length_ms: u64) -> Self {
+        Self { day_length_ms: day_length_ms.max(1) }
+    }
+
+    /// Phase in [0, 1): 0 = day start, 0.5 = day/night boundary region.
+    pub fn phase(&self, now_ms: u64) -> f32 {
+        (now_ms % self.day_length_ms) as f32 / self.day_length_ms as f32
+    }
+
+    /// Night when sin(phase*TAU) dips below -0.05.
+    pub fn is_night(&self, now_ms: u64) -> bool {
+        (self.phase(now_ms) * std::f32::consts::TAU).sin() < -0.05
+    }
+
+    /// Sun height in [-1, 1] (drive lighting / spawn weights).
+    pub fn sun(&self, now_ms: u64) -> f32 {
+        (self.phase(now_ms) * std::f32::consts::TAU).sin()
+    }
+
+    /// Day number since epoch (season math, daily resets).
+    pub fn day_index(&self, now_ms: u64) -> u64 {
+        now_ms / self.day_length_ms
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_twenty_minute_day_turns_to_night_and_back() {
+        let cycle = DayCycle::default();
+        // First half of the cycle: sun up (sin > 0).
+        assert!(!cycle.is_night(60_000));
+        assert!(cycle.sun(300_000) > 0.99); // quarter cycle = noon
+        // Second half: night.
+        assert!(cycle.is_night(900_000)); // three-quarter = midnight
+        assert_eq!(cycle.day_index(2_500_000), 2);
+    }
+
+    #[test]
+    fn deterministic_across_instances() {
+        let a = DayCycle::new(600_000);
+        let b = DayCycle::new(600_000);
+        for t in (0..3_000_000).step_by(90_000) {
+            assert_eq!(a.is_night(t), b.is_night(t));
+            assert_eq!(a.phase(t), b.phase(t));
+        }
+    }
+}

package/crates/ckx-sdk/src/kit/sim/mod.rs

@@ -0,0 +1,10 @@
+//! World simulation a hub runs: [`daycycle`] (a clock everyone agrees on from the time alone),
+//! [`weather`] (seeded fronts), [`nodes`] (resource nodes that deplete and regrow), [`waves`]
+//! (timed spawn waves) and [`zones`] (rule boxes and shrinking circles). Deterministic over
+//! `now_ms` and a seeded [`Rng`](super::Rng).
+
+pub mod daycycle;
+pub mod nodes;
+pub mod waves;
+pub mod weather;
+pub mod zones;

package/crates/ckx-sdk/src/kit/sim/nodes.rs

@@ -0,0 +1,109 @@
+//! Resource nodes: harvest/deplete/respawn lifecycle (ore veins, berry
+//! bushes, fishing spots). Pure state machine — a hub keeps the pool in
+//! its state.
+
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Default)]
+pub enum NodePhase {
+    #[default]
+    Ready,
+    /// Depleted; respawns at the embedded time.
+    Respawning { at_ms: u64 },
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, Default)]
+pub struct Node {
+    pub phase: NodePhase,
+    /// Remaining harvests before depletion (0 = infinite until depleted
+    /// explicitly).
+    pub charges: u32,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, Default)]
+pub struct NodePool {
+    pub nodes: BTreeMap<String, Node>,
+}
+
+pub struct HarvestOutcome {
+    pub harvested: bool,
+    pub depleted: bool,
+}
+
+impl NodePool {
+    /// Register a node (idempotent; keeps existing state).
+    pub fn ensure(&mut self, id: &str, charges: u32) -> &mut Node {
+        self.nodes.entry(id.to_string()).or_insert(Node { phase: NodePhase::Ready, charges })
+    }
+
+    /// Attempt a harvest. Depletes when charges run out.
+    pub fn harvest(&mut self, id: &str, now_ms: u64, respawn_ms: u64) -> HarvestOutcome {
+        let Some(node) = self.nodes.get_mut(id) else {
+            return HarvestOutcome { harvested: false, depleted: false };
+        };
+        if !matches!(node.phase, NodePhase::Ready) {
+            return HarvestOutcome { harvested: false, depleted: false };
+        }
+        let depleted = if node.charges > 0 {
+            node.charges -= 1;
+            node.charges == 0
+        } else {
+            false
+        };
+        if depleted {
+            node.phase = NodePhase::Respawning { at_ms: now_ms + respawn_ms };
+        }
+        HarvestOutcome { harvested: true, depleted }
+    }
+
+    /// Tick respawns: returns ids that just came back (re-arm charges).
+    pub fn tick(&mut self, now_ms: u64, recharge: u32) -> Vec<String> {
+        let mut respawned = Vec::new();
+        for (id, node) in &mut self.nodes {
+            if let NodePhase::Respawning { at_ms } = node.phase
+                && now_ms >= at_ms
+            {
+                node.phase = NodePhase::Ready;
+                node.charges = recharge;
+                respawned.push(id.clone());
+            }
+        }
+        respawned
+    }
+
+    pub fn is_ready(&self, id: &str) -> bool {
+        matches!(self.nodes.get(id), Some(Node { phase: NodePhase::Ready, .. }))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn harvest_deplete_respawn() {
+        let mut pool = NodePool::default();
+        pool.ensure("vein-1", 2);
+        assert!(pool.harvest("vein-1", 1_000, 30_000).harvested);
+        let second = pool.harvest("vein-1", 2_000, 30_000);
+        assert!(second.harvested && second.depleted);
+        // Depleted: further harvests fail; not ready.
+        assert!(!pool.harvest("vein-1", 3_000, 30_000).harvested);
+        assert!(!pool.is_ready("vein-1"));
+        // Respawn on schedule with recharged charges.
+        assert!(pool.tick(31_000, 2).is_empty());
+        assert_eq!(pool.tick(32_000, 2), vec!["vein-1".to_string()]);
+        assert!(pool.harvest("vein-1", 33_000, 30_000).harvested);
+    }
+
+    #[test]
+    fn infinite_nodes_never_self_deplete() {
+        let mut pool = NodePool::default();
+        pool.ensure("well", 0);
+        for t in 0..50 {
+            let outcome = pool.harvest("well", t, 1_000);
+            assert!(outcome.harvested && !outcome.depleted);
+        }
+    }
+}

package/crates/ckx-sdk/src/kit/sim/waves.rs

@@ -0,0 +1,105 @@
+//! Wave schedules: primitives for timed spawn waves (tower defense, horde
+//! nights): the scheduling core a director hub drives.
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub struct WaveDef {
+    /// Entries: (unit id, count).
+    pub units: Vec<(String, u32)>,
+    /// Delay after the previous wave clears (or starts, for timed mode).
+    pub delay_ms: u64,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub enum WavePhase {
+    /// Before wave `next` starts; starts at the embedded time.
+    Countdown { next: usize, starts_at_ms: u64 },
+    /// Wave `index` is live.
+    Active { index: usize },
+    /// All waves done.
+    Complete,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct WaveSchedule {
+    pub phase: WavePhase,
+}
+
+impl Default for WaveSchedule {
+    fn default() -> Self {
+        Self { phase: WavePhase::Complete }
+    }
+}
+
+pub enum WaveEvent {
+    /// Spawn this wave's units now.
+    Start(usize),
+    Finished,
+}
+
+impl WaveSchedule {
+    /// Arm the schedule from wave 0 with the first delay.
+    pub fn start(waves: &[WaveDef], now_ms: u64) -> Self {
+        match waves.first() {
+            Some(first) => Self { phase: WavePhase::Countdown { next: 0, starts_at_ms: now_ms + first.delay_ms } },
+            None => Self { phase: WavePhase::Complete },
+        }
+    }
+
+    /// Advance. `active_cleared` = the live wave's units are all dead.
+    pub fn step(&mut self, waves: &[WaveDef], now_ms: u64, active_cleared: bool) -> Option<WaveEvent> {
+        match self.phase.clone() {
+            WavePhase::Countdown { next, starts_at_ms } if now_ms >= starts_at_ms => {
+                self.phase = WavePhase::Active { index: next };
+                Some(WaveEvent::Start(next))
+            }
+            WavePhase::Active { index } if active_cleared => {
+                let next = index + 1;
+                match waves.get(next) {
+                    Some(wave) => {
+                        self.phase = WavePhase::Countdown { next, starts_at_ms: now_ms + wave.delay_ms };
+                        None
+                    }
+                    None => {
+                        self.phase = WavePhase::Complete;
+                        Some(WaveEvent::Finished)
+                    }
+                }
+            }
+            _ => None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn two_waves() -> Vec<WaveDef> {
+        vec![
+            WaveDef { units: vec![("slime".into(), 3)], delay_ms: 5_000 },
+            WaveDef { units: vec![("skeleton".into(), 2)], delay_ms: 10_000 },
+        ]
+    }
+
+    #[test]
+    fn full_run() {
+        let waves = two_waves();
+        let mut schedule = WaveSchedule::start(&waves, 0);
+        assert!(schedule.step(&waves, 4_999, false).is_none());
+        assert!(matches!(schedule.step(&waves, 5_000, false), Some(WaveEvent::Start(0))));
+        // Wave 0 live until cleared.
+        assert!(schedule.step(&waves, 8_000, false).is_none());
+        assert!(schedule.step(&waves, 9_000, true).is_none()); // countdown to wave 1
+        assert!(matches!(schedule.step(&waves, 19_000, false), Some(WaveEvent::Start(1))));
+        assert!(matches!(schedule.step(&waves, 25_000, true), Some(WaveEvent::Finished)));
+        assert_eq!(schedule.phase, WavePhase::Complete);
+    }
+
+    #[test]
+    fn empty_schedule_completes() {
+        let schedule = WaveSchedule::start(&[], 0);
+        assert_eq!(schedule.phase, WavePhase::Complete);
+    }
+}

package/crates/ckx-sdk/src/kit/sim/weather.rs

@@ -0,0 +1,142 @@
+//! Weather fronts: a seeded state machine that walks through weather kinds
+//! with randomized durations, plus broadcast helpers. Clients receive
+//! transitions as type-90 server events (see `EVENT_WEATHER`) and render
+//! locally; late joiners read the current front from the hub.
+
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+
+use crate::kit::Rng;
+use crate::kit::wire;
+use crate::node::ChunkPos;
+use crate::{Ctx, Result};
+
+/// The platform-reserved server-event type for weather/season transitions.
+pub const EVENT_WEATHER: u16 = 90;
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub struct WeatherKind {
+    pub id: String,
+    /// Relative pick weight (0 disables).
+    pub weight: u32,
+    pub min_ms: u64,
+    pub max_ms: u64,
+}
+
+pub fn default_kinds() -> Vec<WeatherKind> {
+    vec![
+        WeatherKind { id: "clear".into(), weight: 6, min_ms: 300_000, max_ms: 900_000 },
+        WeatherKind { id: "cloudy".into(), weight: 3, min_ms: 180_000, max_ms: 600_000 },
+        WeatherKind { id: "rain".into(), weight: 2, min_ms: 120_000, max_ms: 480_000 },
+        WeatherKind { id: "storm".into(), weight: 1, min_ms: 60_000, max_ms: 240_000 },
+    ]
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, Default)]
+pub struct WeatherState {
+    pub current: String,
+    pub since_ms: u64,
+    pub until_ms: u64,
+}
+
+pub struct Transition {
+    pub from: String,
+    pub to: String,
+    pub until_ms: u64,
+}
+
+/// Advance the front. Returns the transition when the front changed (emit it
+/// to clients), `None` while the current front holds.
+pub fn step(state: &mut WeatherState, kinds: &[WeatherKind], now_ms: u64, rng: &mut Rng) -> Option<Transition> {
+    if !state.current.is_empty() && now_ms < state.until_ms {
+        return None;
+    }
+    let total: u32 = kinds.iter().map(|k| k.weight).sum();
+    if total == 0 {
+        return None;
+    }
+    // Weighted pick, avoiding an immediate repeat when there's a choice.
+    let mut pick = || {
+        let mut roll = (rng.next_u64() % total as u64) as u32;
+        for kind in kinds {
+            if roll < kind.weight {
+                return kind.clone();
+            }
+            roll -= kind.weight;
+        }
+        kinds[0].clone()
+    };
+    let mut next = pick();
+    if next.id == state.current && kinds.iter().filter(|k| k.weight > 0).count() > 1 {
+        for _ in 0..4 {
+            next = pick();
+            if next.id != state.current {
+                break;
+            }
+        }
+    }
+    let duration = next.min_ms + rng.next_u64() % (next.max_ms.saturating_sub(next.min_ms).max(1));
+    let from = std::mem::replace(&mut state.current, next.id.clone());
+    state.since_ms = now_ms;
+    state.until_ms = now_ms + duration;
+    Some(Transition { from, to: next.id, until_ms: state.until_ms })
+}
+
+/// The client-facing JSON for a front (both the event body and `forecast`).
+pub fn front_json(state: &WeatherState, now_ms: u64) -> Value {
+    json!({
+        "weather": state.current,
+        "sinceMs": state.since_ms,
+        "untilMs": state.until_ms,
+        "remainingMs": state.until_ms.saturating_sub(now_ms),
+    })
+}
+
+/// Sends a transition as a type-90 server event to the players within `distance` chunks of
+/// `at`, from the hub's `actor`.
+pub fn emit_transition(ctx: &Ctx, at: ChunkPos, distance: u8, actor: &[u8; 32], state: &WeatherState, now_ms: u64) -> Result<()> {
+    wire::emit_event(ctx, at, distance, actor, EVENT_WEATHER, &front_json(state, now_ms))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn fronts_advance_and_hold() {
+        let kinds = default_kinds();
+        let mut state = WeatherState::default();
+        let mut rng = Rng::seeded(7);
+        let t = step(&mut state, &kinds, 1_000, &mut rng).expect("first step transitions");
+        assert_eq!(t.from, "");
+        assert!(!state.current.is_empty());
+        assert!(state.until_ms > 1_000);
+        // Holds until the front expires.
+        let until = state.until_ms;
+        assert!(step(&mut state, &kinds, until - 1, &mut rng).is_none());
+        let prev = state.current.clone();
+        let t2 = step(&mut state, &kinds, until, &mut rng).expect("expiry transitions");
+        assert_eq!(t2.from, prev);
+        assert_ne!(t2.to, prev, "avoids immediate repeats");
+    }
+
+    #[test]
+    fn deterministic_for_a_seed() {
+        let kinds = default_kinds();
+        let mut a = (WeatherState::default(), Rng::seeded(42));
+        let mut b = (WeatherState::default(), Rng::seeded(42));
+        for t in (0..10_000_000u64).step_by(60_000) {
+            let ta = step(&mut a.0, &kinds, t, &mut a.1).map(|x| x.to);
+            let tb = step(&mut b.0, &kinds, t, &mut b.1).map(|x| x.to);
+            assert_eq!(ta, tb);
+        }
+    }
+
+    #[test]
+    fn front_json_shape() {
+        let state = WeatherState { current: "rain".into(), since_ms: 100, until_ms: 5_100 };
+        let v = front_json(&state, 1_100);
+        assert_eq!(v["weather"], "rain");
+        assert_eq!(v["remainingMs"], 4_000);
+    }
+}

package/crates/ckx-sdk/src/kit/sim/zones.rs

@@ -0,0 +1,218 @@
+//! Rule zones: static axis-aligned boxes tagged with rule strings ("safe",
+//! "pvp", "build-locked") plus **shrinking circles** — the
+//! battle-royale zone: a phased schedule of (radius, hold, shrink) steps
+//! with warning/shrink/settle events for the type-98 lane.
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub struct Zone {
+    pub id: String,
+    pub rule: String,
+    pub min: (f32, f32, f32),
+    pub max: (f32, f32, f32),
+}
+
+impl Zone {
+    pub fn contains(&self, pos: (f32, f32, f32)) -> bool {
+        pos.0 >= self.min.0
+            && pos.0 <= self.max.0
+            && pos.1 >= self.min.1
+            && pos.1 <= self.max.1
+            && pos.2 >= self.min.2
+            && pos.2 <= self.max.2
+    }
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, Default)]
+pub struct ZoneSet {
+    pub zones: Vec<Zone>,
+}
+
+impl ZoneSet {
+    /// All zones containing the position.
+    pub fn at(&self, pos: (f32, f32, f32)) -> Vec<&Zone> {
+        self.zones.iter().filter(|z| z.contains(pos)).collect()
+    }
+
+    /// Does any zone with this rule cover the position?
+    pub fn has_rule(&self, pos: (f32, f32, f32), rule: &str) -> bool {
+        self.zones.iter().any(|z| z.rule == rule && z.contains(pos))
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Shrinking circles (BR zones)
+// ---------------------------------------------------------------------------
+
+/// One phase of a shrinking-zone schedule.
+#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq)]
+pub struct ShrinkPhase {
+    /// The radius this phase shrinks TO.
+    pub radius: f32,
+    /// How long the zone HOLDS before shrinking (the warning window).
+    pub hold_ms: u64,
+    /// How long the shrink itself takes (radius interpolates linearly).
+    pub shrink_ms: u64,
+}
+
+/// Announcements a shrinking zone produces as time advances.
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub enum ZoneEvent {
+    /// A hold began: the zone will start shrinking to `to_radius` at `at_ms`.
+    Warning { phase: usize, to_radius: f32, shrink_starts_at_ms: u64 },
+    /// The shrink began.
+    Shrinking { phase: usize, to_radius: f32 },
+    /// The phase's target radius was reached.
+    Settled { phase: usize, radius: f32 },
+    /// Every phase is done (the final circle).
+    Final { radius: f32 },
+}
+
+/// A battle-royale circle: fixed center, radius stepping down a schedule.
+/// Pure clock math — feed it `now_ms`, read `radius()` and drain events.
+#[derive(Serialize, Deserialize, Clone, Debug, Default)]
+pub struct ShrinkingZone {
+    pub center: (f32, f32),
+    pub initial_radius: f32,
+    pub phases: Vec<ShrinkPhase>,
+    pub started_at_ms: u64,
+    /// Last phase-progress marker events were emitted for (phase, stage).
+    announced: Vec<(usize, u8)>,
+}
+
+impl ShrinkingZone {
+    pub fn start(center: (f32, f32), initial_radius: f32, phases: Vec<ShrinkPhase>, now_ms: u64) -> Self {
+        Self { center, initial_radius, phases, started_at_ms: now_ms, announced: Vec::new() }
+    }
+
+    /// Phase timeline offsets: each phase = hold then shrink.
+    fn phase_bounds(&self, phase: usize) -> (u64, u64, u64) {
+        let mut offset = 0u64;
+        for p in &self.phases[..phase] {
+            offset += p.hold_ms + p.shrink_ms;
+        }
+        let p = &self.phases[phase];
+        (offset, offset + p.hold_ms, offset + p.hold_ms + p.shrink_ms)
+    }
+
+    /// The circle's radius at `now_ms` (linear interpolation during shrinks).
+    pub fn radius(&self, now_ms: u64) -> f32 {
+        let elapsed = now_ms.saturating_sub(self.started_at_ms);
+        let mut from = self.initial_radius;
+        for (index, phase) in self.phases.iter().enumerate() {
+            let (_, shrink_start, shrink_end) = self.phase_bounds(index);
+            if elapsed < shrink_start {
+                return from;
+            }
+            if elapsed < shrink_end {
+                let t = (elapsed - shrink_start) as f32 / (shrink_end - shrink_start).max(1) as f32;
+                return from + (phase.radius - from) * t;
+            }
+            from = phase.radius;
+        }
+        from
+    }
+
+    /// Is a position inside the live circle?
+    pub fn contains(&self, pos: (f32, f32), now_ms: u64) -> bool {
+        let (dx, dz) = (pos.0 - self.center.0, pos.1 - self.center.1);
+        (dx * dx + dz * dz).sqrt() <= self.radius(now_ms)
+    }
+
+    /// Every phase fully settled?
+    pub fn done(&self, now_ms: u64) -> bool {
+        match self.phases.len() {
+            0 => true,
+            n => now_ms.saturating_sub(self.started_at_ms) >= self.phase_bounds(n - 1).2,
+        }
+    }
+
+    /// Advance the announcer: returns the events newly due at `now_ms`
+    /// (warning at hold start, shrinking at shrink start, settled at end,
+    /// final once after the last phase).
+    pub fn poll(&mut self, now_ms: u64) -> Vec<ZoneEvent> {
+        let elapsed = now_ms.saturating_sub(self.started_at_ms);
+        let mut events = Vec::new();
+        for (index, phase) in self.phases.iter().enumerate() {
+            let (hold_start, shrink_start, shrink_end) = self.phase_bounds(index);
+            let stages: [(u8, u64); 3] = [(0, hold_start), (1, shrink_start), (2, shrink_end)];
+            for (stage, at) in stages {
+                if elapsed >= at && !self.announced.contains(&(index, stage)) {
+                    self.announced.push((index, stage));
+                    events.push(match stage {
+                        0 => ZoneEvent::Warning {
+                            phase: index,
+                            to_radius: phase.radius,
+                            shrink_starts_at_ms: self.started_at_ms + shrink_start,
+                        },
+                        1 => ZoneEvent::Shrinking { phase: index, to_radius: phase.radius },
+                        _ => ZoneEvent::Settled { phase: index, radius: phase.radius },
+                    });
+                }
+            }
+        }
+        if self.done(now_ms) && !self.announced.contains(&(usize::MAX, 3)) {
+            self.announced.push((usize::MAX, 3));
+            events.push(ZoneEvent::Final { radius: self.radius(now_ms) });
+        }
+        events
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn shrinking_zone_interpolates_and_announces() {
+        let mut zone = ShrinkingZone::start(
+            (0.0, 0.0),
+            100.0,
+            vec![
+                ShrinkPhase { radius: 50.0, hold_ms: 10_000, shrink_ms: 10_000 },
+                ShrinkPhase { radius: 10.0, hold_ms: 5_000, shrink_ms: 5_000 },
+            ],
+            1_000,
+        );
+        // Hold: full radius; the warning fires immediately.
+        let events = zone.poll(1_000);
+        assert!(matches!(events[0], ZoneEvent::Warning { phase: 0, to_radius, .. } if to_radius == 50.0));
+        assert_eq!(zone.radius(5_000), 100.0);
+        // Mid-shrink: halfway between 100 and 50.
+        let events = zone.poll(16_000);
+        assert!(events.iter().any(|e| matches!(e, ZoneEvent::Shrinking { phase: 0, .. })));
+        assert!((zone.radius(16_000) - 75.0).abs() < 0.01);
+        // Settled at 50, phase 1 warning issued in the same poll window.
+        let events = zone.poll(21_500);
+        assert!(events.iter().any(|e| matches!(e, ZoneEvent::Settled { phase: 0, radius } if *radius == 50.0)));
+        assert!(events.iter().any(|e| matches!(e, ZoneEvent::Warning { phase: 1, .. })));
+        assert_eq!(zone.radius(24_000), 50.0);
+        // Final circle.
+        let events = zone.poll(31_000);
+        assert!(events.iter().any(|e| matches!(e, ZoneEvent::Settled { phase: 1, radius } if *radius == 10.0)));
+        assert!(events.iter().any(|e| matches!(e, ZoneEvent::Final { radius } if *radius == 10.0)));
+        assert!(zone.done(31_000));
+        assert!(zone.poll(40_000).is_empty(), "announce once");
+        // Containment tracks the live radius.
+        assert!(zone.contains((60.0, 0.0), 5_000));
+        assert!(!zone.contains((60.0, 0.0), 31_000));
+    }
+
+    #[test]
+    fn containment_and_rules() {
+        let set = ZoneSet {
+            zones: vec![
+                Zone { id: "spawn".into(), rule: "safe".into(), min: (-10.0, 0.0, -10.0), max: (10.0, 32.0, 10.0) },
+                Zone { id: "arena".into(), rule: "pvp".into(), min: (5.0, 0.0, 5.0), max: (30.0, 32.0, 30.0) },
+            ],
+        };
+        assert!(set.has_rule((0.0, 16.0, 0.0), "safe"));
+        assert!(!set.has_rule((0.0, 16.0, 0.0), "pvp"));
+        // Overlap region carries both rules.
+        assert_eq!(set.at((7.0, 16.0, 7.0)).len(), 2);
+        // Boundaries are inclusive; outside is outside.
+        assert!(set.has_rule((10.0, 32.0, 10.0), "safe"));
+        assert!(set.at((50.0, 16.0, 50.0)).is_empty());
+    }
+}

package/crates/ckx-sdk/src/lib.rs

@@ -47,7 +47,8 @@
 //!
 //! [`kit`] is the game kit's half here: the protocol kit hubs speak to the kit clients
 //! (snapshots and deltas with sequence numbers, retry-safe actions, refusal codes), shard keys,
-//! a seeded random generator, and the realtime event registry.
+//! a seeded random generator, the realtime event registry, and the pieces games are made of
+//! (`kit::play`, `kit::sim`, `kit::ai`, and the soft economy in `kit::econ`).
 
 mod abi;
 pub mod cron;

package/dist/cli/src/new.js

@@ -15,6 +15,17 @@ exports.TEMPLATES = {
     matchmaker: { dir: ['starters', 'matchmaker'], sdk: 'ckx-sdk', about: 'a rating queue that reserves sessions' },
     session: { dir: ['starters', 'session'], sdk: 'ckx-sdk', about: 'one game from lobby to result' },
     'npc-mobs': { dir: ['starters', 'npc-mobs'], sdk: 'ckx-sdk', about: "an area's mobs and NPCs" },
+    leaderboard: { dir: ['starters', 'leaderboard'], sdk: 'ckx-sdk', about: 'a board other hubs submit to, with seasons' },
+    deck: { dir: ['starters', 'deck'], sdk: 'ckx-sdk', about: 'a card table with hands only their player reads' },
+    tactics: { dir: ['starters', 'tactics'], sdk: 'ckx-sdk', about: "a grid battle in phases against the hub's units" },
+    director: { dir: ['starters', 'director'], sdk: 'ckx-sdk', about: 'waves down a lane, towers, a boss with phases' },
+    minigame: { dir: ['starters', 'minigame'], sdk: 'ckx-sdk', about: 'a duel of hidden throws, revealed together' },
+    instance: { dir: ['starters', 'instance'], sdk: 'ckx-sdk', about: "a party's private run: seeded floors, permadeath" },
+    arena: { dir: ['starters', 'arena'], sdk: 'ckx-sdk', about: 'classes and abilities in real time' },
+    racing: { dir: ['starters', 'racing'], sdk: 'ckx-sdk', about: 'races with laps and a ghost, and ball games' },
+    territory: { dir: ['starters', 'territory'], sdk: 'ckx-sdk', about: 'control points, and a shrinking circle' },
+    player: { dir: ['starters', 'player'], sdk: 'ckx-sdk', about: "a player's own hub: items, currency, crafting, quests (not a ledger)" },
+    market: { dir: ['starters', 'market'], sdk: 'ckx-sdk', about: 'vendors, an order book, trades between players (not a ledger)' },
 };
 const CRATE_NAME = /^[a-z][a-z0-9_-]{0,63}$/;
 function copyTree(from, to) {