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