@crowdedkingdoms/ckx-kit 0.4.0-dev.1 → 0.5.0-test.1

package/crates/ckx-sdk/src/kit/econ/loot.rs

@@ -0,0 +1,116 @@
+//! Loot tables with pity: each roll picks by weight, and a pity group the player has not hit in
+//! `pity_within` rolls is guaranteed on the next. A player's [`LootBook`] for a table keeps the
+//! counters and the last rolls, for a dispute.
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+use crate::kit::Rng;
+
+fn one() -> u64 {
+    1
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
+pub struct LootEntry {
+    pub item: String,
+    #[serde(default = "one")]
+    pub count: u64,
+    pub weight: u64,
+    /// Entries in one pity group tick its counter together.
+    #[serde(default)]
+    pub pity_group: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq, Eq)]
+#[serde(default)]
+pub struct LootTable {
+    pub entries: Vec<LootEntry>,
+    /// A pity group, and the rolls within which it is guaranteed.
+    pub pity_within: BTreeMap<String, u32>,
+}
+
+/// What a player's rolls on one table have been.
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq, Eq)]
+#[serde(default)]
+pub struct LootBook {
+    pub rolls: u64,
+    pub pity: BTreeMap<String, u32>,
+    /// The last rolls: `(roll number, item)`.
+    pub recent: Vec<(u64, String)>,
+}
+
+/// How many of a book's rolls it keeps.
+pub const RECENT_KEEP: usize = 32;
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
+pub struct LootRoll {
+    pub item: String,
+    pub count: u64,
+    /// Pity picked it.
+    pub pity: bool,
+    pub roll: u64,
+}
+
+/// Rolls once; `None` for a table with no weight. A due pity group picks its rarest entry.
+pub fn roll(table: &LootTable, book: &mut LootBook, rng: &mut Rng) -> Option<LootRoll> {
+    let due = table.pity_within.iter().find(|(g, within)| book.pity.get(*g).copied().unwrap_or(0) + 1 >= **within).map(|(g, _)| g.clone());
+    let picked = match &due {
+        Some(g) => table.entries.iter().filter(|e| e.pity_group.as_deref() == Some(g)).min_by_key(|e| e.weight).cloned(),
+        None => {
+            let weights: Vec<u64> = table.entries.iter().map(|e| e.weight).collect();
+            rng.weighted(&weights).map(|i| table.entries[i].clone())
+        }
+    }?;
+    book.rolls += 1;
+    for g in table.pity_within.keys() {
+        let c = book.pity.entry(g.clone()).or_insert(0);
+        *c = if picked.pity_group.as_deref() == Some(g) { 0 } else { c.saturating_add(1) };
+    }
+    book.recent.push((book.rolls, picked.item.clone()));
+    if book.recent.len() > RECENT_KEEP {
+        let drop = book.recent.len() - RECENT_KEEP;
+        book.recent.drain(..drop);
+    }
+    Some(LootRoll { item: picked.item, count: picked.count, pity: due.is_some(), roll: book.rolls })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn gacha() -> LootTable {
+        LootTable {
+            entries: vec![
+                LootEntry { item: "common".into(), count: 1, weight: 990, pity_group: None },
+                LootEntry { item: "legendary".into(), count: 1, weight: 10, pity_group: Some("rare".into()) },
+            ],
+            pity_within: BTreeMap::from([("rare".to_string(), 10)]),
+        }
+    }
+
+    #[test]
+    fn pity_guarantees_the_group_within_its_rolls() {
+        let (t, mut book, mut rng) = (gacha(), LootBook::default(), Rng::seeded(7));
+        let mut since = 0;
+        for _ in 0..200 {
+            let r = roll(&t, &mut book, &mut rng).unwrap();
+            since = if r.item == "legendary" { 0 } else { since + 1 };
+            assert!(since < 10, "pity fires within ten rolls");
+        }
+        assert_eq!((book.rolls, book.recent.len()), (200, RECENT_KEEP));
+    }
+
+    #[test]
+    fn a_natural_hit_resets_the_counter_and_an_empty_table_rolls_nothing() {
+        let sure = LootTable {
+            entries: vec![LootEntry { item: "legendary".into(), count: 2, weight: 1, pity_group: Some("rare".into()) }],
+            pity_within: BTreeMap::from([("rare".to_string(), 10)]),
+        };
+        let mut book = LootBook { pity: BTreeMap::from([("rare".to_string(), 5)]), ..LootBook::default() };
+        let r = roll(&sure, &mut book, &mut Rng::seeded(1)).unwrap();
+        assert_eq!((r.count, r.pity, book.pity["rare"]), (2, false, 0));
+        assert!(roll(&LootTable::default(), &mut book, &mut Rng::seeded(1)).is_none());
+    }
+}

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

@@ -0,0 +1,50 @@
+//! The soft economy a game keeps in its hubs: items in stacks ([`items`]), soft currencies
+//! ([`wallet`]), both together with a mailbox for what does not fit ([`holdings`]), escrow holds
+//! and the references a hub answers once ([`holds`]), recipes ([`recipes`]), loot with pity
+//! ([`loot`]), idle production that catches up ([`production`]), vendors that restock
+//! ([`vendor`]), an order book ([`orderbook`]), and levels, achievements and quests
+//! ([`progression`]).
+//!
+//! **It is not a ledger.** A hub's items and balances are its own state, persisted with its
+//! snapshots like everything else it keeps. A transfer between hubs is calls each answered once
+//! by its reference ([`holds::Applied`]), not a transaction: there is no double-entry book, no
+//! audit trail beyond the hubs' logs, and no real money. Escrow is a hold in the owner's own hub
+//! ([`holds::Holds`]), so goods in flight are never in two places, and whatever drives a
+//! transfer (a market) retries each step until its hub answers.
+
+pub mod holdings;
+pub mod holds;
+pub mod items;
+pub mod loot;
+pub mod orderbook;
+pub mod production;
+pub mod progression;
+pub mod recipes;
+pub mod vendor;
+pub mod wallet;
+
+pub use holdings::{Bundle, Holdings};
+pub use holds::{Applied, Holds};
+pub use items::{Catalog, Inventory, ItemDef, Stack};
+pub use wallet::Wallet;
+
+/// The longest item id or currency the economy takes.
+pub const ID_MAX: usize = 64;
+/// The longest reference [`Holds`] and [`Applied`] take: room for a driver's key, a counter and
+/// the suffixes of the steps it derives from one.
+pub const REFERENCE_MAX: usize = 128;
+
+pub(crate) fn check_id(what: &str, id: &str) -> crate::Result<()> {
+    check_len(what, id, ID_MAX)
+}
+
+pub(crate) fn check_reference(reference: &str) -> crate::Result<()> {
+    check_len("reference", reference, REFERENCE_MAX)
+}
+
+fn check_len(what: &str, s: &str, max: usize) -> crate::Result<()> {
+    if s.is_empty() || s.len() > max {
+        return Err(super::error(super::codes::BAD_REQUEST, format!("a {what} is 1 to {max} bytes")));
+    }
+    Ok(())
+}

package/crates/ckx-sdk/src/kit/econ/orderbook.rs

@@ -0,0 +1,155 @@
+//! An order book for one item: limit orders matched at price-time priority, at the resting
+//! order's price. Placing an order answers the [`Fill`]s whoever runs the book settles (the
+//! buyer pays `price * count`, the seller gives `count`); escrow is the runner's ([`super::holds`]).
+
+use serde::{Deserialize, Serialize};
+
+use crate::Result;
+use crate::kit::{codes, error};
+
+#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum Side {
+    Buy,
+    Sell,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
+pub struct Order {
+    pub id: u64,
+    pub player: u64,
+    pub side: Side,
+    /// The limit, per unit.
+    pub price: i64,
+    /// What is still open.
+    pub count: u64,
+    pub at: u64,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
+pub struct Fill {
+    pub buyer: u64,
+    pub seller: u64,
+    pub buy_order: u64,
+    pub sell_order: u64,
+    pub price: i64,
+    pub count: u64,
+}
+
+/// Bids best (highest) first, asks best (lowest) first, earlier first at a price.
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq, Eq)]
+#[serde(default)]
+pub struct OrderBook {
+    pub bids: Vec<Order>,
+    pub asks: Vec<Order>,
+}
+
+impl OrderBook {
+    /// Places order `id` and matches it at once; whatever is left rests on the book.
+    pub fn place(&mut self, id: u64, player: u64, side: Side, price: i64, count: u64, now: u64) -> Result<Vec<Fill>> {
+        if price <= 0 || count == 0 {
+            return Err(error(codes::BAD_REQUEST, "a price and a count are positive"));
+        }
+        let mut left = count;
+        let mut fills = Vec::new();
+        let (far, near) = match side {
+            Side::Buy => (&mut self.asks, &mut self.bids),
+            Side::Sell => (&mut self.bids, &mut self.asks),
+        };
+        while left > 0 {
+            let Some(best) = far.first_mut() else { break };
+            let crosses = match side {
+                Side::Buy => best.price <= price,
+                Side::Sell => best.price >= price,
+            };
+            if !crosses {
+                break;
+            }
+            let n = left.min(best.count);
+            let (buyer, seller, buy_order, sell_order) = match side {
+                Side::Buy => (player, best.player, id, best.id),
+                Side::Sell => (best.player, player, best.id, id),
+            };
+            fills.push(Fill { buyer, seller, buy_order, sell_order, price: best.price, count: n });
+            best.count -= n;
+            left -= n;
+            if best.count == 0 {
+                far.remove(0);
+            }
+        }
+        if left > 0 {
+            let at = near
+                .iter()
+                .position(|o| match side {
+                    Side::Buy => o.price < price,
+                    Side::Sell => o.price > price,
+                })
+                .unwrap_or(near.len());
+            near.insert(at, Order { id, player, side, price, count: left, at: now });
+        }
+        Ok(fills)
+    }
+
+    /// Takes `player`'s order `id` off the book.
+    pub fn cancel(&mut self, id: u64, player: u64) -> Option<Order> {
+        for side in [&mut self.bids, &mut self.asks] {
+            if let Some(i) = side.iter().position(|o| o.id == id && o.player == player) {
+                return Some(side.remove(i));
+            }
+        }
+        None
+    }
+
+    pub fn order(&self, id: u64) -> Option<&Order> {
+        self.bids.iter().chain(self.asks.iter()).find(|o| o.id == id)
+    }
+
+    /// `(price, count)` a level, best first.
+    pub fn depth(&self, side: Side, levels: usize) -> Vec<(i64, u64)> {
+        let orders = match side {
+            Side::Buy => &self.bids,
+            Side::Sell => &self.asks,
+        };
+        let mut out: Vec<(i64, u64)> = Vec::new();
+        for o in orders {
+            if let Some((p, n)) = out.last_mut()
+                && *p == o.price
+            {
+                *n += o.count;
+                continue;
+            }
+            if out.len() == levels {
+                break;
+            }
+            out.push((o.price, o.count));
+        }
+        out
+    }
+
+    pub fn of(&self, player: u64) -> Vec<Order> {
+        self.bids.iter().chain(self.asks.iter()).filter(|o| o.player == player).cloned().collect()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn orders_match_at_the_resting_price_in_price_time_order() {
+        let mut b = OrderBook::default();
+        b.place(1, 10, Side::Sell, 12, 5, 0).unwrap();
+        b.place(2, 11, Side::Sell, 10, 3, 1).unwrap();
+        b.place(3, 12, Side::Sell, 10, 4, 2).unwrap();
+        let fills = b.place(4, 20, Side::Buy, 11, 5, 3).unwrap();
+        assert_eq!(fills.iter().map(|f| (f.seller, f.price, f.count)).collect::<Vec<_>>(), vec![(11, 10, 3), (12, 10, 2)]);
+        assert_eq!(b.depth(Side::Sell, 5), vec![(10, 2), (12, 5)]);
+        assert!(b.bids.is_empty(), "the buy filled whole");
+        let rest = b.place(5, 21, Side::Buy, 9, 4, 4).unwrap();
+        assert!(rest.is_empty());
+        assert_eq!(b.depth(Side::Buy, 5), vec![(9, 4)]);
+        assert_eq!(b.cancel(5, 99), None, "only its owner cancels it");
+        assert_eq!(b.cancel(5, 21).unwrap().count, 4);
+        assert!(b.place(6, 1, Side::Buy, 0, 1, 5).is_err());
+    }
+}

package/crates/ckx-sdk/src/kit/econ/production.rs

@@ -0,0 +1,155 @@
+//! Idle production: producers that turn inputs into outputs at a rate, and catch up on any time
+//! away in one step, bounded by their inputs and their outputs' storage.
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq)]
+#[serde(default)]
+pub struct Producer {
+    pub id: String,
+    /// What a cycle takes from the chain's stock.
+    pub inputs: BTreeMap<String, u64>,
+    /// What a cycle adds to it.
+    pub outputs: BTreeMap<String, u64>,
+    pub per_minute: f64,
+    /// A cycle begun and not finished, from 0 to 1.
+    pub progress: f64,
+}
+
+/// Producers in order (an upstream producer before the ones it feeds), their stock, and how
+/// much of each resource the stock holds at most.
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq)]
+#[serde(default)]
+pub struct Chain {
+    pub producers: Vec<Producer>,
+    pub stock: BTreeMap<String, u64>,
+    pub capacity: BTreeMap<String, u64>,
+    /// When it last caught up; 0 before it starts.
+    pub at: u64,
+}
+
+impl Chain {
+    /// Starts the clock.
+    pub fn start(&mut self, now: u64) {
+        if self.at == 0 {
+            self.at = now.max(1);
+        }
+    }
+
+    /// Catches up to `now`; answers what was made. A producer short of inputs or out of storage
+    /// runs as many whole cycles as it can and loses the rest of the time.
+    pub fn advance(&mut self, now: u64) -> BTreeMap<String, u64> {
+        let mut made = BTreeMap::new();
+        if self.at == 0 || now <= self.at {
+            self.start(now);
+            return made;
+        }
+        let minutes = (now - self.at) as f64 / 60_000.0;
+        self.at = now;
+        for i in 0..self.producers.len() {
+            let p = &self.producers[i];
+            let potential = p.per_minute.max(0.0) * minutes + p.progress;
+            let mut cycles = potential.floor();
+            for (r, &n) in &p.inputs {
+                if let Some(supported) = self.stock.get(r).copied().unwrap_or(0).checked_div(n) {
+                    cycles = cycles.min(supported as f64);
+                }
+            }
+            for (r, &n) in &p.outputs {
+                if let Some(&cap) = self.capacity.get(r)
+                    && let Some(fits) = cap.saturating_sub(self.stock.get(r).copied().unwrap_or(0)).checked_div(n)
+                {
+                    cycles = cycles.min(fits as f64);
+                }
+            }
+            let runs = cycles.max(0.0) as u64;
+            let bound = (runs as f64) < potential.floor();
+            let p = &mut self.producers[i];
+            p.progress = if bound { 0.0 } else { (potential - runs as f64).clamp(0.0, 0.999_999) };
+            if runs == 0 {
+                continue;
+            }
+            let (inputs, outputs) = (p.inputs.clone(), p.outputs.clone());
+            for (r, n) in inputs {
+                let s = self.stock.entry(r).or_insert(0);
+                *s = s.saturating_sub(n.saturating_mul(runs));
+            }
+            for (r, n) in outputs {
+                let add = n.saturating_mul(runs);
+                *self.stock.entry(r.clone()).or_insert(0) += add;
+                *made.entry(r).or_insert(0) += add;
+            }
+        }
+        self.stock.retain(|_, n| *n > 0);
+        made
+    }
+
+    /// Takes up to `count` of `resource` out of the stock; answers how many.
+    pub fn take(&mut self, resource: &str, count: u64) -> u64 {
+        let Some(have) = self.stock.get_mut(resource) else { return 0 };
+        let taken = count.min(*have);
+        *have -= taken;
+        if *have == 0 {
+            self.stock.remove(resource);
+        }
+        taken
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn chain() -> Chain {
+        Chain {
+            producers: vec![
+                Producer { id: "mine".into(), outputs: BTreeMap::from([("ore".into(), 1)]), per_minute: 6.0, ..Producer::default() },
+                Producer {
+                    id: "smelter".into(),
+                    inputs: BTreeMap::from([("ore".into(), 2)]),
+                    outputs: BTreeMap::from([("ingot".into(), 1)]),
+                    per_minute: 2.0,
+                    ..Producer::default()
+                },
+            ],
+            ..Chain::default()
+        }
+    }
+
+    #[test]
+    fn a_night_away_catches_up_in_one_step() {
+        let mut c = chain();
+        c.start(1_000);
+        let made = c.advance(1_000 + 10 * 60_000);
+        assert_eq!(made["ore"], 60, "the mine runs six a minute");
+        assert_eq!(made["ingot"], 20, "the smelter runs two a minute on the mine's ore");
+        assert_eq!(c.stock["ore"], 20);
+    }
+
+    #[test]
+    fn storage_and_inputs_bound_it_and_a_bound_producer_loses_the_rest_of_the_time() {
+        let mut c = chain();
+        c.capacity.insert("ore".into(), 10);
+        c.producers.truncate(1);
+        c.start(1);
+        c.advance(1 + 60 * 60_000);
+        assert_eq!(c.stock["ore"], 10, "the store is full");
+        assert_eq!(c.producers[0].progress, 0.0);
+        assert_eq!(c.take("ore", 4), 4);
+        let made = c.advance(1 + 60 * 60_000 + 30_000);
+        assert_eq!(made["ore"], 3, "half a minute at six a minute");
+    }
+
+    #[test]
+    fn a_partial_cycle_carries_over() {
+        let mut c = chain();
+        c.producers.truncate(1);
+        c.start(1);
+        c.advance(1 + 5_000);
+        assert!(c.stock.is_empty());
+        let made = c.advance(1 + 10_000);
+        assert_eq!(made["ore"], 1, "two halves make a cycle");
+    }
+}