dsh-hoi4-modding 1.1.2 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 1.2.0
+
+坦克设计器 + 3D 模型 + 图标流水线专题（来自一次 30 科技德国坦克树 / 16 槽设计器改造的真实工程，
+全部结论经游戏内对照验证）：
+
+- **新增** `references/tank-designer.md`
+  - 设计器文件地图：`interface/tank_designer_view.gui`（窗口 1091×542、`equipment_modules` 13/146 512×350、
+    9 个 `pos_custom_module_slot_window_*`）、`equipmentdesignerview.gui`（槽位按钮模板 **76×47**）、
+    每底盘蓝图 GUI（`equipment_designer_<底盘>` → archetype 回退）。
+  - 数据侧：槽位 = `module_slots` 书写顺序；模块类别由 `category =` 隐式创建；装备可自定义 `module_slots`。
+  - 16 槽布局（上 7 + 第二排 2 + 下 7，窗口不加高 542）完整坐标与取舍。
+  - **窗口背景固定尺寸坑**：`GFX_tank_designer_popup_bg` 是 1092×553 贴图，只改窗口 size 会让内容溢出；
+    给出“顶部原样 + 中间平铺 + 底部原样”生成加高 DDS 的配方。
+  - 隐藏升级区/自动按钮的安全做法（position 移出屏幕；`auto_upgrade_button` 可能被代码自动摆放）。
+- **新增** `references/tank-models-3d.md`
+  - 四层链路 `graphic_db` → `entity`（`.asset`）→ `pdxmesh`（`.gfx`）→ `.mesh/.anim/.dds`；
+  - 原版德国实体清单（`GER_iw/light/medium/heavy/super_heavy_armor_entity`）、特效节点
+    `barrel`/`left_tracks`/`right_tracks`/`left_exhaust`/`right_exhaust`；
+  - 复用原版 / 换贴图 / 自制 mesh 三条路线，导出器（Maya 官方、Blender 社区）与排错表。
+- **新增** `references/icon-dds-pipeline.md`
+  - 科技卡几何：183×84 卡、`Icon` 中心 x=74 → 内容右移 8px（左 20 / 右 4 / 上下 2，最大 149×73）；
+  - 去背（透明/白底/8px 棋盘格）、白色涂装保护规则（亮度≥235 且 relY<0.8）、批量别名表、卡片预览自检、踩坑表。
+- **新增脚本**
+  - `tank_designer_probe.py`：设计器体检（窗口/槽位位置/槽位模板/背景 DDS 尺寸/模块类别/底盘 archetype 槽数/隐藏元素）
+  - `tank_designer_layout.py`：从原版 GUI 生成自定义槽位布局（默认 16 槽紧凑版，支持 16-tall、背景 sprite 替换、dry-run）
+  - `tech_icon_import.py`：照片/矢量图 → 173×77 DDS（去背 + 安全区 + 183×84 卡片预览，可调尺寸/边距）
+- **文档补充**
+  - `references/tech-tree-ui.md` 新增：多根分支 gridbox（一个页面多个 `_tree`）、生成文件被外部改写导致
+    `Found no grid box` 的排查顺序；
+  - `references/cheatsheet.md` 新增 §16：坦克设计器 / 3D 模型 / 173×77 图标速查；
+  - SKILL.md 铁律 +2 条、配方索引 +3 行、排错表 +3 行、验收清单 +2 条。
+
 ## 1.1.2
 
 - 发布通道切换为 **npm Trusted Publishing (OIDC)**：`release.yml` 去掉 `NPM_TOKEN` 依赖，改用 OIDC 发布并生成 provenance；

package/README.md

@@ -41,6 +41,12 @@ npm: https://www.npmjs.com/package/dsh-hoi4-modding
 | `skills/hoi4-modding/scripts/tech_folder_available.py` | Migrate `technology_folders.available` from `has_country_flag` to `original_tag` (check/apply/revert) |
 | `skills/hoi4-modding/scripts/item_sprite_check.py` | Compare item template sizes with the actual item background sprite pixels ("small item looks big") |
 | `skills/hoi4-modding/scripts/errorlog_triage.py` | Triage `error.log`: tech tree / textures / scopes / unknown fields / localisation |
+| `skills/hoi4-modding/references/tank-designer.md` | Tank designer: window/slot position table, 16-slot layouts, module-slot data, taller-window background trap |
+| `skills/hoi4-modding/references/tank-models-3d.md` | Tank 3D models: `entity`/`pdxmesh`/`.mesh`/`.anim`/`.dds` chain, effect nodes, reuse/repaint/custom-mesh routes |
+| `skills/hoi4-modding/references/icon-dds-pipeline.md` | Tech icon pipeline: photo → 173×77 DDS, de-background, white-paint protection, safe margins, card preview |
+| `skills/hoi4-modding/scripts/tank_designer_probe.py` | Probe designer window, slot table, slot-entry size, module categories, chassis slot counts, background DDS size |
+| `skills/hoi4-modding/scripts/tank_designer_layout.py` | Generate a custom tank-designer slot layout (16-compact preset) into a mod |
+| `skills/hoi4-modding/scripts/tech_icon_import.py` | Photo/vector → 173×77 DDS: de-background, safe-area placement, 183×84 card preview |
 
 ## Requirements
 
@@ -104,7 +110,14 @@ dsh plugin --profile web add github:a1249070611/dsh-hoi4-modding
 刷新/重启后，技能出现在技能目录；直接说「做个 HOI4 mod」「加个国策树」「mod 报错了」即可触发，
 也可以显式说「加载 hoi4-modding 技能」。
 
-### 本次新增（1.1.0）
+### 本次新增（1.2.0）
+- `references/tank-designer.md`：坦克设计器（窗口 / `pos_custom_module_slot_window_N` 槽位位置表 / 底盘 `module_slots` / 模块类别 / 16 槽布局 / 加高窗口背景贴图坑 / 隐藏升级区与自动按钮）
+- `references/tank-models-3d.md`：坦克 3D 模型链路（`entity`→`pdxmesh`→`.mesh/.anim/.dds`、特效节点 `barrel`/`tracks`/`exhaust`、复用原版 / 换贴图 / 自制 mesh 三条路线）
+- `references/icon-dds-pipeline.md`：科技卡 173×77 图标流水线（去白底/棋盘格、白色涂装保护、安全区 20/4、183×84 卡片自检）
+- 新增 3 个脚本：`tank_designer_probe.py`（设计器体检）、`tank_designer_layout.py`（生成 16 槽布局）、`tech_icon_import.py`（照片→图标 DDS）
+- 科技树文档补充：多根分支 gridbox（一个页面多个 `_tree`）、生成文件被外部改写导致 `Found no grid box` 的排查
+
+### 1.1.0 新增（历史）
 - `references/tech-tree-ui.md`：科技树页面可用性 / 连线 / 大小框混排 / 拆页合并 / 三种调试手法（留痕法、对半分、对照探针）
 - 4 个新脚本：`tech_tree_audit.py`（科技页完整性审计）、`tech_folder_available.py`（旗帜判定→国家标签，批量修复整页无连线）、
   `item_sprite_check.py`（模板尺寸 vs 背景精灵像素，专治"小框显示成大框"）、`errorlog_triage.py`（error.log 分诊）

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-hoi4-modding",
-  "version": "1.1.2",
-  "description": "HOI4 1.19.3 modding skill bundle for DeepSeek Harness: create, edit, validate, install and debug Hearts of Iron IV mods (focus trees, events, decisions, ideas, characters, technologies, MIO, special projects, GUI, localisation, DDS) with bundled verifier/installer scripts; plus tech tree UI diagnostics (page availability, connection lines, big/small item layouts).",
+  "version": "1.2.0",
+  "description": "HOI4 1.19.3 modding skill bundle for DeepSeek Harness: create, edit, validate, install and debug Hearts of Iron IV mods (focus trees, events, decisions, ideas, characters, technologies, MIO, special projects, GUI, localisation, DDS) with bundled verifier/installer scripts; plus tech tree UI diagnostics and tank designer (module slots, 16-slot layouts, 3D models, tech icon pipeline).",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -52,7 +52,10 @@
     "hoi4",
     "hoi4-modding",
     "paradox",
-    "modding"
+    "modding",
+    "tank-designer",
+    "3d-models",
+    "icon-pipeline"
   ],
   "icon": "./icon.svg",
   "license": "MIT",

package/skills/hoi4-modding/INSTALL.md

@@ -8,7 +8,8 @@
 ```
 hoi4-modding/
 ├─ SKILL.md          # 必需：frontmatter 含 name、description
-├─ references/       # 可选：参考资料（本技能为 cheatsheet.md、deep-dive.md）
+├─ references/       # 可选：参考资料（本技能为 cheatsheet.md、deep-dive.md、tech-tree-ui.md、
+│                    #       tank-designer.md、tank-models-3d.md、icon-dds-pipeline.md）
 ├─ scripts/          # 可选：可执行工具（Python 3.10+，标准库；DDS 需 Pillow）
 └─ INSTALL.md        # 本文件
 ```

package/skills/hoi4-modding/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hoi4-modding
-description: 《钢铁雄心4》(Hearts of Iron IV, HOI4) 1.19.3 Mod 开发全流程技能：读游戏文件、新建 Mod、写国策/事件/决议/理念/角色/科技/州/MIO/特殊项目/scripted GUI、本地化与 DDS 图标、静态校验、安装启用、按 error.log 排错、发布创意工坊。Use whenever the user asks to create, edit, fix, validate, install, publish, or debug an HOI4 mod or asks about HOI4 scripting (scopes, effects, triggers, variables, focus trees, events, decisions, ideas, characters, MIO, special projects, GUI, localisation, DDS), even if they only say "做个国策树"/"加个事件"/"mod 报错了".
+description: 《钢铁雄心4》(Hearts of Iron IV, HOI4) 1.19.3 Mod 开发全流程技能：读游戏文件、新建 Mod、写国策/事件/决议/理念/角色/科技/州/MIO/特殊项目/scripted GUI、本地化与 DDS 图标、静态校验、安装启用、按 error.log 排错、发布创意工坊。Use whenever the user asks to create, edit, fix, validate, install, publish, or debug an HOI4 mod or asks about HOI4 scripting (scopes, effects, triggers, variables, focus trees, events, decisions, ideas, characters, MIO, special projects, GUI, localisation, DDS, tank designer/module slots/2D icons/3D models), even if they only say "做个国策树"/"加个事件"/"mod 报错了".
 whenToUse: 用户要做/改/修/校验/安装/发布 HOI4 Mod，或问 HOI4 脚本写法（scope/effect/trigger/变量/国策/事件/决议/理念/角色/MIO/特殊项目/GUI/本地化/DDS）时。
 ---
 
@@ -37,6 +37,8 @@ whenToUse: 用户要做/改/修/校验/安装/发布 HOI4 Mod，或问 HOI4 脚
     引擎建页画线时会对该触发器做二次运行时求值，旗帜判定失败时**整页连线被静默丢弃**（方框还在、日志干净、旧存档可能正常而新开档必现）。见 `references/tech-tree-ui.md` §3。
 14. **大框/小框混排是三件套**：科技加 `force_use_small_tech_layout = yes` + 页面有 `techtree_<folder>_small_item` 模板 +
     `GFX_technology_<folder>_small_*_item_bg` 精灵**指向真正的小图**。模板 size 只管排版，背景贴图按自身像素绘制——精灵还指着 203×84 大图时，画面就是"小框模板 + 大框外观 + 整体偏位"。
+15. **坦克设计器是全局 GUI**：改 `interface/tank_designer_view.gui` 会影响所有国家/底盘；窗口背景 `GFX_tank_designer_popup_bg` 是**固定 1092×553 贴图**，只加高窗口而不换背景 → 内容溢出到窗口外/地图上（见 `references/tank-designer.md` §4.3）。
+16. **槽位按钮位置 ≠ 槽位数据**：`pos_custom_module_slot_window_N` 决定按钮在界面上的位置，底盘 `module_slots` 的**书写顺序**决定第 N 个位置是哪一类槽；模块类别由模块的 `category =` 隐式创建（`references/tank-designer.md`）。
 
 ## 2. 标准工作流
 
@@ -71,6 +73,9 @@ whenToUse: 用户要做/改/修/校验/安装/发布 HOI4 Mod，或问 HOI4 脚
 | scripted GUI 面板（4 文件挂载） | §11 |
 | MIO / 特殊项目 | §12 |
 | 贴图、DDS、GFX 注册 | §13 |
+| **坦克设计器：16 槽布局 / 加高窗口 / 隐藏升级区 / 模块类别** | `references/tank-designer.md` |
+| **坦克 3D 模型：复用原版实体 / 换贴图 / 自制 mesh** | `references/tank-models-3d.md` |
+| **科技/装备图标：照片→173×77 DDS、去背、安全区** | `references/icon-dds-pipeline.md` |
 | 调试命令与 error.log 对照表 | §14 |
 | 1.19 与旧教程差异清单 | §15 |
 
@@ -106,6 +111,16 @@ $GAME = "E:\Steam\steamapps\common\Hearts of Iron IV"
 & python "$S\dds_helper.py" make icon.png out.dds --width 60 --height 68
 & python "$S\dds_helper.py" check out.dds
 
+# 坦克设计器体检（窗口/槽位位置/槽位模板/模块类别/底盘槽数/背景尺寸）
+& python "$S	ank_designer_probe.py" --game $GAME
+
+# 生成坦克设计器槽位布局（默认 16 槽紧凑版，写 mod/interface/tank_designer_view.gui；不修改游戏目录）
+& python "$S	ank_designer_layout.py" --mod "D:\mods\MyMod" --dry-run
+& python "$S	ank_designer_layout.py" --mod "D:\mods\MyMod"
+
+# 科技卡图标：照片/矢量图 → 173×77 DDS（去背 + 安全区 + 183×84 卡片预览）
+& python "$S	ech_icon_import.py" "虎式E型.png" out/GER_tiger_e.dds --card-preview preview.png
+
 # 科技页完整性审计（注册表 <-> 页面/页签/item 模板/网格/科技/本地化）
 & python "$S/tech_tree_audit.py" "D:/mods/MyMod"
 
@@ -138,6 +153,9 @@ $GAME = "E:\Steam\steamapps\common\Hearts of Iron IV"
 | `Unexpected token` | 括号/引号不平衡；`.mod` 字段拼错（如 `thumbnail`） | 跑 lint；检查 `picture=`/`path=` |
 | `Tried to get dynamic token` / `dynamic token ... OOS` | 本地化/脚本拼接 key 未注册 | 改用普通 loc key 或 `synchronized_dynamic_tokens` |
 | 图标空白/黑块 | GFX 未注册、texturefile 不存在、DDS 头不对 | `dds_helper.py check`；确认 sprite 在 `interface/*.gfx` |
+| 坦克设计器内容溢出窗口/跑到地图上 | 窗口加高但背景贴图固定 1092×553 | 用 `tank_designer_layout.py` 生成紧凑布局，或按 `references/tank-designer.md` §4.3 做加高背景 sprite |
+| 坦克设计器槽位数/位置不对 | 界面位置数 与 底盘 `module_slots` 数量/顺序不一致 | `tank_designer_probe.py` 打印两者后对比 |
+| 设计器槽位互相叠压/挤出容器 | 槽位模板宽 76px > 列距/容器宽 | 列距 ≥76 或加宽 `equipment_modules`（原版 73 列距本身叠 3px） |
 | 中文方框 | GUI 用了没有中文 `bitmapfont_override` 的字体名 | 换有中文覆盖的字体（见知识库 `05_presentation/chinese_fonts.md`） |
 | 国策树不显示 | 原版树分数更高；或树 id/坐标错误 | 按 §4 规则选「无专属树国家」或覆盖原树 |
 | 科技页**方框全在、连线一条没有**、日志干净 | `technology_folders.available` 用了 `has_country_flag`，建页画线阶段判定失败 → 整页 path 静默丢弃 | 改成 `original_tag = <TAG>`（`tech_folder_available.py`），**新开档**验证 |
@@ -155,6 +173,8 @@ $GAME = "E:\Steam\steamapps\common\Hearts of Iron IV"
 - [ ] 干净 playset 进游戏：新开档、触发全部内容、`error.log` 无自己文件的报错。
 - [ ] **新开档**逐个相关国家打开科技页确认连线（旧存档会掩盖 available 触发器的时机问题）。
 - [ ] `tech_tree_audit.py` 报告 0 问题；大小框混排页跑 `item_sprite_check.py` 无可疑项。
+- [ ] 坦克设计器：窗口背景覆盖整个窗口；槽位位置数 = 底盘 `module_slots` 数；槽位不叠压、能选模块并保存设计。
+- [ ] 坦克 3D：`graphic_db` 的 `models` 实体存在，`.asset` 至少 `idle/move/attack` 三个 state，贴图齐全。
 - [ ] 发布信息（name/supported_version/tags/picture/README/依赖 DLC）齐全；联机 checksum 一致。
 
 ## 7. 深度资料

package/skills/hoi4-modding/references/cheatsheet.md

@@ -555,3 +555,60 @@ spriteTypes = {
 - **理念**：支持 `on_add`/`on_remove`（旧教程说没有是错的）。
 - **文档滞后**：官方 `documentation/*.md` 不是全集（`unit_modifiers`、`is_fighting_in_strategic_region`、`is_deployed` 等未收录），冲突以游戏文件为准。
 - **路径**：`.mod` 的 `path` 建议纯 ASCII；`-debug_mode` 不是 `-debug`。
+
+
+## 16. 坦克设计器 / 3D 模型 / 图标（速查）
+
+### 16.1 坦克设计器文件
+
+| 文件 | 作用 |
+|---|---|
+| `interface/tank_designer_view.gui` | 窗口、`equipment_modules`（槽位容器）、`pos_custom_module_slot_window_N`（每个槽的坐标） |
+| `interface/equipmentdesignerview.gui` | 通用控件；`equipment_designer_module_slot_entry` 槽位按钮模板 = **76×47** |
+| `interface/equipmentdesigner/tanks/*.gui` | 每类底盘蓝图（`equipment_designer_<底盘>` / archetype 回退） |
+| `common/units/equipment/tank_chassis.txt` | archetype 的 `module_slots`；普通底盘 `module_slots = inherit` |
+| `common/units/equipment/modules/*.txt` | 模块；`category =` 隐式建类别 |
+| `gfx/interface/equipmentdesigner/graphic_db/*.txt` | `graphic_db = { GFX_2d_icon models = { ENTITY } }` |
+
+原版 9 槽顺序（= 数据 `module_slots` 顺序）：炮塔/主武器/悬挂/装甲/引擎/特殊1–4；
+界面位置 `pos_0..8` 由原版 GUI 决定，改槽数 = 加 `pos_custom_module_slot_window_N` + 底盘多写槽。
+
+### 16.2 16 槽紧凑布局（不加高窗口）
+
+```pdx
+@fixed_btn_mod_col_0 = 0
+...
+@fixed_btn_mod_col_6 = 432
+@fixed_btn_mod_row_0 = 0     # 上排 7
+@fixed_btn_mod_row_1 = 50    # 第二排 2（通信左 / 工程右）
+@fixed_btn_mod_row_2 = 300   # 下排 7
+```
+
+- 窗口高 542 不用加高；蓝图保持 `position {x=3 y=50} size 508×248`；
+- 隐藏 `equipment_upgrade_0/1`、auto 按钮：把 position 改成 `-4000/-4000`；
+- 槽位宽 76、列距 72（原版就是 73）→ 相邻叠 4px，视觉连成一排；要严格不叠压需加宽容器。
+
+### 16.3 3D 模型四层
+
+```
+graphic_db models = { ENTITY }
+  → gfx/entities/*.asset  entity = { name pdxmesh = ... state = {idle/move/attack} }
+  → gfx/entities/*.gfx    pdxmesh = { name file = "gfx/models/units/tanks/x.mesh" }
+  → gfx/models/units/tanks/*.mesh + *.anim + *_diffuse/_normal/_specular.dds
+```
+
+复用原版：`GER_iw_armor_entity` / `GER_light_armor_entity` / `GER_medium_armor_entity` /
+`GER_heavy_armor_entity` / `GER_super_heavy_armor_entity`。
+
+### 16.4 科技卡图标 173×77
+
+```
+Icon 控件中心 x=74（卡宽 183）→ 内容右移 8px：左留 20 / 右留 4 / 上下 2，最大内容 149×73
+```
+
+- 透明 PNG 最好；白底/棋盘格需要去背；**白色涂装保护**：区域亮度≥235 且 relY<0.8 → 保留；
+- 输出 raw32 DDS 173×77，sprite 名 `GFX_<tech>_medium`；
+- 批量导入必须有别名表（文件名≠科技 id 时）。
+
+对应脚本：`tank_designer_probe.py` / `tank_designer_layout.py` / `tech_icon_import.py`，
+专题文档 `references/tank-designer.md`、`references/tank-models-3d.md`、`references/icon-dds-pipeline.md`。

package/skills/hoi4-modding/references/icon-dds-pipeline.md

@@ -0,0 +1,123 @@
+# 科技/装备 2D 图标流水线：照片 → 173×77 DDS（实战）
+
+> 适用：把坦克照片/矢量图做成 HOI4 科技卡图标、装备 2D 图标；处理白底/棋盘格/阴影、保护白色涂装、
+> 解决“图标出框 / 偏左 / 白边 / 涂装被挖空”。
+> 本文是 `hist_tech_trees`（30 辆德国坦克科技）全套照片图标的量产经验。
+
+## 0. 关键结论（先看这 4 条）
+
+1. **科技卡图标画布 173×77**；卡片背景 183×84，卡内 `Icon` 控件是 `position {x=74 y=50}` + `centerposition`，
+   所以 **173 宽的图在 183 卡里左右各出 5px**：内容必须留安全边距，否则炮管/履带会被卡片边框裁掉。
+2. 原版照片/渲染图多数是**白底或 8px 棋盘格（纯白+灰 130/192）**，必须去背景；透明 PNG 最省事，优先找。
+3. **白色涂装/白色编号会被“去白底”算法一起挖掉**：保护规则 = 区域平均亮度 ≥235 **且** 相对位置偏上（relY<0.8）→ 保留。
+4. 批量导入必须有 **别名表**：文件名 ≠ 科技中文名（如 `四号坦克F型.png` → `GER_pz4_f1`、`38(t)A型`、`35(t)`）。
+
+## 1. 卡片几何：为什么图标要“右移”
+
+```pdx
+# countrytechtreeview.gui 的 item 模板（原版）
+containerWindowType = { name = "techtree_GER_armor_item" size = { width = 183 height = 84 }
+	iconType = { name = "Icon" position = { x = 74 y = 50 } centerposition = yes }
+	instantTextBoxType = { name = "Name" position = { x = 6 y = -1 } }
+	background = { spriteType = "GFX_technology_unavailable_item_bg" }  # 286×109
+}
+```
+
+- 卡片可见内容区约 **183×84**；`Icon` 的中心在卡片 x=74，而卡片中心是 91.5 → 图标整体天然偏左 17.5px。
+- 因此 **173×77 的图标内容**建议：
+  - 水平：左边距 **20px**、右边距 **4px**（内容整体右移 8px，把炮管/车身放在视觉中心）；
+  - 垂直：上下各留 **2px**，最大内容 **149×73**。
+- 具体数值可按立绘方向微调（炮口朝左的图可反过来），但**右侧不能顶满**，否则车头/炮口出框。
+
+## 2. 输入类型与去背景
+
+| 输入 | 处理 |
+|---|---|
+| 透明 PNG/WebP（矢量导出） | 直接用 alpha，最省事；裁 bbox → 缩放 → 贴到安全区 |
+| 纯白底 | 从边界 flood fill 去白（容差 ~12），保留内部白色（高光/白涂装） |
+| 8px 棋盘格（白 + 灰 130/192） | 先识别两种背景色，按“边界连通 + 颜色接近任一背景色”泛洪；再做 1px 腐蚀+描边 |
+| 阴影/渐变背景 | 难；优先找透明版，或 PS 手动抠图 |
+| 白底带白色涂装 | 用第 3 条保护规则，否则涂装会被挖空 |
+
+推荐流程：
+
+```
+1) 转 RGBA
+2) 估计背景色：取四条边上的高频中性色（R≈G≈B），最多取 2 个峰
+3) 从边界 flood fill：颜色接近任一背景色 → 透明
+4) 保护：连通的“白色区域”若 平均亮度≥235 且 中心 relY<0.8 → 保留（白涂装/编号）
+5) 其他内部洞（履带缝、观察窗）：用前景色填充或按最近深色覆盖
+6) 腐蚀 1px（去掉白边），边缘轻微重着色
+7) 预乘 alpha 下采样（避免灰边）
+8) 裁 bbox → 按最大 149×73 等比缩放 → 贴到 173×77 画布的安全位置（左 20/右 4/上下 2）
+9) 输出 PNG + DDS（dds_helper raw32 173×77）
+10) 合成 183×84 卡片预览，检查不越框
+```
+
+## 3. 别名与匹配
+
+批量导入时用**文件名模糊匹配** + 显式别名表：
+
+```python
+ALIASES = {
+    "四号坦克F型": "GER_pz4_f1",      # 早期 F1（短管）与后期 F2 区分
+    "38(t)A型":  "GER_pz38t_ad",
+    "35(t)":     "GER_pz35t",
+}
+```
+
+匹配顺序：`big_zh/big_en` 精确 → 小名（small_zh）精确 → 小名首词 → 唯一子串包含 → 别名表。
+**不要用“任意包含”直接命中**：`四号坦克F型` 会同时匹配 F1/F2/G/H，必须最先用别名表消歧。
+
+## 4. 输出与注册
+
+```bash
+python "$S/dds_helper.py" make GER_pz4_f1.png \
+  gfx/interface/technologies/GER_armor/GER_pz4_f1.dds --width 173 --height 77
+python "$S/dds_helper.py" check gfx/interface/technologies/GER_armor/GER_pz4_f1.dds
+```
+
+```pdx
+# interface/NS_tech_icons.gfx
+spriteTypes = {
+	spriteType = { name = "GFX_GER_pz4_f1_medium" texturefile = "gfx/interface/technologies/GER_armor/GER_pz4_f1.dds" }
+}
+```
+
+- 科技卡模板里图标 sprite 名按原版约定：`GFX_<tech>_medium`（`<tech>_small` 用于小框）；
+- **每张图 173×77，raw32 未压缩**（原版 UI 同构；体积约 53KB/张，30 张 1.6MB，可接受）；
+- 共享占位图标时只注册一张 sprite，多个科技共用。
+
+## 5. 卡片预览自检（不越框）
+
+```python
+CARD = Image.open(GAME / "gfx/interface/techtree/technology_available_item_bg.dds").convert("RGBA")
+card = CARD.resize((183, 84), Image.LANCZOS)
+icon = Image.open("GER_pz4_f1.png").convert("RGBA")
+card.alpha_composite(icon, (74 - icon.width // 2, 50 - icon.height // 2))
+card.save("preview_card.png")
+```
+
+检查点：炮管/车头不出框；左右留白均衡（视觉重心略右）；与同排其他卡片的车体大小一致（缩放按“车长”统一，
+不要按图片 bbox 高度统一，否则炮塔高低不一）。
+
+## 6. 踩坑表
+
+| 症状 | 原因 / 修法 |
+|---|---|
+| 图标左侧被裁 | 内容顶满 173 宽；加大 left margin（本项目用 20px） |
+| 图标整体偏左 | 没考虑 Icon 控件中心 x=74；内容整体右移 8px |
+| 白边/灰边 | 未腐蚀边缘；缩放前未预乘 alpha |
+| 白色涂装/编号被挖空 | 缺少白涂装保护规则（亮度≥235 + relY<0.8） |
+| 棋盘格残留 | 只按单色去背；需检测两种背景色并联合泛洪 |
+| 各卡大小不一 | 缩放基准不一致（按车长/统一系数，而不是 bbox 高） |
+| 导入后图标不显示 | sprite 没注册 / 路径大小写 / DDS 尺寸不对（必须 173×77 或模板要求尺寸） |
+| 装备图标显示错位 | 装备 2D 图标尺寸不同（原版 81×37 等），不要拿科技卡 173×77 混用 |
+
+## 7. 配套脚本
+
+`scripts/tech_icon_import.py`（需 Pillow）：
+- 单张/批量（目录或 JSON 映射）输入 → 去背（transparent / white / checker / auto）→ 安全区 173×77 →
+  PNG + DDS（调用 `dds_helper.py`）；
+- `--card-preview` 输出 183×84 合成卡，直接目检是否出框；
+- `--alias alias.json` 传文件名→科技 id 映射，批量时用于消歧。

package/skills/hoi4-modding/references/tank-designer.md

@@ -0,0 +1,215 @@
+# 坦克设计器（Tank Designer）内部结构与 16 槽自定义布局（HOI4 1.19.3/1.19.4 实战）
+
+> 适用：想改坦克设计器界面、增减模块槽、做"装备设计器"玩法、或排查"槽位不显示 / 重叠 / 窗口溢出"。
+> 全部结论来自 1.19.3 + Arms Against Tyranny、`gui_scale` 1.5@4K 实机对照（Black ICE Tech Tree 与本项目 16 槽改造）。
+
+## 0. 一句话
+
+坦克设计器 = **全局窗口 `interface/tank_designer_view.gui`（槽位按钮的位置表）** + **按底盘插入的蓝图 GUI
+`interface/equipmentdesigner/tanks/*.gui`（美术/挂点）** + **数据侧 `module_slots`（槽位数量与可装类别）** + **模块定义（`category` 隐式建类别）**。
+**槽位按钮显示哪些位置，由 `tank_designer_view.gui` 的 `pos_custom_module_slot_window_N` 数量决定；每个槽是哪一类，由底盘 `module_slots` 里的书写顺序决定（第 N 个槽 → 第 N 个位置）。**
+
+## 1. 文件地图
+
+| 文件 | 作用 |
+|---|---|
+| `interface/tank_designer_view.gui` | 设计器窗口：窗口尺寸、蓝图容器、**槽位位置表**、底部按钮（重置/保存/生产花费） |
+| `interface/equipmentdesignerview.gui` | 设计器通用控件；**`equipment_designer_module_slot_entry` 槽位按钮实例模板（76×47）**、模块选择弹窗 |
+| `interface/equipmentdesigner/tanks/*.gui` | 每类/每国底盘的 2D 蓝图与模块挂点（容器名 `equipment_designer_<底盘装备名>`，可回退到 archetype 名） |
+| `common/units/equipment/tank_chassis.txt` | 底盘装备；**archetype（`is_archetype=yes`）里定义 `module_slots` 白板槽位**，普通底盘多写 `module_slots = inherit` |
+| `common/units/equipment/modules/00_tank_modules.txt` | 模块定义；`category = xxx` **隐式创建模块类别**（无单独类别声明文件） |
+| `gfx/interface/equipmentdesigner/graphic_db/*.txt` | 底盘 → 2D 图标池 / 3D 模型池（`models = { ENTITY }`） |
+| `gfx/entities/tanks.gfx` / `units_tanks.asset` | 3D 用 `pdxmesh` / `entity`（见 `references/tank-models-3d.md`） |
+
+## 2. 窗口与关键控件（原版数值）
+
+```pdx
+# tank_designer_view.gui
+containerWindowType = { name = "tank_designer_view" size = { width = 1091 height = 542 } orientation = CENTER origo = center }
+  background = { spriteType = "GFX_tank_designer_popup_bg" }   # 贴图 tank_designer_popup_bg.dds，固定 1092×553
+  containerWindowType = { name = "equipment_modules" position = { x=13 y=146 } size = { width=512 height=350 }
+    containerWindowType = { name = "equipment_preview" position = { x=3 y=50 } size = { width=508 height=248 } }  # 代码在此插入蓝图 GUI
+    positionType = { name = "pos_custom_module_slot_window_0..8" }   # 9 个槽位按钮位置
+    containerWindowType = { name = "equipment_upgrade_0/1" ... }     # 引擎/装甲等级（不是模块槽）
+  }
+```
+
+- 槽位按钮实例 = `equipment_designer_module_slot_entry`，**尺寸 76×47**（由 `icn_module_slot_frame` 决定）；
+  所以列距必须 ≥76，否则按钮会叠压。原版列宏 `@fixed_btn_mod_col_0..6 = 1,74,147,220,293,366,439`（73 间距，**有一像素级叠压**）。
+- 行宏：`@fixed_btn_mod_row_0 = 1`、`@fixed_btn_mod_row_1 = 300`；`ypos_module_row_0` 只用于 tooltip 上下锚点。
+- 原版 9 槽映射（槽位序号 = `module_slots` 书写顺序）：
+
+| 序号 | 位置 | 原版常见槽 |
+|---|---|---|
+| 0,1 | 上排 col0,col1 | 炮塔、主武器 |
+| 2,3,4 | 下排 col0,col1,col2 | 悬挂、装甲、引擎 |
+| 5,6,7,8 | 上排 col2..col5 | 特殊模块 1–4 |
+| — | 上排 col6 + 末位 | 原版由代码追加“+”/自动升级圆钮，不占 `positionType` |
+
+## 3. 数据侧：槽位数与可装类别
+
+- 槽位名（如 `main_armament_slot` / `special_type_slot_1`）只是**键名**；真正约束来自
+  `allowed_module_categories = { ... }`（引用模块的 `category`）与 `required = yes/no`。
+- **模块类别不需要注册**：在 `modules/*.txt` 里写 `category = my_new_category`，再在槽位 `allowed_module_categories` 引用即可。
+- 一个装备的槽位数量 = 它（或其 archetype）的 `module_slots = { ... }` 条目数；
+  普通底盘写 `module_slots = inherit` 继承 archetype。
+- **装备可以自己写 `module_slots` 覆盖**（飞机 airframe 就是这么做的；坦克底盘实测也可行，
+  这是给不同坦克不同槽数的关键，无需改 archetype）。
+- 槽位数量上限由 **`tank_designer_view.gui` 里 `pos_custom_module_slot_window_N` 的个数**决定：
+  数据里第 k 个槽没有对应位置时，该槽不显示（表现为“少了几个槽”）。
+- 数量限制用 `module_count_limit = { category = tank_special_module count < N }`（防叠加），
+  单件上限如 `module = armor_skirts count < 1`。
+- `default_modules = { slot = module }` 只写在 **archetype** 上最稳；写在普通装备上是否生效随版本而定，先按“让玩家自己填”处理。
+
+## 4. 自定义槽位数：扩展位置表
+
+### 4.1 参考：Black ICE 的 23 槽
+`BlackIce_Tech_Tree/interface/tank_designer_view.gui`：
+
+- 17 个 `pos_fixed_module_slot_window_0..16`（固定显示槽：炮塔/主炮/弹药/同轴/车体MG/发动机/变速箱/齿轮箱/悬挂/装甲厚度/装甲设计/装甲分布/装甲结构/炮塔装甲结构/无线电/人机工效/工艺）；
+- 6 个 `pos_custom_module_slot_window_0..5`（特殊槽）；
+- 行宏扩到 5 行（`row_0=0,row_1=48,row_2=204,row_3=252,row_4=300`），按钮压着蓝图放。
+  → 结论：**位置名可自定义、数量可扩展**，代价是窗口变挤/蓝图被压。
+
+### 4.2 本项目采用的 16 槽紧凑布局（窗口高度不变 542）
+
+在 `equipment_modules`（512×350）内：
+
+| 排 | 位置 | 槽位 |
+|---|---|---|
+| 上排（y=0） | `pos_*_0..6`，col0..col6（72 步距，`@fixed_btn_mod_col_i = 72*i`） | 炮塔 / 主武器 / 弹药 / 副武器 / 发动机 / 传动 / 车体防护 |
+| 第二排（y=50） | `pos_*_7`（col0）、`pos_*_8`（col6） | 通信（左角）/ 工程（右角）——正好压在原蓝图标题行左右 |
+| 下排（y=300） | `pos_*_9..15`，col0..col6 | 炮塔防护 / 内部安全 / 瞄准 / 观察 / 附加防护 / 烟幕 / 续航（+ 若 7 个则加发动机等） |
+
+```pdx
+@fixed_btn_mod_col_0 = 0
+@fixed_btn_mod_col_1 = 72
+...
+@fixed_btn_mod_col_6 = 432
+@fixed_btn_mod_row_0 = 0
+@fixed_btn_mod_row_1 = 50
+@fixed_btn_mod_row_2 = 300
+
+positionType = { name = "ypos_module_row_0" position = { x=0 y=@fixed_btn_mod_row_0 } }
+positionType = { name = "pos_custom_module_slot_window_0" position = { x=@fixed_btn_mod_col_0 y=@fixed_btn_mod_row_0 } }
+...
+positionType = { name = "pos_custom_module_slot_window_7" position = { x=@fixed_btn_mod_col_0 y=@fixed_btn_mod_row_1 } }
+positionType = { name = "pos_custom_module_slot_window_8" position = { x=@fixed_btn_mod_col_6 y=@fixed_btn_mod_row_1 } }
+...
+positionType = { name = "pos_custom_module_slot_window_15" position = { x=@fixed_btn_mod_col_6 y=@fixed_btn_mod_row_2 } }
+```
+
+要点：
+- 蓝图容器保持原版 `position {x=3 y=50} size 508×248` 不动；第二排两个槽会叠在蓝图顶部两角（原版那一带只有标题文字，视觉可接受）。
+- 下排 y=300 正好落在原“悬挂/装甲/引擎 3 槽 + 空位 + 引擎/装甲等级区”，把 `equipment_upgrade_0/1` 移走即可整排利用。
+- 7 个槽 × 76px = 532px > 容器 512px：所以列距只能 72（相邻叠 4px，视觉连成一排）；要严格不叠压需把窗口/容器加宽，或缩小槽位模板。
+
+### 4.3 加高窗口的坑（必看）
+
+**窗口背景 `GFX_tank_designer_popup_bg` 是一张固定尺寸贴图（1092×553），不是九宫格**。
+只改 `tank_designer_view` 的 `size`，背景仍按原尺寸绘制 → 槽位/按钮会“溢到窗口外”，表现为：
+底部槽位/按钮出现在地图背景上、窗口看起来没变高。
+
+修法（二选一）：
+1. **不加高窗口**（推荐，改动最小）：用 §4.2 的紧凑布局，把槽位塞进原 512×350 区域。
+2. 确实要加高：在 mod 里生成一张更长的背景 DDS（例如把原图中段深色纹理纵向平铺到目标高度，保留顶/底边框），
+   注册新 sprite，再把窗口 `background` 换成它：
+
+```bash
+# 生成 1092×780（Pillow + 技能自带 dds_helper）
+python - <<'PY'
+from PIL import Image
+im = Image.open(r"<game>/gfx/interface/equipmentdesigner/tanks/tank_designer_popup_bg.dds").convert("RGBA")
+W, H = im.size
+top, bot = 380, 470            # 保留顶部 380 行、底部 83 行
+need = 780 - top - (H - bot)
+canvas = Image.new("RGBA", (W, 780))
+canvas.paste(im.crop((0, 0, W, top)), (0, 0))
+y = top
+while y < top + need:
+    take = min(bot - top, top + need - y)
+    canvas.paste(im.crop((0, top, W, top + take)), (0, y))
+    y += take
+canvas.paste(im.crop((0, bot, W, H)), (0, y))
+canvas.save("bg.png")
+PY
+python "$S/dds_helper.py" make bg.png gfx/interface/equipmentdesigner/tanks/NS_bg.dds --width 1092 --height 780
+```
+
+```pdx
+# interface/NS_designer.gfx
+spriteTypes = { spriteType = { name = "GFX_NS_tank_designer_bg" texturefile = "gfx/interface/equipmentdesigner/tanks/NS_bg.dds" } }
+```
+
+```pdx
+# tank_designer_view.gui：只改窗口背景引用 + 窗口高度
+background = { name = "Background" spriteType = "GFX_NS_tank_designer_bg" }
+size = { width = 1091 height = 780 }
+```
+
+> 背景贴图本身自带左右两栏分隔/米色数据区纹理，**加高时不要简单整图拉伸**（数据区/边框会变形），
+> 用“顶部原样 + 中间平铺 + 底部原样”的方式拼。
+
+## 5. 隐藏原版控件（升级区 / 自动按钮 / 悬浮图标）
+
+改窗口时经常需要清掉原版元素。统一做法：**保留控件本体，只把 position 移到屏幕外**（删元素可能被代码引用报错）。
+
+```python
+import re
+pat = re.compile(r'position\s*=\s*\{\s*x\s*=\s*-?\d+\s*y\s*=\s*-?\d+\s*\}')
+
+def hide(text, name):
+    i = text.find(f'name = "{name}"')
+    if i < 0: return text
+    m = pat.search(text, i)
+    return text[:m.start()] + "position = { x = -4000 y = -4000 }" + text[m.end():]
+```
+
+可安全隐藏：`equipment_upgrade_0/1`（引擎/装甲等级）、`niche_button`、`tag_icon_bg`、
+`auto_button`、`auto_upgraded_checkbox_button`、`save_to_file_button`、`historical_design_button`、
+`design_company_icon`、`design_team_button`、`upgrade_assigned_industrial_org`、`icon_selection_container`。
+
+> `auto_upgrade_button`（末位圆钮）有时由代码自动摆放，**改 position 可能无效**；真正要去掉需删元素，
+> 但这棵按钮与升级逻辑相关，删前先备份并在 error.log 确认没有 `auto_upgrade` 相关报错。
+
+底部栏元素在窗口加高后一起下移（示例 +218）：
+`reset_button`、`duplicate_button`、`save_button`、`experience_bg`、`experience`、`resources_bg`、
+`production_resources`、`refit_cost`、`production_value`。
+
+## 6. 蓝图 2D GUI 与“设计器容器选择”
+
+- 代码把**底盘对应的 2D 蓝图容器**插入 `equipment_preview`。容器名匹配顺序：
+  `equipment_designer_<底盘装备 id>` → 回退 `equipment_designer_<archetype>`（原版有 253 个这样的文件/容器）。
+- 蓝图 GUI 里的小图标（`main_armament_slot`、`suspension_type_slot`…）只是**美术挂点/highlight**，
+  与 `tank_designer_view.gui` 的槽位按钮是两套东西；槽位名改掉后这些挂点对不上只是“蓝图不再高亮”，不报错。
+- 想让某个底盘有专属蓝图布局：新建 `interface/equipmentdesigner/tanks/NS_<chassis>.gui`，
+  容器名 `equipment_designer_<chassis>`，内部尺寸对齐 `508×248`。
+
+## 7. 验收清单（设计器相关）
+
+- [ ] `tank_designer_view.gui` 括号配平（`{`/`}` 数量相等），元素名唯一；
+- [ ] 槽位按钮不重叠、不越出 `equipment_modules` 区域（槽宽 76：列距 ≥76 或接受 4px 叠压）；
+- [ ] 数据侧 `module_slots` 条目数 = 位置数（多出的不显示，少的不占位）；
+- [ ] 所有 `allowed_module_categories` 引用的 `category` 都能在某个模块文件里找到；
+- [ ] 进游戏开设计器：窗口不破图、无报错；槽位能点开、能选模块、能保存设计；
+- [ ] `logs/error.log` 无 `gui` / `tank_designer_view` / `module` 相关新错误；
+- [ ] 旧存档/新开档都试一次（GUI 改动通常与新开档无关，但设计数据可能受影响）。
+
+## 8. 症状 → 故障点
+
+| 症状 | 最可能原因 |
+|---|---|
+| 改了窗口高度，内容溢出到窗口外/地图上 | 背景贴图固定尺寸（§4.3） |
+| 槽位少显示 | `pos_custom_module_slot_window_N` 数量 < 数据槽数 |
+| 槽位重叠/挤压 | 槽位模板 76px > 列距；容器宽度不足 |
+| 窗口里出现原版的“+”/圆钮/等级区 | 未隐藏对应控件（§5） |
+| 设计器打不开/空白 | GUI 语法错、缺少代码必需控件（不要删窗口/统计/3D 相关元素） |
+| 新槽位点开无模块 | `allowed_module_categories` 里的类别没有任何模块，或模块没被科技解锁 |
+| “设计无效”无法保存 | 必选槽（`required = yes`）为空，或有冲突的 `module_count_limit` |
+
+## 9. 配套脚本
+
+- `scripts/tank_designer_probe.py`：读游戏文件，打印窗口尺寸、槽位位置表、槽位模板尺寸、模块类别、
+  底盘 archetype 槽数、背景贴图尺寸（排错第一步）。
+- `scripts/tank_designer_layout.py`：从原版 GUI 生成自定义槽位布局（默认本项目 16 槽紧凑版），
+  可隐藏升级区/自动按钮，输出到 mod；支持 `--dry-run` 只打印将要改的坐标。