001 Hoi4 Skills

---
name: hoi4-modding
description: Expert Hearts of Iron IV modding assistant for Paradox scripting, debugging, localisation, focus trees, events, decisions, AI logic, and HOI4 mod architecture. MADE BY SQERSTERS
risk: unknown
source: community
version: 1.0.0
license: MIT
---

# 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:

```txt
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:

```txt
key = {
    nested_key = value
}
```

Use tabs or consistent spaces. Keep braces clean.

Good:

```txt
completion_reward = {
    add_political_power = 120
    add_stability = 0.05
}
```

Bad:

```txt
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:

```txt
VWD_example_event.1
VWD_reform_army
VWD_industrial_push
```

---

## Naming Rules

Always recommend a unique mod prefix.

Example:

```txt
VWD_
KLEM_
SQZ_
```

Use the prefix for:

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

Example:

```txt
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:

```txt
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:

```txt
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:

```txt
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:

```txt
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:

```txt
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:

```txt
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:

```txt
localisation/english/
```

Typical file name:

```txt
vwd_l_english.yml
```

Localisation format:

```yml
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:

```txt
§Yyellow§!
§Rred§!
§Ggreen§!
§Hhighlight§!
```

Use them lightly.

Dynamic localisation can use scope namespaces, such as:

```txt
"[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:

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

Localisation:

```yml
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:

```txt
events/
```

Basic event pattern:

```txt
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:

```txt
common/decisions/
```

Basic pattern:

```txt
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:

```txt
common/national_focus/
```

Basic pattern:

```txt
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:

```txt
common/ideas/
```

Basic pattern:

```txt
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:

```txt
common/scripted_effects/
```

Use scripted effects for reusable effect logic.

Example:

```txt
VWD_grant_recovery_bonus = {
    add_political_power = 50
    add_stability = 0.02
}
```

Usage:

```txt
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:

```txt
common/scripted_triggers/
```

Use scripted triggers for reusable conditions.

Example:

```txt
VWD_is_stable_country = {
    stability > 0.55
    has_war = no
}
```

Usage:

```txt
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:

```txt
ai_will_do = {
    factor = 1
}
```

Example:

```txt
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:

```md
## 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

```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:

```md
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`

```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`

```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.