HOI4 Modding

Follow the rules in references/modding-rules.md for all HOI4 modding work.

Reference Files

Core rules and language foundation

```
references/modding-rules.md
```
— Core rules for HOI4 modding (encoding, comments, tooltips, loc flavor, design units).

references/mod-structure-template.md

—

.mod

descriptor.mod

, load order,

dependencies

replace_path

references/scopes-template.md

— Scopes (

ROOT

FROM

PREV

every_*

any_*

, event targets.

```
references/effects-template.md
```
— Common effects and where to use them.

references/triggers-template.md

— Common triggers, logic blocks,

allowed

available

visible

```
references/variables-arrays-template.md
```
— Variables, arrays, collections, event targets, loc display.

references/scripted-effects-template.md

— Reusable

common/scripted_effects

blocks.

references/on-actions-template.md

—

common/on_actions

hooks and ROOT/FROM discipline.

```
references/localisation-syntax-template.md
```
— YML encoding, color codes, dynamic keys, variables in loc.

Content system templates

```
references/focus-template.md
```
— National focus tree templates and field reference.
```
references/decision-template.md
```
— Decision category and decision templates.
```
references/event-template.md
```
— Country event and news event templates.
```
references/mio-template.md
```
— Military industrial organization (MIO) templates and equipment bonuses.
```
references/idea-template.md
```
— Laws, national spirits, and manufacturer advisors.
```
references/subdoctrine-template.md
```
— Sub-doctrine templates and mastery rewards.
```
references/special-projects-template.md
```
— Special projects, specializations, scientists, and facilities.
```
references/bop-template.md
```
— Balance of power (BOP) templates.
```
references/ai-template.md
```
— AI areas and AI strategies.
```
references/equipment-template.md
```
— Equipment archetypes and variants.
```
references/equipment-module-template.md
```
— Tank, plane, and ship equipment modules.
```
references/equipment-variant-template.md
```
— Create equipment variant examples and parts lists.
```
references/unit-template.md
```
— Sub unit definitions and icon registration.
```
references/country-history-template.md
```
— Country history file structure and starting effects.
```
references/oob-template.md
```
— Order of battle and production line setup.
```
references/state-template.md
```
— State/province definitions and buildings.
```
references/advisor-traits-template.md
```
— Vanilla advisor slots and trait effects.
```
references/character-template.md
```
— Character definitions for leaders, advisors, commanders, scientists.

references/opinion-modifiers-template.md

— Diplomatic opinion modifiers.

```
references/scripted-triggers-template.md
```
— Scripted triggers and scripted localisation.
```
references/buildings-template.md
```
— Custom building definitions and spawn points.
```
references/intelligence-diplo-template.md
```
— Operatives, intelligence operations, and scripted diplomatic actions.
```
references/faction-system-template.md
```
— Faction templates, goals, manifests, rules, member upgrades, and AI FI spending.
```
references/dynamic-modifier-template.md
```
— Dynamic national spirits with variable-driven modifiers and tooltip conventions.

Extended content (medium priority)

```
references/bookmarks-template.md
```
— Bookmarks / scenario select screen.
```
references/new-country-template.md
```
— Full new-country checklist (tag → history → flag → loc).
```
references/gfx-registration-template.md
```
—
```
.gfx
```
sprite registration (goals, ideas, events, shine, flags).
```
references/ideologies-template.md
```
— Ideologies and sub-ideologies.
```
references/custom-traits-template.md
```
— Custom country_leader and unit_leader traits.
```
references/autonomy-template.md
```
— Autonomous states / puppet levels.
```
references/wargoals-peace-template.md
```
— Wargoals, declare war, peace conference AI hooks.
```
references/resources-supply-template.md
```
— Resources, railways, supply nodes, strategic regions.
```
references/names-template.md
```
— Name pools and division name groups.
```
references/technology-file-template.md
```
— Technology file structure (not just ID lists).
```
references/modifiers-index-template.md
```
— Where modifiers live and how to look up keys.
```
references/version-migration-template.md
```
— Version adaption / migration checklist.

Gap-fill (common coverage)

```
references/common-directory-index.md
```
— Full
```
common/
```
folder → skill page map; check here before inventing systems.
```
references/continuous-focus-template.md
```
— Continuous focus palettes.

references/occupation-resistance-template.md

— Occupation laws, resistance/compliance.

references/game-rules-template.md

— Pre-game rules and

has_game_rule

references/technology-sharing-template.md

— Technology sharing groups.

references/country-tag-aliases-template.md

— Dynamic country tag aliases.

```
references/raids-template.md
```
— Raid types.
```
references/abilities-template.md
```
— Commander abilities (command power).
```
references/aces-medals-template.md
```
— Aces and unit medals.
```
references/idea-tags-template.md
```
— Idea category / advisor slot layout.

references/state-category-terrain-template.md

— State categories and terrain.

```
references/doctrine-system-template.md
```
— Grand doctrine / tracks / mastery overview.

references/script-constants-template.md

—

script_constants

and

constant:

values.

Advanced / low priority

```
references/scripted-gui-template.md
```
— Scripted GUI +
```
.gui
```
wiring.
```
references/super-event-template.md
```
— Super event (big event UI) community pattern.

references/defines-template.md

—

common/defines

Lua overrides (use sparingly).

```
references/map-modding-template.md
```
— Map folder responsibilities and safe vs unsafe edits.
```
references/unit-models-template.md
```
— 3D unit models / entities entry.
```
references/music-radio-template.md
```
— Music assets, songs lists, radio.
```
references/fonts-template.md
```
— Bitmap fonts registration.
```
references/shaders-template.md
```
—
```
gfx/FX
```
shaders entry (advanced).
```
references/map-modes-template.md
```
— Scripted map modes.
```
references/dynamic-renaming-template.md
```
— Dynamic place-name renaming entry.
```
references/diplomacy-enable-triggers-template.md
```
— Lock diplomacy buttons via fixed scripted_trigger names.
```
references/debug-workflow-template.md
```
— error.log workflow and debugging order.

Data quick-reference

```
references/data/tech-list.md
```
— Vanilla technology code reference.
```
references/data/doctrine-list.md
```
— Vanilla doctrine and sub-doctrine codes.
```
references/data/equipment-list.md
```
— Vanilla equipment codes for bonuses and OOB.
```
references/data/state-modifiers.md
```
— State categories and national spirit modifier keys.

Workflow

Read
```
references/modding-rules.md
```
before making changes. 1b. Hard rule — backup before editing existing files: Before modifying any existing file, create a timestamped backup; after the edit, compare against the backup for truncation, missing blocks, or brace imbalance; if clean, delete the backup; if broken, restore/fix then delete the backup. See
```
references/modding-rules.md
```
section "Mandatory backup before editing existing files". Never skip this.

When editing

.mod

descriptor.mod

, load order,

dependencies

, or

replace_path

, check

references/mod-structure-template.md

When writing scopes,

ROOT

FROM

PREV

, or

every_*

any_*

blocks, check

references/scopes-template.md

When writing or looking up effects, check
```
references/effects-template.md
```
.

When writing or looking up triggers /

limit

available

visible

, check

references/triggers-template.md

When writing variables, arrays, collections, or event targets, check
```
references/variables-arrays-template.md
```
.
When writing reusable scripted effects, check
```
references/scripted-effects-template.md
```
.

When writing

on_actions

hooks, check

references/on-actions-template.md

When writing localization files (syntax, color codes, dynamic keys), check
```
references/localisation-syntax-template.md
```
and match vanilla flavor per
```
modding-rules.md
```
.
When writing a national focus, check
```
references/focus-template.md
```
.
When writing a decision, check
```
references/decision-template.md
```
.
When writing an event, check
```
references/event-template.md
```
.
When writing an MIO, check
```
references/mio-template.md
```
.
When writing an idea, check
```
references/idea-template.md
```
.
When writing a sub-doctrine, check
```
references/subdoctrine-template.md
```
.
When writing a special project, check
```
references/special-projects-template.md
```
.
When writing a balance of power, check
```
references/bop-template.md
```
.
When writing AI behavior, check
```
references/ai-template.md
```
.
When writing equipment, check
```
references/equipment-template.md
```
.
When writing equipment modules, check
```
references/equipment-module-template.md
```
.

When creating equipment variants, check

references/equipment-variant-template.md

When writing units, check
```
references/unit-template.md
```
.
When writing country history, check
```
references/country-history-template.md
```
.
When writing OOB or production lines, check
```
references/oob-template.md
```
.
When writing states, check
```
references/state-template.md
```
.
When assigning vanilla advisor traits, check
```
references/advisor-traits-template.md
```
.
When writing characters, check
```
references/character-template.md
```
.
When adding diplomatic opinion modifiers, check
```
references/opinion-modifiers-template.md
```
.
When writing scripted triggers or scripted localisation, check
```
references/scripted-triggers-template.md
```
.
When writing buildings, check
```
references/buildings-template.md
```
.
When writing intelligence operations or diplomatic actions, check
```
references/intelligence-diplo-template.md
```
.
When writing a faction system, check
```
references/faction-system-template.md
```
.
When writing a dynamic national spirit, check
```
references/dynamic-modifier-template.md
```
.
When writing bookmarks / scenario select, check
```
references/bookmarks-template.md
```
.
When creating a new country (tag, color, history, flag, loc), check
```
references/new-country-template.md
```
.
When registering GFX (focus icons, idea icons, event pics, shine, flags), check
```
references/gfx-registration-template.md
```
.
When editing ideologies or sub-ideologies, check
```
references/ideologies-template.md
```
.
When writing custom leader or unit leader traits, check
```
references/custom-traits-template.md
```
.
When defining or setting autonomy/puppet levels, check
```
references/autonomy-template.md
```
.
When writing wargoals, war declaration, or peace conference AI, check
```
references/wargoals-peace-template.md
```
.
When placing resources, railways, supply nodes, or strategic regions, check
```
references/resources-supply-template.md
```
.
When writing name pools or division name groups, check
```
references/names-template.md
```
.
When writing technology files (tree structure, not only IDs), check
```
references/technology-file-template.md
```
.

When looking up or placing modifier keys, check

references/modifiers-index-template.md

then

references/data/state-modifiers.md

When adapting a mod to a new game version, check
```
references/version-migration-template.md
```
.
When writing scripted GUI or custom
```
.gui
```
windows, check
```
references/scripted-gui-template.md
```
.
When implementing super events (big event UI), check
```
references/super-event-template.md
```
.
When editing defines, check
```
references/defines-template.md
```
(prefer minimal overrides).
When editing map files or province layout, check
```
references/map-modding-template.md
```
.
When replacing unit 3D models/entities, check
```
references/unit-models-template.md
```
.
When adding music or radio stations, check
```
references/music-radio-template.md
```
.
When adding or changing fonts, check
```
references/fonts-template.md
```
.
When editing shaders under
```
gfx/FX
```
, check
```
references/shaders-template.md
```
.
When writing scripted map modes, check
```
references/map-modes-template.md
```
.
When implementing dynamic place renaming, check
```
references/dynamic-renaming-template.md
```
.

When locking diplomacy actions, check

references/diplomacy-enable-triggers-template.md

When debugging load errors or unexpected behavior, check
```
references/debug-workflow-template.md
```
.
When auditing which
```
common/
```
systems exist vs this skill, check
```
references/common-directory-index.md
```
.
When writing continuous focuses, check
```
references/continuous-focus-template.md
```
.
When writing occupation laws or resistance/compliance, check
```
references/occupation-resistance-template.md
```
.
When writing game rules or AI path rules, check
```
references/game-rules-template.md
```
.
When writing technology sharing groups, check
```
references/technology-sharing-template.md
```
.

When writing country tag aliases, check

references/country-tag-aliases-template.md

When writing raids, check
```
references/raids-template.md
```
.
When writing commander abilities, check
```
references/abilities-template.md
```
.
When writing aces or unit medals, check
```
references/aces-medals-template.md
```
.

When editing idea slot layout (

idea_tags

), check

references/idea-tags-template.md

When editing state categories or terrain, check
```
references/state-category-terrain-template.md
```
.
When working on the grand doctrine system (not only subdoctrines), check
```
references/doctrine-system-template.md
```
.
When defining script constants, check
```
references/script-constants-template.md
```
.
When looking up vanilla technology codes, check
```
references/data/tech-list.md
```
.
When looking up vanilla doctrine codes, check
```
references/data/doctrine-list.md
```
.
When looking up vanilla equipment codes, check
```
references/data/equipment-list.md
```
.
When looking up state categories or modifier keys, check
```
references/data/state-modifiers.md
```
.
When writing localization text (names/descriptions for focus/event/news/idea/decision), look up vanilla localization first and match its flavor/register.
When unsure about syntax or structure:

Check
```
references/common-directory-index.md
```
if the folder is unfamiliar.
Check this skill's references first (language base → content → gap-fill → advanced).
Check other files in the same directory within the project.
Check the user's HOI4 base game installation and official wiki / local library.
Ask the user if none of the above resolve the question.

hoi4-modding

NPX Install

Tags

SKILL.md Content