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

package/README.md

@@ -37,7 +37,7 @@ on the platform: Crowdy Studio, or `execModBuild` then `execModDeploy` (see
 
 | Command | What it does |
 |---|---|
-| `ckx-kit new <template> <name>` | A crate to start from: `mod`, `client` (a mod's CLIENT half), `hub`, `spoke`, or a starter pack crate (`world-tick`, `matchmaker`, `session`, `npc-mobs`). |
+| `ckx-kit new <template> <name>` | A crate to start from: `mod`, `client` (a mod's CLIENT half), `hub`, `spoke`, or a starter pack crate (`world-tick`, `matchmaker`, `session`, `npc-mobs`, `leaderboard`, `deck`, `tactics`, `director`, `minigame`, `instance`, `arena`, `racing`, `territory`, `player`, `market`). |
 | `ckx-kit check [dir]` | The platform's source checks, on exactly the files it takes (`Cargo.toml`, `README.md`, `.rs` files under `src/`). Lists what it would not send. |
 | `ckx-kit build [dir]` | The checks, then the pinned Rust for `wasm32-unknown-unknown` with the platform's release profile and the platform's dependency versions, then the module check. `--mod` adds the mod limits. A CLIENT half is metered and optimized as the platform does it, and its capability summary, the list visitors are asked to agree to, is printed with its hash. `--json` prints a report. |
 | `ckx-kit doctor` | What a build here needs, and which platform toolchain this kit matches. |
@@ -52,7 +52,14 @@ protocol a kit hub speaks to the kit clients in CrowdyJS, CrowdyCPP and CrowdyPy
 that carry a sequence number and resync after a gap, actions a client may resend with an
 `action_id` that the hub answers once, refusals with a `kit:<code>:` code), shard keys, a seeded
 random generator and the realtime event registry. The starter pack crates speak it, so the kit
-clients' typed modules drive them as they are.
+clients' typed modules drive them as they are. From `ckx-sdk` 0.11.0 it also has the pieces the
+genre starters are made of: `kit::play` (turns, scores, cards, combat, abilities, timing, a
+movement warden for positions clients report), `kit::sim` (day cycle, weather, resource nodes,
+waves, zones) and `kit::ai` (paths, flow fields, steering, behavior trees); from 0.12.0
+`kit::econ`, the soft economy the `player` and `market` starters keep in hub state: items,
+wallets, holds, references answered once, recipes, loot with pity, production, vendors, an
+order book, levels, achievements and quests. It is not a ledger: no real money, and a transfer
+between hubs is steps, not a transaction.
 
 ## Test
 

package/crates/ckx-sdk/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ckx-sdk"
-version = "0.10.0-dev.1"
+version = "0.12.1-dev.1"
 edition = "2024"
 description = "Write ck-exec hubs, spokes and mods for Crowded Kingdoms in Rust, compiled to wasm32-unknown-unknown"
 license = "MIT OR Apache-2.0"

package/crates/ckx-sdk/src/kit/ai/brain.rs

@@ -0,0 +1,288 @@
+//! Data-driven agent behavior: a small behavior-tree interpreter whose trees
+//! live as JSON (in a hub's state or its seed), so designers
+//! iterate without recompiling Rust.
+//!
+//! Node shapes (JSON):
+//!   { "type": "sequence", "children": [...] }
+//!   { "type": "selector", "children": [...] }
+//!   { "type": "condition", "if": "<sensor>", "then": {...} }   sensors below
+//!   { "type": "idle" }
+//!   { "type": "wander", "range": 12.0, "retarget_ms": 6000 }
+//!   { "type": "follow", "target": "owner"|"nearest_player", "stop_at": 2.0 }
+//!   { "type": "chase",  "range": 14.0, "stop_at": 1.1 }
+//!   { "type": "flee",   "range": 8.0 }
+//!   { "type": "patrol", "points": [[x,z], ...], "pause_ms": 2000 }
+//!
+//! Sensors for `condition.if`: "player_near" (within `range`, default 10),
+//! "is_night", "is_day".
+//!
+//! The interpreter never moves the agent itself: it returns a [`Decision`]
+//! the hub turns into steering and emits. Ticks are bounded (tree depth
+//! caps at 8, first-decision wins), so fuel stays predictable.
+
+use super::steering::{self, Vec2};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+/// What the agent decided to do this tick.
+#[derive(Debug, Clone, PartialEq)]
+pub enum Decision {
+    Idle,
+    /// Move by this bounded step.
+    Step(Vec2),
+    /// Nothing matched / tree invalid — caller may fall back.
+    None,
+}
+
+/// Everything a tree evaluation may look at (the hub fills this in).
+pub struct Perception {
+    pub pos: Vec2,
+    pub home: Vec2,
+    /// Nearest player position, when one is visible.
+    pub nearest_player: Option<Vec2>,
+    /// Owner position (pets), when known.
+    pub owner: Option<Vec2>,
+    pub is_night: bool,
+    pub speed: f32,
+    pub dt: f32,
+    pub now_ms: u64,
+    /// Two uniform rolls in [0,1) for this tick (from the hub's seeded RNG).
+    pub roll: (f32, f32),
+    /// World half-extent for wander clamping.
+    pub bounds: f32,
+}
+
+/// Per-agent mutable memory the tree reads/writes across ticks (serde-able
+/// into the hub's state).
+#[derive(Serialize, Deserialize, Clone, Debug, Default)]
+pub struct AgentMemory {
+    pub target: Option<(f32, f32)>,
+    pub retarget_at_ms: u64,
+    pub patrol_index: usize,
+    pub pause_until_ms: u64,
+}
+
+const MAX_DEPTH: usize = 8;
+
+pub fn evaluate(tree: &Value, p: &Perception, memory: &mut AgentMemory) -> Decision {
+    eval_node(tree, p, memory, 0)
+}
+
+fn eval_node(node: &Value, p: &Perception, m: &mut AgentMemory, depth: usize) -> Decision {
+    if depth > MAX_DEPTH {
+        return Decision::None;
+    }
+    match node["type"].as_str().unwrap_or("") {
+        "sequence" | "selector" => {
+            // First child returning a real decision wins (bounded work).
+            for child in node["children"].as_array().unwrap_or(&Vec::new()) {
+                match eval_node(child, p, m, depth + 1) {
+                    Decision::None => continue,
+                    decision => return decision,
+                }
+            }
+            Decision::None
+        }
+        "condition" => {
+            if sense(node, p) {
+                eval_node(&node["then"], p, m, depth + 1)
+            } else {
+                Decision::None
+            }
+        }
+        "idle" => Decision::Idle,
+        "wander" => {
+            let range = node["range"].as_f64().unwrap_or(12.0) as f32;
+            let retarget_ms = node["retarget_ms"].as_u64().unwrap_or(6_000);
+            if m.target.is_none() || p.now_ms >= m.retarget_at_ms {
+                let t = steering::wander_target(p.home, range, p.roll.0, p.roll.1, p.bounds);
+                m.target = Some((t.x, t.z));
+                m.retarget_at_ms = p.now_ms + retarget_ms;
+            }
+            let (tx, tz) = m.target.unwrap();
+            Decision::Step(steering::seek(p.pos, Vec2::new(tx, tz), p.speed, p.dt, 0.4))
+        }
+        "follow" => {
+            let target = match node["target"].as_str().unwrap_or("nearest_player") {
+                "owner" => p.owner,
+                _ => p.nearest_player,
+            };
+            let stop_at = node["stop_at"].as_f64().unwrap_or(2.0) as f32;
+            match target {
+                Some(t) => Decision::Step(steering::arrive(p.pos, t, p.speed, p.dt, stop_at * 2.0)),
+                None => Decision::None,
+            }
+        }
+        "chase" => {
+            let range = node["range"].as_f64().unwrap_or(14.0) as f32;
+            let stop_at = node["stop_at"].as_f64().unwrap_or(1.1) as f32;
+            match p.nearest_player {
+                Some(t) if p.pos.dist(t) <= range => Decision::Step(steering::seek(p.pos, t, p.speed, p.dt, stop_at)),
+                _ => Decision::None,
+            }
+        }
+        "flee" => {
+            let range = node["range"].as_f64().unwrap_or(8.0) as f32;
+            match p.nearest_player {
+                Some(t) if p.pos.dist(t) <= range => Decision::Step(steering::flee(p.pos, t, p.speed, p.dt)),
+                _ => Decision::None,
+            }
+        }
+        "patrol" => {
+            let points: Vec<Vec2> = node["points"]
+                .as_array()
+                .unwrap_or(&Vec::new())
+                .iter()
+                .filter_map(|pt| Some(Vec2::new(pt[0].as_f64()? as f32, pt[1].as_f64()? as f32)))
+                .collect();
+            if points.is_empty() {
+                return Decision::None;
+            }
+            if p.now_ms < m.pause_until_ms {
+                return Decision::Idle;
+            }
+            let target = points[m.patrol_index % points.len()];
+            if p.pos.dist(target) <= 0.5 {
+                m.patrol_index = (m.patrol_index + 1) % points.len();
+                m.pause_until_ms = p.now_ms + node["pause_ms"].as_u64().unwrap_or(2_000);
+                return Decision::Idle;
+            }
+            Decision::Step(steering::seek(p.pos, target, p.speed, p.dt, 0.3))
+        }
+        _ => Decision::None,
+    }
+}
+
+fn sense(node: &Value, p: &Perception) -> bool {
+    match node["if"].as_str().unwrap_or("") {
+        "player_near" => {
+            let range = node["range"].as_f64().unwrap_or(10.0) as f32;
+            p.nearest_player.map(|t| p.pos.dist(t) <= range).unwrap_or(false)
+        }
+        "is_night" => p.is_night,
+        "is_day" => !p.is_night,
+        _ => false,
+    }
+}
+
+/// Canonical trees for the built-in behavior names a game's agent definitions use
+/// (`wander_passive`, `wander_hostile`, `chase_hostile`).
+pub fn builtin_tree(name: &str) -> Option<Value> {
+    let tree = match name {
+        "wander_passive" => serde_json::json!({
+            "type": "selector",
+            "children": [
+                { "type": "condition", "if": "player_near", "range": 2.5,
+                  "then": { "type": "flee", "range": 2.5 } },
+                { "type": "wander", "range": 12.0 }
+            ]
+        }),
+        "wander_hostile" | "chase_hostile" => serde_json::json!({
+            "type": "selector",
+            "children": [
+                { "type": "chase", "range": 14.0, "stop_at": 1.1 },
+                { "type": "wander", "range": 12.0 }
+            ]
+        }),
+        "wander" => serde_json::json!({ "type": "wander", "range": 12.0 }),
+        "follow_owner" => serde_json::json!({
+            "type": "selector",
+            "children": [
+                { "type": "follow", "target": "owner", "stop_at": 2.0 },
+                { "type": "wander", "range": 4.0 }
+            ]
+        }),
+        _ => return None,
+    };
+    Some(tree)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn perception(pos: (f32, f32), player: Option<(f32, f32)>) -> Perception {
+        Perception {
+            pos: Vec2::new(pos.0, pos.1),
+            home: Vec2::default(),
+            nearest_player: player.map(|(x, z)| Vec2::new(x, z)),
+            owner: None,
+            is_night: false,
+            speed: 2.0,
+            dt: 0.25,
+            now_ms: 10_000,
+            roll: (0.9, 0.1),
+            bounds: 40.0,
+        }
+    }
+
+    #[test]
+    fn hostile_chases_then_wanders() {
+        let tree = builtin_tree("chase_hostile").unwrap();
+        let mut memory = AgentMemory::default();
+        // Player in aggro range: chase step points at the player.
+        let d = evaluate(&tree, &perception((0.0, 0.0), Some((5.0, 0.0))), &mut memory);
+        match d {
+            Decision::Step(step) => assert!(step.x > 0.0),
+            other => panic!("expected chase step, got {other:?}"),
+        }
+        // No player: falls through to wander (sets a target).
+        let d = evaluate(&tree, &perception((0.0, 0.0), None), &mut memory);
+        assert!(matches!(d, Decision::Step(_)));
+        assert!(memory.target.is_some());
+    }
+
+    #[test]
+    fn passive_flees_close_players() {
+        let tree = builtin_tree("wander_passive").unwrap();
+        let mut memory = AgentMemory::default();
+        let d = evaluate(&tree, &perception((0.0, 0.0), Some((1.0, 0.0))), &mut memory);
+        match d {
+            Decision::Step(step) => assert!(step.x < 0.0, "flees away"),
+            other => panic!("expected flee, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn patrol_cycles_points() {
+        let tree = serde_json::json!({
+            "type": "patrol", "points": [[0.0, 0.0], [10.0, 0.0]], "pause_ms": 1000
+        });
+        let mut memory = AgentMemory::default();
+        // Standing on point 0: advances the index and pauses.
+        let d = evaluate(&tree, &perception((0.0, 0.0), None), &mut memory);
+        assert_eq!(d, Decision::Idle);
+        assert_eq!(memory.patrol_index, 1);
+        // After the pause: walks toward point 1.
+        let mut p = perception((0.0, 0.0), None);
+        p.now_ms = 20_000;
+        match evaluate(&tree, &p, &mut memory) {
+            Decision::Step(step) => assert!(step.x > 0.0),
+            other => panic!("expected step, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn depth_cap_and_unknown_nodes() {
+        // Deeply nested selector chain past the cap yields None.
+        let mut node = serde_json::json!({ "type": "idle" });
+        for _ in 0..12 {
+            node = serde_json::json!({ "type": "selector", "children": [node] });
+        }
+        let mut memory = AgentMemory::default();
+        assert_eq!(evaluate(&node, &perception((0.0, 0.0), None), &mut memory), Decision::None);
+        assert_eq!(evaluate(&serde_json::json!({"type": "nope"}), &perception((0.0, 0.0), None), &mut memory), Decision::None);
+    }
+
+    #[test]
+    fn follow_owner_tree() {
+        let tree = builtin_tree("follow_owner").unwrap();
+        let mut memory = AgentMemory::default();
+        let mut p = perception((0.0, 0.0), None);
+        p.owner = Some(Vec2::new(8.0, 0.0));
+        match evaluate(&tree, &p, &mut memory) {
+            Decision::Step(step) => assert!(step.x > 0.0),
+            other => panic!("expected follow step, got {other:?}"),
+        }
+    }
+}

package/crates/ckx-sdk/src/kit/ai/flow.rs

@@ -0,0 +1,163 @@
+//! Flow fields: one breadth-first distance field from the goal(s), then any
+//! number of agents descend it with O(1) lookups per step — the tower-defense
+//! creep mover (many agents, one goal, shared computation). Rebuild the field
+//! only when the world changes (tower placed); agents just follow.
+
+use super::path::CostProvider;
+use serde::{Deserialize, Serialize};
+use std::collections::VecDeque;
+
+/// A baked distance field over a bounded grid window. Serde-able so hubs
+/// can persist it, but rebuilding from the provider is usually cheaper than
+/// storing it durably.
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct FlowField {
+    pub min_x: i32,
+    pub min_z: i32,
+    pub width: i32,
+    pub height: i32,
+    /// Distance to the nearest goal per cell; u32::MAX = unreachable/blocked.
+    distances: Vec<u32>,
+}
+
+impl FlowField {
+    /// Build the field inside the window from the goal cells outward,
+    /// respecting the provider's blocked cells. Cost = uniform 1 per step
+    /// (weighted providers still gate walkability; weighting the descent is
+    /// deliberately v2). `max_cells` caps the BFS for fuel safety.
+    pub fn build(
+        provider: &impl CostProvider,
+        window: (i32, i32, i32, i32), // min_x, min_z, width, height
+        goals: &[(i32, i32)],
+        max_cells: usize,
+    ) -> Self {
+        let (min_x, min_z, width, height) = window;
+        let mut field = Self { min_x, min_z, width, height, distances: vec![u32::MAX; (width * height).max(0) as usize] };
+        let mut queue: VecDeque<(i32, i32)> = VecDeque::new();
+        for &(gx, gz) in goals {
+            if let Some(index) = field.index(gx, gz)
+                && provider.cost(gx, gz).is_some()
+            {
+                field.distances[index] = 0;
+                queue.push_back((gx, gz));
+            }
+        }
+        let mut visited = 0usize;
+        while let Some((x, z)) = queue.pop_front() {
+            visited += 1;
+            if visited > max_cells {
+                break;
+            }
+            let here = field.distance(x, z).unwrap_or(u32::MAX);
+            for (dx, dz) in [(0, 1), (0, -1), (1, 0), (-1, 0)] {
+                let (nx, nz) = (x + dx, z + dz);
+                let Some(index) = field.index(nx, nz) else { continue };
+                if provider.cost(nx, nz).is_none() {
+                    continue;
+                }
+                if field.distances[index] > here.saturating_add(1) {
+                    field.distances[index] = here + 1;
+                    queue.push_back((nx, nz));
+                }
+            }
+        }
+        field
+    }
+
+    fn index(&self, x: i32, z: i32) -> Option<usize> {
+        let (dx, dz) = (x - self.min_x, z - self.min_z);
+        if dx < 0 || dz < 0 || dx >= self.width || dz >= self.height {
+            return None;
+        }
+        Some((dz * self.width + dx) as usize)
+    }
+
+    /// Distance to the nearest goal (None outside the window or unreachable).
+    pub fn distance(&self, x: i32, z: i32) -> Option<u32> {
+        let d = self.distances[self.index(x, z)?];
+        (d != u32::MAX).then_some(d)
+    }
+
+    /// The descending step from (x, z): the 4-neighbor with the smallest
+    /// distance, when strictly smaller than here. None at goals/unreachable.
+    pub fn step(&self, x: i32, z: i32) -> Option<(i32, i32)> {
+        let here = self.distance(x, z)?;
+        if here == 0 {
+            return None; // at a goal
+        }
+        let mut best: Option<((i32, i32), u32)> = None;
+        for (dx, dz) in [(0, 1), (0, -1), (1, 0), (-1, 0)] {
+            let (nx, nz) = (x + dx, z + dz);
+            if let Some(d) = self.distance(nx, nz)
+                && d < here
+                && best.is_none_or(|(_, bd)| d < bd)
+            {
+                best = Some(((dx, dz), d));
+            }
+        }
+        best.map(|(step, _)| step)
+    }
+
+    /// Follow the field from (x, z) for up to `max_steps`, returning the
+    /// walked cells (excluding the start). Agents usually take 1 per tick;
+    /// this helper powers tests and catch-up moves.
+    pub fn walk(&self, mut x: i32, mut z: i32, max_steps: usize) -> Vec<(i32, i32)> {
+        let mut path = Vec::new();
+        for _ in 0..max_steps {
+            let Some((dx, dz)) = self.step(x, z) else { break };
+            x += dx;
+            z += dz;
+            path.push((x, z));
+        }
+        path
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::kit::ai::path::GridProvider;
+
+    fn provider<'a>(blocked: &'a dyn Fn(i32, i32) -> bool) -> GridProvider<'a> {
+        GridProvider { width: 32, height: 32, blocked }
+    }
+
+    #[test]
+    fn field_descends_to_goal() {
+        let open = |_x: i32, _z: i32| false;
+        let field = FlowField::build(&provider(&open), (0, 0, 32, 32), &[(31, 16)], 100_000);
+        assert_eq!(field.distance(31, 16), Some(0));
+        assert_eq!(field.distance(0, 16), Some(31));
+        // Walking from anywhere reaches the goal in exactly distance steps.
+        let path = field.walk(0, 16, 100);
+        assert_eq!(path.len(), 31);
+        assert_eq!(*path.last().unwrap(), (31, 16));
+    }
+
+    #[test]
+    fn field_routes_around_walls_and_marks_unreachable() {
+        // Wall at x=10 with a gap at z=0.
+        let wall = |x: i32, z: i32| x == 10 && z != 0;
+        let field = FlowField::build(&provider(&wall), (0, 0, 32, 32), &[(31, 16)], 100_000);
+        let path = field.walk(0, 16, 200);
+        assert_eq!(*path.last().unwrap(), (31, 16));
+        assert!(path.contains(&(10, 0)), "routes through the gap");
+        // Fully sealed column: left side unreachable.
+        let sealed = |x: i32, _z: i32| x == 10;
+        let field = FlowField::build(&provider(&sealed), (0, 0, 32, 32), &[(31, 16)], 100_000);
+        assert_eq!(field.distance(0, 16), None);
+        assert!(field.walk(0, 16, 10).is_empty());
+    }
+
+    #[test]
+    fn multiple_goals_pick_nearest() {
+        let open = |_x: i32, _z: i32| false;
+        let field = FlowField::build(&provider(&open), (0, 0, 32, 32), &[(0, 0), (31, 31)], 100_000);
+        assert_eq!(field.distance(2, 2), Some(4));
+        assert_eq!(field.distance(29, 30), Some(3));
+        // Descent from the middle goes to ONE of the goals.
+        let path = field.walk(16, 16, 200);
+        let end = *path.last().unwrap();
+        assert!(end == (0, 0) || end == (31, 31));
+    }
+}

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

@@ -0,0 +1,10 @@
+//! Agent brains for hubs that move things: [`path`] (A* with a step budget), [`flow`] (one
+//! distance field many agents descend), [`steering`] (seek, flee, arrive, wander, separate),
+//! [`brain`] (behavior trees as JSON) and [`turn`] (budgeted movers for turn-based enemies).
+//! Every search is capped, so one bad query cannot use up a call's fuel.
+
+pub mod brain;
+pub mod flow;
+pub mod path;
+pub mod steering;
+pub mod turn;