一、目录结构
主题包完整镜像游戏内的资源路径。想覆盖 res://assets/sprites/insects/fly.png，就在主题里放 assets/sprites/insects/fly.png。
themes/<your-theme-id>/
manifest.json 必需
preview.png 建议，列表封面
assets/
sprites/
ant1.png ant2.png ant3.png 4 品级贴图
goldant.png 金色变异
p.png 搬运碎屑
ant_head.png 好友探头
nest.png nest_path.png 蚁巢皮肤
insects/<id>.png + .tpsheet 9 种昆虫
foods/<id>.png + .tpsheet 食物阶段动画
ui/icons/*.png 卡片与资源栏图标
data/*.csv 数值表，可选
translations/messages.csv 文案覆盖，可选范围限制
只有 assets/、data/、translations/ 三个顶层目录会被读取。主题包无法覆盖脚本与场景，覆盖表由游戏遍历磁盘生成，不存在路径穿越风险。
二、manifest.json
{
"id": "wolf_pack",
"name": "Wolf Pack",
"name_i18n": { "zh": "狼群", "ja": "狼の群れ" },
"desc": "Replaces the ant colony with a wolf pack.",
"desc_i18n": { "zh": "把蚁群换成狼群。" },
"version": "1.0.0",
"author": "your name",
"theme_type": "beast",
"requires": { "game_version": "0.8" },
"tags": ["wolf", "beast"],
"contents": ["data", "translations", "insects"]
}id必须与目录名完全一致，否则该主题被跳过。name必需，而且是纯文本不是翻译键。主题列表要显示所有已安装主题，未激活主题的译文并没有加载，翻译键在那里取不到值。多语言用name_i18n/desc_i18n，按zh_TW→zh→name回退。requires.game_version会被真正检查：声明版本高于当前游戏版本时不会加载（列表仍可见，点了不生效并提示）。不声明即视为兼容。theme_type/tags/contents目前仅作元数据留存，供后续创意工坊筛选，当前版本不读取。
三、数值表
数值表是整表替换而非按行合并，所以必须从游戏的 data/ 复制一整份再改，缺列缺行会被校验拦下。
整包拒绝
启动时全部 CSV 走与基础表相同的校验（类型、范围、跨表引用）。任何一处错误都会整包拒绝并自动回到默认主题，游戏内会列出前几条错误。不做逐表回退——「主题的昆虫表 + 默认的食物表」这种混合态会让跨表引用指向不存在的 id，比拒绝加载更糟。
四、哪些改动会暂停成就同步
判定是字段级的：只有改了影响玩法的字段，该主题才会暂停 Steam 成就与统计上传。本地成就照常解锁可见，已解锁的不回滚，切回默认主题后自动恢复同步。
纯外观白名单：改这些不影响同步
| 表 | 可自由修改的列 |
|---|---|
skins.csv | 整表 |
ant_castes.csv | name texture display_width* |
insects.csv | name sheet icon display_width* |
foods.csv | name tint_r tint_g tint_b icon |
upgrades.csv | name desc icon |
achievements.csv | name desc subject icon icon_locked |
rare_elements.csv | name icon source order icon_texture |
resources.csv | name icon order icon_texture |
upgrade_categories.csv | name order page_type icon |
game_params.csv | 全部 shadow_* 与 lift_* 键 |
* display_width 允许在基础值的 1/3 ~ 3 倍之间调整（换个物种体型自然要变），超出这个范围判为影响玩法。
其余任何改动都会暂停同步，包括增删行、改 id、改表头，以及 hp、speed、各类成本与 target 等数值。官方狼群主题只改了上表内的列，所以它是纯外观主题、成就照常上传——照抄它的做法即可。
注意 insects.texture（静态贴图）不在白名单：昆虫的围咬半径由该图的不透明边缘扫描得出，换图会改变战斗几何。走 sheet 图集替换即可。
五、改资源类型与升级页
除了换数值和换皮，还能改两处结构——这也是「换个题材」与「换套皮肤」的区别。
自定义资源轴
淀粉/糖/蛋白不是写死的，整表替换 data/resources.csv 即可换成兽肉/皮毛/骨头。列为 id,name,icon,order,initial,icon_texture。id 是存档键，只用 [a-z0-9_]；initial 是开局存量（影响难度，会暂停成就同步）。资源数量不限于 3 个。
跨屏远征遇到跑别的主题的好友时，对方奖励里本主题不认识的资源会被忽略——不会崩，但也收不到。
自定义升级页
升级页的数量、名称与顺序由 data/upgrade_categories.csv 决定，列为 id,name,order,page_type,icon：
upgrade_categories.csv
id,name,order,page_type,icon
den,ui.tab.nest_upgrade,0,generic,res://assets/ui/icons/yichao_1.png
wolf,ui.tab.ant_upgrade,1,generic,res://assets/ui/icons/mayi_1.png
food,ui.tab.food_upgrade,2,food,res://assets/ui/icons/shiwu_1.png
beast,ui.tab.beast_upgrade,3,generic,res://assets/ui/icons/mayi_2.pngupgrades.csv的category列必须引用本表的id，写错会被校验拦下（不再静默消失）。page_type：generic是通用升级页；food指向食物专用页（含投喂选择与解锁区），只能有一个。- 不在本表里列出的分类等于移除该页；分类下没有任何升级项时该页也不显示。
- 新增分类要自带译文（如上面的
ui.tab.beast_upgrade）。成就 / 创意工坊 / 设置三页属于程序外壳，不受此表影响。
新增升级项的效果列
新增升级项必须填 upgrades.csv 的 6 个 effect_* 列，否则卡片上的效果说明是空白（空 effect_key 会被校验报错）：
| 列 | 含义 |
|---|---|
effect_key | 效果文案的翻译键，内含 {0} 占位符 |
effect_unit | absolute 原值 / percent 小数转百分比 / multiplier 倍率 / minutes 秒转分钟 / unlock 无数值只判解锁 |
effect_base | 0 级时的基数。可写数字，也可写 ant_params / combat_params / game_params 里的键名 |
effect_per_level | 每级增量，同样支持键名 |
effect_max | 上限，留空即不限 |
effect_decimals | 显示小数位 |
显示值 = base + 等级 × per_level，再按 unit 换算。引用键名而非抄数字，可避免调平衡时同一个数在两处分叉；键名拼错会被校验报出。
六、文案覆盖
与数值表相反，文案是键级覆盖：只需列出想改的键，其余继续用基础译文。
表头必须是 keys,zh,en,ja,ko,fr,de,zh_TW,ar,it,es（列名即 locale 码）。含逗号的译文要用双引号包起来，文本内的双引号写成两个 ""。
七、贴图规范
- 尺寸自由：蚂蚁、昆虫、蚁巢都按「目标显示宽度 ÷ 贴图实际宽度」自动归一化，换素材不必改配置。但
p.png（搬运碎屑）按固定倍率缩放，请贴近原图尺寸。 - 图集（
.tpsheet+.png）请整对替换，两个文件都要放进主题目录。.tpsheet是 TexturePacker 导出的 JSON，帧布局不变时可直接沿用原文件只换图。 - 主题贴图是外部文件、不经引擎导入，因此只支持 PNG，且显存占用高于打包内的压缩贴图。
- 窗口按钮一类的界面外壳有意不做主题化：它属于程序外壳而非游戏世界。
八、安装位置
主题装在游戏根目录的 themes\ 下（keyarium.exe 同级），一个主题一个子目录。游戏内「创意工坊」标签页的「打开主题文件夹」按钮会直接打开实际生效的那个目录。
| 位置 | 用途 | 优先级 |
|---|---|---|
keyarium.exe 同级的 themes\<id>\ |
玩家安装位置，随包发布的官方主题也在这里 | 中 |
%APPDATA%\Godot\app_userdata\Keyarium\themes\<id>\ |
游戏目录不可写时（如装在 Program Files）的兜底位置 | 高 |
| 仓库内 themes/<id>/ | 仅编辑器内可见，供开发调试 | 低 |
同 id 时兜底目录优先，方便在本地迭代官方主题而不动发布文件。切换主题需要重启游戏，点确认后游戏自动保存进度并重新拉起自己。主题选择存在 user://theme.json，与存档分离——清档不会重置主题，因为主题是显示偏好而非游戏进度。
九、本地校验
改完包不必反复进游戏试，用启动参数直接跑一遍与游戏内完全相同的校验：
keyarium.exe -- --validate-theme <your-theme-id>它会打印：覆盖了几个文件、哪些数值表、是否影响 Steam 成就同步，以及逐条列出的错误（表名 + 条目 + 原因）。无错误退出码 0，有错误退出码 1，可直接接进自己的打包脚本。编辑器内用 godot --path . -- --validate-theme <id>。
内置主题必须是 exe 旁边的散文件，不能打进 pck——外部贴图走文件系统读取，读不到 pck 内的资源。
十、已知边界
蚂蚁品级（生态位）硬性为 4 个，只能改名字、贴图与数值，不能增删。4 个位置分别是「弱 / 主力 / 强 / 远程」，狼群的幼狼/灰狼/头狼/黑狼正好对应。放宽它要同时改存档与跨屏网络协议，留待后续版本。
同理，主题不能新增成就的统计维度（统计由引擎产生），但可以复用现有维度改文案与目标值。
从模板开始
游戏内置两个包可以照抄：wolf_pack/ 是官方狼群主题，数值与文案已就绪，只改白名单内的列，所以不影响成就同步——推荐作为创作模板。verify/ 是框架验证包，覆盖了孵化间隔、三条蚁巢文案和染色后的苍蝇图集，用于跑通「数值 + 文案 + 美术」全链路（它改了孵化间隔，属于影响玩法，会暂停同步）。