AI rule: never guess HOI4 syntax. Retrieve the definition, check its source, patch, scope and dependencies, then validate against the target game installation.
A local-first Hearts of Iron IV modding reference and working Python toolkit for researching scripts, finding vanilla examples, and catching structural mistakes before launching the game. Built for modders and AI coding assistants.
- Source-backed guides covering scripting, focuses, events, decisions, characters, politics, military systems, maps, economy, AI, localisation, assets and debugging.
- Offline search and exact lookup backed by SQLite FTS5, with source paths, line numbers, evidence labels and version metadata.
- Local importers for installed engine documentation, CWTools configuration,
and Markdown references. Sources remain separate; unknown APIs are
UNVERIFIED. - Read-only project indexing for symbol definitions and script occurrences, including bounded vanilla examples with stale-file detection.
- Conservative diagnostics for structure, localisation formatting, duplicate definitions, event namespaces and focus prerequisite graphs.
- An optional nine-tool MCP server for AI clients. Direct filesystem reads require explicit allowed roots; index changes stay in the CLI.
- Automated tests and CI for the parser, retrieval, source handling and project checks.
This is a v0.1 toolkit, not a complete engine validator or an autonomous mod generator. It does not resolve mod load order, prove every scope correct, render focus trees, validate map binaries, or replace in-game testing.
Python 3.10+ with SQLite FTS5 is required. The core has no third-party runtime dependencies.
git clone https://github.com/Angelicismo01/hoi4kdb.git
cd hoi4kdb
python -m venv .venv
.venv\Scripts\python -m pip install -e .
.venv\Scripts\hoi4kb build
.venv\Scripts\hoi4kb search "targeted state decisions"
.venv\Scripts\hoi4kb verifyOn macOS/Linux, use .venv/bin/python and .venv/bin/hoi4kb.
Every command emits JSON; --json is also accepted.
Replace the path if your Steam library is elsewhere:
.venv\Scripts\hoi4kb import-vanilla-docs "C:\Program Files (x86)\Steam\steamapps\common\Hearts of Iron IV"
.venv\Scripts\hoi4kb get effect add_stability
.venv\Scripts\hoi4kb scope add_stability
.venv\Scripts\hoi4kb index-vanilla "C:\Program Files (x86)\Steam\steamapps\common\Hearts of Iron IV" --name vanilla
.venv\Scripts\hoi4kb examples add_stability --reference vanillaGenerated databases stay outside the repository by default. No game files, upstream mirrors, or machine-local indexes are distributed here.
.venv\Scripts\python -m pip install -e ".[mcp]"
.venv\Scripts\hoi4kb-mcp --allow-root "D:\Mods\MyHOI4Mod"The server uses stdio and is intended to be launched by an MCP client. See tooling and MCP setup for commands, permissions and limitations. It does not install or modify any AI client's configuration automatically.
- Knowledge index — choose the right guide for the system you are changing.
- Sources and evidence policy — upstream revisions, provenance and conflicts.
- Reusable patterns — linked implementation recipes.
- Completeness checklists and common errors.
- Validation report — what was actually checked and what was not.
- AI contributor instructions and third-party notice.
The initial research baseline is the locally installed HOI4 1.19.2.0 snapshot, researched on 2026-09-04, not a claim about the latest public patch. Live Paradox Wiki access returned HTTP 401 during research; guides were cross-checked with local engine documentation, shipped examples, a pinned community mirror and CWTools. Imported sources carry their own versions and confidence labels.
python -m unittest discover -s tests -v
python -m hoi4kb build
python -m hoi4kb verifyNo project-wide redistribution license has been selected. Third-party sources retain their own rights; see notices before redistributing material.