KARDS DIY 制卡指南

主题

DIY 扩展包 ​

DIY Pack v1 是可移植、只增不改、原子装载的卡牌扩展格式。仓库提供：

  • schemas/manifest-v1.schema.json
  • schemas/card-pack-v1.schema.json
  • schemas/card-v1.schema.json
  • schemas/effects-v1.schema.json
  • examples/diy-pack/

三个文件 ​

text
manifest.json
cards.json
effects.json

最小 manifest：

json
{
  "schema_version": 1,
  "pack_id": "fieldlab",
  "pack_version": "1.0.0",
  "engine_api": "1",
  "dependencies": [],
  "patch_policy": "forbid"
}

pack_id 必须以小写字母开头，只含小写字母、数字、下划线或连字符；core 与 system 是保留命名空间。

命名空间 ​

包内卡牌必须使用 <pack_id>:<local_id>，例如 fieldlab:combat_engineers。v1 禁止覆盖官方卡、系统卡或其他包中的卡，也不接受隐式 补前缀。这样可在合并前准确诊断冲突和悬空引用。

依赖 ​

依赖使用精确版本匹配。构建器会：

  1. 检查依赖是否存在且版本完全一致；
  2. 检查重复依赖、自依赖和依赖环；
  3. 以稳定拓扑顺序装载；
  4. 合并后验证全部跨卡引用闭合。

未实现的版本范围不会被当成兼容。

原子构建 ​

rust
use kards_core::{CatalogBuilder, PackBundle};

let mut builder = CatalogBuilder::new(official_pool);
builder.add_pack(PackBundle {
    manifest_json,
    cards_json,
    effects_json,
})?;
let (combined_pool, report) = builder.finish()?;

add_pack 解析失败时不写入 staging；finish 始终在私有副本上完成索引、引用闭包、效果 合并和可执行性检查。任何一步失败都不会返回半成品卡池。

v1 安全边界 ​

  • JSON DTO 使用 deny_unknown_fields；
  • 禁止 Script，DIY 必须使用公开声明式 DSL；
  • 重复 card_id、重复 numeric ID 和未知引用会失败；
  • can_create、Veteran 配对必须闭合；
  • 无法由主管线完整执行的效果返回 effect_not_executable；
  • 不会静默删除效果或自动修正包内容。

错误包含稳定 code、包 ID、文件、JSON Pointer、卡牌 ID 与相关 ID，便于编辑器定位。

从示例开始 ​

复制 examples/diy-pack/ 后只修改命名空间、卡面与效果。先用仓库 JSON Schema 做编辑期 检查，再交给 CatalogBuilder 做最终语义校验。玩家向写法可参考站内 DIY 制卡指南。