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

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

@@ -0,0 +1,370 @@
+//! Realtime ability casts: cooldown/resource/range validation books,
+//! server-stepped projectiles with tolerance windows, and AoE resolution
+//! with falloff. Pure state machines — the hub feeds live
+//! actor positions in and applies the resulting damage itself (see
+//! [`super::combat`]). All stepping is bounded (max lifetime / max range) so fuel
+//! stays predictable at a hub's tick rate.
+
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+/// What a cast does once validated.
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub enum AbilityKind {
+    /// Immediate hit on a target in range (hitscan).
+    Instant { damage: i64 },
+    /// A stepped projectile along a direction; first actor within
+    /// `hit_radius` takes the damage.
+    Projectile { speed: f32, damage: i64, max_range: f32, hit_radius: f32 },
+    /// A delayed explosion at a target point; damage within `radius`,
+    /// optionally scaled down linearly with distance.
+    Aoe { radius: f32, damage: i64, delay_ms: u64, falloff: bool },
+}
+
+/// One ability's rules (usually from the hub's config).
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub struct AbilitySpec {
+    pub ability_id: String,
+    pub cooldown_ms: u64,
+    pub resource_cost: i64,
+    /// Max cast distance (target point / initial direction anchor).
+    pub range: f32,
+    pub kind: AbilityKind,
+}
+
+/// Per-caster server-held book: cooldown stamps + a regenerating resource
+/// pool. One book per user, kept in the hub's state.
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub struct CasterBook {
+    /// ability id -> earliest next cast (ms).
+    pub ready_at: BTreeMap<String, u64>,
+    pub resource: i64,
+    pub resource_max: i64,
+    /// Resource points regenerated per second.
+    pub regen_per_sec: i64,
+    pub last_regen_ms: u64,
+}
+
+impl Default for CasterBook {
+    fn default() -> Self {
+        Self { ready_at: BTreeMap::new(), resource: 100, resource_max: 100, regen_per_sec: 5, last_regen_ms: 0 }
+    }
+}
+
+impl CasterBook {
+    /// Apply resource regeneration up to `now_ms`.
+    pub fn regen(&mut self, now_ms: u64) {
+        if self.last_regen_ms == 0 {
+            self.last_regen_ms = now_ms;
+            return;
+        }
+        let elapsed = now_ms.saturating_sub(self.last_regen_ms);
+        let gained = (elapsed as i64 * self.regen_per_sec) / 1000;
+        if gained > 0 {
+            self.resource = (self.resource + gained).min(self.resource_max);
+            // Keep the remainder window so slow regen still accrues.
+            self.last_regen_ms += (gained * 1000 / self.regen_per_sec.max(1)) as u64;
+        }
+    }
+}
+
+fn dist(a: (f32, f32), b: (f32, f32)) -> f32 {
+    let (dx, dz) = (a.0 - b.0, a.1 - b.1);
+    (dx * dx + dz * dz).sqrt()
+}
+
+/// A validated cast, ready for the hub to act on.
+#[derive(Debug, Clone, PartialEq)]
+pub struct ValidCast {
+    pub ability_id: String,
+    /// Normalized aim direction (projectiles).
+    pub dir: (f32, f32),
+    /// Clamped target point (instant/AoE).
+    pub target: (f32, f32),
+}
+
+/// Validate a cast against the book: cooldown, resource, range. On success
+/// the cooldown is armed and the resource deducted (the cast is committed).
+pub fn validate_cast(
+    spec: &AbilitySpec,
+    book: &mut CasterBook,
+    caster_pos: (f32, f32),
+    target: (f32, f32),
+    now_ms: u64,
+) -> Result<ValidCast, &'static str> {
+    book.regen(now_ms);
+    if book.ready_at.get(&spec.ability_id).copied().unwrap_or(0) > now_ms {
+        return Err("ability on cooldown");
+    }
+    if book.resource < spec.resource_cost {
+        return Err("not enough resource");
+    }
+    let to_target = dist(caster_pos, target);
+    if to_target > spec.range && !matches!(spec.kind, AbilityKind::Projectile { .. }) {
+        return Err("target out of range");
+    }
+    // Aim direction: toward the target; degenerate aim defaults to +x.
+    let dir = if to_target > 1e-3 { ((target.0 - caster_pos.0) / to_target, (target.1 - caster_pos.1) / to_target) } else { (1.0, 0.0) };
+    book.ready_at.insert(spec.ability_id.clone(), now_ms + spec.cooldown_ms);
+    book.resource -= spec.resource_cost;
+    Ok(ValidCast { ability_id: spec.ability_id.clone(), dir, target })
+}
+
+// ---------------------------------------------------------------------------
+// Projectiles
+// ---------------------------------------------------------------------------
+
+/// A live projectile the hub steps each tick.
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub struct Projectile {
+    pub ability_id: String,
+    pub caster_id: String,
+    pub x: f32,
+    pub z: f32,
+    pub dir: (f32, f32),
+    pub speed: f32,
+    pub damage: i64,
+    pub hit_radius: f32,
+    pub traveled: f32,
+    pub max_range: f32,
+    pub launched_at_ms: u64,
+}
+
+/// The outcome of one projectile step.
+#[derive(Debug, Clone, PartialEq)]
+pub enum ProjectileStep {
+    /// Still flying (new position recorded on the projectile).
+    Flying,
+    /// Hit `target_id` at the recorded position; despawn.
+    Hit { target_id: String },
+    /// Ran out of range or was blocked; despawn.
+    Expired,
+}
+
+impl Projectile {
+    pub fn launch(spec: &AbilitySpec, caster_id: &str, from: (f32, f32), cast: &ValidCast, now_ms: u64) -> Option<Self> {
+        let AbilityKind::Projectile { speed, damage, max_range, hit_radius } = spec.kind else {
+            return None;
+        };
+        Some(Self {
+            ability_id: spec.ability_id.clone(),
+            caster_id: caster_id.to_string(),
+            x: from.0,
+            z: from.1,
+            dir: cast.dir,
+            speed,
+            damage,
+            hit_radius,
+            traveled: 0.0,
+            max_range,
+            launched_at_ms: now_ms,
+        })
+    }
+
+    /// Advance `dt_ms`, sub-stepping so tick-rate simulation cannot tunnel
+    /// through targets (tolerance window = hit_radius per sub-step).
+    /// `hit_test(x, z, radius)` returns a hit target (never the caster) or
+    /// None; `blocked(x, z)` marks walls.
+    pub fn step(
+        &mut self,
+        dt_ms: u64,
+        hit_test: &mut impl FnMut(f32, f32, f32) -> Option<String>,
+        blocked: &mut impl FnMut(f32, f32) -> bool,
+    ) -> ProjectileStep {
+        let total = self.speed * dt_ms as f32 / 1000.0;
+        let sub = self.hit_radius.max(0.25);
+        let mut moved = 0.0f32;
+        while moved < total {
+            let advance = sub.min(total - moved);
+            self.x += self.dir.0 * advance;
+            self.z += self.dir.1 * advance;
+            self.traveled += advance;
+            moved += advance;
+            if blocked(self.x, self.z) {
+                return ProjectileStep::Expired;
+            }
+            if let Some(target_id) = hit_test(self.x, self.z, self.hit_radius) {
+                return ProjectileStep::Hit { target_id };
+            }
+            if self.traveled >= self.max_range {
+                return ProjectileStep::Expired;
+            }
+        }
+        ProjectileStep::Flying
+    }
+}
+
+// ---------------------------------------------------------------------------
+// AoE
+// ---------------------------------------------------------------------------
+
+/// A delayed area effect awaiting detonation.
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub struct PendingAoe {
+    pub ability_id: String,
+    pub caster_id: String,
+    pub x: f32,
+    pub z: f32,
+    pub radius: f32,
+    pub damage: i64,
+    pub falloff: bool,
+    pub detonate_at_ms: u64,
+}
+
+impl PendingAoe {
+    pub fn from_cast(spec: &AbilitySpec, caster_id: &str, cast: &ValidCast, now_ms: u64) -> Option<Self> {
+        let AbilityKind::Aoe { radius, damage, delay_ms, falloff } = spec.kind else {
+            return None;
+        };
+        Some(Self {
+            ability_id: spec.ability_id.clone(),
+            caster_id: caster_id.to_string(),
+            x: cast.target.0,
+            z: cast.target.1,
+            radius,
+            damage,
+            falloff,
+            detonate_at_ms: now_ms + delay_ms,
+        })
+    }
+
+    pub fn ready(&self, now_ms: u64) -> bool {
+        now_ms >= self.detonate_at_ms
+    }
+
+    /// Damage per victim inside the radius (linear falloff to 25% at the
+    /// edge when enabled). Victims = (id, position); the caster is exempt.
+    pub fn resolve(&self, victims: &[(String, (f32, f32))]) -> Vec<(String, i64)> {
+        victims
+            .iter()
+            .filter(|(id, _)| *id != self.caster_id)
+            .filter_map(|(id, pos)| {
+                let d = dist((self.x, self.z), *pos);
+                if d > self.radius {
+                    return None;
+                }
+                let damage = if self.falloff && self.radius > 0.0 {
+                    let scale = 1.0 - 0.75 * (d / self.radius);
+                    ((self.damage as f32) * scale).round() as i64
+                } else {
+                    self.damage
+                };
+                Some((id.clone(), damage.max(1)))
+            })
+            .collect()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn bolt() -> AbilitySpec {
+        AbilitySpec {
+            ability_id: "bolt".into(),
+            cooldown_ms: 1_000,
+            resource_cost: 10,
+            range: 20.0,
+            kind: AbilityKind::Projectile { speed: 10.0, damage: 5, max_range: 12.0, hit_radius: 0.5 },
+        }
+    }
+
+    fn nova() -> AbilitySpec {
+        AbilitySpec {
+            ability_id: "nova".into(),
+            cooldown_ms: 5_000,
+            resource_cost: 30,
+            range: 8.0,
+            kind: AbilityKind::Aoe { radius: 4.0, damage: 20, delay_ms: 500, falloff: true },
+        }
+    }
+
+    #[test]
+    fn cast_validation_cooldown_resource_range() {
+        let spec = nova();
+        let mut book = CasterBook::default();
+        // Out of range for a targeted AoE.
+        assert_eq!(validate_cast(&spec, &mut book, (0.0, 0.0), (20.0, 0.0), 1_000).unwrap_err(), "target out of range");
+        let cast = validate_cast(&spec, &mut book, (0.0, 0.0), (5.0, 0.0), 1_000).unwrap();
+        assert_eq!(cast.target, (5.0, 0.0));
+        assert_eq!(book.resource, 70);
+        // Cooldown blocks an immediate re-cast.
+        assert_eq!(validate_cast(&spec, &mut book, (0.0, 0.0), (5.0, 0.0), 1_100).unwrap_err(), "ability on cooldown");
+        // After cooldown, resource gate: drain (regen off) then fail.
+        book.resource = 5;
+        book.regen_per_sec = 0;
+        assert_eq!(validate_cast(&spec, &mut book, (0.0, 0.0), (5.0, 0.0), 7_000).unwrap_err(), "not enough resource");
+    }
+
+    #[test]
+    fn resource_regenerates_over_time() {
+        let mut book = CasterBook { resource: 0, last_regen_ms: 1_000, ..Default::default() };
+        book.regen(3_000); // 2s at 5/s
+        assert_eq!(book.resource, 10);
+        book.regen(3_000);
+        assert_eq!(book.resource, 10, "no double counting");
+        book.regen(100_000);
+        assert_eq!(book.resource, book.resource_max, "clamped at max");
+    }
+
+    #[test]
+    fn projectile_flies_hits_and_expires() {
+        let spec = bolt();
+        let mut book = CasterBook::default();
+        let cast = validate_cast(&spec, &mut book, (0.0, 0.0), (10.0, 0.0), 0).unwrap();
+        let mut projectile = Projectile::launch(&spec, "caster", (0.0, 0.0), &cast, 0).unwrap();
+
+        // A target at x=5 gets hit during the first second of flight.
+        let mut hit = |x: f32, z: f32, r: f32| (dist((x, z), (5.0, 0.0)) <= r).then(|| "victim".to_string());
+        let mut open = |_x: f32, _z: f32| false;
+        let step = projectile.step(1_000, &mut hit, &mut open);
+        assert_eq!(step, ProjectileStep::Hit { target_id: "victim".into() });
+        assert!(projectile.traveled <= 5.5, "stops at the hit, no overshoot");
+
+        // No targets: expires at max_range (12 units at 10 u/s).
+        let cast = validate_cast(&spec, &mut book, (0.0, 0.0), (10.0, 0.0), 5_000).unwrap();
+        let mut projectile = Projectile::launch(&spec, "caster", (0.0, 0.0), &cast, 5_000).unwrap();
+        let mut none = |_x: f32, _z: f32, _r: f32| None;
+        assert_eq!(projectile.step(1_000, &mut none, &mut open), ProjectileStep::Flying);
+        assert_eq!(projectile.step(1_000, &mut none, &mut open), ProjectileStep::Expired);
+
+        // Walls block flight.
+        let cast = validate_cast(&spec, &mut book, (0.0, 0.0), (10.0, 0.0), 20_000).unwrap();
+        let mut projectile = Projectile::launch(&spec, "caster", (0.0, 0.0), &cast, 20_000).unwrap();
+        let mut wall = |x: f32, _z: f32| x >= 2.0;
+        assert_eq!(projectile.step(1_000, &mut none, &mut wall), ProjectileStep::Expired);
+        assert!(projectile.x <= 2.5);
+    }
+
+    #[test]
+    fn aoe_delays_resolves_with_falloff_and_exempts_caster() {
+        let spec = nova();
+        let mut book = CasterBook::default();
+        let cast = validate_cast(&spec, &mut book, (0.0, 0.0), (5.0, 0.0), 1_000).unwrap();
+        let aoe = PendingAoe::from_cast(&spec, "caster", &cast, 1_000).unwrap();
+        assert!(!aoe.ready(1_400));
+        assert!(aoe.ready(1_500));
+        let victims = vec![
+            ("caster".to_string(), (5.0, 0.0)),   // exempt
+            ("center".to_string(), (5.0, 0.0)),   // full damage
+            ("edge".to_string(), (9.0, 0.0)),     // r=4 away -> 25%
+            ("outside".to_string(), (10.5, 0.0)), // out
+        ];
+        let hits = aoe.resolve(&victims);
+        assert_eq!(hits.len(), 2);
+        assert_eq!(hits[0], ("center".to_string(), 20));
+        assert_eq!(hits[1], ("edge".to_string(), 5));
+    }
+
+    #[test]
+    fn serde_roundtrip() {
+        let spec = bolt();
+        let mut book = CasterBook::default();
+        let cast = validate_cast(&spec, &mut book, (0.0, 0.0), (3.0, 4.0), 0).unwrap();
+        let projectile = Projectile::launch(&spec, "c", (0.0, 0.0), &cast, 0).unwrap();
+        let json = serde_json::to_string(&(&book, &projectile)).unwrap();
+        let (book2, projectile2): (CasterBook, Projectile) = serde_json::from_str(&json).unwrap();
+        assert_eq!(book2.resource, book.resource);
+        assert_eq!(projectile2.dir, projectile.dir);
+    }
+}

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

@@ -0,0 +1,220 @@
+//! Deck/hand/zone logic with true hidden information: hands and deck order
+//! live in the HUB'S STATE (secrets the hub holds — clients only ever see their
+//! own hand through a call the hub answers for its caller), while public zones are published
+//! on its topics. Shuffles are seeded (`kit::Rng`)
+//! so instance replays are deterministic.
+
+use crate::kit::Rng;
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+use std::collections::BTreeMap;
+
+pub type CardId = String;
+
+/// A pile with hidden order (draw deck / discard).
+#[derive(Serialize, Deserialize, Clone, Debug, Default)]
+pub struct Pile {
+    /// Top of the pile is the END of the vec (pop to draw).
+    pub cards: Vec<CardId>,
+}
+
+impl Pile {
+    pub fn len(&self) -> usize {
+        self.cards.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.cards.is_empty()
+    }
+
+    pub fn draw(&mut self) -> Option<CardId> {
+        self.cards.pop()
+    }
+
+    pub fn put(&mut self, card: CardId) {
+        self.cards.push(card);
+    }
+
+    /// Seeded Fisher-Yates shuffle.
+    pub fn shuffle(&mut self, rng: &mut Rng) {
+        let n = self.cards.len();
+        for i in (1..n).rev() {
+            let j = (rng.next_u64() % (i as u64 + 1)) as usize;
+            self.cards.swap(i, j);
+        }
+    }
+}
+
+/// The full table: draw pile, discard, per-actor hidden hands, and named
+/// public zones. Everything serde — one `CardTable` per match partition.
+#[derive(Serialize, Deserialize, Clone, Debug, Default)]
+pub struct CardTable {
+    pub draw: Pile,
+    pub discard: Pile,
+    pub hands: BTreeMap<String, Vec<CardId>>,
+    /// Named public zones (battlefield, trick, melds, ...), in play order.
+    pub zones: BTreeMap<String, Vec<(String, CardId)>>,
+    pub seed: u64,
+}
+
+impl CardTable {
+    /// Build a table from a card catalog and shuffle with the given seed.
+    pub fn new(catalog: impl IntoIterator<Item = CardId>, seed: u64) -> Self {
+        let mut table = Self { draw: Pile { cards: catalog.into_iter().collect() }, seed, ..Default::default() };
+        let mut rng = Rng::seeded(seed);
+        table.draw.shuffle(&mut rng);
+        table
+    }
+
+    /// Deal `count` cards to each actor (round-robin, deterministic order).
+    pub fn deal(&mut self, actors: &[String], count: usize) {
+        for _ in 0..count {
+            for actor in actors {
+                if let Some(card) = self.draw.draw() {
+                    self.hands.entry(actor.clone()).or_default().push(card);
+                }
+            }
+        }
+    }
+
+    /// Draw one card into an actor's hidden hand. Recycles the discard
+    /// (reshuffled with the table seed + draw count) when the deck empties.
+    pub fn draw_to_hand(&mut self, actor_id: &str) -> Option<CardId> {
+        if self.draw.is_empty() && !self.discard.is_empty() {
+            std::mem::swap(&mut self.draw.cards, &mut self.discard.cards);
+            let mut rng = Rng::seeded(self.seed ^ (self.draw.len() as u64) << 8);
+            self.draw.shuffle(&mut rng);
+        }
+        let card = self.draw.draw()?;
+        self.hands.entry(actor_id.to_string()).or_default().push(card.clone());
+        Some(card)
+    }
+
+    /// The caller's own hand (the ONLY read path for hidden cards).
+    pub fn hand(&self, actor_id: &str) -> &[CardId] {
+        self.hands.get(actor_id).map(Vec::as_slice).unwrap_or(&[])
+    }
+
+    pub fn hand_sizes(&self) -> BTreeMap<String, usize> {
+        self.hands.iter().map(|(id, hand)| (id.clone(), hand.len())).collect()
+    }
+
+    /// Play (reveal) a card from a hand into a public zone. Fails when the
+    /// caller does not hold the card — the legality floor every game gets.
+    pub fn play(&mut self, actor_id: &str, card: &str, zone: &str) -> Result<(), &'static str> {
+        let hand = self.hands.entry(actor_id.to_string()).or_default();
+        let index = hand.iter().position(|c| c == card).ok_or("card not in hand")?;
+        let card = hand.remove(index);
+        self.zones.entry(zone.to_string()).or_default().push((actor_id.to_string(), card));
+        Ok(())
+    }
+
+    /// Move every card in a zone to the discard (trick taken, turn over).
+    pub fn clear_zone(&mut self, zone: &str) -> Vec<(String, CardId)> {
+        let cards = self.zones.remove(zone).unwrap_or_default();
+        for (_, card) in &cards {
+            self.discard.put(card.clone());
+        }
+        cards
+    }
+
+    /// The public view (zones + counts, NEVER hidden cards) for model sync
+    /// and spectator events.
+    pub fn public_json(&self) -> Value {
+        json!({
+            "drawCount": self.draw.len(),
+            "discardCount": self.discard.len(),
+            "handSizes": self.hand_sizes(),
+            "zones": self.zones.iter().map(|(name, cards)| {
+                (name.clone(), cards.iter().map(|(actor, card)| json!({
+                    "actorId": actor, "card": card,
+                })).collect::<Vec<_>>())
+            }).collect::<BTreeMap<_, _>>(),
+        })
+    }
+}
+
+/// Build a standard 52-card catalog ("AS", "2S", ..., "KC") — handy for
+/// examples and tests; a real game builds its own from its hub's config.
+pub fn standard_52() -> Vec<CardId> {
+    let ranks = ["A", "2", "3", "4", "5", "6", "7", "8", "9", "10", "J", "Q", "K"];
+    let suits = ["S", "H", "D", "C"];
+    let mut cards = Vec::with_capacity(52);
+    for suit in suits {
+        for rank in ranks {
+            cards.push(format!("{rank}{suit}"));
+        }
+    }
+    cards
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn seeded_shuffles_are_deterministic_and_seed_sensitive() {
+        let a = CardTable::new(standard_52(), 42);
+        let b = CardTable::new(standard_52(), 42);
+        let c = CardTable::new(standard_52(), 43);
+        assert_eq!(a.draw.cards, b.draw.cards);
+        assert_ne!(a.draw.cards, c.draw.cards);
+        // Shuffle is a permutation.
+        let mut sorted = a.draw.cards.clone();
+        sorted.sort();
+        let mut catalog = standard_52();
+        catalog.sort();
+        assert_eq!(sorted, catalog);
+    }
+
+    #[test]
+    fn deal_draw_play_lifecycle() {
+        let actors = vec!["a".to_string(), "b".to_string()];
+        let mut table = CardTable::new(standard_52(), 7);
+        table.deal(&actors, 5);
+        assert_eq!(table.hand("a").len(), 5);
+        assert_eq!(table.hand("b").len(), 5);
+        assert_eq!(table.draw.len(), 42);
+
+        let drawn = table.draw_to_hand("a").unwrap();
+        assert!(table.hand("a").contains(&drawn));
+
+        let card = table.hand("a")[0].clone();
+        table.play("a", &card, "trick").unwrap();
+        assert_eq!(table.hand("a").len(), 5);
+        assert_eq!(table.zones["trick"].len(), 1);
+        assert_eq!(table.play("a", "not-held", "trick").unwrap_err(), "card not in hand");
+        // b cannot play a's cards.
+        let b_err = table.play("b", &card, "trick");
+        assert!(b_err.is_err());
+
+        let taken = table.clear_zone("trick");
+        assert_eq!(taken.len(), 1);
+        assert_eq!(table.discard.len(), 1);
+    }
+
+    #[test]
+    fn discard_recycles_into_draw() {
+        let mut table = CardTable::new(vec!["x".into(), "y".into()], 1);
+        table.draw_to_hand("a");
+        table.draw_to_hand("a");
+        assert!(table.draw.is_empty());
+        assert!(table.draw_to_hand("a").is_none(), "nothing anywhere");
+        // Discard a card, then drawing recycles it.
+        let card = table.hand("a")[0].clone();
+        table.play("a", &card, "z").unwrap();
+        table.clear_zone("z");
+        let recycled = table.draw_to_hand("b").unwrap();
+        assert_eq!(recycled, card);
+    }
+
+    #[test]
+    fn public_view_hides_hands() {
+        let mut table = CardTable::new(standard_52(), 9);
+        table.deal(&["a".to_string()], 3);
+        let view = table.public_json();
+        assert_eq!(view["handSizes"]["a"], 3);
+        assert!(view.get("hands").is_none(), "hidden hands never serialize publicly");
+        assert_eq!(view["drawCount"], 49);
+    }
+}