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

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

@@ -0,0 +1,292 @@
+//! The combat referee: the hub decides every hit, its damage and who dies; health never moves on
+//! a client's say-so. Pieces a hub keeps in its state:
+//!
+//! - [`Health`] and [`Combatant`]: hit points, status effects that tick (poison, burning,
+//!   regeneration), damage and healing with kill detection.
+//! - [`Cooldowns`]: per-actor, per-action minimum intervals (an attack, a cast).
+//! - [`in_reach`]: a target in range of the attacker, from positions the hub saw (`presence`).
+//! - [`RespawnBook`]: kill credit and respawn timers.
+//! - [`ContactBook`]: a hostile's touch on a player, once per cooldown (event 77).
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+/// Hit points with a maximum.
+#[derive(Serialize, Deserialize, Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct Health {
+    pub current: i64,
+    pub max: i64,
+}
+
+/// What damage did.
+#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
+pub struct DamageOutcome {
+    /// Health after it.
+    pub health: i64,
+    /// Damage actually taken (never more than the health it had).
+    pub dealt: i64,
+    pub killed: bool,
+}
+
+impl Health {
+    pub fn new(max: i64) -> Self {
+        Self { current: max.max(1), max: max.max(1) }
+    }
+
+    pub fn alive(&self) -> bool {
+        self.current > 0
+    }
+
+    pub fn apply(&mut self, amount: i64) -> DamageOutcome {
+        let before = self.current;
+        self.current = (self.current - amount.max(0)).max(0);
+        DamageOutcome { health: self.current, dealt: before - self.current, killed: before > 0 && self.current == 0 }
+    }
+
+    /// Heals up to the maximum; a dead one stays dead. Returns what was healed.
+    pub fn heal(&mut self, amount: i64) -> i64 {
+        if !self.alive() {
+            return 0;
+        }
+        let before = self.current;
+        self.current = (self.current + amount.max(0)).min(self.max);
+        self.current - before
+    }
+
+    pub fn revive(&mut self) {
+        self.current = self.max;
+    }
+}
+
+/// A status effect: `per_tick` damage (negative heals) every `every_ms` until `until_ms`.
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub struct Status {
+    pub kind: String,
+    pub until_ms: u64,
+    pub per_tick: i64,
+    pub every_ms: u64,
+    pub next_ms: u64,
+    /// Who applied it, for kill credit.
+    #[serde(default)]
+    pub source: Option<String>,
+}
+
+/// Something that fights: health and the effects on it.
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq)]
+pub struct Combatant {
+    pub health: Health,
+    #[serde(default)]
+    pub statuses: Vec<Status>,
+    #[serde(default)]
+    pub kills: u32,
+    #[serde(default)]
+    pub deaths: u32,
+}
+
+/// What a status tick did to a combatant.
+#[derive(Clone, Debug, PartialEq)]
+pub struct TickEffect {
+    pub kind: String,
+    pub outcome: DamageOutcome,
+    pub source: Option<String>,
+}
+
+impl Combatant {
+    pub fn new(max_hp: i64) -> Self {
+        Self { health: Health::new(max_hp), ..Default::default() }
+    }
+
+    /// Applies `kind` (replacing one of the same kind), first ticking `every_ms` from `now`.
+    pub fn afflict(&mut self, kind: &str, per_tick: i64, every_ms: u64, duration_ms: u64, source: Option<String>, now: u64) {
+        self.statuses.retain(|s| s.kind != kind);
+        let every_ms = every_ms.max(100);
+        self.statuses.push(Status {
+            kind: kind.to_owned(),
+            until_ms: now + duration_ms,
+            per_tick,
+            every_ms,
+            next_ms: now + every_ms,
+            source,
+        });
+    }
+
+    pub fn has(&self, kind: &str) -> bool {
+        self.statuses.iter().any(|s| s.kind == kind)
+    }
+
+    /// Runs every tick due by `now`, drops expired effects, and returns what each did.
+    pub fn tick(&mut self, now: u64) -> Vec<TickEffect> {
+        let mut out = Vec::new();
+        for s in &mut self.statuses {
+            while s.next_ms <= now.min(s.until_ms) && self.health.alive() {
+                s.next_ms += s.every_ms;
+                let outcome = if s.per_tick >= 0 {
+                    self.health.apply(s.per_tick)
+                } else {
+                    let healed = self.health.heal(-s.per_tick);
+                    DamageOutcome { health: self.health.current, dealt: -healed, killed: false }
+                };
+                out.push(TickEffect { kind: s.kind.clone(), outcome, source: s.source.clone() });
+            }
+        }
+        self.statuses.retain(|s| s.until_ms > now && s.next_ms <= s.until_ms);
+        if out.iter().any(|e| e.outcome.killed) {
+            self.deaths += 1;
+            self.statuses.clear();
+        }
+        out
+    }
+
+    /// Damage from `amount`; counts the death.
+    pub fn hit(&mut self, amount: i64) -> DamageOutcome {
+        let outcome = self.health.apply(amount);
+        if outcome.killed {
+            self.deaths += 1;
+            self.statuses.clear();
+        }
+        outcome
+    }
+}
+
+/// Per-actor, per-action last-use times.
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq, Eq)]
+pub struct Cooldowns {
+    #[serde(default)]
+    pub last: BTreeMap<String, u64>,
+}
+
+impl Cooldowns {
+    fn key(actor: &str, action: &str) -> String {
+        format!("{actor}\u{0}{action}")
+    }
+
+    /// Whether `actor` may `action` at `now` with `cooldown_ms` between uses; when it may, the
+    /// use is taken.
+    pub fn take(&mut self, actor: &str, action: &str, cooldown_ms: u64, now: u64) -> bool {
+        let k = Self::key(actor, action);
+        if self.last.get(&k).is_some_and(|at| now < at + cooldown_ms) {
+            return false;
+        }
+        self.last.insert(k, now);
+        true
+    }
+
+    /// Milliseconds until `actor` may `action` again; 0 when it may now.
+    pub fn remaining(&self, actor: &str, action: &str, cooldown_ms: u64, now: u64) -> u64 {
+        self.last.get(&Self::key(actor, action)).map(|at| (at + cooldown_ms).saturating_sub(now)).unwrap_or(0)
+    }
+
+    /// Forgets uses older than `older_than_ms`.
+    pub fn prune(&mut self, now: u64, older_than_ms: u64) {
+        self.last.retain(|_, at| now.saturating_sub(*at) < older_than_ms);
+    }
+}
+
+/// Whether `target` is within `range` chunks of `attacker` on the ground.
+pub fn in_reach(attacker: (f64, f64), target: (f64, f64), range: f64) -> bool {
+    super::super::presence::ground_distance(attacker, target) <= range
+}
+
+/// A kill: who did it, when, and when the victim comes back.
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
+pub struct KillRecord {
+    pub killer: String,
+    pub at_ms: u64,
+    pub respawn_at_ms: u64,
+}
+
+/// Kill credit and respawn timers, by victim id.
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq, Eq)]
+pub struct RespawnBook {
+    #[serde(default)]
+    pub kills: BTreeMap<String, KillRecord>,
+}
+
+impl RespawnBook {
+    pub fn record_kill(&mut self, victim: &str, killer: &str, now: u64, respawn_ms: u64) {
+        self.kills.insert(victim.to_owned(), KillRecord { killer: killer.to_owned(), at_ms: now, respawn_at_ms: now + respawn_ms });
+    }
+
+    /// Victims whose respawn came due, taken out of the book.
+    pub fn due(&mut self, now: u64) -> Vec<String> {
+        let ready: Vec<String> = self.kills.iter().filter(|(_, r)| now >= r.respawn_at_ms).map(|(id, _)| id.clone()).collect();
+        for id in &ready {
+            self.kills.remove(id);
+        }
+        ready
+    }
+
+    pub fn is_down(&self, victim: &str) -> bool {
+        self.kills.contains_key(victim)
+    }
+}
+
+/// A hostile's touch on a player, at most once per victim per cooldown.
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq, Eq)]
+pub struct ContactBook {
+    #[serde(default)]
+    pub at: BTreeMap<String, u64>,
+}
+
+impl ContactBook {
+    /// Whether the hostile at `attacker` touches the victim at `victim` (within `range`) now;
+    /// when it does, the victim's cooldown starts.
+    pub fn touch(&mut self, victim: &str, victim_at: (f64, f64), attacker: (f64, f64), range: f64, cooldown_ms: u64, now: u64) -> bool {
+        if self.at.get(victim).is_some_and(|t| now.saturating_sub(*t) < cooldown_ms) || !in_reach(attacker, victim_at, range) {
+            return false;
+        }
+        self.at.insert(victim.to_owned(), now);
+        true
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn damage_kills_once_and_healing_stops_at_the_maximum() {
+        let mut h = Health::new(10);
+        assert_eq!(h.apply(4), DamageOutcome { health: 6, dealt: 4, killed: false });
+        assert_eq!(h.heal(99), 4);
+        assert_eq!(h.apply(30), DamageOutcome { health: 0, dealt: 10, killed: true });
+        assert!(!h.apply(1).killed, "dead already");
+        assert_eq!(h.heal(5), 0, "the dead stay dead");
+    }
+
+    #[test]
+    fn statuses_tick_on_time_expire_and_credit_their_source() {
+        let mut c = Combatant::new(20);
+        c.afflict("poison", 3, 1_000, 3_500, Some("p7".into()), 0);
+        assert!(c.tick(500).is_empty());
+        let ticks = c.tick(3_600);
+        assert_eq!(ticks.len(), 3);
+        assert_eq!(c.health.current, 11);
+        assert!(!c.has("poison"), "expired");
+        c.afflict("regen", -5, 1_000, 10_000, None, 4_000);
+        c.tick(6_000);
+        assert_eq!(c.health.current, 20, "healing stops at the maximum");
+        c.afflict("burn", 50, 500, 2_000, Some("p9".into()), 7_000);
+        let burn = c.tick(7_600);
+        assert!(burn.last().unwrap().outcome.killed && burn.last().unwrap().source.as_deref() == Some("p9"));
+        assert_eq!((c.deaths, c.statuses.len()), (1, 0));
+    }
+
+    #[test]
+    fn cooldowns_respawns_and_contact() {
+        let mut cd = Cooldowns::default();
+        assert!(cd.take("p1", "attack", 500, 0));
+        assert!(!cd.take("p1", "attack", 500, 300));
+        assert_eq!(cd.remaining("p1", "attack", 500, 300), 200);
+        assert!(cd.take("p1", "cast", 500, 300), "another action");
+        let mut rb = RespawnBook::default();
+        rb.record_kill("mob-3", "p1", 0, 1_000);
+        assert!(rb.is_down("mob-3"));
+        assert_eq!(rb.due(1_000), vec!["mob-3".to_string()]);
+        let mut cb = ContactBook::default();
+        assert!(!cb.touch("p1", (0.0, 0.0), (3.0, 0.0), 1.5, 1_000, 0), "too far");
+        assert!(cb.touch("p1", (0.0, 0.0), (1.0, 0.0), 1.5, 1_000, 0));
+        assert!(!cb.touch("p1", (0.0, 0.0), (1.0, 0.0), 1.5, 1_000, 500), "cooldown");
+    }
+}

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

@@ -0,0 +1,15 @@
+//! Gameplay rules a hub keeps: [`turns`] (initiative, timeouts, simultaneous reveal),
+//! [`score`] (score books, win conditions, standings), [`cards`] (decks, hands held as the
+//! hub's secret, public piles), [`combat`] (the hit referee: health, statuses, cooldowns,
+//! respawns), [`abilities`] (casts with cooldowns and resources, projectiles, area damage),
+//! [`movement`] (the warden for positions clients report) and [`timing`] (checkpoints, laps,
+//! splits, ghosts). Each is plain data over `now_ms` and a seeded [`Rng`](super::Rng): keep it
+//! in the hub's state, and it carries on after a snapshot.
+
+pub mod abilities;
+pub mod cards;
+pub mod combat;
+pub mod movement;
+pub mod score;
+pub mod timing;
+pub mod turns;

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

@@ -0,0 +1,196 @@
+//! The movement warden: checks the positions a player's client reports (how far since the last
+//! one, how fast, inside the bounds) and says which position the hub keeps. A hub that takes
+//! positions from clients (a race, a ball game, an arena) runs every report through it; one that
+//! reads where the platform sees players ([`super::super::presence`]) need not.
+//!
+//! A report too fast is cut to the farthest the player could have gone; a jump past `teleport`
+//! is refused (the player stays put); one outside the bounds is pulled back in. Each is a
+//! [`Violation`] the hub may publish (the realtime registry's 95) and counts as a strike;
+//! strikes clear after [`STRIKE_WINDOW_MS`] without one, so a hub can act on a run of them
+//! (drop the player, report them) and forgive a lag spike.
+
+use serde::{Deserialize, Serialize};
+
+/// How long strikes are remembered after the last one.
+pub const STRIKE_WINDOW_MS: u64 = 10_000;
+
+/// What a player's movement may do, in the hub's own units.
+#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq)]
+#[serde(default)]
+pub struct Rules {
+    /// Units a second.
+    pub max_speed: f64,
+    /// A move this far or more at once is refused.
+    pub teleport: f64,
+    /// `(min_x, min_z, max_x, max_z)`, when there are any.
+    pub bounds: Option<(f64, f64, f64, f64)>,
+    /// Slack on `max_speed` for jitter in the reports' timing (1.25 lets a report be 25% fast).
+    pub grace: f64,
+}
+
+impl Default for Rules {
+    fn default() -> Self {
+        Self { max_speed: 8.0, teleport: 30.0, bounds: None, grace: 1.25 }
+    }
+}
+
+#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum ViolationKind {
+    Speed,
+    Teleport,
+    Bounds,
+}
+
+impl ViolationKind {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Speed => "speed",
+            Self::Teleport => "teleport",
+            Self::Bounds => "bounds",
+        }
+    }
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub struct Violation {
+    pub kind: ViolationKind,
+    pub detail: String,
+}
+
+/// The position the hub keeps for a report, and what was wrong with it.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Verdict {
+    pub at: (f64, f64),
+    pub violation: Option<Violation>,
+}
+
+/// One player's movement as the hub last accepted it.
+#[derive(Serialize, Deserialize, Clone, Copy, Debug, Default, PartialEq)]
+pub struct Warden {
+    /// The position kept, and when.
+    pub last: Option<(f64, f64, u64)>,
+    pub strikes: u32,
+    pub last_strike_ms: u64,
+}
+
+fn clamp_to(bounds: Option<(f64, f64, f64, f64)>, p: (f64, f64)) -> (f64, f64) {
+    match bounds {
+        Some((x0, z0, x1, z1)) => (p.0.clamp(x0.min(x1), x0.max(x1)), p.1.clamp(z0.min(z1), z0.max(z1))),
+        None => p,
+    }
+}
+
+impl Warden {
+    /// A warden that starts from `at`: a spawn, a respawn, a place the hub moved the player to.
+    pub fn at(at: (f64, f64), now: u64) -> Self {
+        Self { last: Some((at.0, at.1, now)), ..Self::default() }
+    }
+
+    /// Moves the player where the hub says, with no check.
+    pub fn place(&mut self, at: (f64, f64), now: u64) {
+        self.last = Some((at.0, at.1, now));
+    }
+
+    /// The position kept.
+    pub fn position(&self) -> Option<(f64, f64)> {
+        self.last.map(|(x, z, _)| (x, z))
+    }
+
+    /// Strikes in the current window.
+    pub fn strikes(&self, now: u64) -> u32 {
+        if now.saturating_sub(self.last_strike_ms) >= STRIKE_WINDOW_MS { 0 } else { self.strikes }
+    }
+
+    /// Checks a reported position and keeps the one the rules allow.
+    pub fn check(&mut self, rules: &Rules, claimed: (f64, f64), now: u64) -> Verdict {
+        let mut violation = None;
+        let mut at = claimed;
+        if !at.0.is_finite() || !at.1.is_finite() {
+            let kept = self.position().unwrap_or((0.0, 0.0));
+            return self.strike(now, kept, ViolationKind::Teleport, "a position that is not a number".into());
+        }
+        let inside = clamp_to(rules.bounds, at);
+        if inside != at {
+            violation =
+                Some(Violation { kind: ViolationKind::Bounds, detail: format!("({:.1}, {:.1}) is outside the bounds", at.0, at.1) });
+            at = inside;
+        }
+        if let Some((x, z, t)) = self.last {
+            let (dx, dz) = (at.0 - x, at.1 - z);
+            let dist = (dx * dx + dz * dz).sqrt();
+            let dt = now.saturating_sub(t) as f64 / 1000.0;
+            let allowed = rules.max_speed * dt * rules.grace.max(1.0) + 0.5;
+            if dist >= rules.teleport {
+                return self.strike(now, (x, z), ViolationKind::Teleport, format!("{dist:.1} units at once"));
+            }
+            if dist > allowed {
+                let k = allowed / dist;
+                at = (x + dx * k, z + dz * k);
+                violation = Some(Violation { kind: ViolationKind::Speed, detail: format!("{:.1} units a second", dist / dt.max(0.001)) });
+            }
+        }
+        self.last = Some((at.0, at.1, now));
+        match violation {
+            Some(v) => self.strike(now, at, v.kind, v.detail),
+            None => Verdict { at, violation: None },
+        }
+    }
+
+    fn strike(&mut self, now: u64, at: (f64, f64), kind: ViolationKind, detail: String) -> Verdict {
+        self.strikes = self.strikes(now) + 1;
+        self.last_strike_ms = now;
+        if kind == ViolationKind::Teleport {
+            let t = self.last.map(|l| l.2).unwrap_or(now);
+            self.last = Some((at.0, at.1, t));
+        }
+        Verdict { at, violation: Some(Violation { kind, detail }) }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn rules() -> Rules {
+        Rules { max_speed: 10.0, teleport: 25.0, bounds: Some((0.0, 0.0, 100.0, 100.0)), grace: 1.0 }
+    }
+
+    #[test]
+    fn a_fair_move_is_kept() {
+        let mut w = Warden::at((10.0, 10.0), 0);
+        let v = w.check(&rules(), (14.0, 10.0), 500);
+        assert_eq!(v, Verdict { at: (14.0, 10.0), violation: None });
+        assert_eq!(w.strikes(500), 0);
+    }
+
+    #[test]
+    fn a_fast_move_is_cut_to_what_the_speed_allows() {
+        let mut w = Warden::at((10.0, 10.0), 0);
+        let v = w.check(&rules(), (20.0, 10.0), 500);
+        assert_eq!(v.violation.map(|v| v.kind), Some(ViolationKind::Speed));
+        assert!((v.at.0 - 15.5).abs() < 1e-9 && v.at.1 == 10.0, "{:?}", v.at);
+        assert_eq!(w.position(), Some(v.at));
+    }
+
+    #[test]
+    fn a_teleport_is_refused_and_the_player_stays_put() {
+        let mut w = Warden::at((10.0, 10.0), 0);
+        let v = w.check(&rules(), (60.0, 10.0), 10_000);
+        assert_eq!((v.at, v.violation.map(|v| v.kind)), ((10.0, 10.0), Some(ViolationKind::Teleport)));
+        let v = w.check(&rules(), (f64::NAN, 1.0), 10_100);
+        assert_eq!((v.at, v.violation.map(|v| v.kind)), ((10.0, 10.0), Some(ViolationKind::Teleport)));
+        assert_eq!(w.strikes(10_100), 2);
+    }
+
+    #[test]
+    fn the_bounds_pull_a_move_back_in_and_strikes_clear_after_a_quiet_window() {
+        let mut w = Warden::at((99.0, 50.0), 0);
+        let v = w.check(&rules(), (101.0, 50.0), 1_000);
+        assert_eq!((v.at, v.violation.map(|v| v.kind)), ((100.0, 50.0), Some(ViolationKind::Bounds)));
+        assert_eq!(w.strikes(1_000), 1);
+        assert_eq!(w.strikes(1_000 + STRIKE_WINDOW_MS), 0);
+        w.place((5.0, 5.0), 20_000);
+        assert_eq!(w.check(&rules(), (6.0, 5.0), 20_200).violation, None);
+    }
+}

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

@@ -0,0 +1,183 @@
+//! Authoritative scoring: server-held score books, typed win conditions, and
+//! match summaries. The hub owns the only write path (a client never
+//! submits its own score), then publishes the summary on a topic or
+//! as an event.
+
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+use std::collections::BTreeMap;
+
+/// When is the match decided?
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub enum WinCondition {
+    /// First to reach `target` points.
+    ScoreReached { target: i64 },
+    /// Highest score when round `final_round` completes.
+    BestOfRounds { final_round: u32 },
+    /// Last active participant standing (driven by forfeits/eliminations).
+    LastStanding,
+    /// Survive until the timer: highest score at `ends_at_ms`.
+    TimeLimit { ends_at_ms: u64 },
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub struct Standing {
+    pub actor_id: String,
+    pub score: i64,
+    pub rank: u32,
+}
+
+/// The published result of a decided match.
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+pub struct MatchSummary {
+    pub winner_id: Option<String>,
+    pub standings: Vec<Standing>,
+    pub rounds_played: u32,
+    pub decided_by: String,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, Default)]
+pub struct ScoreBook {
+    pub scores: BTreeMap<String, i64>,
+    /// Actors still in the running (forfeits/eliminations remove).
+    pub active: Vec<String>,
+    pub decided: Option<MatchSummary>,
+}
+
+impl ScoreBook {
+    pub fn new(actors: impl IntoIterator<Item = String>) -> Self {
+        let active: Vec<String> = actors.into_iter().collect();
+        let scores = active.iter().map(|id| (id.clone(), 0)).collect();
+        Self { scores, active, decided: None }
+    }
+
+    /// Add points (the hub calls this from validated moves only).
+    pub fn award(&mut self, actor_id: &str, points: i64) -> i64 {
+        let entry = self.scores.entry(actor_id.to_string()).or_insert(0);
+        *entry += points;
+        *entry
+    }
+
+    pub fn score(&self, actor_id: &str) -> i64 {
+        self.scores.get(actor_id).copied().unwrap_or(0)
+    }
+
+    /// Remove an actor from contention (death/forfeit/disconnect).
+    pub fn eliminate(&mut self, actor_id: &str) {
+        self.active.retain(|id| id != actor_id);
+    }
+
+    /// Standings ordered by score desc (stable; rank is 1-based, ties share
+    /// the earlier rank's position order but distinct ranks — simple v1).
+    pub fn standings(&self) -> Vec<Standing> {
+        let mut rows: Vec<(String, i64)> = self.scores.iter().map(|(id, s)| (id.clone(), *s)).collect();
+        rows.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(&b.0)));
+        rows.into_iter().enumerate().map(|(index, (actor_id, score))| Standing { actor_id, score, rank: index as u32 + 1 }).collect()
+    }
+
+    /// Evaluate the condition; the first decision sticks (idempotent after).
+    pub fn evaluate(&mut self, condition: &WinCondition, rounds_played: u32, now_ms: u64) -> Option<&MatchSummary> {
+        if self.decided.is_some() {
+            return self.decided.as_ref();
+        }
+        let (decided, decided_by) = match condition {
+            WinCondition::ScoreReached { target } => (self.scores.values().any(|s| *s >= *target), "score_reached"),
+            WinCondition::BestOfRounds { final_round } => (rounds_played >= *final_round, "rounds_complete"),
+            WinCondition::LastStanding => (self.active.len() <= 1, "last_standing"),
+            WinCondition::TimeLimit { ends_at_ms } => (now_ms >= *ends_at_ms, "time_limit"),
+        };
+        if !decided {
+            return None;
+        }
+        let standings = self.standings();
+        let winner_id = match condition {
+            // Standing-based conditions crown the survivor; score-based the top.
+            WinCondition::LastStanding => self.active.first().cloned(),
+            _ => standings.first().map(|s| s.actor_id.clone()),
+        };
+        self.decided = Some(MatchSummary { winner_id, standings, rounds_played, decided_by: decided_by.to_string() });
+        self.decided.as_ref()
+    }
+}
+
+/// The summary as the JSON shape clients/events consume.
+pub fn summary_json(summary: &MatchSummary) -> Value {
+    json!({
+        "winnerId": summary.winner_id,
+        "standings": summary.standings.iter().map(|s| json!({
+            "actorId": s.actor_id, "score": s.score, "rank": s.rank,
+        })).collect::<Vec<_>>(),
+        "roundsPlayed": summary.rounds_played,
+        "decidedBy": summary.decided_by,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn book() -> ScoreBook {
+        ScoreBook::new(["a".to_string(), "b".to_string(), "c".to_string()])
+    }
+
+    #[test]
+    fn scoring_and_standings() {
+        let mut scores = book();
+        scores.award("b", 5);
+        scores.award("a", 3);
+        scores.award("b", 2);
+        let standings = scores.standings();
+        assert_eq!(standings[0].actor_id, "b");
+        assert_eq!(standings[0].score, 7);
+        assert_eq!(standings[0].rank, 1);
+        assert_eq!(standings[2].actor_id, "c");
+    }
+
+    #[test]
+    fn score_reached_decides_once() {
+        let mut scores = book();
+        scores.award("a", 9);
+        assert!(scores.evaluate(&WinCondition::ScoreReached { target: 10 }, 1, 0).is_none());
+        scores.award("a", 1);
+        let summary = scores.evaluate(&WinCondition::ScoreReached { target: 10 }, 1, 0).cloned().unwrap();
+        assert_eq!(summary.winner_id.as_deref(), Some("a"));
+        assert_eq!(summary.decided_by, "score_reached");
+        // Later evaluations return the same decision even if scores move.
+        scores.award("b", 99);
+        let again = scores.evaluate(&WinCondition::ScoreReached { target: 10 }, 2, 0).unwrap();
+        assert_eq!(again.winner_id.as_deref(), Some("a"));
+    }
+
+    #[test]
+    fn last_standing_and_rounds_and_time() {
+        let mut scores = book();
+        scores.eliminate("a");
+        assert!(scores.evaluate(&WinCondition::LastStanding, 1, 0).is_none());
+        scores.eliminate("c");
+        let summary = scores.evaluate(&WinCondition::LastStanding, 1, 0).unwrap();
+        assert_eq!(summary.winner_id.as_deref(), Some("b"));
+        assert_eq!(summary.decided_by, "last_standing");
+
+        let mut rounds = book();
+        rounds.award("c", 4);
+        assert!(rounds.evaluate(&WinCondition::BestOfRounds { final_round: 3 }, 2, 0).is_none());
+        let summary = rounds.evaluate(&WinCondition::BestOfRounds { final_round: 3 }, 3, 0).unwrap();
+        assert_eq!(summary.winner_id.as_deref(), Some("c"));
+
+        let mut timed = book();
+        timed.award("a", 1);
+        assert!(timed.evaluate(&WinCondition::TimeLimit { ends_at_ms: 60_000 }, 5, 59_999).is_none());
+        assert!(timed.evaluate(&WinCondition::TimeLimit { ends_at_ms: 60_000 }, 5, 60_000).is_some());
+    }
+
+    #[test]
+    fn summary_json_shape() {
+        let mut scores = book();
+        scores.award("a", 10);
+        let summary = scores.evaluate(&WinCondition::ScoreReached { target: 10 }, 2, 0).unwrap();
+        let v = summary_json(summary);
+        assert_eq!(v["winnerId"], "a");
+        assert_eq!(v["standings"][0]["rank"], 1);
+        assert_eq!(v["roundsPlayed"], 2);
+    }
+}