# HOI4 Mod-Maker Skill 完整示例文档

**版本**: 7.1  
**更新时间**: 2026-04-25 13:15 (Asia/Shanghai)

---

## 📚 文档导航

本 Skill 包含完整的 HOI4 modding 文档和示例，帮助你从零开始创建完整的 mod。

### 🎓 学习路径

```
1. SKILL.md → 语法速查表 + 整体概览
   ↓
2. examples/01_focus_tree_annotated.md → 国策树详解
   ↓
3. examples/02_ideas_annotated.md → Ideas系统详解
   ↓
4. examples/03_events_annotated.md → 事件系统详解
   ↓
5. examples/04_localisation_annotated.md → 本地化详解
   ↓
6. examples/05_decisions_annotated.md → 决议系统详解
   ↓
7. examples/06_characters_annotated.md → 人物系统详解
   ↓
8. examples/07_leader_traits_annotated.md → 领导人特质详解
   ↓
9. examples/08_importing_ideas_annotated.md → 民族精神导入详解
   ↓
10. examples/09_focus_tree_design_guide.md → 国策树规划设计 ← 新增
   ↓
11. examples/complete_tutorial.md → 完整实战案例
```

---

## 📂 文件结构

```
hoi4-mod-maker/
│
├── SKILL.md                              # 主入口 + Meta + 使用场景
│   ├── Skill Meta（版本/能力/场景表）
│   ├── 快速开始
│   ├── 代码规范
│   ├── 国策树指南
│   ├── 民族精神
│   ├── 本地化
│   ├── 事件
│   ├── 决议
│   ├── 变量与动态修饰符
│   ├── 调试技巧
│   └── 常用模板
│
├── references/                            # 参考文档
│   ├── focus_syntax_complete.md         # 国策树完整语法（17.2 KB）
│   ├── advanced_syntax.md               # 高级语法特性（15.8 KB）
│   ├── syntax.md                        # 形式化语法 + BNF + 11个陷阱（25.7 KB）
│   ├── dictionary.md                    # 效果/触发器字典 169+79（18.9 KB）
│   ├── ideas_syntax.md                  # Ideas完整语法（13.8 KB）
│   ├── localisation_guide.md            # 本地化指南（8.6 KB）
│   ├── events_guide.md                  # 事件系统参考（12.0 KB）
│   ├── dynamic_modifiers.md             # 动态修正语法
│   ├── scripted_effects.md              # 脚本效果语法
│   ├── scripted_triggers.md             # 脚本触发器语法
│   ├── quick_reference.md               # 快速参考卡片（新增）
│   └── vanilla_focus_trees/             # 原版国策树参考库
│       ├── README.md                    # 索引表（74个国家分类索引）
│       ├── germany.txt                  # 德国 (german_focus, 437焦点)
│       ├── soviet.txt                   # 苏联 (soviet_focus, 311焦点)
│       ├── japan.txt                    # 日本 (japan_wtt_focus, 450焦点)
│       ├── italy.txt                    # 意大利 (italian_focus, 314焦点)
│       ├── usa.txt                      # 美国
│       ├── uk.txt                       # 英国
│       ├── france.txt                   # 法国
│       ├── poland.txt                   # 波兰
│       ├── spain.txt                    # 西班牙
│       ├── generic.txt                  # 通用树
│       └── ... (共74个文件)
│
└── examples/                             # 详细示例（带注释）
    ├── 01_focus_tree_annotated.md       # 国策树详解（16.9 KB）
    ├── 02_ideas_annotated.md            # Ideas详解（22.5 KB）
    ├── 03_events_annotated.md           # 事件详解（14.0 KB）
    ├── 04_localisation_annotated.md     # 本地化详解（8.3 KB）
    ├── 05_decisions_annotated.md        # 决议详解（13.3 KB）
    ├── 06_characters_annotated.md       # 人物系统详解（13.0 KB）
    ├── 07_leader_traits_annotated.md    # 领导人特质详解（15.2 KB）
    ├── 08_importing_ideas_annotated.md  # 民族精神导入详解（12.3 KB）
    ├── 09_focus_tree_design_guide.md   # 国策树规划设计指南（60+ KB）
    ├── complete_tutorial.md             # 完整mod教程（17.7 KB）
    ├── complete_mod_example.md          # 完整mod示例（13.3 KB）
    ├── focus_real_examples.md           # 真实国策示例（16.6 KB）
    ├── ideas_real_examples.md           # 真实Ideas示例（13.5 KB）
    ├── events_real_examples.md          # 真实事件示例（13.0 KB）
    └── snippet_library.md               # 代码片段库（新增）

└── tools/                                # 工具和脚本（新增）
    └── validator.md                     # 验证检查清单
```

**总计**: 约 **400+ KB**，**109 文件**（含74个原版国策树 + 11个参考文档 + 16个注释示例 + 2个工具文档）

---

## 📖 各文档内容概览

### 1. 主文档 (SKILL.md)

**适合**: 所有用户（必读）

**包含**:
- ✅ 快速开始指南
- ✅ 完整代码规范
- ✅ 所有系统的基础语法
- ✅ 调试技巧和控制台命令
- ✅ 常用模板（可直接复制使用）

**特色**:
- 语法速查表
- 文件结构说明
- 编码规范
- 最佳实践建议

---

### 2. 国策树详解 (01_focus_tree_annotated.md)

**适合**: 想深入理解国策系统的用户

**包含**:
- ✅ 6个真实游戏示例（法国、日本、意大利、苏联、德国、Generic）
- ✅ 每个字段的详细注释
- ✅ 高级特性：内圈焦点、快捷方式、连续焦点
- ✅ 条件偏移、建筑建造、变量追踪
- ✅ UI优化技巧

**特色**:
- 所有示例均来自游戏本体
- 每个示例都有详细注释
- 包含复杂逻辑的实现方法

**示例列表**:
1. 基础国策结构（法国）
2. 条件建筑建造（法国）
3. 条件偏移（意大利）
4. 复杂快捷方式（日本）
5. 连续焦点（Generic）
6. 内圈焦点（德国）

---

### 3. Ideas详解 (02_ideas_annotated.md)

**适合**: 想创建民族精神、顾问、设计商的用户

**包含**:
- ✅ 6个真实游戏示例（法国、海军精神、陆军精神、政治顾问、理论家、设计商）
- ✅ 所有字段详细说明
- ✅ allowed、visible、available的区别
- ✅ 内战处理规则
- ✅ AI权重配置

**特色**:
- 涵盖所有ideas类型
- 详细的条件逻辑说明
- 完整的本地化示例

**示例列表**:
1. 国家精神基础（法国）
2. 海军学院精神
3. 陆军学院精神
4. 政治顾问
5. 理论家
6. 设计商

---

### 4. 事件详解 (03_events_annotated.md)

**适合**: 想创建复杂事件链的用户

**包含**:
- ✅ 8个真实游戏示例（波兰、Generic）
- ✅ 多描述文本实现
- ✅ 条件选项、事件链
- ✅ MTTH计算、省份事件
- ✅ 变量使用技巧

**特色**:
- 复杂事件逻辑的实现方法
- 效果预览技术
- 事件链设计模式

**示例列表**:
1. 基础国家事件（波兰）
2. 复杂选项逻辑（波兰）
3. 条件执行效果（波兰）
4. 多描述文本事件（Generic）
5. MTTH事件
6. 省份事件
7. 新闻事件
8. 带变量事件

---

### 5. 本地化详解 (04_localisation_annotated.md)

**适合**: 需要创建多语言支持的用户

**包含**:
- ✅ 完整的YML格式说明
- ✅ 所有颜色代码
- ✅ 图标代码
- ✅ 变量插值方法
- ✅ 中文本地化技巧

**特色**:
- 快速参考表（颜色、图标）
- 常见错误和解决方法
- 文件组织最佳实践

---

### 6. 决议详解 (05_decisions_annotated.md)

**适合**: 想创建动态决议系统的用户

**包含**:
- ✅ 6个完整示例
- ✅ 省份决议、外交决议
- ✅ 可升级决议系统
- ✅ 超时机制
- ✅ AI权重配置

**特色**:
- 多种决议类型的实现
- 状态管理技巧
- 完整的本地化支持

---

### 7. 人物系统详解 (06_characters_annotated.md)

**适合**: 想创建自定义领导人和将领的用户

**包含**:
- ✅ 8个真实游戏示例（波兰、德国）
- ✅ 国家领导人定义
- ✅ 军事指挥官（军级、元帅级）
- ✅ 海军指挥官
- ✅ 顾问系统
- ✅ 头像系统
- ✅ 性别支持
- ✅ 条件可见性
- ✅ 多角色支持
- ✅ 在效果中设置领导人

**特色**:
- 一人可担任多个角色
- DLC锁定、国策解锁的条件控制
- 完整的头像系统（大头像、小头像）

**示例列表**:
1. 国家领导人（波兰）
2. 军级指挥官（波兰）
3. 陆军元帅（波兰）
4. 海军指挥官（波兰）
5. 政治顾问（波兰）
6. 多角色人物（德国）
7. 条件可见性（德国）
8. 性别支持（波兰）

---

### 8. 领导人特质详解 (07_leader_traits_annotated.md)

**适合**: 想创建自定义特质系统的用户

**包含**:
- ✅ 8个完整示例
- ✅ 4种特质类型系统
- ✅ 6种技能系统
- ✅ 修正值系统
- ✅ 单位修正值（sub_unit_modifiers）
- ✅ 经验获得条件（gain_xp）
- ✅ 互斥特质
- ✅ 前置条件
- ✅ GUI布局
- ✅ 海军特质系统

**特色**:
- 完整的特质类型分类
- 技能因子控制升级概率
- 地形特质自动获得经验
- 可分配特质需要政治点数成本

**示例列表**:
1. 个性特质（基础）
2. 地形特质（山地）
3. 可分配特质（后勤专家）
4. 状态特质（冬季专家）
5. 海军特质（水面突袭者）
6. 技能系统示例
7. 单位修正值示例
8. GUI布局示例

---

### 9. 民族精神导入详解 (08_importing_ideas_annotated.md)

**适合**: 想在国策/事件中使用民族精神的用户

**包含**:
- ✅ 8个使用场景
- ✅ 在国策中添加民族精神
- ✅ 在事件中添加民族精神
- ✅ 临时民族精神（定时移除）
- ✅ 多级民族精神系统
- ✅ 动态修饰符系统
- ✅ 从其他Mod导入
- ✅ 兼容性检查
- ✅ 条件自动移除

**特色**:
- 完整的工作流程
- 永久 vs 临时 vs 动态的选择
- 多级升级系统的实现
- Mod兼容性最佳实践

**示例列表**:
1. 永久民族精神
2. 定时民族精神
3. 条件自动移除
4. 多级系统
5. 动态修饰符
6. 作用域限定
7. Mod导入
8. 兼容性检查

---

### 10. 国策树规划设计指南 (09_focus_tree_design_guide.md)

**适合**: 想学习如何设计国策树布局，避免图标重合的用户

**包含**:
- ✅ 坐标系统详解（x/y轴、相对定位）
- ✅ 节点尺寸与间距规则
- ✅ 布局规划方法论（4步骤）
- ✅ 常见问题与解决方案（4大问题）
- ✅ 2个完整实战案例（政治三分支、工业多层分叉）
- ✅ 设计检查清单（视觉、功能、代码质量）
- ✅ 进阶技巧（累积计算、条件偏移、模块化设计）
- ✅ **视口与导航设计**（initial_show_position/shortcut/continuous_focus_position/inlay_window）
- ✅ **动态与条件定位**（offset/if-else链/visible/3种设计模式/空间预留/常见陷阱）
- ✅ **真实游戏架构模式**（内圈/条件分支/环形/嵌入窗口/连续焦点，5种完整代码骨架）

**特色**:
- **先规划，后编码**的方法论
- ASCII草图可视化设计
- 坐标唯一性检查算法
- 连线交叉的解决方案
- 互斥链的标准布局模板
- 5种原版游戏布局模式的完整代码骨架
- offset/visible 的决策树和检查清单

**章节列表**:
1. 坐标系统详解
2. 节点尺寸与间距
3. 布局规划方法论
4. 常见问题与解决方案
5. 实战案例
6. 设计检查清单
7. 进阶技巧
8. 视口与导航设计
9. 动态与条件定位
10. 真实游戏架构模式
11. 参考资源

---

### 11. 完整教程 (complete_tutorial.md)

**适合**: 想从零开始创建完整mod的用户

**包含**:
- ✅ 虚构国家 "威塞克斯共和国" 完整实现
- ✅ 国策树（政治+工业分支）
- ✅ 民族精神系统
- ✅ 事件链
- ✅ 本地化（英文+中文）
- ✅ 自定义修正值

**特色**:
- 约350行完整代码
- 可直接使用的模板
- 双语言支持

---

## 🎯 使用指南

### 场景1: 我想快速了解语法

👉 阅读 `SKILL.md` 的"代码规范"和"常用模板"章节

### 场景2: 我想创建国策树

1. 阅读 `01_focus_tree_annotated.md` 理解基础结构
2. 参考 `focus_real_examples.md` 看复杂示例
3. 使用 `complete_tutorial.md` 中的模板开始编写

### 场景3: 我想创建民族精神

1. 阅读 `02_ideas_annotated.md` 理解字段含义
2. 参考 `ideas_real_examples.md` 看真实实现
3. 注意 `allowed`、`visible`、`available` 的区别

### 场景4: 我想创建事件链

1. 阅读 `03_events_annotated.md` 理解事件机制
2. 学习 `FROM` 作用域和事件链设计
3. 使用 `hidden_effect` 隐藏实现细节

### 场景5: 我想支持多语言

1. 阅读 `04_localisation_annotated.md`
2. 使用颜色代码和图标增强可读性
3. 测试编码（UTF-8 带 BOM）

### 场景6: 我想添加决议系统

1. 阅读 `05_decisions_annotated.md`
2. 选择合适的决议类型（普通/省份/外交）
3. 设计AI权重逻辑

### 场景7: 我想创建自定义领导人

1. 阅读 `06_characters_annotated.md`
2. 定义人物 + country_leader 角色
3. 准备头像图片（128x128 PNG）
4. 通过国策或事件设置领导人

### 场景8: 我想创建自定义特质

1. 阅读 `07_leader_traits_annotated.md`
2. 确定特质类型（个性/状态/可分配/地形）
3. 设置技能加成和修正值
4. 定义GUI布局（可选）

### 场景9: 我想导入民族精神

1. 阅读 `08_importing_ideas_annotated.md`
2. 选择合适的方式（永久/临时/动态）
3. 在国策或事件中添加
4. 设置移除条件（可选）

### 场景10: 我想规划设计国策树布局

1. 阅读 `09_focus_tree_design_guide.md`
2. 绘制ASCII草图规划结构
3. 应用布局算法分配坐标
4. 使用检查清单验证设计
5. 编写代码并测试

### 场景11: 我想查原版国策的 focus ID

1. 打开 `references/vanilla_focus_trees/README.md` 查索引表
2. 找到目标国家对应的 .txt 文件
3. 用编辑器搜索 focus ID 或 `prerequisite`
4. 也可全局搜索整个 `vanilla_focus_trees/` 文件夹

### 场景12: 我想修改原版国策树

1. 在 `vanilla_focus_trees/` 中找到原版文件
2. 找到要修改的 focus ID
3. 方式A：同ID追加（只覆盖特定焦点，不破坏其他内容）
4. 方式B：`replace_path`（完全替换整个树，注意兼容性）
5. 参考 `09_focus_tree_design_guide.md` 的布局规则避免重叠

### 场景13: 我想做内圈/嵌入窗口/连续焦点

1. 阅读 `09_focus_tree_design_guide.md` 的「真实游戏架构模式」章节
2. 选择对应模式（内圈/条件分支/环形/嵌入窗口/连续焦点）
3. 参考对应原版文件（德国=内圈、意大利=环形、波兰=嵌入窗口、苏联=连续焦点）
4. 复制代码骨架，修改为国家tag和焦点内容

### 场景14: 我想做条件偏移/动态布局

1. 阅读 `09_focus_tree_design_guide.md` 的「动态与条件定位」章节
2. 选择模式：平行替换 / 渐进展开 / 扇形展开
3. 用 `offset` + `if/else_if/else` 实现条件偏移
4. 用 `visible` 控制分支的显示/隐藏
5. 注意空间预留，避免条件分支出现时重叠

### 场景15: 我想快速查阅常用语法

👉 查看 `references/quick_reference.md` - 一页速查卡片

包含：
- 国策树核心字段（必需/可选）
- Ideas 核心字段
- Events 核心字段
- 常用效果/触发器速查
- 颜色与图标代码速查表
- 布局间距速查表
- 常见错误速查
- 文件位置速查
- 调试命令速查

### 场景16: 我想复制代码模板

👉 查看 `examples/snippet_library.md` - 可直接复用的模板库

包含：
- 完整国策树模板（最小可用/政治三分支/工业分支/军事分支）
- 民族精神模板（永久/临时/条件触发）
- 事件模板（简单事件/条件事件/事件链）
- 决议模板（普通/省份）
- 完整本地化模板（英文+中文）
- 人物模板（国家领导人/多角色人物）
- 效果片段库（政治/军事/经济/外交）
- 触发器片段库（国家/领土/科技/时间/逻辑）

### 场景17: 我想验证我的代码

👉 查看 `tools/validator.md` - 完整检查清单

包含：
- 文件基础检查（编码、结构、命名）
- 语法检查（括号、ID、字段拼写）
- 国策树检查（坐标、前置、互斥、布局）
- Ideas 检查（类型、条件、图标）
- Events 检查（结构、作用域、触发）
- 本地化检查（编码、键值对、格式）
- 作用域检查（ROOT、FROM、省份作用域）
- PowerShell 自动化检查脚本
- 错误日志分析指南

---

## 🔧 调试技巧

### 快速检查清单

- [ ] 文件编码：UTF-8 带 BOM
- [ ] 括号匹配：使用编辑器检查
- [ ] ID唯一性：避免重复ID
- [ ] 本地化：所有文本都有对应键
- [ ] 作用域：检查 `ROOT`、`FROM`、`THIS`

### 常见错误

| 错误 | 原因 | 解决 |
|------|------|------|
| 乱码 | 编码错误 | 使用 UTF-8 带 BOM |
| 语法错误 | 括号不匹配 | 使用编辑器检查 |
| 无效效果 | 拼写错误 | 对照字典检查 |
| 不显示 | 条件不满足 | 检查 `visible` |

---

## 📊 数据来源

本 Skill 整合了以下游戏本地文件：

### 原版国策树参考库 (`references/vanilla_focus_trees/`)

全部 74 个国家的完整国策树原始文本，可直接搜索 focus ID、布局坐标、前置关系。
详见 `vanilla_focus_trees/README.md`。

| 重点参考文件 | 用途 |
|-------------|------|
| `germany.txt` | 内圈焦点、快捷方式、互斥焦点 |
| `japan.txt` | 条件分支互锁、快捷方式 |
| `soviet.txt` | 连续焦点、建筑焦点、变量追踪 |
| `italy.txt` | 环形布局、嵌入窗口 |
| `poland.txt` | 嵌入窗口、条件分支 |
| `france.txt` | 基础结构、临时精神 |
| `spain.txt` | 内战双线布局 |
| `generic.txt` | 通用树、连续焦点基础示例 |

### 其他参考文件

| 来源 | 内容 |
|------|------|
| `air_spirits.txt` | 空军精神、研究加成 |
| `army_spirits.txt` | 陆军精神、显示条件 |
| `navy_spirits.txt` | 海军精神、学说要求 |
| `focus_l_english.yml` | 本地化格式 |

---

## ✨ 核心能力

现在这个 skill 可以帮助你：

✅ **理解语法** - 从基础到高级的完整覆盖  
✅ **编写代码** - 直接生成正确的 HOI4 代码  
✅ **发现问题** - 识别常见错误和不规范写法  
✅ **提供示例** - 真实游戏代码 + 完整教程  
✅ **指导调试** - 调试技巧和错误排查方法  
✅ **最佳实践** - 编码规范、文件组织、命名约定  
✅ **多语言支持** - 英文+中文本地化示例  
✅ **真实参考** - 74个原版国策树 + 注释示例  
✅ **布局设计** - 坐标规划、内圈/嵌入窗口/连续焦点等高级布局  
✅ **原版ID查询** - 快速搜索任何原版 focus ID 和前置关系  
✅ **兼容性指导** - replace_path、同ID追加、DLC锁定  
✅ **完整工作流** - 从设计规划到编码实现到测试调试  

---

## 🚀 快速开始

### 第一个 mod（5分钟）

1. 创建 `descriptor.mod`
2. 复制 `complete_tutorial.md` 中的代码
3. 放入正确的文件夹
4. 使用 `-debug` 启动测试

### 第一个国策（2分钟）

1. 复制 `SKILL.md` 中的模板
2. 修改 ID 和效果
3. 添加本地化
4. 测试

---

## 📝 维护说明

### 更新频率

- HOI4 大版本更新时同步更新
- 发现新特性或错误时及时修正
- 用户反馈的问题及时处理

### 版本历史

- **v7.1** (2026-04-25): 新增快速参考卡片、代码片段库、验证工具；优化文档导航；更新README结构
- **v7.0** (2026-04-25): 新增原版国策树参考库（74国）、Skill Meta、使用场景表；增强设计指南（视口导航/动态定位/架构模式3章）
- **v6.0** (2026-04-24): 新增国策树规划设计指南，解决图标重合问题
- **v5.0** (2026-04-24): 添加人物系统、领导人特质、民族精神导入详解
- **v4.0** (2026-04-24): 添加详细注释示例，真实游戏代码
- **v3.0** (2026-04-24): 整合 Wiki 信息，完善结构
- **v2.0** (2026-04-23): 扩展为完整 mod-maker 框架
- **v1.0** (2026-04-23): 初始版本，国策树基础

---

**祝你 modding 愉快！** 🎮
