A new Visual Studio Code extension for Hearts of Iron IV mod development, focused on ease of use, orchestration, and assisting the mod community and mod teams with a modern HOI4 modding toolset with multiple functions and uses.
A comprehensive Visual Studio Code extension for Hearts of Iron IV mod development. This extension provides a complete suite of visual editors, analyzers, and productivity tools for creating professional HOI4 mods.
Table of Contents
Installation
From VSIX File (Recommended)
- Download the latest
.vsix file from Releases
- Open VS Code
- Press
Ctrl+Shift+P and type Install from VSIX
- Select the downloaded file
- Reload VS Code when prompted
Quick Start
- Open your mod folder in VS Code (File > Open Folder)
- Look for the Shield icon in the Activity Bar (left sidebar)
- Click it to reveal all tools organized by category
- Start with Welcome / Help for an interactive guide
Visual Editors
Focus Tree Editor
Command: HOI4: Focus Tree Editor
A full visual editor for creating and modifying national focus trees with drag-and-drop functionality.
Opening the Editor
- Click Focus Tree Editor in the sidebar, or
- Press
Ctrl+Shift+P and type "Focus Tree Editor"
Main Interface
- Left Sidebar: List of all focus trees in your mod
- Center Canvas: Visual focus tree with draggable nodes
- Right Panel: Property editor for selected focus
Creating a New Focus Tree
- Click the + New Tree button
- Enter country tag (e.g.,
GER, ENG)
- Enter tree name
- Click Create
Adding Focuses
- Click Add Focus in toolbar, or
- Right-click on canvas and select "Add Focus Here", or
- Press A key to add at center
Editing Focus Properties
- Click a focus node to select it
- Edit properties in right panel:
- Focus ID: Internal identifier
- Name/Description: Click to edit localization
- Icon: GFX sprite name (with preview)
- X/Y Position: Grid coordinates
- Cost: Days to complete
- Prerequisites: Required focuses (AND groups, OR within groups)
- Mutually Exclusive: Blocking focuses
- Available/Bypass: Trigger conditions
- Completion Reward: Effects on completion
- AI Will Do: AI weighting
Moving Focuses
- Drag and drop focus nodes to reposition
- Position snaps to grid automatically
- Connections update in real-time
Linking Prerequisites
- Click Link Prerequisites button or press P
- Click the parent focus first
- Click the child focus
- Repeat for more connections
- Press Escape to exit link mode
For OR prerequisites (any one required), add multiple focuses to the same prerequisite group using the dropdown in the editor.
Linking Mutual Exclusives
- Click Link Exclusives button or press M
- Click first focus
- Click second focus
- Both focuses will block each other
Focus Tree Keyboard Shortcuts
| Key |
Action |
| A |
Add focus at center |
| P |
Toggle prerequisite linking mode |
| M |
Toggle exclusive linking mode |
| Delete |
Delete selected focus |
| Escape |
Cancel current operation |
Tips
- Focus positions use HOI4's grid system (each unit = 1 column/row)
- Focuses with
relative_position_id show calculated absolute positions
- Double-click a focus to quickly edit its name
- Use the zoom controls for large trees
Decision Editor
Command: HOI4: Decision Editor
Visual editor for creating and managing decisions with full support for all decision types.
Decision Types Supported (Work in Progress)
- Standard Decisions: Instant effect on activation
- Timed Decisions: Effect after countdown
- Timed Missions: AI-triggered with timeout
- Selectable Missions: Player-chosen missions
Main Interface
- Left Sidebar: File browser and decision list
- Center Panel: Decision list with categories
- Right Panel: Full property editor
Creating Decisions from Template
- Click Templates button
- Choose a template:
- War Goal Decision
- Political Action
- Timed Mission
- Economic Decision
- State Action
- Faction Interaction
- Select target category
- Click "Create from Template"
Manual Creation
- Click + Add button
- Select decision type
- Select category
- Edit properties in right panel
Editing Decisions
Select a decision to edit:
- Basic Info: ID, name, description, icon, category
- Cost and Timing: PP cost, days, re-enable delay
- Conditions: Allowed, Available, Visible triggers
- Targets: Fixed targets, target array, state targeting
- Effects: Complete, Remove, Timeout, Cancel effects
- AI: AI weighting and conditions
Icon Browser
- Click Browse... next to Icon field
- Search or scroll through available GFX sprites
- Click to preview, double-click to select
State Picker
For highlight_states:
- Click Pick States... button
- Search by ID or name
- Click states to select (multi-select)
- Click "Apply" to insert state list
In-Game Preview
Click Preview to see how the decision appears in-game UI, including icon display, name and description, cost and duration, and category placement.
Validation
- Click Validate to check for errors
- Automatic validation on save
- Shows missing localizations, invalid references
Search Across Files
- Click Search All button
- Enter search term
- Filter by type (flags, events, ideas, states)
- Click results to jump to that decision
Tech Tree Editor
Command: HOI4: Tech Tree Editor
Visual editor for technology trees with research time calculations.
Features
- Visual tech tree layout matching in-game view
- Drag-and-drop positioning
- Research time and cost editing
- Prerequisite linking
- Category management
- Icon preview
Usage
- Select a technology file
- Click technologies to edit properties
- Drag to reposition
- Link prerequisites by clicking connection mode
Technology Properties
- Research time and cost
- Start year
- Categories and folders
- Prerequisites
- Research bonuses
- Unlocked equipment/units
Map Editor
Command: HOI4: Open Map Editor
Visual map editor for provinces, states, and strategic regions.
Map Layers
- Provinces: Individual province view
- States: State boundaries and ownership
- Strategic Regions: Military regions
- Supply Areas: Logistics visualization
Province Picker
- Open Map Editor
- Click on map to select province
- Province ID shown in status bar
- Copy ID with button or
Ctrl+C
State Editing
Click state to select, then edit properties in side panel:
- Owner and controller
- Victory points
- Buildings (infrastructure, factories, etc.)
- Resources (steel, oil, etc.)
- Core states
Building Placement
- Click building icons to place
- Adjust levels with +/- buttons
- Visual indicators on map
OOB Creator
Command: HOI4: OOB Creator
Create Orders of Battle (starting military units) for countries.
Creating an OOB
- Click New OOB or select existing
- Set country tag
- Build military hierarchy
Unit Hierarchy
- Theater > Army Group > Army > Corps > Division
- Drag units to reorganize
- Right-click for context menu
Division Designer
- Click New Division
- Select division template or create custom
- Add battalions: Infantry, Artillery, Armor, Support companies
- Set equipment levels
- Assign to army/corps
Air Wings
- Create air wings
- Assign aircraft types and counts
- Set home air base
Naval Fleets
- Create task forces
- Assign ships
- Set home port
Export
- Generates valid HOI4 OOB file
- Automatically creates unit history file
- Proper formatting and structure
Equipment Analyzer
Command: HOI4: Equipment Analyzer
Analyze, compare, and simulate production of equipment.
Equipment Browser
- Browse all equipment by category
- Filter by year, type, archetype
- View detailed stats
Equipment Editor
- Select equipment to edit
- Modify any stat
- See combat preview update
- Save to original file
Production Simulator
- Select equipment
- Set factory count
- Apply modifiers (industrial capacity, production efficiency, resource availability)
- View production rate and time estimates
Comparison Mode
- Select up to 3 equipment items
- Side-by-side stat comparison
- Highlights best/worst values
- Cost efficiency analysis
Battle Simulator
Command: HOI4: Battle Simulator
Simulate combat between divisions to test effectiveness.
Setting Up a Battle
- Attacker: Build or select division
- Defender: Build or select division
- Terrain: Select combat terrain
- Modifiers: Add entrenchment, air support, etc.
Division Builder
- Add any unit types
- Set equipment variants
- Apply doctrines and modifiers
Combat Stats
- Soft/Hard Attack values
- Defense and Breakthrough
- Organization and HP
- Armor and Piercing
Simulation Results
- Predicted winner
- Estimated battle duration
- Casualty estimates
- Organization damage over time
AI Behavior Viewer
Command: HOI4: AI Behavior
Analyze and understand AI decision-making in your mod.
Features
- View AI strategy plans
- Analyze focus tree AI weights
- See decision AI priorities
- Understand AI division templates
Usage
- Select country or AI file
- Browse AI behaviors by type
- View conditions and weights
- Identify potential issues
Event Chain Visualizer
Command: HOI4: Event Chain Visualizer
Visualize event relationships and chains.
Features
- Interactive graph view
- Automatic chain detection
- Option tracking
- Namespace filtering
Usage
- Open Event Chain Visualizer
- Select event namespace or file
- View connected events as graph
- Click nodes to see event details
- Follow option arrows to see triggers
Graph Controls
- Zoom with scroll wheel
- Pan by dragging background
- Click nodes to select
- Double-click to open event file
Dependency Graph
Command: HOI4: Show Dependency Graph
Shortcut: Ctrl+Alt+D
Visualize relationships between files in your mod.
Features
- File dependency visualization
- Circular dependency detection
- Impact analysis
- Filter by file type
Usage
- Open from sidebar or command
- Select root file or view all
- Explore connections
- Click nodes to see details
Impact Analysis
Right-click any file and select "Analyze Impact" to see:
- What files depend on this file
- What this file depends on
- Potential cascade effects of changes
Content Browsers
Idea Browser
Command: HOI4: Idea Browser
Browse and search all ideas, national spirits, and advisors.
Categories
- National Spirits
- Political Advisors
- Military Advisors (Army, Navy, Air)
- Theorists
- Laws (Economy, Trade, Conscription)
- Hidden Ideas
Features
- Search by name or effect
- Filter by category
- View all modifiers
- See availability conditions
- Cost information
Usage
- Open Idea Browser
- Select category or search
- Click idea to see details
- Double-click to open source file
Flag and Variable Tracker
Command: HOI4: Flag Tracker
Track global flags, country flags, and variables across your mod.
Features
- Find all flag/variable definitions
- Track where flags are set
- Track where flags are checked
- Identify unused flags
Flag Types
- Global flags
- Country flags
- State flags
- Variables
- Dynamic modifiers
Usage
- Open Flag Tracker
- Search for flag name
- View all references
- Click to jump to location
GFX Auditor
Command: HOI4: GFX Auditor
Validate and manage graphical assets.
Audit Types
- Missing Assets: GFX defined but file missing
- Unused Assets: Files with no GFX reference
- Invalid Dimensions: Wrong image sizes
- Format Issues: Incorrect file formats
Usage
- Open GFX Auditor
- Run audit (automatic on open)
- Review issues by category
- Click to navigate to problem
- Use Quick Fix for common issues
Quick Fixes
- Generate missing GFX entries
- Create placeholder images
- Fix path references
Command: HOI4: Image Toolkit
Image processing and conversion tools.
Features
- View DDS files directly
- Convert between formats (DDS, PNG, TGA)
- Resize images
- Generate mipmaps
- Batch processing
- DDS (DXT1, DXT5, BC7)
- PNG
- TGA
- BMP
Event Picture Creator
Command: HOI4: Event Picture Creator
Create and manage event pictures.
Features
- Browse existing event pictures
- Create new event GFX entries
- Preview at correct dimensions
- Auto-generate sprite definitions
Usage
- Open Event Picture Creator
- Browse or create new
- Select source image
- Set GFX name
- Generate entry and copy files
Animated DDS Viewer
Command: HOI4: Animated DDS
View animated DDS files used in HOI4.
Features
- Play animated textures
- Frame-by-frame view
- Speed controls
- Export frames
Localization Dashboard
Command: HOI4: Localization Dashboard
Shortcut: Ctrl+Alt+L
Overview of localization coverage and management.
Features
- Coverage statistics by category
- Missing key detection
- Language comparison
- Batch operations
Dashboard Views
- Overview: Total coverage percentage
- By File: Coverage per localization file
- Missing: List of unlocalized keys
- Comparison: Compare languages
Batch Operations
- Add multiple keys at once
- Copy from one language to another
- Export missing keys list
Event Localizer
Command: HOI4: Event Localizer
Quickly localize events with assisted suggestions.
Features
- Event-focused localization
- Title and description editing
- Option text management
- Preview formatted text
Usage
- Open Event Localizer
- Select event file
- Edit titles, descriptions, options
- Save to localization file
Quick Localize
Shortcut: Ctrl+Shift+L
Instantly add localization for selected text.
Usage
- Select a localization key in your code (e.g.,
my_event.1.t)
- Press
Ctrl+Shift+L
- Enter the localized text
- Automatically added to your localization file
Configuration
Set your default localization file in settings:
{
"hoi4.localizationFile": "localisation/mymod_l_english.yml"
}
Dev Notes and Kanban
Command: HOI4: Dev Notes
Project management integrated into your mod workspace.
Kanban Board
- Drag-and-drop task management
- Customizable columns
- Card labels and due dates
- Rich text descriptions
File Notes
- Attach notes to specific files
- Quick access from explorer
- Color-coded by priority
TODO Scanner
Automatically finds comments:
// TODO: ...// FIXME: ...// NOTE: ...# ISSUE: ...
Data Storage
- Saved to
.hoi4-dev-notes.json
- Add to
.gitignore if desired
- Share via version control
Command: HOI4: Performance Profiler
Shortcut: Ctrl+Alt+P
Analyze mod performance and find bottlenecks.
Metrics Analyzed
- File size analysis
- Trigger complexity scoring
- Effect chain depth
- Event fire frequency estimates
Reports
- Large Files: Files that may cause loading issues
- Complex Triggers: Expensive condition checks
- Heavy Effects: Resource-intensive effects
- Recommendations: Optimization suggestions
Usage
- Open Performance Profiler
- Run analysis
- Review issues by severity
- Click items to navigate
- Follow recommendations
Debug Log Viewer
Command: HOI4: Show Debug Log
Shortcut: Ctrl+Alt+O
View and analyze HOI4's debug output.
Features
- Live log tailing
- Error highlighting (red)
- Warning highlighting (yellow)
- Filter by type
- Search functionality
- Click errors to open source
Log Watcher
Start continuous monitoring:
HOI4: Start Debug Log Watcher- Run the game
- Errors appear in real-time
HOI4: Stop Debug Log Watcher when done
Configuration
Set your log path:
{
"hoi4.debugLogPath": "C:/Users/You/Documents/Paradox Interactive/Hearts of Iron IV/logs"
}
Changelog Generator
Command: HOI4: Changelog Generator
Generate changelogs from git history.
Features
- Reads git commits automatically
- Auto-categorizes changes
- Version tagging
- Markdown export
- Custom templates
Categories
- Features
- Bug Fixes
- Balance Changes
- Content Additions
- Performance
Usage
- Open Changelog Generator
- Select date range or version tags
- Review and edit entries
- Export as Markdown
- Ready for Steam/GitHub
Search and Navigation
Global Search
Command: HOI4: Global Search
Shortcut: Ctrl+Alt+G
Search across all mod content.
Specialized Searches
| Command |
Shortcut |
Searches |
| Search Flags |
Ctrl+Shift+F |
Country flags, global flags |
| Search Events |
- |
Event IDs and content |
| Search Focus |
- |
Focus tree IDs and effects |
| Search Decisions |
- |
Decision IDs and triggers |
Go to Definition
Shortcut: F12
Jump to the definition of event IDs, focus IDs, decision IDs, idea IDs, and technology IDs.
Find All References
Shortcut: Shift+F12
Find everywhere something is used.
Keyboard Shortcuts
| Shortcut |
Action |
|
Ctrl+Shift+L |
Quick Localize selected text |
(Or select text and right click and click HOI4: Add Dev Note Here) |
Ctrl+Alt+G |
Global Search |
|
Ctrl+Alt+D |
Dependency Graph |
|
Ctrl+Alt+P |
Performance Profiler |
|
Ctrl+Alt+L |
Localization Dashboard |
|
Ctrl+Alt+O |
Debug Log Viewer |
Or click Problems by Output on the bottom menu pane |
Ctrl+Shift+I |
Analyze Impact |
|
F12 |
Go to Definition |
|
Shift+F12 |
Find All References |
|
Ctrl+Space |
IntelliSense suggestions |
|
Ctrl+. |
Quick Fix menu |
|
Configuration
Extension Settings
Access via File > Preferences > Settings and search for "HOI4" or edit the Extension Settings Workspace.
{
"hoi4.gamePath": "C:/Program Files/Steam/steamapps/common/Hearts of Iron IV",
"hoi4.defaultLanguage": "english",
"hoi4.localizationFile": "localisation/mymod_l_english.yml",
"hoi4.enableDiagnostics": true,
"hoi4.debugLogPath": "Documents/Paradox Interactive/Hearts of Iron IV/logs"
}
Workspace Settings
Create .vscode/settings.json in your mod folder for project-specific settings:
{
"hoi4.modName": "My Awesome Mod",
"hoi4.modVersion": "1.0.0",
"hoi4.supportedGameVersion": "1.14.*"
}
Troubleshooting
Extension Not Loading
- Ensure you opened a folder, not individual files
- Check for
descriptor.mod in root (identifies HOI4 mod)
- Reload VS Code:
Ctrl+Shift+P > "Reload Window"
- Check Output panel for errors: View > Output > "HOI4 Modding Tools"
Map Editor Issues
- Verify
map/definition.csv exists
- Ensure
map/provinces.bmp is valid
- Check file permissions
Localization Not Working
- Set localization file in settings
- Ensure file uses UTF-8-BOM encoding
- Verify file path is correct relative to workspace
Focus Tree Not Displaying Correctly
- Check for circular
relative_position_id references
- Verify all referenced focuses exist
- Save and reload the tree
- Large mods take time to index on first open
- Close unused editor panels
- Disable unused features in settings
- Rebuild index:
HOI4: Rebuild File Index
Expected Mod Structure
your-mod/
├── common/
│ ├── countries/
│ ├── country_tags/
│ ├── decisions/
│ │ └── categories/
│ ├── ideas/
│ ├── national_focus/
│ ├── technologies/
│ └── units/
│ └── equipment/
├── events/
├── gfx/
│ ├── event_pictures/
│ ├── interface/
│ │ └── goals/
│ └── leaders/
├── history/
│ ├── countries/
│ ├── states/
│ └── units/
├── interface/
├── localisation/
├── map/
│ ├── definition.csv
│ └── provinces.bmp
└── descriptor.mod
Reporting Issues
- Message awesome___. aka Olander on Discord
Acknowledgments
- Hearts of Iron IV by Paradox Interactive
- VS Code Extension API
- The HOI4 modding community
- Chaofan
Changelog
v2.5.0
Chinese Localization & i18n System
- Added Simplified Chinese (simp_chinese) support across all language lists — localization manager, dashboard, and settings
- Built full i18n translation framework with
t() function, 232 translated strings (English + Chinese), and locale switching via hoi4.extensionLanguage setting
- Migrated 143 strings across 5 panels: Map Editor, Particle Editor, Focus Tree Editor, Building Generator, and Localization Editor
- Localization Dashboard "Generate Missing Keys" now respects the active language setting
Translator Workbench (New Panel)
- Tab 1 — MOD Localisation: scan source/target coverage, inline editing with auto-save, export templates with English comments, import completed translations
- Tab 2 — Extension UI: scan and edit extension locale strings with coverage stats
Map Editor — Full State Editor
- Quick Edit State panel expanded: owner, category, manpower, display name, victory points (add/edit/remove), cores (add/remove chip UI), resources (all 6 types), buildings, and province list
- Province management: "Move Selection Here", "New State from Selection", manual province ID input to add provinces to a state
- Province move backend with automatic source/target state file updates
- Data loader expanded:
updateStateFile now handles owner, category, resources, cores; new moveProvincesToState method
Map Editor — Railway Drawing Fix
- Fixed railway and supply network rendering: in-progress railway lines, placed supply hubs, and deletions now render immediately (7 missing
renderOverlay() calls fixed)
Localization Editor Fixes
- Fixed file list empty on load (race condition: embedded initial data + message retries)
- Now scans all 9 language subfolders (english, german, french, spanish, russian, polish, braz_por, japanese, simp_chinese)
- File creation respects selected language and adds UTF-8 BOM
- Language-colored file badges (EN, DE, FR, ES, RU, PL, PT, JA, ZH)
- CSV export scans all
.yml files instead of hardcoded English
Focus Tree Editor Fixes
- Fixed tree list not rendering (onclick handler crash from escaped quotes in template literal)
- Fixed 10 i18n
t() calls using wrong string concatenation syntax inside template literals
Province Editor Crash Fixes
- Fixed 2 webview crash bugs from
getElementById('...') with single quotes inside inline onclick/oninput handlers
Keybinding Fix
- Color insert keybindings changed from
Shift+Number to Ctrl+Shift+Number (stops hijacking !, #, (, ) etc.)
Critical Webview Fix
- Fixed i18n injection in all 5 panels — was using string concatenation inside template literals instead of
${...} interpolation, which caused SyntaxError: Unexpected token 'const' and killed entire panel scripts
Translation Guide
- TRANSLATION_GUIDE_CHINESE.md bundled: HOI4 mod localization format, extension UI translation approach, and full English↔中文 terminology table
Support
