Civ6 Asset Forge

🧰 工具先查名录（硬性）：要写脚本做某件事之前，先看本 skill 的 TOOLS.md —— 本 skill 全部脚本的用途 / 用法 / 路径清单，外加本机路径收纳表。 有能用的就改它，不要重建。 新增或改名脚本后，跑一次 python "<skills>/civ6-modding/tools/skill_manifest.py" civ6-asset-forge 刷新名录（--check 可做漂移检测）。

本 skill 由 4 个美术素材合成类 skill 合并而来（civ6-loyalty-icon / civ6-promotion-icon / civ6-governor-art / civ6-leader-2d），来源与各自最后 commit 见 CHANGELOG.md； 2026-09-17 新增第 ⑤ 类（UI 领袖立绘 / Suk 选人界面背景，reference/ui-leader-portrait.md） 与第 ⑥ 类（历史时刻插画，reference/moment-illustration.md）； 2026-09-17/18 类别③ 单位晋升图标的生成管线按用户裁决作废（失败尝试的遗留，已删除）， 只保留尺寸/格式规格 reference/promotion-icon-sizes.md（清单见 CHANGELOG.md）。 骨架共用：给定 PNG → 确定性合成器（Python/Pillow）→ 原版风格素材 → 注册链 → 校验器； 注册链逻辑只在本文件维护一份，类别专属实测规格（尺寸/坐标/配色/像素参数）逐字保留在 reference/*.md。

一、本 skill 覆盖的五类素材（边界先读）

⚠ 已作废：原类别③ 单位晋升图标（promotion icon）。 其生成管线（盾形模板 + 白剪影合成器 / 四色重着色 / 图集切格 / IoU 校验 / 生图模板与提示词手册）是失败尝试的遗留，已按用户裁决作废并删除； 本 skill 只保留尺寸与格式事实：reference/promotion-icon-sizes.md。不要再照旧文档做图。

三条最容易踩的混用：

1. 总督 24px 徽章是八边形（上下切角），单位晋升是五边形盾形——两者规格、配色、图集完全是两套，禁止互相套用（详见 reference/governor-art/specs.md §2.3「与单位晋升的区别」、reference/governor-art.md「边界」节，与 reference/promotion-icon-sizes.md 的盾形轮廓表）。
2. 「晋升」一词要分清：单位晋升（原类别③，生成管线已作废、仅存尺寸规格）与总督晋升徽章（类别①，现行管线）不是同一件事。
3. 「领袖立绘」要分清：类别④是给 3D 引擎当纸片人的 _TEXTURE/_OPACITY（走 Leaders.artdef）；类别⑤是给 Suk 这类 2D 选人界面用的 SUK_UI_* UI 贴图（走 UITexture XLP）。两者同名前缀 FALLBACK_NEUTRAL_* 但类别不同，详见 reference/ui-leader-portrait.md §4.4。

范围外的相邻任务：png→dds/.tex 转换与素材导入 → civ6-modding 的 art-pipeline.md； 原版素材引用链查询/克隆（ArtDef/XLP 四层引用、cook 层排查）→ civ6-art-reference。

二、任务 → 类别路由

路由判定三条：

1. 先判对象：总督 / 文明忠诚度 / 宗教 / 单位晋升 / 领袖（3D 纸片人）/ 领袖（UI 立绘）/ 历史时刻——"宗教"并入类别②（与忠诚度同一套引擎机制，仅命名映射与 artdef 目标集合不同）；"历史时刻"独立成类（走 MomentIllustrations 数据表 + UI/PrideMoments 贴图包，机制与其它四类都不同）。
2. 再判产出层级：只要 PNG 素材（合成层）还是连注册链（注册层）一起做。注册层逻辑五类共用（第六节），差别只在声明层文件名与目标集合。
3. 素材与注册链都要时：先出 PNG 交用户审核，审核通过后才做 DDS/.tex 与注册链（第七节）。

2.1 类别⑤ 的触发判定（先说清再动手）

用户提到 Suk / 选人界面相关词时，先判定关联性再决定走哪条：

判定为类别⑤ 后，先按第三节询问素材来源（复用工程既有立绘+外交背景 / 用户提供），再动手。 完整规格、类别陷阱与验证顺序见 reference/ui-leader-portrait.md。

2.2 类别⑥ 的触发判定与素材询问

判定为类别⑥ 后，询问模板与源图：

历史时刻插画需要官方形状模板套版（否则 UI 里卡片形状不对）。

• 模板：已随 skill 内置 templates/moment_illustration/1..18.psd （18 张官方形状；4.psd 是空的工作稿会自动跳过）——脚本默认就取这一份，无需再传路径。 要换成自己的模板时给 --template-dir（或写 local_paths.json 的 moment_template_dir）。
• 源图：每张成品插画的原图（PNG/PSD 导出均可，任意尺寸，脚本会缩放到 456×332）。 请给出目录或文件列表。
• 模板选择：指定编号（--template N）或让脚本按源图长宽比自动挑（--auto）。

⚠ 模板目录探测链：内置 templates/moment_illustration/ → local_paths.json: moment_template_dir → 作者机历史默认值 → 当前工作目录的 模板/历史图片模板（新）/；全都没有才报错。 若用户想自造蒙版，不要凭猜——先看清内置模板的图层语义 （python scripts/psd_inspect.py templates/moment_illustration --pick 1,4,18：哪个是形状遮罩、哪个是描边）， 再决定套哪一号模板。

三、铁律一：处理用户素材前必须先询问（五类共用）

开始任何一类素材任务前，必须先询问用户是否提供素材，得到答复后再动手。默认只生成注册文件/注册链，不主动生成、不擅自处理素材。

• 询问必须包含：格式要求、尺寸要求、自动兜底方案、输出目录四项，并给出「已有素材 / 暂无素材」两个选项。
• 每类的询问模板与素材要求（逐字原文）在对应 reference 文件里，照用不要自己改写尺寸：

• 用户坚持用自己提供的模板/素材时，一律按其提供的路径走参数（如 --glow、--icon、--avatar、--input），不要替换成内置模板。
• 交付物中必须写明实际用了哪个素材文件（含自动兜底时选中的源文件路径）。

四、铁律二：不静默备份

不静默备份。有 git 走 git；仅在用户明确要求时才另存副本。

• 不做 *.bak_*、不做时间戳目录、不做"先拷一份再改"。
• 破坏性改动（覆盖/重写 Art.xml、*.civ6proj、artdef、xlp）前，先确认工程工作区已 commit，把历史交给 git。
• 可再生中间产物（合成图、临时 manifest/asset_map.json）用完即删，不留存。

五、铁律三：原版素材来源（只读 pantry，禁止解包）

（原为类别① 总督 与 类别③ 单位晋升 共用的强制约定；③ 的生成管线已作废、原文不再保留，现仅类别① 适用）

• 美术素材只允许在 F:\Steam\steamapps\common\Sid Meier's Civilization VI SDK Assets 内查找（各类 pantry 子路径见对应 reference）。
• 任何情况下不允许解包（.blp 等打包文件不碰、不写解包器）；需要原版图就用 pantry 散装 DDS，用 civ6-modding 的 texconv 做纯格式转换 （随包内置 civ6-modding/art/bin/texconv.exe，定位真源 art/_texconv.py：TEXCONV → 内置 → PATH → WinGet Links；探测链说明见 civ6-modding/art/bin/README.md）。
• 游戏安装目录只读 XML/Lua 数据定义，不作素材来源。
• 交付产物一律写到用户指定目录；不修改游戏文件。

六、注册链总览（五类共用链条）

用户/合成器产出 PNG（512/256/128/1024/24/32/64/206×208/326×339/内容定宽×1024 等）
        │  ① 审核通过后才进入下一步
        ▼
   DDS + .tex（civ6-modding art-pipeline：convert_art.ps1 / gen_tex.py；role 按类别选）
        │
        ▼
   声明层：xlp（条目包） + artdef（集合/槽位） + mtl（材质→贴图） + ast（行为资产）
        │
        ▼
   工程接线：*.Art.xml（artConsumers / gameLibraries / requiredGameArtIDs）
        │
        ▼
   打包清单：*.civ6proj 幂等补注册（Content Include；类别⑤ 另需 FrontEndAction + Criteria）
        │
        ▼
   ModBuddy 构建 → 进游戏开一局验证

6.1 五类的声明层落点

原类别③ 单位晋升图标的声明层落点已随管线作废移出本节；仅存的事实值 （IconTextureAtlases IconSize="32" + Icons_Promotions.xml 的 ICON_<UnitPromotionType> 行） 见 reference/promotion-icon-sizes.md §六。

类别②「宗教分支」与忠诚度同一套引擎机制（同两个 XLP 包 + 同两个 artdef + 同一套官方几何/贴图类别约束），差别仅在命名映射与 artdef 目标集合（ReligionLensIcons / ReligionLensArrows 同名元素合并追加）。细节见 reference/loyalty-icon.md 第八节。

6.2 工程接线的五条共用规则

1. Materials/、Assets/、Textures/、Geometries/、LightRigs/、EnvironmentLights/ 构建时自动扫描编译进 Platforms\Windows\BLPs\*.blp，不需要写进 *.civ6proj 清单。
2. XLP / ArtDef 的构建接入点：.civ6proj 的 <Content> 条目不是必需 —— 实测可运行工程（示例工程）的 .civ6proj 里 .artdef / .xlp 条目为 0，而其构建产物 .modinfo 自动收进全部 .artdef（.xlp 属 cook 输入，不进产物）。真正必须的是第 3 条的 .Art.xml。历史脚本（gen_loyalty_art.py / gen_religion_art.py）会幂等补写 Content 条目，属可选冗余、写了不报错；civ6proj 可能有多个 ItemGroup，脚本统一插到最后一个 </Content> 之后，重复运行不产生重复条目。
3. Art.xml 与 artdef/xlp 必须同步：新增/修改 XLPs\、ArtDefs\ 之后必须重新生成 .Art.xml——用 python <civ6-modding skill>\art\gen_modartxml.py <projectRoot> --check，人工确认差异后加 --write（脚本按工程实存文件重算 artConsumers / gameLibraries / requiredGameArtIDs，优于手工补引用）。
4. 已存在的 artdef 不整体覆盖：走脚本的幂等合并；脚本找不到锚点时必须报"请手动合并"，不静默跳过（防止覆盖工程里其他功能条目）。
5. .tex 类别是硬约束：类别写错时 cooker 报 has class: 'X', but is bound to parameter: 'Y' which does not accept this class，且错误会沿"材质 → 资产 → XLP 条目"逐级传播、XLP cook 仍显示 "completed with success" 但条目已被替换成 error asset——不能当成功处理。各类正确类别见参考模板：
   • 3D 镜头贴图（忠诚度/宗教 *_Overlay_* / *_Pressure_*）→ Generic_BaseColor（m_Tags 留空）
   • 战略视图 sprite → StrategicView_Sprite（m_Tags 三连 StrategicView_Sprite / StrategicView / Sprite）
   • 带 alpha 的贴图 → PF_R8G8B8A8_UNORM + bUseMips=false（texconv 必须带 -m 1）；OPACITY 用单通道 PF_R8_UNORM
   • gen_tex.py 默认把 m_ClassName 写成 UserInterface，出 .tex 后必须手工改类别，可直接照抄 templates/ 下的对应模板字段顺序
   • UI 立绘 / 选人界面贴图 → UserInterface（m_Tags 单条 UserInterface）。 ★ 命名空间铁律：第三方界面适配素材不得借用官方模板前缀 （FALLBACK_ = 官方 3D 回退 = Leader_Fallback，LEADER_/ICON_ 同理）， 一律走 <适配对象短名>_UI_<KIND>_<KEY>——Suk 选人界面适配＝SUK_UI_* （立绘 SUK_UI_PORTRAIT_{KEY} / 背景 SUK_UI_BACKGROUND_{KEY}）。 Players.Portrait 是自由字符串列，贴图名无格式要求，所以改名无技术约束。 旧命名（FALLBACK_NEUTRAL_{X}_Suk）迁移：scripts/migrate_suk_namespace.py <工程根> --write。 详见 reference/ui-leader-portrait.md §4.4

6.3 素材搬运边界（避免污染工程 pantry）

• 不要为导入而把源 PNG 复制进工程（.assets / Textures）：.tex 的 SourceFilePath 只在 AssetEditor 重新导入时用得到，构建/游戏只读同名 DDS，导入后删除源 PNG 不影响任何东西。
• manifest / asset_map.json 等临时工作文件用完即删。
• 素材（fgx/wig/环境光 dds/立绘 png）由用户提供时，复制后必须做哈希校验并在交付说明中列出结果。

七、通用验证顺序与校验脚本

五类共用同一顺序，缺一不可：

1. 合成后立刻跑本类的本地校验脚本（数值判据，不依赖模型）：

2. 视觉评审 / 人眼验收：与原版对照检查轮廓、描边、高光、渐变、图形对比度。
   • 视觉评审不可用（模型侧 429 / 配额耗尽）时不要反复重试，改用本地像素度量 + 输出棋盘底预览图（--checker / _preview.png）给人眼验收。
3. 数值不达标时回退参数/模板（改 --keep、--feather 等类别参数重生成），不要手工修图。
4. 审核通过后才做 DDS/.tex（滞后步骤，走 civ6-modding art-pipeline；role 与 .tex 类别按第六节 6.2 第 5 条）。 ⚠ .tex 类别是本 skill 最大的静默坑（类别与所绑 XLP 参数不匹配 → cooker 仍报 success，条目被换成 error asset）： 交付前必须跑一遍 civ6-modding 的类别校验器 python <civ6-modding>/art/verify_tex_class.py --project <工程根>（可加 --full 遍历全部 UITexture 包）—— 这是家族内唯一能机械拦住该类别的校验器；本 skill 的类别①~⑥ 校验表都不覆盖 .tex 类别。
5. 工程构建 + 进游戏开一局验证（3D 六边形/战略视图/图集实际显示）。
6. 上传/交付：审核未通过前不得生成 DDS/.tex，不得提交 git。

常见"静默失败"：名字打错、引用名与定义名不逐字符一致时，游戏与 cooker 都不报错，只是图标不显示。凡是 artdef 元素名 / XLP 条目名 / ArtDefReferenceValue 引用名，都必须逐字符核对（各类坑位清单见对应 reference）。

八、目录结构与本 skill 内文件归属

civ6-asset-forge/
├─ SKILL.md              ← 本文件：路由 + 五类共用链条（只写一份）
├─ CHANGELOG.md          ← 合并来源、各原仓库最后 commit、引用修正清单
├─ reference/
│   ├─ loyalty-icon.md          ← 类别② 全部类别专属内容（逐字）
│   ├─ promotion-icon-sizes.md  ← 原类别③：**仅尺寸/格式规格**（生成管线已作废）
│   ├─ governor-art.md          ← 类别①
│   ├─ leader-2d.md             ← 类别④
│   ├─ ui-leader-portrait.md    ← 类别⑤（Suk 选人界面适配）
│   ├─ moment-illustration.md   ← 类别⑥（历史时刻插画）
│   └─ governor-art/     ← 原 governor 的 specs.md / inventory.md / palette.json（实测规格、素材清单、配色）
├─ scripts/              ← 五类脚本合并（原 18 个，③ 的 5 个已随管线删除）
├─ templates/            ← 模板合集：loyalty_chain/、religion_chain/、**moment_illustration/（18 张官方形状 PSD + README）**、
│                            领袖模板 + 光晕模板（⑤ 无需模板）
└─ assets/               ← 素材合并（**仅总督官方对照图**：`TEMPLATE_badge24_canonical.png` / `_x16.png`、
                            `REF_official_promotions24_x6.png`；晋升模板/剪影样例已随管线删除；⑤⑥ 无需素材）

templates/ 与 scripts/ 必须保持同级：process_loyalty_icon.py（默认光晕模板 templates/Loyalty_Overlay_Template.png）、 gen_leader_2d.py、process_leader_png.py 都按 scripts/../templates 定位模板。 类别⑤ 两个脚本按 scripts/../../civ6-modding/art/dds_io.py 复用 DDS 读写（单一真源）。

九、交付要求（五类共用）

• 交付说明必须包含：生成文件清单（含尺寸/输出目录）、注册链文件清单、Art.xml / *.civ6proj 改动说明、"待用户审核 / 待 tex+dds / 待用户提供素材"清单。
• 素材相关一律标注"待用户处理"，除非用户明确要求代处理。
• 素材未提供时，明确标注实际使用了哪个文件作为源（含自动兜底选中的源文件路径）。
• 处理过立绘/头像时，列出生成的 PNG 尺寸、.tex 更新结果、DDS 生成结果（或明确提示未生成）。
• 不静默备份（第四节）：交付物里不应出现任何 *.bak_* / 时间戳副本 / copy_*。

作者与致谢

• 整理人：千与千寻瀑
• 随包素材/模板：18 张历史时刻形状 PSD（由原版时刻插画轮廓整理）、总督官方对照图 —— 社区与官方素材的整理成果； 本 skill 的管线、工作流与实测规格为整理人所作
• texconv（PNG→DDS）来自 microsoft/DirectXTex（MIT，随包内置在 civ6-modding/art/bin/）
• 致谢：优妮