### Define bookmarks

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Sets up game start scenarios including date, description, and available countries.

```jsonl
{"bookmarks": [{"_file": "my_bookmark", "bookmark": {"name": "MY_BOOKMARK", "desc": "MY_BOOKMARK_DESC", "date": "1936.1.1", "picture": "GFX_select_date_1936", "default_country": "GER", "default": true, "country": ["GER", "FRA", "ENG"]}}]}
```

--------------------------------

### Basic hoi4yaml Usage Examples

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/README.md

Demonstrates common command-line operations for hoi4yaml, including generating mod files, cleaning output, validating files, and listing available sections.

```bash
hoi4yaml mod.jsonl          # generate mod files
hoi4yaml mod.jsonl --clean  # clean output first
hoi4yaml mod.jsonl --check  # validate only
hoi4yaml --list             # show all sections, shorthands, and validations
```

--------------------------------

### Install hoi4yaml using pip

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/README.md

Installs the hoi4yaml package from GitHub using pip. This command requires Python and pip to be installed on your system.

```bash
pip install git+https://github.com/maebahesioru/hoi4yaml.git
```

--------------------------------

### Common Modding Pitfalls

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Examples addressing common errors such as wrapping opinion modifiers, handling multiple blocks, and correct ID usage.

```jsonl
{"opinion_modifiers": [{"_file": "my_file", "_wrap": "opinion_modifiers", "my_modifier": {"value": 30}}]}
{"add_opinion_modifier": [{"target": "ETH", "modifier": "X"}, {"target": "SAF", "modifier": "X"}]}
{"events": [{"_file": "my_events", "_namespace": "my_mod", "country_event": [{"id": "my_mod.1"}]}]}
{"history_countries": [{"_file": "GER", "capital": 11650}]}
{"add_core_of": "GER"}
{"add_core": 64}
```

--------------------------------

### Define complete minimal mod structure

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

A comprehensive example demonstrating how to define mod metadata, national focuses, ideas, decisions, characters, events, opinion modifiers, country history, and localisation using JSONL.

```jsonl
{"mod": {"name": "My First Mod", "version": "1.0", "supported_version": "1.14.*"}}
{"national_focus": [{"_file": "GER_focuses", "focus_tree": {"id": "GER_focus_tree", "country": {"factor": 0, "modifier": {"add": 10, "tag": "GER"}}, "focus": [{"id": "GER_rearm", "x": 0, "y": 0, "cost": 10, "reward": {"add_political_power": 100}}]}}]}
{"ideas": [{"_file": "GER_ideas", "_category": "country", "GER_war_economy": {"picture": "generic_production_bonus", "removal_cost": -1, "modifier": {"industrial_capacity_factory": 0.1}}}]}
{"decisions": [{"_file": "GER_decisions", "GER_political": {"GER_rally_the_nation": {"icon": "generic_political_discourse", "cost": 50, "days_remove": 30, "available": {"tag": "GER"}, "complete_effect": {"add_stability": 0.05}}}}]}
{"characters": [{"_file": "GER_characters", "_wrap": "characters", "GER_hitler": {"name": "Adolf Hitler", "portraits": {"civilian": {"large": "GFX_portrait_GER_Hitler"}}, "country_leader": {"ideology": "nazism", "traits": ["dictator"]}}}]}
{"events": [{"_file": "GER_events", "country_event": [{"id": "GER_events.1", "is_triggered_only": true, "option": [{"name": "GER_events.1.a", "add_political_power": 50}]}]}]}
{"opinion_modifiers": [{"_file": "GER_opinion_modifiers", "_wrap": "opinion_modifiers", "GER_rival": {"value": -30, "decay": 1, "min": -30}}]}
{"history_countries": [{"_file": "GER", "capital": 11650, "set_tech": ["infantry_weapons", "tech_support"], "set_ruling_party": "fascism", "add_pop": {"fascism": 0.5}, "recruit_character": "GER_hitler"}]}
{"localisation": {"english": {"GER_rearm": "Rearmament", "GER_rearm_desc": "Germany begins its secret rearmament program.", "GER_war_economy": "War Economy", "GER_war_economy_desc": "The nation's industry is geared toward military production.", "GER_rally_the_nation": "Rally the Nation", "GER_rally_the_nation_desc": "A nationwide rally to boost morale.", "GER_events.1.t": "A New Dawn", "GER_events.1.d": "Germany stands at a crossroads.", "GER_events.1.a": "Press forward.", "GER_hitler": "Adolf Hitler", "GER_rival": "Rival Nation"}}}
```

--------------------------------

### Define a minimal working mod structure

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Demonstrates a comprehensive example of a mod definition using JSONL. It includes national focuses, ideas, events, characters, country history, and localisation keys.

```jsonl
{"mod": {"name": "My First Mod", "version": "1.0", "supported_version": "1.14.*"}}
{"national_focus": [{"_file": "GER_focuses", "focus_tree": {"id": "GER_focus_tree", "country": {"factor": 0, "modifier": {"add": 10, "tag": "GER"}}, "focus": [{"id": "GER_rearm", "x": 0, "y": 0, "cost": 10, "reward": {"add_political_power": 100}}, {"id": "GER_expand", "prereq": "GER_rearm", "cost": 10, "reward": {"army_experience": 50}}]}}]}
{"ideas": [{"_file": "GER_ideas", "_category": "country", "GER_war_economy": {"removal_cost": -1, "modifier": {"industrial_capacity_factory": 0.1}}}]}
{"events": [{"_file": "GER_events", "country_event": [{"id": "GER_events.1", "is_triggered_only": true, "option": [{"name": "GER_events.1.a", "add_political_power": 50}]}]}]}
{"characters": [{"_file": "GER_characters", "_wrap": "characters", "GER_leader": {"name": "Leader Name", "portraits": {"civilian": {"large": "GFX_portrait_GER_generic"}}, "country_leader": {"ideology": "fascism_ideology", "traits": ["dictator"]}}}]}
{"history_countries": [{"_file": "GER", "capital": 11650, "set_tech": ["infantry_weapons"], "set_ruling_party": "fascism", "recruit_character": "GER_leader"}]}
{"localisation": {"english": {"GER_rearm": "Rearmament", "GER_rearm_desc": "Rebuild military strength.", "GER_expand": "Expand Forces", "GER_expand_desc": "Grow the army.", "GER_war_economy": "War Economy", "GER_events.1.t": "New Dawn", "GER_events.1.d": "A new era begins.", "GER_events.1.a": "Press forward."}}}
```

--------------------------------

### Define Game History and Entities

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Examples of defining historical data such as countries, states, units, opinion modifiers, characters, technologies, and interface sprites using JSONL.

```jsonl
{"history_countries": [{"_file": "GER", "capital": 11650, "set_tech": ["infantry_weapons", "tech_support"], "set_ruling_party": "fascism", "add_pop": {"fascism": 0.3}}]}
{"history_states": [{"_file": "64_berlin", "state": {"id": 64, "name": "STATE_64", "history": {"owner": "GER", "add_core_of": "GER"}}}]}
{"history_units": [{"_file": "GER_1936", "division_template": [{"name": "Infantry Division", "regiments": [{"infantry": 9}, {"artillery_brigade": 1}], "support_companies": [{"engineer": 1}]}]}]}
```

```jsonl
{"opinion_modifiers": [{"_file": "my_opinion_modifiers", "_wrap": "opinion_modifiers", "my_modifier": {"value": 30, "decay": 1, "max": 30}}]}
```

```jsonl
{"characters": [{"_file": "my_characters", "_wrap": "characters", "GER_leader": {"name": "Adolf Hitler", "portraits": {"civilian": {"large": "GFX_portrait_GER_hitler"}}, "country_leader": {"ideology": "nazism", "traits": ["dictator"]}}}]}
```

```jsonl
{"technologies": [{"_file": "my_techs", "my_tech": {"research_cost": 1.5, "start_year": 1936, "folder": {"name": "infantry_folder", "position": {"x": 0, "y": 0}}, "path": [{"leads_to_tech": "my_tech_2", "research_cost_factor": 1}], "categories": ["infantry"], "on_research_complete": {"add_political_power": 50}}}]}
```

```jsonl
{"interface": [{"_file": "my_interface", "sprites": [{"name": "GFX_my_sprite", "texturefile": "gfx/interface/my_sprite.dds"}]}]}
```

--------------------------------

### Quick Example of JSONL Structure for HoI4 Modding

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/README.md

Illustrates the basic JSONL format for defining mod properties, focus trees, and focuses with inline localization. Each line represents a self-contained JSON object.

```jsonl
{"mod":{"name":"My Mod","version":"1.0","supported_version":"1.14.*"}}
{"focus_tree":{"_file":"GER_focuses","id":"GER_focus_tree","country":{"factor":0,"modifier":{"add":10,"tag":"GER"}}}}
{"focus":{"id":"GER_rearm","cost":10,"reward":{"add_political_power":100}},"loc":{"GER_rearm":"Rearmament","GER_rearm_desc":"Germany begins its rearmament."}}
```

--------------------------------

### JSONL Format with Inline Localization (English and Japanese)

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/README.md

Shows detailed JSONL examples for a focus tree, an idea, and an event, all including inline localization for multiple languages. This format allows for direct translation within the data.

```jsonl
// Focus with inline loc (English + Japanese)
{"focus":{"id":"GER_rearm","prereq":"GER_start","cost":10,"reward":{"add_political_power":100}},"loc":{"GER_rearm":"Rearmament","GER_rearm_desc":"Begin rearmament.","ja":{"GER_rearm":"再軍備","GER_rearm_desc":"再軍備を開始する。"}}}

// Idea with inline loc
{"idea":{"GER_spirit_militarism":{"modifier":{"army_attack_factor":0.1}}},"loc":{"GER_spirit_militarism":"Militarism","GER_spirit_militarism_desc":"A strong military tradition."}}

// Event with inline loc
{"country_event":{"id":"GER.1","title":"GER.1.t","desc":"GER.1.d","option":[{"name":"GER.1.a","add_political_power":50}]},"loc":{"GER.1.t":"Event Title","GER.1.d":"Event description.","GER.1.a":"Option A"}}
```

--------------------------------

### Define Timed Idea with JSONL

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Defines a timed idea that grants a specific idea for a set duration. The 'days' value is informational; 'days_remove' must be set in the idea definition. Also shows an example of adding state buildings.

```jsonl
{"reward": {"timed_idea": {"idea": "my_timed_idea", "days": 180}}}
```

```jsonl
{"add_state_building": {"state_id": 64, "type": "industrial_complex", "level": 3}}
```

--------------------------------

### Reference other mods using mod_paths in hoi4yaml

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

The `mod_paths` option within a `mod` object allows hoi4yaml to load definitions (GFX keys, traits, states, etc.) from other installed mods. This helps suppress validation warnings when your mod depends on assets from other mods. The paths provided should point to the root directory of the other mods.

```jsonl
{"mod": {"name": "My Mod", "mod_paths": ["/mnt/c/Users/me/Documents/Paradox Interactive/Hearts of Iron IV/mod/kaiserreich", "/mnt/c/Users/me/Documents/Paradox Interactive/Hearts of Iron IV/mod/road_to_56"]}}
```

--------------------------------

### Variable Substitution

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Demonstrates the use of $VAR syntax to dynamically inject values into keys and file definitions.

```jsonl
{"vars": {"TAG": "GER", "PREFIX": "ger"}}
{"national_focus": [{"_file": "$TAG_focuses", "_namespace": "$PREFIX", "focus_tree": {"focus": [{"id": "$PREFIX_first_focus"}]}}]}
```

--------------------------------

### Variables and Templates

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Utilize variables and templates to reduce redundancy in focus tree definitions.

```jsonl
{"vars": {"TAG": "GER", "PREFIX": "ger_focus"}}
{"templates": {"standard_focus": {"cost": 10, "ai_will_do": 1}}}
{"national_focus": [{"_file": "$TAG_focuses", "focus_tree": {"focus": [{"id": "$PREFIX_first", "_template": "standard_focus", "x": 0, "y": 0, "reward": {"add_political_power": 100}}]}}]}
```

--------------------------------

### Name Resolution and State Building

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Demonstrates how the tool resolves human-readable names to IDs and handles state building operations.

```jsonl
{"add_state_building": {"state": "berlin", "type": "industrial_complex", "level": 3}}
{"add_opinion_modifier": {"target": "ethiopia", "modifier": "my_modifier"}}
{"owner": "germany"}
```

```jsonl
{"reward": {"add_state_building": {"state": "berlin", "type": "industrial_complex", "level": 3, "instant": true}, "add_state_manpower": {"state": 64, "value": 10000}}}
```

--------------------------------

### Use Prerequisite Shorthands

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Simplifies complex Clausewitz prerequisite syntax using shorthand keys for AND/OR logic.

```json
{"focus":{"id":"GER_expand","prereq":"GER_rearm","cost":10}}
{"focus":{"id":"GER_final","prereq":["GER_army","GER_navy"],"cost":10}}
{"focus":{"id":"GER_choice","prereq_or":["GER_path_a","GER_path_b"],"cost":10}}
```

--------------------------------

### Event Namespace Configuration

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Shows how to define event files. If the _namespace key is omitted, it defaults to the value of the _file key.

```jsonl
{"events": [{"_file": "my_events", "country_event": [{"id": "my_events.1"}]}]}
```

--------------------------------

### CLI Usage and Flags

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Lists available command-line interface flags for generating, validating, importing, and managing mod files.

```bash
hoi4yaml mod.jsonl                    # generate
hoi4yaml mod.jsonl --clean            # delete output dir first
hoi4yaml mod.jsonl --check            # validate only, no output
hoi4yaml mod.jsonl --validate         # same as --check
hoi4yaml mod.jsonl --diff             # write changed files only
hoi4yaml mod.jsonl --dry-run          # show what would be written, no output
hoi4yaml mod.jsonl --zip              # generate + zip archive
hoi4yaml mod.jsonl --watch            # watch for file changes, regenerate automatically
hoi4yaml mod.jsonl --output ./dist    # set output directory (default: ./output)
hoi4yaml a.yaml b.yaml               # merge multiple YAML files into one mod
hoi4yaml --list                      # show all sections, shorthands, validations
hoi4yaml --list-states japan         # search state IDs by name
hoi4yaml --list-countries ger        # search country TAGs by name
hoi4yaml --import path/to/dir        # convert Clausewitz files → YAML
hoi4yaml --init                      # create mod.jsonl scaffold
```

--------------------------------

### Define Focus Trees with Auto-Layout

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Shows how to define focus trees where x/y coordinates are automatically calculated and icons are guessed based on ID keywords.

```json
{"national_focus": [{"_file": "my_focuses", "focus_tree": {"id": "my_tree", "country": {"factor": 0, "modifier": {"add": 10, "tag": "GER"}}, "focus": [{"id": "GER_focus_1", "cost": 10, "prereq": ["GER_start"], "reward": {"add_political_power": 100}}]}}]}
```

--------------------------------

### Search Game Data and Import Mods

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

CLI utilities for looking up state IDs, country tags, and importing existing Clausewitz-formatted mods into YAML.

```bash
hoi4yaml --list
hoi4yaml --list-states japan
hoi4yaml --list-countries ger
hoi4yaml --import path/to/mod/dir
hoi4yaml --init
```

--------------------------------

### Define technologies

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Defines custom technology trees, research costs, folders, and completion effects.

```jsonl
{"technologies": [{"_file": "my_infantry_techs", "my_infantry_1": {"research_cost": 1.0, "start_year": 1936, "folder": {"name": "infantry_folder", "position": {"x": 0, "y": 0}}, "path": [{"leads_to_tech": "my_infantry_2", "research_cost_factor": 1}], "categories": ["infantry_weapons"], "on_research_complete": {"add_political_power": 25}}, "my_infantry_2": {"research_cost": 1.5, "start_year": 1938, "folder": {"name": "infantry_folder", "position": {"x": 0, "y": 2}}, "categories": ["infantry_weapons"]}}]}
```

--------------------------------

### Use conditional entries

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Demonstrates the use of _if keys to conditionally include data based on variables.

```jsonl
{"vars": {"DEBUG": false}}
{"national_focus": [{"_file": "GER_focuses", "focus_tree": {"focus": [{"id": "GER_focus_1", "x": 0, "y": 0, "reward": {"add_political_power": 100}}, {"_if": "$DEBUG", "id": "GER_debug_focus", "x": 0, "y": 1}]}}]}
```

--------------------------------

### Prerequisite Logic

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Defines logical requirements for game objects. prereq acts as an AND condition, while prereq_or acts as an OR condition.

```jsonl
{"prereq": ["A", "B"]}
{"prereq_or": ["A", "B"]}
```

--------------------------------

### Use Variables and Templates

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Utilizes variable substitution and template inheritance to reduce redundancy in mod files. Templates are merged into entries referencing them via the _template key.

```jsonl
{"vars": {"TAG": "GER", "PREFIX": "ger_focus", "COST": 10}}
{"national_focus": [{"_file": "$TAG_focuses", "focus_tree": {"focus": [{"id": "$PREFIX_first", "cost": "$COST", "reward": {"add_political_power": 100}}]}}]}
{"templates": {"standard_focus": {"cost": 10, "ai_will_do": 1}}}
{"national_focus": [{"_file": "GER_focuses", "focus_tree": {"focus": [{"id": "GER_first", "_template": "standard_focus", "reward": {"add_political_power": 100}}]}}]}
```

--------------------------------

### Define Game Events

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Shorthand structure for defining country, news, and state events. Requires a namespace and file definition for proper output generation.

```jsonl
{"events": [{"_file": "my_events", "_namespace": "my_mod", "country_event": [{"id": "my_mod.1", "is_triggered_only": true, "option": [{"name": "my_mod.1.a", "add_political_power": 50}]}], "news_event": [{"id": "my_mod.2", "is_triggered_only": true, "option": [{"name": "my_mod.2.a"}]}], "state_event": [{"id": "my_mod.3", "is_triggered_only": true, "option": [{"name": "my_mod.3.a"}]}]}]}
```

--------------------------------

### Use Scripted Triggers and Effects in JSONL

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Demonstrates how to use previously defined scripted triggers and effects within other game mechanics, such as rewards or general triggers.

```jsonl
{"reward": {"my_boost_industry": true}}
```

```jsonl
{"trigger": {"my_is_major_democracy": true}}
```

--------------------------------

### Define Technologies

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Configures research technologies with costs, categories, and tree positioning. Requires folder or path definitions to be visible in the game's research interface.

```jsonl
{"technologies": [{"_file": "my_techs", "my_infantry_1": {"research_cost": 1.0, "start_year": 1936, "folder": {"name": "infantry_folder", "position": {"x": 0, "y": 0}}, "path": [{"leads_to_tech": "my_infantry_2", "research_cost_factor": 1}], "categories": ["infantry_weapons"], "on_research_complete": {"add_political_power": 25}}}]}
```

--------------------------------

### Define Localisation Data

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Demonstrates the structure for defining game localisation keys. Supports multiple languages with English as the base and overrides for specific languages.

```jsonl
{"localisation": {"english": {"MY_key": "My Text"}, "japanese": {"MY_key": "テキスト"}}}
```

--------------------------------

### Implement Inline Localisation

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Demonstrates how to provide English localisation at the top level and nested language-specific overrides.

```json
{"focus":{"id":"GER_rearm"},"loc":{"GER_rearm":"Rearmament","GER_rearm_desc":"Begin rearmament.","ja":{"GER_rearm":"再軍備","GER_rearm_desc":"再軍備を開始する。"}}}
```

--------------------------------

### Configure mod_paths for cross-mod referencing

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Configures the project to load data from external mods. This prevents false validation warnings by allowing the tool to resolve GFX keys, traits, and localisation from dependencies.

```jsonl
{"mod": {"name": "My Mod", "mod_paths": ["/path/to/kaiserreich", "/path/to/road_to_56"]}}
```

--------------------------------

### Wargoal Definition

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Defines custom wargoals and demonstrates how to trigger them using the create_wargoal effect.

```jsonl
{"wargoals": [{"_file": "my_wargoals", "my_wargoal": {"icon": "generic_conquest", "allowed": {"always": true}, "available": {"has_war": false}, "ai_will_do": {"factor": 1}, "on_add": {"add_political_power": -50}, "peace_options": ["transfer_state", "puppet"]}}]}
{"reward": {"create_wargoal": {"type": "my_wargoal", "target": "FRA"}}}
```

--------------------------------

### Import Clausewitz files to YAML with hoi4yaml

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

The `hoi4yaml --import` command converts Clausewitz game files (like .txt) into a YAML format. Each input file is represented as a top-level key in the output JSON Lines file. Manual cleanup of the generated YAML may be necessary.

```bash
hoi4yaml --import path/to/dir
```

--------------------------------

### Generate and Manage Mod Files via CLI

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Commands to generate, validate, and manage HoI4 mod files from input data. Supports various flags for incremental builds, dry runs, and directory management.

```bash
hoi4yaml mod.jsonl
hoi4yaml mod.jsonl --clean
hoi4yaml mod.jsonl --check
hoi4yaml mod.jsonl --diff
hoi4yaml mod.jsonl --dry-run
hoi4yaml mod.jsonl --zip
hoi4yaml mod.jsonl --watch
hoi4yaml mod.jsonl --output ./dist
hoi4yaml base.yaml focuses.yaml events.yaml
```

--------------------------------

### Define On Actions in JSONL

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Defines game actions that trigger on specific events, such as startup, monthly updates for a country, or winning a war. These actions can apply effects like political power or stability changes.

```jsonl
{"on_actions": [{"_file": "my_on_actions", "on_startup": {"effect": {"GER = { add_political_power": "50 }"}}, "on_monthly_GER": {"effect": {"add_political_power": 5}}, "on_war_won": {"effect": {"add_stability": 0.05}}}]}
```

--------------------------------

### Define History Files

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Handles country, state, and unit history definitions. Includes shorthands for technology, politics, state buildings, and division template layouts.

```jsonl
{"history_units": [{"_file": "GER_1936", "division_template": [{"name": "Infantry Division", "regiments": [{"infantry": 9}, {"artillery_brigade": 1}], "support_companies": [{"engineer": 1}, {"recon": 1}]}]}]}
```

--------------------------------

### Mod Path Referencing

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Allows the tool to reference external mod files to resolve validation warnings for GFX, traits, and localization.

```jsonl
{"mod": {"name": "My Mod", "mod_paths": ["C:/Users/.../mod/kaiserreich", "C:/Users/.../mod/road_to_56"]}}
```

--------------------------------

### Resolve Names and IDs

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Demonstrates automatic resolution of human-readable names to internal game IDs and tags using localisation files.

```jsonl
{"add_state_building": {"state": "berlin", "type": "industrial_complex", "level": 3}}
{"add_opinion_modifier": {"target": "ethiopia", "modifier": "my_modifier"}}
{"owner": "germany"}
{"capital": "Brandenburg"}
```

--------------------------------

### Define Focus Rewards with Shorthands

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Uses simplified JSON syntax to define focus rewards, which are automatically expanded into standard HOI4 script format. This reduces boilerplate for common operations like adding buildings or manpower.

```jsonl
{"focus":{"id":"GER_build","cost":10,"reward":{"add_state_building":{"state":"berlin","type":"industrial_complex","level":3,"instant":true},"add_state_manpower":{"state":"berlin","value":50000}}}}
```

--------------------------------

### Define National Focus Tree

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Shorthand structure for defining a national focus tree. Automatically calculates x/y coordinates, icons, and descriptions if omitted.

```jsonl
{"national_focus": [{"_file": "my_focuses", "focus_tree": {"id": "my_tree", "country": {"factor": 0, "modifier": {"add": 10, "tag": "GER"}}, "focus": [{"id": "GER_focus_1", "x": 0, "y": 0, "cost": 10, "prereq": ["A", "B"], "prereq_or": ["A", "B"], "rel_pos": "GER_focus_0", "reward": {"add_political_power": 100}, "ai_will_do": 5, "hidden": {"set_country_flag": "my_flag"}}]}}]}
```

--------------------------------

### Define Characters and Commanders

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Configures country leaders and military commanders including portraits, traits, and skill levels. Automatically wraps definitions into the required character file structure.

```jsonl
{"characters": [{"_file": "my_characters", "_wrap": "characters", "GER_rommel": {"name": "Erwin Rommel", "portraits": {"army": {"large": "GFX_portrait_GER_rommel"}}, "field_marshal": {"traits": ["brilliant_strategist", "desert_fox"], "skill": 4, "attack_skill": 4, "defense_skill": 3, "planning_skill": 4, "logistics_skill": 3}}, "GER_guderian": {"name": "Heinz Guderian", "portraits": {"army": {"large": "GFX_portrait_GER_guderian"}}, "corps_commander": {"traits": ["panzer_leader"], "skill": 4, "attack_skill": 5, "defense_skill": 2, "planning_skill": 4, "logistics_skill": 3}}}]}
```

--------------------------------

### Define Country and News Events

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Creates game events with automatic namespace and localization key generation. Supports multiple event types including country, news, and state events within a single definition.

```jsonl
{"events": [{"_file": "my_events", "_namespace": "my_mod", "country_event": [{"id": "my_mod.1", "is_triggered_only": true, "option": [{"name": "my_mod.1.a"}]}], "news_event": [{"id": "my_mod.2", "is_triggered_only": true, "major": true, "option": [{"name": "my_mod.2.a"}]}], "state_event": [{"id": "my_mod.3", "is_triggered_only": true, "option": [{"name": "my_mod.3.a"}]}]}]}
```

--------------------------------

### Define sprites

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Defines interface sprites by mapping names to texture files.

```jsonl
{"interface": [{"_file": "my_interface", "sprites": [{"name": "GFX_my_focus", "texturefile": "gfx/interface/my_focus.dds"}, {"name": "GFX_my_idea", "texturefile": "gfx/interface/my_idea.dds"}]}]}
```

--------------------------------

### Define portraits

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Maps country leaders to specific portrait files for different roles.

```jsonl
{"portraits": [{"_file": "my_portraits", "GER": {"army": {"male": ["gfx/leaders/GER/portrait_ger_generic_1.dds", "gfx/leaders/GER/portrait_ger_generic_2.dds"]}, "civilian": {"male": ["gfx/leaders/GER/portrait_ger_civ_generic_1.dds"]}}}]}
```

--------------------------------

### Set Technology Effect

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Demonstrates how to apply the set_tech effect within a reward block. This can be used anywhere an effect is valid.

```jsonl
{"reward": {"set_tech": ["infantry_weapons", "tech_support"]}}
```

--------------------------------

### Define history states

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Configures state data including manpower, category, history, resources, and province mapping.

```jsonl
{"history_states": [{"_file": "64_berlin", "state": {"id": 64, "name": "STATE_64", "manpower": 500000, "state_category": "megalopolis", "history": {"owner": "GER", "controller": "GER", "add_core_of": "GER", "victory_points": [[11650, 10]], "buildings": {"infrastructure": 5, "industrial_complex": 3, "arms_factory": 2, "air_base": 2, "11650": {"naval_base": 3}}}, "resources": {"steel": 8, "aluminium": 4}, "provinces": [11650, 11651]}}]}
```

--------------------------------

### Define country colors

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Sets RGB colors for countries on the map and in the UI.

```jsonl
{"country_colors": [{"_file": "my_country_colors", "MY_TAG": {"color": [0.5, 0.2, 0.1], "color_ui": [0.6, 0.3, 0.2]}}]}
```

--------------------------------

### Define Country Ideas

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Shorthand structure for creating country ideas. The 'picture' field is auto-guessed based on the idea ID if not explicitly provided.

```jsonl
{"ideas": [{"_file": "my_ideas", "_category": "country", "my_idea": {"picture": "GFX_idea_my_idea", "removal_cost": -1, "modifier": {"stability_factor": 0.05}}}]}
```

--------------------------------

### Scripted Triggers, Effects, and On Actions

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Defines reusable scripted triggers, effects, and game event hooks (on_actions) to centralize logic for events and modifiers.

```jsonl
{"scripted_triggers": [{"_file": "my_triggers", "my_is_major_democracy": {"is_major": true, "has_government": "democratic"}}]}
{"scripted_effects": [{"_file": "my_effects", "my_boost_industry": {"add_ideas": "my_industry_spirit", "add_political_power": 50}}]}
{"on_actions": [{"_file": "my_on_actions", "on_startup": {"effect": {"every_country": {"add_political_power": 10}}}, "on_war": {"effect": {"add_stability": -0.05}}}]}
```

--------------------------------

### Define Unit Leaders (Field Marshal, Corps Commander, Navy Leader) in JSONL

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Defines various unit leaders with their names, portraits, traits, and skill levels. Supports field marshals, corps commanders, and navy leaders, each with specific skill attributes.

```jsonl
{"characters": [{"_file": "my_characters", "_wrap": "characters", "GER_rommel": {"name": "Erwin Rommel", "portraits": {"army": {"large": "GFX_portrait_GER_rommel"}}, "field_marshal": {"traits": ["brilliant_strategist", "desert_fox"], "skill": 4, "attack_skill": 4, "defense_skill": 3, "planning_skill": 4, "logistics_skill": 3}}, "GER_guderian": {"name": "Heinz Guderian", "portraits": {"army": {"large": "GFX_portrait_GER_guderian"}}, "corps_commander": {"traits": ["panzer_leader", "fast_planner"], "skill": 4, "attack_skill": 5, "defense_skill": 2, "planning_skill": 4, "logistics_skill": 3}}, "GER_raeder": {"name": "Erich Raeder", "portraits": {"navy": {"large": "GFX_portrait_GER_raeder"}}, "navy_leader": {"traits": ["fleet_in_being_expert"], "skill": 3, "attack_skill": 3, "defense_skill": 3, "maneuvering_skill": 2, "coordination_skill": 3}}}]}
```

--------------------------------

### Define Decisions in JSONL

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Defines game decisions, including their category, icon, cost, availability, visibility, effects, and AI weighting. This format allows for complex decision trees and effects.

```jsonl
{"decisions": [{"_file": "my_decisions", "my_category": {"my_decision": {"icon": "generic_political_discourse", "cost": 50, "days_remove": 60, "available": {"tag": "GER", "has_war": false}, "visible": {"tag": "GER"}, "modifier": {"stability_factor": 0.05}, "complete_effect": {"add_political_power": 25}, "remove_effect": {"add_stability": 0.05}, "ai_will_do": {"factor": 1}}}}]}
```

```jsonl
{"decisions_categories": [{"_file": "my_categories", "my_category": {"icon": "generic_political_discourse", "picture": "GFX_decision_cat_my_category"}}]}
```

--------------------------------

### Define Decisions and Categories

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Defines decision categories and individual decisions including costs, availability, visibility, and effects. These structures are used to populate the game's decision menu.

```jsonl
{"decisions_categories": [{"_file": "my_categories", "my_category": {"icon": "generic_political_discourse", "picture": "GFX_decision_cat_generic"}}]}
{"decisions": [{"_file": "my_decisions", "my_category": {"my_decision": {"icon": "generic_political_discourse", "cost": 50, "days_remove": 60, "available": {"tag": "GER", "has_war": false}, "visible": {"tag": "GER"}, "modifier": {"stability_factor": 0.05}, "complete_effect": {"add_political_power": 25}, "remove_effect": {"add_stability": 0.05}, "ai_will_do": {"factor": 1}}}}]}
```

--------------------------------

### Define Named Colors

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Configures custom colors for use in the mod. Colors are defined as RGB arrays.

```jsonl
{"named_colors": [{"_file": "my_colors", "my_color": {"color": [0.5, 0.2, 0.1]}}]}
```

--------------------------------

### Cosmetic Tags

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Defines cosmetic tags to change country names and flags without altering the underlying country TAG.

```jsonl
{"cosmetic_tags": [{"_file": "my_cosmetic_tags", "GER_GREATER_GERMANY": {"name": "GREATER_GERMANY", "adjective": "GREATER_GERMANY_ADJ", "flag": "GER_GREATER_GERMANY"}}]}
{"localisation": {"english": {"GREATER_GERMANY": "Greater Germany", "GREATER_GERMANY_ADJ": "Greater German"}}}
{"reward": {"set_cosmetic_tag": "GER_GREATER_GERMANY"}}
```

--------------------------------

### Define Scripted Triggers and Effects in JSONL

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Defines reusable scripted triggers and effects. Triggers are conditions that can be checked, while effects are actions that can be applied. These can be used in other game mechanics.

```jsonl
{"scripted_triggers": [{"_file": "my_triggers", "my_is_major_democracy": {"is_major": true, "has_government": "democratic"}}]}
```

```jsonl
{"scripted_effects": [{"_file": "my_effects", "my_boost_industry": {"add_ideas": "my_industry_spirit", "add_political_power": 50}}]}
```

--------------------------------

### Define dynamic modifiers

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Creates dynamic modifiers with conditional activation and removal triggers.

```jsonl
{"dynamic_modifiers": [{"_file": "my_dynamic_modifiers", "my_war_effort": {"icon": "GFX_idea_my_war_effort", "enable": {"has_war": true}, "remove": {"has_war": false}, "modifier": {"industrial_capacity_factory": {"var": "my_war_effort_bonus", "multiply": 1}}}}]}
```

--------------------------------

### Define autonomy levels

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Configures autonomy system levels and their associated modifiers and capabilities.

```jsonl
{"autonomy": [{"_file": "my_autonomy", "autonomy_free": {"min_level": 0, "max_level": 0, "manpower_influence": 0, "can_send_volunteers": true, "can_be_called_to_war": false, "modifier": {"autonomy_manpower_share": 0}}}]}
```

--------------------------------

### Define Sprites and GFX

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Defines UI sprite graphics for game elements like focuses or ideas, which are automatically expanded into the required HOI4 spriteType structures.

```jsonl
{"interface": [{"_file": "my_interface", "sprites": [{"name": "GFX_my_focus", "texturefile": "gfx/interface/focuses/my_focus.dds"}, {"name": "GFX_my_idea", "texturefile": "gfx/interface/ideas/my_idea.dds"}]}]}
```

--------------------------------

### Define AI Behavior with Conditions in HOI4 Script

Source: https://github.com/maebahesioru/hoi4yaml/blob/main/REFERENCE.md

Represents the expanded HOI4 script format for AI behavior defined with conditional modifiers. This format is generated from the JSONL input.

```hoi4script
ai_will_do = {
    factor = 1
    modifier = { factor = 2 has_war = yes }
    modifier = { factor = 0 tag = GER }
}
```

--------------------------------

### Configure AI Decision Making

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Defines complex AI behavior using conditional modifiers that determine the likelihood of the AI performing a specific action.

```jsonl
{"ai_will_do": {"factor": 1, "if": [{"has_war": true, "mult": 2}, {"tag": "GER", "mult": 0}]}}
```

--------------------------------

### Validate Mod Content

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Executes the built-in validation suite to check for errors such as invalid IDs, missing localisation, or incorrect usage of effects and triggers.

```bash
hoi4yaml mod.jsonl --check
```

--------------------------------

### Define National Ideas and Spirits

Source: https://context7.com/maebahesioru/hoi4yaml/llms.txt

Defines country ideas and political advisors with automatic picture guessing based on ID keywords. Supports categorization into different types like country spirits or high command.

```yaml
ideas:
  - _file: my_ideas
    ideas:
      country:
        my_spirit:
          picture: generic_production_bonus
          removal_cost: -1
          modifier:
            industrial_capacity_factory: 0.1
      political_advisor:
        my_advisor:
          picture: generic_political_advisor_europe_1
          traits:
            - smooth_talking_charmer
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.