\r \r

HOI4 Complete Mod-Maker Skill\r

\r 触发关键词: HOI4 mod, 钢铁雄心4, 钢4, 国策, 国策树, 民族精神, 焦点树, focus tree, national_focus, ideas, spirits, events, decisions, localisation, inner circle, 连续焦点, replace_path, Paradox modding\r \r ---\r \r

⚠ 国策树布局黄金法则（每次生成前必读）\r

\r

AI 在生成国策树时最常见的错误。生成代码前，必须确认以下七点全部满足：\r \r

1. 图标尺寸：每个国策图标是一个以坐标 (x,y) 为中心的 2×2 正方形。即图标左边界在 x-1，右边界在 x+1，上边界在 y+1，下边界在 y-1。左右相邻（同行）时 x 差必须 >= 2，否则图标重叠；上下相邻时 y 差 >= 1 即可。同一焦点块内紧凑排列时 x 间距用 2（最小合法值）。\r \r
2. relative_position_id 是首选：除非有充分理由（固定窗口锚点、避免 offset 继承等），一律使用 relative_position_id = \x3C父节点ID> + 小的 x/y 偏移量。绝对坐标只用于树的根节点或没有父节点的主干焦点。\r \r
3. 前置国策必须存在：每个 prerequisite = { focus = XXX } 引用的 XXX 必须在同一个国策树文件中实际定义。不得凭空捏造 focus ID，也不得使用其他国家的 focus ID 作为前置。生成完成后，对照 examples/09_focus_tree_design_guide.md 的检查清单逐条验证。\r \r
4. 禁止长线性链：同一条路径上连续节点不得超过 3 个（即 A->B->C 之后必须出现分支或汇合）。超过 3 个连续节点会让玩家感到单调，且视觉上形成难看的长竖线。如需表达「递进过程」，用分支+汇合代替直线延伸。\r \r
5. 子节点数量上限：单个焦点的直接子节点（同一 prerequisite 指向同一父节点）不得超过 5 个。超过 5 个时，将部分子节点改为二级分支（先汇到中间节点，再展开）。\r \r
6. 树深度要求：单个国策树的主路径深度应 >= 5 层，建议 6-10 层。浅层树（\x3C5层）会让玩家缺乏战略规划感。通过添加中间节点、分支选择、汇聚节点来增加深度。\r \r
7. 不同板块间距：同一 focus_tree 内的不同分支（如政治/工业/军事），根节点 x 坐标差应 >= 6。不同 focus_tree 文件之间，使用不同的 initial_show_position 错开显示。严禁不同板块的国策左右相邻且 x 差 \x3C 2，这会导致视觉混乱。\r \r ---\r \r \r

Skill Meta\r

\r | 属性 | 值 |\r |------|----|\r | 版本 | 7.2 |\r | 更新 | 2026-04-26 |\r | 游戏版本 | HOI4 1.14+ |\r | 覆盖范围 | 国策树 / 民族精神 / 人物 / 事件 / 决议 / 本地化 / 变量 / 调试 |\r | 参考文件 | 74 原版国策树 + 10 语法参考 + 12 注释示例 |\r | 特色能力 | 布局设计 / 原版ID查询 / 代码生成 / 递进奖励设计 / 兼容性指导 |\r \r

典型使用场景 → 推荐路径\r

\r | 用户意图 | 推荐路径 |\r |---------|----------|\r | 做国策树 | 09设计指南 → 布局规划 → 代码生成 → 检查清单 |\r | 图标重叠 | 09设计指南 → 坐标系统/间距规则 |\r | 查原版国策ID | references/vanilla_focus_trees/ → 搜索对应国家.txt |\r | 条件偏移 | 09设计指南(动态与条件定位) → advanced_syntax.md |\r | 修改原版树 | 查原版ID → replace_path/同ID追加 |\r | 写民族精神 | 02注释示例 → ideas_syntax.md → 08导入详解 |\r | 内圈焦点 | 09设计指南(真实架构模式) → germany.txt参考 |\r | 完成效果写法 | focus_complete_guide.md / dictionary.md |\r | 本地化编码 | 04本地化详解 → UTF-8 BOM |\r | mod不生效 | 调试技巧 → error.log |\r \r ---\r \r

快速开始\r

\r

Mod 基础文件结构\r

\r

your_mod/\r
├── descriptor.mod              # Mod 描述符（必需）\r
├── thumbnail.png               # 封面图（推荐 256x256）\r
├── common/\r
│   ├── national_focus/         # 国策树 .txt\r
│   ├── ideas/                  # 民族精神 .txt\r
│   ├── characters/             # 人物定义 .txt\r
│   ├── unit_leader/            # 领导人特质 .txt\r
│   ├── decisions/              # 决议 .txt\r
│   └── modifiers/              # 自定义修正值\r
├── events/                     # 事件 .txt\r
├── localisation/\r
│   ├── english/                # 英文本地化 .yml\r
│   └── simp_chinese/           # 中文本地化 .yml\r
├── interface/                  # GFX 图标定义\r
└── gfx/\r
    └── goals/                  # 国策图标图片\r
```\r
\r
### descriptor.mod 模板\r
\r
```\r
name = "Your Mod Name"\r
version = "0.2.0"  # changelog: 扩展黄金法则至7条；去除模板机械拼装；新增孤立节点/碰撞检测；BOM清理修复skill加载\r
tags = { "National Focus" "Gameplay" }\r
picture = "thumbnail.png"\r
```\r
\r
---\r
\r
## 代码规范\r
\r
### 基础语法\r
\r
```\r
\x3Cattribute> = \x3Cargument>    # 数值/字符串/布尔值/代码块\r
```\r
\r
### 编码要求\r
\r
| 文件类型 | 编码 |\r
|---------|------|\r
| 脚本文件 (.txt) | UTF-8 无 BOM |\r
| 本地化文件 (.yml) | UTF-8 带 BOM |\r
\r
### 缩进规范\r
\r
- 开闭括号同一缩进层级\r
- 代码块内部增加一层缩进（Tab 或 4空格）\r
- 一行不要有多于一个括号\r
\r
### 注释\r
\r
```\r
# 单行注释（无多行注释）\r
cost = 10  # TODO: 检查平衡性\r
```\r
\r
### 常量定义\r
\r
```\r
@base_cost = 10\r
focus = { id = POL_focus  cost = @base_cost }\r
```\r
\r
---\r
\r
## 文件结构\r
\r
### 加载顺序\r
\r
```\r
Base Game → DLCs → User Directory → Mods\r
```\r
\r
文件名排序：ASCII 字符顺序，`00_` 前缀先加载，`zz_` 后加载。\r
\r
---\r
\r
## 国策树\r
\r
> 📄 **完整语法**: `references/focus_complete_guide.md` — Focus Tree 结构、节点字段、定位方式、前置条件、互斥、available、bypass、completion_reward 完整效果列表、内圈焦点、连续焦点、Search Filters\r
>\r
> 📄 **高级语法**: `references/advanced_syntax.md` — 备选图标、默认树、内圈窗口、快捷方式、嵌入窗口、连续焦点位置\r
>\r
> 📄 **形式化语法**: `references/syntax.md` — BNF 语法 + Joint/Shared Focus + 11 个常见陷阱\r
>\r
> 📄 **布局设计**: `examples/09_focus_tree_design_guide.md` — 坐标系统、间距、4步方法论、视口导航、动态定位、真实架构模式、递进奖励设计、原版数据分析\r
\r
### 最小可用模板\r
\r
```\r
focus_tree = {\r
    id = {TAG}_focus\r
    country = { factor = 0  modifier = { add = 10  tag = {TAG} } }\r
    default = no\r
    initial_show_position = { x = 500  y = 300 }\r
    \r
    focus = {\r
        id = {TAG}_root\r
        icon = GFX_goal_generic_political_pressure\r
        x = 0  y = 0\r
        cost = 5\r
        search_filters = { FOCUS_FILTER_POLITICAL }\r
        completion_reward = { add_political_power = 50 }\r
    }\r
    \r
    focus = {\r
        id = {TAG}_child\r
        prerequisite = { focus = {TAG}_root }\r
        relative_position_id = {TAG}_root\r
        x = 0  y = 1\r
        icon = GFX_goal_generic_authoritarian\r
        cost = 10\r
        completion_reward = { add_political_power = 100 }\r
    }\r
}\r
```\r
\r
### 递进奖励（Progressive Reward）\r
\r
> 📄 **完整设计指南**: `examples/09_focus_tree_design_guide.md` → 递进奖励设计章节\r
\r
```\r
三层奖励结构：\r
  🪨 过程层 → cost=5, 1基建/10-15XP/25PP（克制，推动继续走）\r
  📦 阶段层 → cost=10, 1-2工厂+科技加成/50PP+25XP（阶段性成果）\r
  🏆 终点层 → cost=10-15, 3-4工厂+科技+50-100XP+100PP（终极目标）\r
\r
核心原则：递进 ≠ 加量，是把相同总量重新分配——中间少给，终点多给\r
```\r
\r
### 建筑效果（正确语法）\r
\r
> 📄 **完整参考**: `references/focus_complete_guide.md` → 建筑效果章节\r
\r
```\r
# ❌ 错误写法：random_owned_controlled_state + state = 762\r
# ✅ 正确写法：在 state scope 内直接调用 add_building_construction\r
\r
# 指定州建造（推荐）\r
123 = {\r
    add_extra_state_shared_building_slots = 1    # 先扩容（如需）\r
    add_building_construction = {\r
        type = industrial_complex              # 民用工厂\r
        level = 1\r
        instant_build = yes\r
    }\r
}\r
124 = {\r
    add_extra_state_shared_building_slots = 2\r
    add_building_construction = { type = arms_factory  level = 2  instant_build = yes }\r
}\r
\r
# 遍历所有符合条件的州\r
# every_owned_state = {\r
#     limit = { free_building_slots = { building = industrial_complex size > 0 } }\r
#     add_building_construction = { type = industrial_complex level = 1 instant_build = yes }\r
# }\r
\r
# 建筑类型：industrial_complex / arms_factory / dockyard\r
#           infrastructure / air_base / naval_base / bunker / coastal_bunker\r
```\r
\r
### 可持久/连续国策\r
\r
> 📄 **完整参考**: `references/focus_complete_guide.md` → Continuous Focus 章节\r
\r
```\r
# 连续焦点（continuous = yes）：完成10个常规国策后解锁，激活期间持续生效\r
focus = {\r
    id = continuous_army_xp\r
    icon = GFX_focus_generic_army_xp\r
    x = 0  y = 0\r
    continuous = yes                  # 关键标记\r
    cost = 0                         # 连续焦点必须为 0\r
    search_filters = { FOCUS_FILTER_ARMY_XP }\r
    # ✅ 用 modifier = {} 提供持续效果（不是 completion_reward）\r
    modifier = { army_experience_gain_factor = 0.05 }\r
}\r
\r
# 可取消的持久国策（带 cancel 块）\r
focus = {\r
    id = TAG_mobilization\r
    cost = 30\r
    cancel = {                        # ❗ 被取消时触发\r
        add_stability = -0.05\r
    }\r
    cancel_if_invalid = yes            # 条件失效时自动取消\r
    ai_will_do = { factor = 0 }       # AI 不会自动选（玩家决策）\r
}\r
\r
# 可取消属性\r
cancelable = yes        # 可手动取消（默认）\r
cancelable = no         # 不可取消（内圈选择等）\r
```\r
\r
---\r
\r
## 民族精神\r
\r
> 📄 **完整语法**: `references/ideas_syntax.md` | **注释示例**: `examples/02_ideas_annotated.md` | **导入详解**: `examples/08_importing_ideas_annotated.md`\r
\r
### Ideas 类型\r
\r
| 类型 | 槽位 | 说明 |\r
|------|------|------|\r
| `country` | 无限制 | 国家精神 |\r
| `army/navy/air` | 各1个 | 军种精神（需DLC） |\r
| `political_advisor` | 1个 | 政治顾问 |\r
| `theorist` | 1个 | 理论家 |\r
| `chief_of_staff/army_chief/navy_chief/air_chief` | 各1个 | 军事首脑 |\r
\r
### 国家精神模板\r
\r
```\r
ideas = {\r
    country = {\r
        {TAG}_spirit_name = {\r
            allowed = { original_tag = {TAG}  always = no }\r
            allowed_civil_war = { always = no }\r
            removal_cost = -1\r
            picture = generic_authoritarian_regime\r
            modifier = {\r
                political_power_gain = 0.10\r
                stability_factor = 0.05\r
            }\r
        }\r
    }\r
}\r
```\r
\r
---\r
\r
## 人物系统\r
\r
> 📄 **注释示例**: `examples/06_characters_annotated.md`\r
\r
### 角色类型\r
\r
| 角色类型 | 说明 |\r
|----------|------|\r
| `country_leader` | 国家领导人 |\r
| `corps_commander` | 军级指挥官 |\r
| `field_marshal` | 陆军元帅 |\r
| `navy_leader` | 海军指挥官 |\r
| `advisor` | 顾问 |\r
\r
### 完整人物定义\r
\r
```\r
characters = {\r
    {TAG}_character = {\r
        name = "Character Name"\r
        portraits = {\r
            civilian = { large = "GFX_portrait_{TAG}_char" }\r
            army = { large = "GFX_portrait_{TAG}_char" }\r
        }\r
        country_leader = {\r
            ideology = despotism\r
            traits = { trait_name }\r
            expire = "1965.1.1.1"  id = -1\r
        }\r
        corps_commander = {\r
            traits = { cavalry_officer war_hero }\r
            skill = 2  attack_skill = 2  defense_skill = 2\r
            planning_skill = 2  logistics_skill = 1\r
        }\r
    }\r
}\r
```\r
\r
---\r
\r
## 领导人特质\r
\r
> 📄 **注释示例**: `examples/07_leader_traits_annotated.md`\r
\r
### 特质类型\r
\r
| 类型 | 获得方式 |\r
|------|----------|\r
| `personality_trait` | 开局随机 |\r
| `status_trait` | 战斗获得 |\r
| `assignable_trait` | 手动分配 |\r
| `terrain_trait` | 地形战斗 |\r
\r
### 特质定义模板\r
\r
```\r
leader_traits = {\r
    trait_name = {\r
        type = land\r
        trait_type = personality_trait\r
        attack_skill = 1\r
        modifier = { planning_speed = 0.10 }\r
    }\r
}\r
```\r
\r
---\r
\r
## 本地化\r
\r
> 📄 **详细指南**: `references/localisation_guide.md` | **注释示例**: `examples/04_localisation_annotated.md`\r
\r
### YML 格式\r
\r
```yaml\r
l_english:\r
 {TAG}_focus_name:0 "Focus Display Name"\r
 {TAG}_focus_name_desc:0 "Detailed description..."\r
```\r
\r
### 编码：本地化文件必须 UTF-8 带 BOM + LF\r
\r
> ⚠️ **AI 生成 .yml 本地化文件时必须遵守此格式，零例外：**\r
>\r
> | 属性 | 值 |\r
> |------|-----|\r
> | **编码** | UTF-8 with BOM（文件开头三个隐藏字节 `\xEF\xBB\xBF`） |\r
> | **换行符** | LF（`\
`，不是 CRLF `\r\
`） |\r
> | **文件路径示例** | `localisation/simp_chinese/{TAG}_l_simp_chinese.yml` |\r
>\r
> **为什么必须带 BOM**：Paradox Launcher 读取 .yml 本地化文件时依赖 BOM 识别 UTF-8。\r
> 无 BOM 的文件在游戏中直接显示为乱码，无法事后修复。\r
>\r
> **生成后自检命令**：\r
> ```powershell\r
> $bytes = [System.IO.File]::ReadAllBytes("path	o\file.yml")\r
> if ($bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) {\r
>     Write-Host "✅ BOM 正确"\r
> } else {\r
>     Write-Host "❌ 缺少 BOM，请重新生成并确保编辑器保存为 UTF-8 with BOM"\r
> }\r
> ```\r
>\r
> **常见错误避坑**：\r
> - ❌ VSCode 保存为「UTF-8」（无 BOM）→ 游戏中文乱码\r
> - ❌ 记事本 / Notepad 保存为 ANSI/GBK → 中文完全无法显示\r
> - ❌ LF/CRLF 混用 → 部分游戏版本解析异常\r
> - ✅ 正确：VSCode 选「UTF-8 with BOM」，底部状态栏 CRLF 改为 LF\r
\r
### 颜色与图标\r
\r
```yaml\r
§R红色§!  §G绿色§!  §B蓝色§!  §Y黄色§!  §H高亮§!\r
£pol_power  £stability  £civilian_factory\r
```\r
\r
---\r
\r
## 事件\r
\r
> 📄 **事件参考**: `references/events_guide.md` | **注释示例**: `examples/03_events_annotated.md`\r
\r
### 国家事件模板\r
\r
```\r
add_namespace = {TAG}_events\r
\r
country_event = {\r
    id = {TAG}_events.1\r
    title = {TAG}_events.1_title\r
    desc = {TAG}_events.1_desc\r
    picture = generic_event\r
    is_triggered_only = yes\r
    \r
    option = {\r
        name = {TAG}_events.1_option_a\r
        add_political_power = 100\r
    }\r
}\r
```\r
\r
---\r
\r
## 决议\r
\r
> 📄 **注释示例**: `examples/05_decisions_annotated.md`\r
\r
### 决议模板\r
\r
```\r
decisions = {\r
    {TAG}_category = {\r
        icon = GFX_goal_generic_major_alliance\r
        \r
        {TAG}_decision = {\r
            available = { tag = {TAG} }\r
            visible = { has_war_with = GER }\r
            cost = 50\r
            complete_effect = {\r
                transfer_state = { state = 123  target = ROOT }\r
            }\r
        }\r
    }\r
}\r
```\r
\r
---\r
\r
## 变量与动态修饰符\r
\r
> 📄 **动态修饰符**: `references/dynamic_modifiers.md` | **脚本效果**: `references/scripted_effects.md` | **脚本触发器**: `references/scripted_triggers.md`\r
\r
### 变量操作\r
\r
```\r
set_variable = { var = {TAG}_var  value = 10 }\r
add_to_variable = { var = {TAG}_var  value = 5 }\r
subtract_from_variable = { var = {TAG}_var  value = 3 }\r
clamp_variable = { var = {TAG}_var  min = 0  max = 100 }\r
```\r
\r
### 动态修饰符\r
\r
```\r
add_dynamic_modifier = { modifier = {TAG}_modifier  days = 365 }\r
remove_dynamic_modifier = { modifier = {TAG}_old_modifier }\r
```\r
\r
---\r
\r
## 调试技巧\r
\r
### 启用调试模式\r
\r
Steam 启动选项加 `-debug`\r
\r
### 控制台命令\r
\r
```\r
debug_yesmen       # AI 总是接受\r
debug_events       # 显示事件 ID\r
tdebug             # 显示调试信息\r
error              # 打开错误日志\r
```\r
\r
### 错误日志\r
\r
```\r
Windows: C:\Users\\x3C用户名>\Documents\Paradox Interactive\Hearts of Iron IV\logs\error.log\r
```\r
\r
---\r
\r
## 参考文档\r
\r
### 语法参考\r
\r
| 文件 | 内容 |\r
|------|------|\r
| `references/focus_complete_guide.md` | **国策树完整语法**（结构/字段/效果/内圈/连续焦点） |\r
| `references/focus_syntax_complete.md` | 国策树语法（含Joint/Shared/波兰示例） |\r
| `references/advanced_syntax.md` | 高级语法（备选图标/默认树/内圈窗口/快捷方式/嵌入窗口/连续焦点位置） |\r
| `references/syntax.md` | 形式化语法 + BNF + 11个常见陷阱 |\r
| `references/dictionary.md` | 效果/触发器语义字典（169效果 + 79触发器 + 作用域） |\r
| `references/ideas_syntax.md` | Ideas 完整语法 |\r
| `references/localisation_guide.md` | 本地化详细指南 |\r
| `references/events_guide.md` | 事件系统参考 |\r
| `references/dynamic_modifiers.md` | 动态修正完整语法 |\r
| `references/scripted_effects.md` | 脚本效果完整语法 |\r
| `references/scripted_triggers.md` | 脚本触发器完整语法 |\r
\r
### 示例与模板\r
\r
| 文件 | 内容 |\r
|------|------|\r
| `examples/09_focus_tree_design_guide.md` | **布局设计指南**（坐标/间距/视口/动态定位/真实架构/递进奖励/原版数据分析） |\r
| \examples/templates.md\ | **基础模板+经典子模块** 国策+民族精神+建筑效果+5个可组装子模块 |\r
| `examples/snippet_library.md` | 代码片段库 |\r
| `examples/01_focus_tree_annotated.md` | 国策树注释示例 |\r
| `examples/02_ideas_annotated.md` | 民族精神注释示例 |\r
| `examples/03_events_annotated.md` | 事件注释示例 |\r
| `examples/04_localisation_annotated.md` | 本地化注释示例 |\r
| `examples/05_decisions_annotated.md` | 决议注释示例 |\r
| `examples/06_characters_annotated.md` | 人物系统注释示例 |\r
| `examples/07_leader_traits_annotated.md` | 领导人特质注释示例 |\r
| `examples/08_importing_ideas_annotated.md` | Ideas 导入详解 |\r
| `examples/10_dynamic_modifiers_annotated.md` | 动态修饰符注释示例 |\r
| `examples/complete_mod_example.md` | 完整 mod 示例 |\r
| `examples/complete_tutorial.md` | 完整教程 |\r
| `examples/focus_real_examples.md` | 原版国策真实示例 |\r
| `examples/ideas_real_examples.md` | 原版精神真实示例 |\r
| `examples/events_real_examples.md` | 原版事件真实示例 |\r
\r
### 原版参考\r
\r
| 文件 | 内容 |\r
|------|------|\r
| `references/vanilla_focus_trees/` | **74个原版国策树文本** |\r
| `references/vanilla_focus_trees/README.md` | 原版国策树索引表 |\r
| `tools/validator.md` | 验证清单 |\r
\r
### 官方参考\r
\r
- Wiki: https://hoi4.paradoxwikis.com/Modding\r
- 本地文件: `Hearts of Iron IV/common/`\r
\r
### 推荐工具\r
\r
- VS Code + CWTools 扩展\r
- Notepad++\r
- WinMerge\r
\r
---\r
\r
**版本**: 7.2 | **更新**: 2026-04-26