快速开始

1. 运行全量验证

在仓库根目录执行：

cargo test -p kards-core --manifest-path engine/Cargo.toml
cargo fmt --all --manifest-path engine/Cargo.toml -- --check

engine/ 是 Cargo workspace，当前公共库为 kards-core。

2. 装配卡池

核心库不做文件 I/O。调用方先读取卡面与效果 JSON，再一次性传入：

use kards_core::{assemble_catalog, CatalogSources, EffectSource};

let effects = [
    EffectSource { name: "britain", json: britain_effects },
    EffectSource { name: "germany", json: germany_effects },
    // 继续传入其余国家和 neutral_spawnables。
];

let (pool, report) = assemble_catalog(CatalogSources {
    cards_json,
    supplemental_json,
    spawnable_tokens_json,
    veteran_json,
    card_tags_json: Some(card_tags_json),
    card_subtypes_json: None,
    effects: &effects,
})?;

装配是严格的：未知卡、未知脚本、非法 token、悬空 can_create 或主管线无法完整执行的 效果都会返回 CatalogError。接口不会通过静默删槽得到“可用”卡池。

3. 创建最小规则对局

use kards_core::{
    create_match, DeckFormat, DeckList, MatchSession, MatchSpec,
};

let spec = MatchSpec {
    seed: 20260728,
    format: DeckFormat::Standard,
    players: [
        DeckList::from_json(player_zero_deck_json)?,
        DeckList::from_json(player_one_deck_json)?,
    ],
};

let (state, match_report) = create_match(&pool, &spec)?;
let mut session = MatchSession::new(&pool, state)?;

此时状态处于双方换牌阶段。match_report 给出种子、双方构筑分类、盟国张数和实际先手。 调用方只需持续提交合法动作即可驱动规则状态机；界面、传输和存储由仓库外上层负责。

4. 驱动决策

for decision in session.decisions(&pool)? {
    println!("P{} 有 {} 个合法动作", decision.actor.0, decision.actions.len());

    // 示例只选择第一个动作；真实调用方应把 observation 与 actions 交给该玩家。
    let transition = session.advance_index(
        &pool,
        decision.actor,
        decision.state,
        0,
    )?;

    if transition.finished {
        println!("对局结束：{:?}", transition.outcome);
    }
}

decision.state 是动作列表对应的状态指纹。状态已变化时，旧索引会以 StaleDecision 响亮失败，不会落到另一项动作上。

5. 保存结果

use kards_core::{encode_snapshot, replay_match};

let snapshot_json = encode_snapshot(&pool, session.state())?;
let trace = session.trace(&pool)?;
let replayed = replay_match(&pool, &trace)?;

快照用于恢复某一时刻；回放用于证明一串动作在同一卡池与协议下逐步得到相同状态。