纸片化学社区版 · 数据格式

本文档定义数据源（远程服务器）提供的数据格式。游戏运行时通过 DownloadManager 从 GameManager.data_origin（数据源根 URL）下载数据，并加载到 GameManager 的各字典中。

本文档由 AI 生成，对应数据后端 0.1.1 版本。

目录结构（数据源服务器端）

<data_origin>/
├── index.json               # 数据源信息
├── card/list.json           # 卡牌索引
├── card/id/{id}             # 某张卡牌的详细定义（文本，JSON 格式）
├── reaction/list.json       # 反应索引
├── reaction/id/{id}         # 某条反应的详细定义
├── matter/list.json         # 物质索引
├── matter/id/{id}           # 某物质的详细定义
└── asset/list.json          # 图片与音频资源索引
    ├── asset/pic/{id}       # 图片文件
    └── asset/sound/{id}     # 音频文件

index.json

{
  "name": "数据源名称",
  "uuid": "c8f3b2a1-...（唯一标识，用于本地缓存目录名）"
}

list.json（三类通用结构）

card、reaction、matter 的 list.json 均为「id → 文件名」映射：

{
  "card-h": "H",
  "card-o": "O",
  "card-ignite": "点燃·升温"
}

客户端下载后按文件名保存为 cards/H.json、cards/点燃·升温.json 等，load_resource() 会读取每个详细定义并以 id 为键存入对应字典。

asset/list.json

{
  "pics": {
    "pic-metal-fe": "fe.png"
  },
  "sounds": {
    "sound-hit": "hit.ogg"
  }
}

卡牌定义（card/*.json）

{
  "id": "card-h",
  "name": "H",
  "name_en": "Hydrogen",
  "type": "atom",
  "category": "nonmetal",
  "count": 4,
  "pic": "pic-metal-fe",
  "effects": ["IGNITE", "HEAT"]
}

单局单种卡牌数量上限（count）

count 字段定义某张卡牌在一局游戏中的总张数上限。引擎在开局初始化牌堆时，每种卡牌恰好放入 count 张；此后所有操作（发牌、摸牌、调度、O2、结晶、提取、增益、攻击者/队友补牌等）只在不同区域间移动卡牌，总量守恒，因此任意时刻该卡牌在「牌堆＋手牌＋反应区＋元素区＋弃牌堆」中的总张数都不会超过 count。

• 默认值：4。
• count <= 0：该卡牌本局不进入牌堆（不参与游戏）。
• 引擎提供 GameLoopManager.get_card_count_limit(card_id)（单种上限）与 GameLoopManager.get_card_global_count(card_id)（当前整局总张数）查询接口；若数据异常导致某卡牌整局总张数超过上限，引擎会剔除该张并打印告警（见 _draw_from_deck）。

条件效果枚举（effects 合法值）

物质定义（matter/*.json）

物质定义驱动「伤害自动分类」，是结算阶段的唯一数据依据。

{
  "id": "matter-h2so4",
  "formula": "H2SO4",
  "composition": ["H", "H", "S", "O", "O", "O", "O"],
  "state": "liquid",
  "solubility": "soluble",
  "categories": ["strong_acid", "corrosive"],
  "damage_type": "CORROSION",
  "corrosion_strength": "strong",
  "is_illegal_attack": false,
  "is_harmless_gas": false,
  "is_generated_water": false,
  "special": []
}

物质分类标签（categories 合法值）

分类重复规则：一个物质可同时属于多个分类（如 Zn(CN)₂ 既是 cyanide 又是 insoluble_salt_base），但伤害不叠加，按「最早的结算时机」结算：

1. GENERAL（结算阶段一）优先于 POISONING / CORROSION（结算阶段二）
2. POISONING 优先于 CORROSION

引擎在 _auto_classify_damage() 中按此优先级自动推导 damage_type；若定义中显式写了 damage_type，则以其为准。

已配平产物与无伤害物质：不包含上述任何 categories 的物质的 damage_type 为 null（非伤害物），可用于暗攻、反应中间体等。

反应定义（reaction/*.json）

反应定义驱动「自动反应引擎」。引擎在反应区内为每个玩家的物质自动匹配反应，遵循规则「反应区内能反应物质之间会立即发生反应」。

{
  "id": "reaction-h2so4-naoh",
  "reactants": ["matter-h2so4", "matter-naoh"],
  "products": ["matter-na2so4", "matter-h2o"],
  "conditions": [],
  "priority": 0
}

{
  "id": "reaction-mg-ignite",
  "reactants": ["matter-mg", "matter-o2"],
  "products": ["matter-mgo"],
  "conditions": ["IGNITE"],
  "priority": 1
}

反应语义

• 进攻 / 辅助 / 暗攻 / 补伤触发：反应物被消耗（其卡片组合进生成物），生成物留在反应区，参与伤害结算；自动完成伤害分类。
• 防御触发：反应物被消耗，生成物直接进入弃牌堆，视为防御成功。
• 条件消耗：反应要求 conditions 时，参与反应的条件效果视为被该反应消耗，条件牌随反应物一并进入弃牌堆。
• 递归触发：生成物可能继续与反应区其他物质反应，引擎会反复匹配直到无反应可发生（最多 32 轮，防止死循环）。
• 产物的 source_player_id：取参与反应物中 timestamp 最大者（即「最后补全的人」），保证伤害来源正确。

客户端加载结果（GameManager 字典）

DownloadManager.load_resource() 加载后：

兼容性：若某个详细定义文件不存在（旧版数据源），对应键保留 list.json 中的原始文件名字符串，游戏逻辑可通过 is Dictionary 判断。

物质实例（substance_data）字段约定

引擎在 create_substance_data() 基础上补充/修正以下字段，供 UI 与结算读取：