Hoi4 Content Builder

HOI4 content builder

Start from the user's idea

The user may describe only the desired fantasy or gameplay result. Do not ask them to design scopes, files, triggers, or syntax. Read natural-language-intake.md, infer safe defaults, and produce a concise content contract covering visible behavior, rules, AI, lifecycle, compatibility, assets, save impact, and acceptance tests.

Read target-repository guidance and sibling hoi4-pdx-modding references for every affected system. Discover the game, mod, dependency, and playset paths; never assume the paths or conventions from the machine that authored this skill. Verify version-sensitive syntax in installed documentation and current vanilla or dependency consumers.

When extending or repairing existing content, first read all affected visible localisation and scripted-localisation consumers. Follow the sibling skill's semantic-intent-audit.md before translating IDs into a content contract. Identifiers are not evidence for character names, narrative roles, costs, dates, or player-facing behavior. For a whole-mod health, balance, UX, or improvement pass rather than one requested feature, route to the sibling hoi4-review-debug skill's improve-existing-mod.md workflow.

P-language grammar and editor-tool limits live in the sibling pdx-language.md and ide-extensions.md. Preview focus, tech, GUI, or map layout in HOI4 Mod Utilities when the change is user-visible; do not paste CWTools or Modding Tools generator output.

Choose a workflow

• New mod from an idea: build-complete-mod.md
• One feature in an existing mod: build-feature.md
• Advanced or cross-system feature: build-advanced-system.md
• Animated GUI images from video, GIF, or frame sequences: read the sibling frame-animated texture reference and then use the workflow matching the owning GUI consumer.
• Country/state/map history: build-map-history.md
• Collections, arrays, event targets, dynamic modifiers, or dynamic text: use-advanced-patterns.md
• Static-to-runtime validation: test-mod.md
• Versioned distribution: release-mod.md

Use system-coverage.md to route any beginner or advanced feature and advanced-engineering.md for architecture, performance, compatibility, save migration, and tooling.

Reuse verified resources

Start from assets/templates/ for one object and assets/kits/ for a proven multi-file dependency chain. Read template-catalog.md before copying. Replace every MOD, sample numeric ID, path, asset, and text. Templates are not permission to skip target-build verification.

Treat assets/template-manifest.json as the machine-readable verification contract. Run scripts/validate-template-manifest.ps1 after changing templates or kits; rebuild the manifest with scripts/build-template-manifest.ps1 -Force only after updating the human catalog and verifying the new current consumer.

Use scripts/new-country-scaffold.ps1 to generate a staged country tree and scripts/generate-gfx-manifest.ps1 for deterministic sprite registration. Generate into an empty staging directory, review the diff, then merge only the required files into the target mod. Never let a helper silently overwrite the target tree.

If no verified resource fits, follow verify-template.md: check installed schema, at least one current working consumer, caller scopes, all dependent resources, and a minimal runtime test before promoting it.

Build the complete graph

1. Establish stable IDs and file ownership.
2. Assign each subsystem an existing owner file or compact registry. Add related objects to that owner instead of creating one small file per event, decision, sprite, or asset registration. Consolidate definitions that share parser directory, load conditions, lifecycle, and consumers; keep separate files for genuine compatibility/load-order boundaries, independent generated ownership, or materially different subsystems.
3. Map IDs to visible names, descriptions, tooltips, and promised behavior.
4. Create definitions before consumers.
5. Wire callers, lifecycle updates, cleanup, AI, and compatibility gates.
6. Add or update localisation and visible assets for every player-facing path.
7. Search the whole target mod for definitions, callers, stale IDs, and collisions. Preserve unrelated work and project encoding conventions.
8. Keep a minimal runnable path first; add branches and optimization only after the core path validates.
9. Create or update the mod's technical documentation and current development handoff, and add readable contract comments to the implementation. Use the base skill's development-documentation.md and the bundled documentation templates; documentation is part of the feature graph.

Do not stop after writing the central object. A focus needs effects and text; a GUI needs sprites, callbacks, and localisation; a project needs facilities, scientists, rewards, AI, and DLC gates; a country needs tag, definition, history, character, flags, and ownership planning.

Finish with evidence

Follow the sibling hoi4-pdx-modding Validate proportionally lanes. Do not run the full validator, Mod Doctor, or a log scrape for a small inspectable diff. User AI quota is not free.

When the change needs scripts, run the sibling validator on the edited paths, inspect only the links those paths can break, and separate static proof from runtime proof. After a non-trivial static pass, ask whether the user wants AI-assisted in-game testing. If they agree and computer-use is available, follow workflows/test-mod.md exactly. If they decline, provide the smallest manual test plan and do not open Steam. Inspect-only work does not require a Steam prompt.