KARDS 规则引擎

kards-engine 是一套纯 Rust、确定性、可克隆的最小对局规则层。它不仅能在白板盘面上 验证单张卡，也能从两副合法构筑创建对局，处理换牌、回合、合法动作、私有选择、终局， 并输出带状态指纹的快照与回放。

它是无头状态机，不提供界面、账号、大厅、匹配、网络服务或数据库。上层应用可以组合 这些稳定值接口，但不属于本仓库。

能做什么

• 严格装配官方卡面、生成卡、Veteran 卡、标签、兵种与效果。
• 校验 39 张构筑、主盟国、稀有度副本上限和标准/预备模式。
• 创建双总部、双牌库、确定性洗牌和双方换牌阶段。
• 只向决策方公开其可见观察与当前合法动作。
• 通过同一主管线结算部署、移动、攻击、指令、反制、触发、延迟和死亡波。
• 在伤害窗口稳定后原子判定胜、负或平局。
• 严格加载带命名空间与依赖关系的 DIY Pack。
• 编码带版本、卡池和状态指纹的快照，或逐步验证完整回放。

核心边界

核心库不读取文件、不访问网络，也不依赖进程级可变状态。调用方负责取得 JSON 文本并 传给装配接口；规则库只接收值、返回值或结构化错误。随机性只来自 GameState 内的 ChaCha20Rng 状态，因此克隆状态后执行同一动作会得到同一结果。

文档事实源

仓库中已跟踪的 docs/ 是项目唯一维护的知识事实源；本站由 docs/diy-guide/ 直接构建。项目不再维护 .qoder/repowiki 或其他平行知识库，线上 页面和服务器目录也不会反向覆盖仓库文档。

推荐阅读顺序

1. 快速开始：从卡池到第一批合法动作。
2. 架构与边界：模块责任和单向依赖。
3. 构筑与开局：最小规则对局生命周期。
4. 动作与私有信息：决策、观察和待选状态。
5. 结算与终局：伤害窗口、死亡波和回滚。
6. DIY 扩展包：可移植扩展的严格契约。

卡牌作者可直接进入 DIY 制卡指南；规则实现的最高权威仍是仓库内 docs/rules.md。