Menu
Use when designing, researching, registering, wiring, testing, or documenting a Hearts of Iron IV Super Event with the optional reusable runtime.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use only when the selected HOI4 portrait provider is the Comfy Cloud MCP route.
Use only when the selected HOI4 portrait provider is a configured loopback ComfyUI installation.
Use only when the selected HOI4 portrait provider is an existing RunPod ComfyUI workspace.
Use when creating, sourcing, processing, converting, organizing, wiring, or documenting visual assets for a Hearts of Iron IV mod.
Use for the provider-neutral HOI4 portrait source, prompt, archive, validation, and runtime handoff contract.
Use when coordinating custom Codex subagents for HOI4 mod implementation, asset production, text and audio research, audits, active small patches, planning handoffs, or documentation work.
| name | hoi4-super-events |
| description | Use when designing, researching, registering, wiring, testing, or documenting a Hearts of Iron IV Super Event with the optional reusable runtime. |
Use this skill only when the optional Super Events workflow is installed or the repository already has an accepted Super Event architecture. A Super Event is a large campaign presentation moment, not a substitute for an ordinary event popup.
The HOI4 Mod Setup package provides a neutral runtime derived from a proven mod architecture and adapted to the project’s confirmed namespace. It includes GUI, GFX, scripted GUI, scripted localisation, one hidden smoke-test event, default assets, editable Photoshop templates, and a registration guide.
The main agent owns final registration, caller effects, GUI/GFX integration, localisation, audio wiring, documentation, validation, and completion claims.
Route bounded work to:
hoi4_quote_remark_researcher for exact quotations, attribution, cultural remarks, slogans, title references, and copyright riskhoi4_audio_researcher for licensed or public-domain audio research, downloads, editing, conversion, rights evidence, and handoffhoi4_asset_source_researcher for real or archival Super Event imageshoi4_generated_feature_art for approved fictional, symbolic, supernatural, or alternate-history Super Event imageshoi4_localisation_auditor for consistency and key coveragehoi4_repo_explorer only when the owning caller or an existing custom architecture is not already knownUse hoi4-feature-assets for image production and DDS handoff, hoi4-text-audio-research for source-aware text and audio, hoi4-events for event-chain ownership, and hoi4-subagents for bounded delegation.
Subagents do not edit the registry, scripted localisation, GUI, GFX, callers, sound definitions, or gameplay unless the parent explicitly grants that narrow scope.
The optional package installs these managed surfaces:
interface/hoi4ms_super_events.gui
interface/hoi4ms_super_events.gfx
common/scripted_guis/hoi4ms_super_events.txt
common/scripted_effects/hoi4ms_super_events.txt
common/scripted_localisation/hoi4ms_super_events.txt
events/hoi4ms_super_event_examples.txt
localisation/english/hoi4ms_super_events_l_english.yml
gfx/interface/super_event_option.dds
gfx/super_events/super_event_bg.dds
gfx/super_events/super_event_default.dds
gfx/super_events/super_event_image_default.dds
gfx/super_events/super_event_template.psd
gfx/super_events/super_event_image_template_457x328.psd
docs/super_events/README.md
.agents/skills/hoi4-super-events/assets/examples/
Filenames stay stable for managed update and repair. Scripted identifiers, event namespace, sprite names, flags, localisation keys, and example text are adapted from [MOD_PREFIX] and [MOD_NAME] during installation.
Never copy identifiers or event-specific content from another mod. Never silently replace an existing custom Super Event architecture. Compare base, local, and incoming files through the setup transaction and honor the user’s conflict choices.
Before editing:
AGENTS.md.docs/super_events/README.md.Use hoi4.gui_inspect before changing a scripted GUI you do not understand. Use hoi4.gui_render after wiring when the available scenario can represent the window. Keep tool output as evidence; it does not replace source review or live in-game validation.
If the installed runtime is absent, do not fabricate its paths or claim it is available. Either use the repository’s accepted custom architecture or ask the user to add the optional workflow through HOI4 Mod Setup.
Every registered Super Event keeps these surfaces aligned:
Do not wire only one part. A new image without registry text, a caller without close cleanup, or audio without rights evidence is incomplete.
Treat working titles, draft descriptions, unsourced quotes, generic response text, placeholder art, and unverified audio as planning inputs only. Do not promote them into final localisation or runtime registration until the relevant research and asset handoffs are complete.
Reserve one integer ID per Super Event. Never recycle an established ID for a different moment.
The installed runtime exposes:
<mod_prefix>_show_super_event = {
SUPER_EVENT_ID = <integer>
}
The helper stores the ID as the value of <mod_prefix>_super_event_visible. The scripted GUI becomes visible while that flag is present. Each defined_text block selects image, title, description, quote, and remark from that same value. The close action clears the visibility flag.
For every new ID:
interface/hoi4ms_super_events.gfx.defined_text blocks in common/scripted_localisation/hoi4ms_super_events.txt.<mod_prefix>_show_super_event from the accepted gameplay moment.Keep every branch keyed to the same integer. Do not use one ID for text and a different ID for image or audio.
The package includes one hidden, trigger-only event:
event <mod_prefix>_super_event.1
Run it from the debug console. It should open the default package, render the project-adapted text and image, and close cleanly. The example is test infrastructure, not a finished campaign moment. Do not repurpose ID 1 without updating the package docs and test.
Use a Super Event for campaign-scale reveals, irreversible escalation, a major world-order change, rare ideological victory, catastrophic collapse, global defeat, or a genuine campaign-ending moment. Do not create one merely because a normal event is dramatic.
Before production, define:
If planning identifies a Super Event, write a bounded handoff that records the intended role, owning caller, title and description direction, quote themes, response tone, image direction, audio requirement, research questions, and acceptance scenario. Planning does not invent final sourced text or claim that research has been completed.
The title, image, quote, response, and audio should express the same moment. Avoid a generic “dramatic” package with unrelated components.
Titles should be short, memorable, and specific. Prefer a person, state, movement, place, institution, transformation, collapse, or irreversible condition. Avoid generic labels such as THE CRISIS unless the project’s accepted style requires them.
Descriptions should:
Keep text readable at the actual game resolution and UI scale. Long text that overflows the window is a blocking presentation defect.
Do not invent a quotation and present it as real. Use hoi4_quote_remark_researcher when wording, attribution, cultural origin, or copyright risk needs research.
For every direct quote record:
Prefer primary sources, official transcripts, libraries, archives, reputable editions, and traceable historical collections. Unsourced quote sites are search leads only.
The response remark is a short player reaction, not a second description. It may be sober, ceremonial, bitter, fatalistic, defiant, or culturally grounded. For modern copyrighted works, keep direct fragments very short and prefer a title-like allusion or paraphrase. Record the source and risk.
The visible image area is 457x328. Use gfx/super_events/super_event_image_template_457x328.psd for the image and gfx/super_events/super_event_template.psd to review the complete composition. Inspect .agents/skills/hoi4-super-events/assets/examples/contact_sheet.png and the five individual reference PNGs for framing, contrast, subject scale, and text-safe composition. They are review references only: never register them as project sprites or present them as original art for a new mod.
Choose source mode deliberately:
Keep the full-resolution source, processed PNG, final DDS, hashes, dimensions, crop/composition notes, source link, rights status, and sprite handoff. Use hoi4-feature-assets; do not wire a contact sheet, PSD, or temporary evidence path as runtime art.
The image must remain legible at 457x328, match the described moment, and avoid text baked into the image unless the accepted design explicitly needs it.
Audio is optional for the reusable runtime. A missing or blocked track must not break the visual Super Event.
When the accepted design requires audio, the Super Event is incomplete until one intentional final track is sourced, rights-checked, converted through the project's verified audio route, registered, wired, and documented. Give each completed Super Event its own track and project-scoped sound ID unless the user explicitly approves a specific reuse. Do not leave default, placeholder, mismatched, wrong-format, or undocumented audio in a completed package.
When audio is requested:
hoi4_audio_researcher when no approved track fits.Do not use commercial game, film, trailer, or album music without verified permission. Do not treat a public-domain composition as proof that a modern recording is public domain. Do not use test tones, beeps, oscillator output, or noise beds as final music.
Prefer an intentional musical recording such as a chant, hymn, orchestral excerpt, song, march, or other structured track. Do not manufacture a final cue from primitive waveforms, generated beeps, metronome clicks, noise beds, abstract ambience, or quick local synthesis. If no legally usable track fits a required-audio design, report the blocker instead of fabricating success.
If the mod has no settings-aware playback helper, do not invent one silently. Document the existing sound route or propose a bounded design before adding a new settings surface.
Show the Super Event from the gameplay effect that owns the completed moment, after the state transition it announces is established. Avoid firing from multiple routes unless duplicate suppression is explicit.
Verify:
Keep project-specific cleanup in the owning feature, not in the generic close button.
For a world-end Super Event, align the presentation with the owning terminal-state rules. Establish the terminal state before showing the window, set the scenario-specific state, gate incompatible future systems, prevent ordinary retriggers, and make the title, quote, image, response, audio decision, caller, docs, and acceptance scenario communicate finality.
Use a defeat-aftermath Super Event only when the defeated threat was sufficiently global, sustained, and costly to reshape the campaign. Communicate what ended, what was lost, what remains unstable, and what order or memory follows. Prefer reflective weight over cost-free triumph.
Maintain one permanent registry or research note under docs/super_events/. For each Super Event include:
not usedTemporary asset workspaces may hold downloads, processed previews, contact sheets, and handoffs during active work. Before declaring the feature complete, promote durable facts into permanent docs, verify runtime paths, and clean only the task-owned temporary workspace.
Use an event-scoped temporary workspace such as docs/assets/<event_id>_<event_slug>/ when the project follows that convention. Preserve it while work is active, blocked, awaiting review, or undergoing acceptance. Before completion, move durable provenance, research, conversion, and crosswalk facts into permanent event, plan, specification, or Super Event documentation; verify that no runtime path points into the temporary workspace; then remove only that event-scoped workspace.
Before completion:
A Super Event is incomplete while any caller, registry branch, localisation key, image, required audio, close path, provenance record, or acceptance scenario is missing or contradictory.