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

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

@@ -0,0 +1,65 @@
+//! Shard keys: one keyed hub per square of the world, so no one hub holds everyone.
+//!
+//! A shard is `size` by `size` chunks on the x and z axes, and its key is its centre chunk,
+//! `"<x>,<z>"`. Players' clients compute the same keys (the kit clients carry this function),
+//! so a client finds the hub for where it stands without asking anyone. A hub that sees its
+//! neighbours' edges subscribes to [`around`]'s keys.
+
+/// The shard's centre chunk for chunk `(x, z)`. `size` is at least 1.
+pub fn centre(x: i64, z: i64, size: i64) -> (i64, i64) {
+    let size = size.max(1);
+    (x.div_euclid(size) * size + size / 2, z.div_euclid(size) * size + size / 2)
+}
+
+/// The key of the shard that holds chunk `(x, z)`.
+pub fn key(x: i64, z: i64, size: i64) -> String {
+    let (cx, cz) = centre(x, z, size);
+    format!("{cx},{cz}")
+}
+
+/// The centre chunk a key names, or `None` when it is not `"<x>,<z>"`.
+pub fn parse(key: &str) -> Option<(i64, i64)> {
+    let (x, z) = key.split_once(',')?;
+    Some((x.trim().parse().ok()?, z.trim().parse().ok()?))
+}
+
+/// The keys of the shards within `radius` shards of the one holding `(x, z)`, its own first,
+/// then row by row.
+pub fn around(x: i64, z: i64, size: i64, radius: i64) -> Vec<String> {
+    let size = size.max(1);
+    let (cx, cz) = centre(x, z, size);
+    let mut keys = vec![format!("{cx},{cz}")];
+    for dz in -radius..=radius {
+        for dx in -radius..=radius {
+            if (dx, dz) != (0, 0) {
+                keys.push(format!("{},{}", cx + dx * size, cz + dz * size));
+            }
+        }
+    }
+    keys
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_chunk_falls_in_one_shard_named_by_its_centre() {
+        assert_eq!(key(10, -4, 8), "12,-4");
+        assert_eq!(key(8, -8, 8), "12,-4");
+        assert_eq!(key(7, -9, 8), "4,-12");
+        assert_eq!(key(-1, 0, 16), "-8,8");
+        assert_eq!(key(3, 5, 1), "3,5", "size 1 is the chunk itself");
+        assert_eq!(parse("12,-4"), Some((12, -4)));
+        assert_eq!(parse("x"), None);
+    }
+
+    #[test]
+    fn around_starts_with_its_own_shard() {
+        let keys = around(0, 0, 8, 1);
+        assert_eq!(keys.len(), 9);
+        assert_eq!(keys[0], "4,4");
+        assert!(keys.contains(&"-4,-4".to_string()) && keys.contains(&"12,12".to_string()));
+        assert_eq!(around(0, 0, 8, 0), vec!["4,4".to_string()]);
+    }
+}

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

@@ -0,0 +1,266 @@
+//! What kit hubs show players near them through the realtime tier ([`crate::emit`]): server
+//! events, numbered by the registry below, and the state of server-driven actors.
+//!
+//! A server event's payload is `[event type, u16 little endian][JSON]`. The bodies here use
+//! camelCase keys, the shape the kit clients' event parsers read. An app's own events take
+//! numbers from [`APP_EVENTS`] up.
+//!
+//! A server-driven actor's state is [`ActorState`] as MessagePack: the kit clients decode it
+//! into their actor stores like a player's.
+
+use serde::{Deserialize, Serialize};
+
+use crate::emit::{MAX_DISTANCE, MAX_PAYLOAD, Spatial};
+use crate::node::ChunkPos;
+use crate::{Ctx, Error, Result, encode};
+
+/// A mob or a trap hit a player.
+pub const CONTACT_DAMAGE: u16 = 77;
+/// The weather or the time of day turned.
+pub const WEATHER: u16 = 90;
+/// A turn passed to the next player.
+pub const TURN: u16 = 91;
+/// Scores or a result.
+pub const SCORE: u16 = 92;
+/// A match was proposed to the players in it.
+pub const PROPOSAL: u16 = 93;
+/// An ability was cast, or landed.
+pub const ABILITY: u16 = 94;
+/// A movement the warden flagged.
+pub const MOVEMENT_VIOLATION: u16 = 95;
+/// A control point changed hands, or its capture moved.
+pub const CONTROL_POINT: u16 = 96;
+/// A racer started, passed a checkpoint, finished a lap or the race.
+pub const RACE_TIMING: u16 = 97;
+/// A play zone moved or shrank.
+pub const ZONE_CHANGE: u16 = 98;
+/// A wave began or ended, or a boss changed phase.
+pub const ENCOUNTER: u16 = 99;
+/// The contested object (a ball) changed hands, or a goal was scored.
+pub const POSSESSION: u16 = 100;
+/// An emote: a client event players send each other (the kit clients' convention); a hub may
+/// send one too, for a server-driven actor.
+pub const EMOTE: u16 = 101;
+/// The first number an app's own events may use.
+pub const APP_EVENTS: u16 = 1000;
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct ContactDamage {
+    pub target_uuid: String,
+    pub damage: i64,
+    pub mob_id: String,
+    pub mob_name: String,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct WeatherChange {
+    pub weather: String,
+    pub since_ms: u64,
+    pub until_ms: u64,
+    pub night: bool,
+    pub time_of_day: f64,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct TurnChange {
+    /// Whose turn it is now: a player id, or a unit's id.
+    pub actor_id: String,
+    pub round: u32,
+    pub turn_in_round: u32,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct Standing {
+    pub actor_id: String,
+    pub score: i64,
+    pub rank: u32,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct ScoreUpdate {
+    pub standings: Vec<Standing>,
+    pub winner_id: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct ProposalMade {
+    pub proposal_id: String,
+    pub mode: String,
+    pub players: Vec<String>,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct AbilityUse {
+    /// `cast` or `impact`.
+    pub kind: String,
+    pub ability_id: String,
+    pub caster_id: String,
+    pub victim_id: Option<String>,
+    pub damage: i64,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct MovementViolation {
+    /// `speed`, `teleport` or `bounds`.
+    pub kind: String,
+    pub user_id: String,
+    pub detail: String,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct ControlPointChange {
+    pub point_id: String,
+    pub owner: String,
+    pub previous_owner: String,
+    /// Capture progress toward the attacker, 0 to 1.
+    pub progress: f64,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct RaceTiming {
+    /// `started`, `checkpoint`, `lap` or `finished`.
+    pub kind: String,
+    pub course_id: String,
+    pub user_id: String,
+    pub checkpoint: u32,
+    pub lap: u32,
+    pub elapsed_ms: u64,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct ZoneChange {
+    /// `hold`, `shrink` or `closed`.
+    pub kind: String,
+    pub phase: Option<u32>,
+    pub radius_now: f64,
+    pub center_x: f64,
+    pub center_z: f64,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct EncounterChange {
+    /// `wave_started`, `wave_cleared`, `boss_phase` or `finished`.
+    pub kind: String,
+    pub encounter_id: String,
+    pub wave: u32,
+    pub phase: u32,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PossessionChange {
+    /// `claimed`, `passed`, `loose` or `goal`.
+    pub kind: String,
+    pub holder_id: Option<String>,
+    pub team: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct Emote {
+    /// The emote's name, as the game knows it: `wave`, `cheer`, ...
+    pub emote: String,
+    /// The actor it is aimed at, if any.
+    pub target_uuid: Option<String>,
+}
+
+/// A server event's payload: its type, then its body as JSON.
+pub fn event_bytes<T: Serialize + ?Sized>(event_type: u16, body: &T) -> Result<Vec<u8>> {
+    let json = serde_json::to_vec(body).map_err(|e| Error::new(format!("an event body encodes as JSON: {e}")))?;
+    let mut out = Vec::with_capacity(2 + json.len());
+    out.extend_from_slice(&event_type.to_le_bytes());
+    out.extend_from_slice(&json);
+    if out.len() > MAX_PAYLOAD {
+        return Err(Error::new(format!("a realtime payload is at most {MAX_PAYLOAD} bytes")));
+    }
+    Ok(out)
+}
+
+/// Sends a server event to the players within `distance` chunks of `at` (at most
+/// [`MAX_DISTANCE`]). `actor` is the event's actor: the one it is about, or the hub's own.
+pub fn emit_event<T: Serialize + ?Sized>(ctx: &Ctx, at: ChunkPos, distance: u8, actor: &[u8; 32], event_type: u16, body: &T) -> Result<()> {
+    let bytes = event_bytes(event_type, body)?;
+    ctx.emit_spatial(at, distance.min(MAX_DISTANCE), actor, Spatial::Event { event_type, state: &bytes[2..] })?;
+    Ok(())
+}
+
+/// A server-driven actor as players near it see it.
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub struct ActorState {
+    /// What it is: `mob`, `npc`, `pet`, `ball`, `ghost`, a game's own word.
+    pub kind: String,
+    /// Its id within the hub that shows it.
+    pub id: u64,
+    /// Where it is, in chunks.
+    pub x: f64,
+    #[serde(default)]
+    pub y: f64,
+    pub z: f64,
+    /// Its health, when it has any.
+    pub hp: Option<i64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_hp: Option<i64>,
+    /// What it is doing: `idle`, `chase`, `follow`, ...
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub mode: Option<String>,
+    /// The player it belongs to (a pet, a summon).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub owner: Option<u64>,
+    /// Facing, in radians.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub yaw: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub name: Option<String>,
+}
+
+impl ActorState {
+    pub fn new(kind: &str, id: u64, x: f64, z: f64) -> Self {
+        Self { kind: kind.to_owned(), id, x, y: 0.0, z, hp: None, max_hp: None, mode: None, owner: None, yaw: None, name: None }
+    }
+
+    /// The chunk it stands in.
+    pub fn chunk(&self) -> ChunkPos {
+        ChunkPos::new(self.x.floor() as i64, self.y.floor() as i64, self.z.floor() as i64)
+    }
+}
+
+/// Shows a server-driven actor to the players within `distance` chunks of where it stands.
+pub fn emit_actor_state(ctx: &Ctx, actor: &[u8; 32], distance: u8, state: &ActorState) -> Result<()> {
+    ctx.emit_actor(actor, state.chunk(), distance.min(MAX_DISTANCE), &encode(state)?)?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn an_event_is_its_type_then_json() {
+        let bytes = event_bytes(TURN, &TurnChange { actor_id: "7".into(), round: 2, turn_in_round: 1 }).unwrap();
+        assert_eq!(&bytes[..2], &[91, 0]);
+        let body: serde_json::Value = serde_json::from_slice(&bytes[2..]).unwrap();
+        assert_eq!(body, serde_json::json!({ "actorId": "7", "round": 2, "turnInRound": 1 }));
+        assert!(event_bytes(APP_EVENTS, &"x".repeat(MAX_PAYLOAD)).is_err());
+    }
+
+    #[test]
+    fn an_actor_state_leaves_out_what_it_does_not_have() {
+        let mut s = ActorState::new("mob", 3, 1.5, -2.25);
+        s.hp = Some(40);
+        let back: serde_json::Value = crate::decode(&encode(&s).unwrap()).unwrap();
+        assert_eq!(back, serde_json::json!({ "kind": "mob", "id": 3, "x": 1.5, "y": 0.0, "z": -2.25, "hp": 40 }));
+        assert_eq!(s.chunk(), ChunkPos::new(1, 0, -3));
+    }
+}

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

@@ -44,10 +44,15 @@
 //! Nodes are unit tested natively with `cargo test`: `testing` runs one against a fake of the
 //! platform (calls, timers, events, snapshots, the node API, a mod's grid). [`limits`] has the
 //! platform's bounds.
+//!
+//! [`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.
 
 mod abi;
 pub mod cron;
 pub mod emit;
+pub mod kit;
 pub mod limits;
 pub mod model;
 pub mod node;
@@ -546,20 +551,25 @@ macro_rules! export_spoke {
     };
 }
 
+// Only the module the sandbox loads needs the exports: a native build (a unit test, a crate
+// that includes several nodes' sources) defines none, so nodes link side by side.
 #[doc(hidden)]
 #[macro_export]
 macro_rules! __export_node {
     ($node:ty) => {
+        #[cfg(target_arch = "wasm32")]
         #[unsafe(no_mangle)]
         pub extern "C" fn ckx_abi() -> u32 {
             $crate::rt::ABI_VERSION
         }
 
+        #[cfg(target_arch = "wasm32")]
         #[unsafe(no_mangle)]
         pub extern "C" fn ckx_alloc(len: u32) -> u32 {
             $crate::rt::alloc(len)
         }
 
+        #[cfg(target_arch = "wasm32")]
         #[unsafe(no_mangle)]
         pub extern "C" fn ckx_init(
             ctx_ptr: u32,
@@ -574,16 +584,19 @@ macro_rules! __export_node {
             $crate::rt::init::<$node>(ctx_ptr, ctx_len, seed_ptr, seed_len, snap_ptr, snap_len, snap_version, has_snap)
         }
 
+        #[cfg(target_arch = "wasm32")]
         #[unsafe(no_mangle)]
         pub extern "C" fn ckx_handle(caller_kind: u32, caller_id: u64, buf_ptr: u32, method_len: u32, payload_len: u32) -> u64 {
             $crate::rt::handle(caller_kind, caller_id, buf_ptr, method_len, payload_len)
         }
 
+        #[cfg(target_arch = "wasm32")]
         #[unsafe(no_mangle)]
         pub extern "C" fn ckx_persist() -> u64 {
             $crate::rt::persist()
         }
 
+        #[cfg(target_arch = "wasm32")]
         #[unsafe(no_mangle)]
         pub extern "C" fn ckx_evict() {
             $crate::rt::evict()

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

@@ -209,6 +209,11 @@ impl Model {
         self.containers.get(&id)
     }
 
+    /// Every container's id, oldest first.
+    pub fn ids(&self) -> impl Iterator<Item = u64> + '_ {
+        self.containers.keys().copied()
+    }
+
     /// Every container of `type_name`, oldest first.
     pub fn of_type<'a>(&'a self, type_name: &'a str) -> impl Iterator<Item = u64> + 'a {
         self.containers.iter().filter(move |(_, c)| c.type_name == type_name).map(|(id, _)| *id)

package/crates/crowdy-client-sdk/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "crowdy-client-sdk"
-version = "0.1.0"
+version = "0.1.0-dev.1"
 edition = "2021"
 description = "Guest SDK for the CLIENT half of a ck-exec mod: browser WASM (ck ABI v0 + the client host calls)."
 license = "MIT OR Apache-2.0"

package/kit.pin

@@ -1,9 +1,9 @@
 # The platform toolchain release this kit was copied from (sync-kit.sh in the platform's
 # repository). The paths in `copied` are byte-identical to it: change them there, never here.
-toolchain_version=v1.10.1
-toolchain_commit=277975dcb57b2fc770e67933cd47b0f911bf6b7d
-sdk_commit=4aa2af5aa86c3b1d90ed7eb10f65a0fcd14a1387
-ckx_sdk_version=0.9.0
+toolchain_version=v1.12.0
+toolchain_commit=41921e53e1bbd4901fb8c4946e4277aa1e93bfec
+sdk_commit=60e91d4892727b847531e657cc9c4ba1edd2e2c1
+ckx_sdk_version=0.10.0
 crowdy_client_sdk_version=0.1.0
 rust_version=1.97.1
 copied=crates/ckx-sdk/src crates/crowdy-client-sdk/src tools/instrument/Cargo.toml tools/instrument/Cargo.lock tools/instrument/src checks/src/build/exec-source.ts checks/src/build/exec-source.spec.ts checks/src/build/rust-source-guard.ts checks/src/build/rust-source-guard.spec.ts checks/src/build/wasm-inspect.ts checks/src/build/wasm-inspect.spec.ts checks/src/build/client-capabilities.ts checks/src/build/client-capabilities.spec.ts checks/src/test-support/wasm-module.ts checks/compute-toolchain/host-catalog.json starters rust-toolchain.toml vendor.lock

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdedkingdoms/ckx-kit",
-  "version": "0.2.0",
+  "version": "0.3.0-dev.1",
   "description": "Build, check and test Crowded Kingdoms ck-exec mods, hubs and spokes on your machine, as the platform builds them",
   "license": "MIT OR Apache-2.0",
   "homepage": "https://docs.crowdedkingdoms.com/exec/intro",

package/starters/grid-mod/Cargo.toml

@@ -9,5 +9,5 @@ publish = false
 crate-type = ["cdylib"]
 
 [dependencies]
-ckx-sdk = "0.9.0"
+ckx-sdk = "0.10.0"
 serde = { version = "1", features = ["derive"] }

package/starters/matchmaker/Cargo.toml

@@ -9,5 +9,5 @@ publish = false
 crate-type = ["cdylib"]
 
 [dependencies]
-ckx-sdk = "0.9.0"
+ckx-sdk = "0.10.0"
 serde = { version = "1", features = ["derive"] }