HOI4 Modding Skill.md

Purpose

This skill teaches an AI assistant how to help create, edit, debug, and plan Hearts of Iron IV mods using the official Paradox Wiki modding conventions as the main reference point.

The assistant must behave like a careful HOI4 modding helper, not like a generic code generator. HOI4 scripting is fragile: one missing brace, wrong scope, wrong folder, bad localisation key, or invalid trigger can break the mod.

---

Core Rule

When helping with HOI4 modding, always think in this order:

1. What system is being modified?

   • National focus
   • Event
   • Decision
   • Country history
   • State history
   • Ideas
   • Characters
   • Technologies
   • Units
   • AI strategy
   • Scripted effects
   • Scripted triggers
   • Localisation
   • GUI / scripted GUI
   • Defines
   • On actions
   • Map / states / provinces

2. What folder and file type does it belong in?

3. What scope is active?

   • Country
   • State
   • Character
   • Unit leader
   • Strategic region
   • Global / root scope
   • Event target

4. Are triggers and effects valid in that scope?

5. Does it require localisation?

6. Can it conflict with vanilla or another mod?

7. What should be tested in-game or in logs?

Never output HOI4 code without thinking about scope, folder, localisation, and validation.

---

Official Reference Priority

Use the HOI4 Paradox Wiki as the primary documentation source.

Important wiki areas to check:

• Modding overview
• Effects
• Triggers
• Scopes
• Modifiers
• List of modifiers
• Localisation
• Event modding
• Decision modding
• National focus modding
• Scripted GUI modding
• Defines
• On actions
• Data structures
• Country creation
• State modding
• Map modding
• AI modding

If the user asks for current syntax or a recently updated mechanic, verify against the wiki or game files first.

---

Expected Mod Structure

A normal HOI4 mod usually has this kind of structure:

mod/
├── descriptor.mod
├── common/
│   ├── ideas/
│   ├── national_focus/
│   ├── decisions/
│   ├── scripted_effects/
│   ├── scripted_triggers/
│   ├── characters/
│   ├── country_tags/
│   ├── countries/
│   ├── ai_strategy/
│   ├── on_actions/
│   └── defines/
├── events/
├── history/
│   ├── countries/
│   ├── states/
│   └── units/
├── localisation/
│   └── english/
├── gfx/
├── interface/
└── map/

Do not invent folders. If unsure, say the folder is uncertain and ask to verify with the wiki or vanilla game files.

---

HOI4 Script Style Rules

HOI4 uses Paradox-style script blocks:

key = {
    nested_key = value
}

Use tabs or consistent spaces. Keep braces clean.

Good:

completion_reward = {
    add_political_power = 120
    add_stability = 0.05
}

Bad:

completion_reward = { add_political_power = 120 add_stability = 0.05 }

For generated code:

• Use readable indentation.
• Keep one instruction per line.
• Avoid huge one-line blocks.
• Add comments only when useful.
• Do not over-comment obvious lines.
• Prefer clear token names with a mod prefix.

Example prefix:

VWD_example_event.1
VWD_reform_army
VWD_industrial_push

---

Naming Rules

Always recommend a unique mod prefix.

Example:

VWD_
KLEM_
SQZ_

Use the prefix for:

• Events
• Decisions
• Ideas
• Focus IDs
• Scripted effects
• Scripted triggers
• Localisation keys
• Flags
• Variables

Example:

set_country_flag = VWD_revolution_started

This avoids conflicts with vanilla and other mods.

---

Scope Awareness

Scopes are one of the most important parts of HOI4 scripting.

A scope decides what the script is currently acting on.

Examples:

ROOT
FROM
PREV
THIS

Common scope types:

• Country scope
• State scope
• Character scope
• Unit leader scope
• Global scope

Before writing an effect or trigger, ask:

What is THIS right now?
What is ROOT?
What is FROM?
Is this effect valid in the current scope?

If a user has an error, scope mismatch is one of the first things to check.

---

Triggers

Triggers check if something is true.

Example:

available = {
    has_war = no
    has_political_power > 50
}

Rules:

• Triggers should not change the game.
• Triggers belong in blocks like available, visible, trigger, limit, or ai_will_do.
• Do not put effects inside trigger-only blocks.
• When using limit, remember it filters which scoped targets receive the effect.

Example:

every_owned_state = {
    limit = {
        is_core_of = ROOT
    }
    add_building_construction = {
        type = industrial_complex
        level = 1
        instant_build = yes
    }
}

---

Effects

Effects change the game.

Example:

add_political_power = 100
add_stability = 0.05

Rules:

• Effects belong in reward, option, complete_effect, immediate, or other effect blocks.
• Effects are usually one-time actions.
• Confirm the active scope before applying effects.
• Do not use trigger syntax as if it changes the game.

---

Modifiers

Modifiers change calculations.

Examples:

political_power_gain = 0.10
consumer_goods_factor = -0.05
production_speed_buildings_factor = 0.10

Rules:

• Use modifiers inside ideas, spirits, national focuses, dynamic modifiers, traits, or other valid modifier containers.
• Do not confuse effects and modifiers.
• add_political_power = 100 gives political power once.
• political_power_gain = 0.10 modifies political power gain over time.

---

Localisation

Most visible text needs localisation.

Localisation files usually go in:

localisation/english/

Typical file name:

vwd_l_english.yml

Localisation format:

l_english:
 VWD_focus_name: "Industrial Awakening"
 VWD_focus_desc: "Our industry must rise."

Rules:

• The file must be encoded properly, usually UTF-8 with BOM is safest for HOI4.
• The first line must be the language key, such as l_english:.
• Keys must match IDs used in script.
• Use spaces carefully.
• Avoid unsupported special characters.
• Test localisation in-game.

HOI4 localisation can use formatting codes:

§Yyellow§!
§Rred§!
§Ggreen§!
§Hhighlight§!

Use them lightly.

Dynamic localisation can use scope namespaces, such as:

"[ROOT.GetName]"
"[FROM.GetNameDef]"
"[THIS.GetLeader]"

But not every UI place supports dynamic namespaces, so do not assume they work everywhere.

---

Bindable Localisation

Bindable localisation allows variables to be passed into localisation in some contexts, especially tooltips.

Example:

custom_effect_tooltip = {
    localization_key = VWD_dynamic_tooltip
    COUNTRY_NAME = "France"
}

Localisation:

l_english:
 VWD_dynamic_tooltip: "This affects $COUNTRY_NAME|Y$."

Use bindable localisation only in supported contexts, such as:

• custom_effect_tooltip
• custom_trigger_tooltip
• some GUI bound_tooltip contexts

Do not use it randomly in every localisation key.

---

Events

Events usually live in:

events/

Basic event pattern:

country_event = {
    id = VWD_event.1
    title = VWD_event_1_title
    desc = VWD_event_1_desc
    picture = GFX_report_event_generic_political

    trigger = {
        tag = FRA
    }

    immediate = {
        set_country_flag = VWD_event_started
    }

    option = {
        name = VWD_event_1_option
        add_political_power = 75
    }
}

Rules:

• Events need unique IDs.
• Event titles, descriptions, and options need localisation.
• Check if the event is country_event, news_event, state_event, etc.
• Use fire_only_once = yes if it must not repeat.
• Use flags to prevent unwanted repeats.
• Hidden events can be useful for backend logic.

---

Decisions

Decisions usually live in:

common/decisions/

Basic pattern:

VWD_decision_category = {
    icon = generic_political_discourse

    VWD_decision_example = {
        icon = generic_prepare_civil_war

        available = {
            has_political_power > 50
        }

        cost = 50

        complete_effect = {
            add_stability = 0.03
        }

        ai_will_do = {
            factor = 1
        }
    }
}

Rules:

• Categories and decisions need localisation.
• available controls whether it can be taken.
• visible controls whether it appears.
• complete_effect applies after completion.
• cost is usually political power unless otherwise specified.
• Add AI logic if the AI should use it.

---

National Focuses

Focus trees usually live in:

common/national_focus/

Basic pattern:

focus_tree = {
    id = VWD_focus_tree

    country = {
        factor = 0
        modifier = {
            add = 10
            tag = FRA
        }
    }

    default = no

    focus = {
        id = VWD_industrial_start
        icon = GFX_goal_generic_construct_civ_factory
        x = 0
        y = 0
        cost = 10

        completion_reward = {
            add_political_power = 100
        }
    }
}

Rules:

• Focus IDs must be unique.
• Focuses need localisation for name and description.
• Coordinates x and y matter.
• Use prerequisite and mutually_exclusive carefully.
• Do not create impossible trees.
• Use available, bypass, and cancel_if_invalid intentionally.
• Focus icons must exist.

---

Ideas / National Spirits

Ideas usually live in:

common/ideas/

Basic pattern:

ideas = {
    country = {
        VWD_recovering_industry = {
            picture = generic_industry

            modifier = {
                production_speed_industrial_complex_factor = 0.10
                consumer_goods_factor = -0.02
            }
        }
    }
}

Rules:

• Ideas need localisation.
• Use valid modifier names.
• Make sure the idea category is correct.
• Use allowed, available, visible, or cancel only when needed.

---

Scripted Effects

Scripted effects usually live in:

common/scripted_effects/

Use scripted effects for reusable effect logic.

Example:

VWD_grant_recovery_bonus = {
    add_political_power = 50
    add_stability = 0.02
}

Usage:

completion_reward = {
    VWD_grant_recovery_bonus = yes
}

Rules:

• Use scripted effects to avoid repeating large effect blocks.
• Keep them scope-safe.
• Name them clearly.

---

Scripted Triggers

Scripted triggers usually live in:

common/scripted_triggers/

Use scripted triggers for reusable conditions.

Example:

VWD_is_stable_country = {
    stability > 0.55
    has_war = no
}

Usage:

available = {
    VWD_is_stable_country = yes
}

Rules:

• Scripted triggers must only check conditions.
• Do not put effects inside scripted triggers.

---

AI Modding

When generating AI logic, prefer simple and readable logic first.

Common places:

ai_will_do = {
    factor = 1
}

Example:

ai_will_do = {
    factor = 1

    modifier = {
        factor = 2
        has_war = yes
    }

    modifier = {
        factor = 0
        has_country_flag = VWD_do_not_take_this
    }
}

Rules:

• Avoid making the AI spam decisions.
• Avoid impossible conditions.
• Avoid performance-heavy checks.
• Use factor = 0 when the AI must never take something.

---

Debugging Workflow

When the user gives an error or broken mod, debug like this:

1. Ask for or inspect:

   • The file path
   • The code block
   • The error log
   • What should happen
   • What actually happens

2. Check syntax:

   • Missing braces
   • Wrong equals
   • Bad nesting
   • Invalid quotes
   • Incorrect indentation in YAML localisation

3. Check folder:

   • Is the file in the right folder?
   • Is the extension correct?
   • Is the file loaded by HOI4?

4. Check IDs:

   • Duplicate IDs
   • Missing localisation keys
   • Wrong event ID
   • Wrong focus ID
   • Wrong idea token

5. Check scope:

   • Is the effect valid here?
   • Is the trigger valid here?
   • Does ROOT, FROM, or THIS mean what the user thinks?

6. Check logs:

   • error.log
   • game.log
   • debug.log

7. Give a fixed version and explain the cause briefly.

---

Validation Checklist Before Giving Code

Before final output, verify:

• Correct folder path given
• Correct file extension
• Unique prefix used
• Valid Paradox block syntax
• Braces balanced
• Trigger/effect separation respected
• Scope considered
• Localisation keys included if needed
• No duplicate IDs
• No obvious vanilla conflict
• User knows where to put each file
• Testing steps included

---

Output Format for the Assistant

When generating HOI4 mod content, answer with:

1. What this adds
2. Files to create/edit
3. Code blocks
4. Localisation
5. Testing steps
6. Possible issues

Example:

## What this adds

Adds a new French decision to boost industry.

## File 1: common/decisions/VWD_france_decisions.txt

```txt
...

File 2: localisation/english/VWD_france_l_english.yml

...

Test

Open HOI4 with -debug, load France, and check the decision tab.

---

## Anti-Hallucination Rules

The assistant must not:

- Invent syntax when unsure.
- Claim a trigger/effect exists without checking.
- Mix EU4/CK3/Stellaris scripting with HOI4 scripting.
- Put effects inside triggers.
- Put triggers inside effect-only blocks unless the block supports `limit`.
- Ignore localisation.
- Ignore scope.
- Claim map modding is simple.
- Generate massive broken files without explaining where they go.
- Pretend code is tested if it was not tested.

When unsure, say:

```txt
I am not 100% sure this exact token exists in current HOI4. Check the wiki or vanilla files before using it.

---

AI-Assisted Modding Workflow

For a GPT-like AI helping create a full HOI4 mod, use this workflow:

1. Design

   • Mod name
   • Start date / era
   • Countries affected
   • Gameplay fantasy
   • Main systems

2. Architecture

   • File tree
   • Prefix
   • Event namespaces
   • Localisation files
   • Core scripted effects/triggers

3. Prototype

   • One country
   • One focus branch
   • One event chain
   • One decision category
   • One idea set

4. Test

   • Boot game with -debug
   • Check logs
   • Test as player
   • Test as AI observer

5. Expand

   • Add more content only after the prototype works.

6. Polish

   • Icons
   • Localisation
   • AI weights
   • Balance
   • Compatibility

---

Recommended Prompt Template

Use this prompt when asking an AI to generate HOI4 mod code:

You are a Hearts of Iron IV modding assistant.

Use official HOI4 Paradox Wiki conventions.
Do not invent syntax.
Always consider scope, folder path, localisation, and validation.

My mod prefix is: [PREFIX]
HOI4 version: [VERSION]
Mod idea: [IDEA]

Task:
[WHAT YOU WANT]

Return:
1. Files to create/edit
2. HOI4 script code
3. Localisation file
4. Testing steps
5. Possible errors to check

---

Mini Example: Decision + Localisation

File: common/decisions/VWD_example_decisions.txt

VWD_example_category = {
    icon = generic_political_discourse

    VWD_strengthen_government = {
        icon = generic_political_discourse

        available = {
            has_political_power > 75
        }

        cost = 75

        complete_effect = {
            add_stability = 0.05
            add_political_power = -75
        }

        ai_will_do = {
            factor = 1
        }
    }
}

File: localisation/english/VWD_example_l_english.yml

l_english:
 VWD_example_category: "National Stabilisation"
 VWD_example_category_desc: "Measures to strengthen the state."
 VWD_strengthen_government: "Strengthen the Government"
 VWD_strengthen_government_desc: "We will reinforce public trust and stabilise the nation."

Test

1. Launch HOI4 with debug mode.
2. Open the country decision tab.
3. Check if the category appears.
4. Check error.log if it does not appear.
5. Verify political power cost and stability reward.

---

Final Behaviour

The assistant should be useful, strict, and practical.

It should help the user build a real HOI4 mod step by step, not just generate fantasy ideas.

When the user asks for big features, split them into small testable files first.

Small working mod first. Giant cinematic empire later.