Menu
Use when creating, sourcing, processing, converting, organizing, wiring, or documenting visual assets for a Hearts of Iron IV mod.
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.
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 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.
Use when implementing, updating, auditing, or documenting Hearts of Iron IV events and event chains, including news and report events, on_action hooks, localisation, pictures, registration hooks, and validation.
| name | hoi4-feature-assets |
| description | Use when creating, sourcing, processing, converting, organizing, wiring, or documenting visual assets for a Hearts of Iron IV mod. |
Use this skill when a HOI4 modding task requires final visual assets.
This includes event pictures, UI assets, focus tree assets, country assets, achievement assets, generated icons, sourced feature art, generated icon art, animated sprites, animated portraits, sprite sheets, GIF previews, and any asset package that must be wired into the mod.
All active HOI4 asset skills and agents use this one reference folder:
.agents/skills/hoi4-feature-assets/assets/vanilla_reference/
All category paths in this skill are relative to that exact folder. Do not use a project-local copy, another skill-local copy, a compatibility pack, or a different parent asset folder.
The goal is to turn asset needs from a feature spec into real HOI4-ready files.
The asset workflow must produce:
Do not leave assets as loose generated or downloaded images.
If an asset is used by the feature, it must be processed, placed, documented, and handed off so the main agent can wire it cleanly.
Use this skill for:
Use this skill when the user asks the agent to create, source, process, or wire final visual assets.
Use this skill when the implementation task includes generated, sourced, or user-provided PNG files that must be turned into HOI4-ready assets.
Use hoi4-frame-animation together with this skill when an asset needs animation. Animated final assets must come from planned source frames, not from moving, scaling, rotating, warping, blurring, recoloring, or filtering one still image.
When actual files must be created, route the work through narrow project subagents instead of one broad asset worker.
The main agent decides which subagent to spawn, gives it a bounded asset prompt, reviews the output, and performs final wiring.
Use:
hoi4_asset_source_researcher for real or archival image sourcing, real country-leader, commander, operative, advisor, and named-officeholder portraits, historical flag-design research, historically attested symbols, user-provided source photos, and report, news, or custom feature images that must depict real photographed materialhoi4_portrait_creator for every final sourced or grounded character portrait after source research; fictional or impossible portraits use native ImageGen under the parent brief and never enter this workerhoi4_generated_feature_art for generated non-icon feature art, including fictional or alternate-history report images, news images, large presentation images, flat fictional flag designs, faction emblems, UI panels, and progression-state base art; it does not own final character portraitshoi4_icon_artist for focus icons, idea icons, national spirit icons, officer corps spirit icons, decision icons, decision category icons, achievement icons, and tech iconsFor animated work, route by asset type first. Then require the chosen asset subagent to follow hoi4-frame-animation for frame plans, per-frame source art, normalization, contact sheets, preview GIFs, frame sheets, static fallbacks, and animation handoffs.
Asset subagents may create:
docs/assets/<feature_slug>/gfx_handoff.mdAsset subagents must not edit .gfx, localisation, GUI, event, focus, idea, decision, scripted effect, scripted trigger, on_action, history, country, external tabular data files, or workbooks unless the parent explicitly grants that scope.
The main agent owns final .gfx sprite definitions, gameplay references, docs alignment, and validation.
A good parent prompt to an asset subagent includes the feature slug, asset list, asset type, target size, source mode, final DDS folder, sprite name if already registered, reference folder, visual direction, source constraints, and anything the subagent must mark blocked instead of substituting.
Feature-owned final assets should be grouped under a feature-scoped folder whenever the engine surface uses explicit sprite or texture paths.
Use this folder form:
<feature_slug>
Place the feature folder directly under the asset category folder, for example gfx/event_pictures/<feature_slug>/ or gfx/interface/ideas/<feature_slug>/. Do not insert a project namespace layer such as gfx/event_pictures/<mod_namespace>/<feature_slug>/; the mod root already provides the project namespace.
Do not leave new feature assets loose in category roots such as gfx/event_pictures/, gfx/presentations/, gfx/interface/ideas/, gfx/interface/goals/, gfx/interface/decisions/, or gfx/leaders/ unless that root placement is an engine-facing lookup requirement.
Root-only and engine-convention exceptions:
gfx/achievements/ must keep achievement DDS files directly in the root. Do not create gfx/achievements/<feature_slug>/ subfolders unless a new engine behavior has been verified locally. Achievement filenames must match the full achievement ids from common/achievements/, so feature-owned achievement ids and triplet filenames should use <feature_slug>_<achievement_name>{,_grey,_not_eligible}.dds or the exact established id if it includes an ordinal.gfx/flags/, gfx/flags/medium/, and gfx/flags/small/ must keep HOI4 tag/ideology filenames. Do not put flags into feature folders; use cosmetic tags or route-specific tag filenames when a feature needs transformed flags.Shared systems may use a clear shared or system folder. Do not force shared assets into a feature folder just to avoid a root directory.
When moving or adding an asset, update every .gfx, .gui, event, idea, decision, focus, localisation, and documentation reference that names the old path or sprite. Keep sprite names stable unless the engine-facing identifier itself has to change, as with achievement ids.
Researched presentation audio belongs to hoi4-text-audio-research. Use feature-scoped music and sound paths only when the repository already uses that convention or the parent prompt asks for it. Preserve source downloads under a documented source-audio path instead of burying them among final game files.
Use this handoff whenever the project has portrait production enabled. The
provider-neutral hoi4-portrait-production skill owns the common contract,
the one installed provider skill owns provider-specific execution,
hoi4_portrait_creator owns selected-provider output and final portrait
production, and this asset skill owns durable source, crop, prompt, provenance,
output review, DDS validation, and runtime handoff. The canonical portrait
project is https://github.com/klimPaskov/comfyui-hoi4-portraits.
When the handoff is in scope, create a durable source and prompt pair before provider production. The current approved runtime portrait remains usable while a replacement is pending; if the provider is Disabled or temporarily unavailable, use and report only the source-based fallback.
Resolve the stable runtime basename first:
portrait_<tag>_<character_key>
Use that exact basename for all three artifacts:
<runtime_portrait_path>/portrait_<tag>_<character_key>.dds
docs/assets/portraits/<feature_slug>/portrait_<tag>_<character_key>.png
docs/assets/portraits/<feature_slug>/portrait_<tag>_<character_key>.txt
<tag> is the owning country or cosmetic tag. <character_key> is the stable scripted character or institutional subject key, never a localised display name. Save the highest-resolution source that anchors the subject as the PNG before final resizing and DDS conversion. Preserve separate immutable source and provenance evidence for a sourced real person.
The matching TXT contains only the final person-only prompt. It must begin with hoi4_portrait, and may describe visible age, gender presentation, face shape/proportions, hair, facial hair, expression, gaze, head direction, clothing or uniform, medals, accessories, and framing. Omit the subject's name, game-style instructions, background/scenery, lighting, rendering/restoration instructions, and unsupported biographical details. Record provenance and non-visual identity or role facts in the manifest, not in the prompt TXT.
Record each pair's runtime path and one state:
comfyui_replacement_pendingcomfyui_replacedcomfyui_not_neededThe durable archive is not runtime storage. No .gfx, character, GUI, event, focus, idea, or decision reference may point into docs/assets/portraits/. Never delete it during temporary feature-workspace cleanup unless the user explicitly asks.
Choose the source mode based on asset type.
Do not default feature art to maps, cartographic overlays, arrows, staff tables, conference rooms, or generic war-room compositions unless that is the strongest visual for the specific asset.
For a feature, many visuals should focus on the actor, force, symbol, ritual, creature, crowd, machine, government, army, leader, or strange condition behind the event. The image should usually make the event feel active and dangerous, not merely show that territory changed.
Prefer visuals that show:
Avoid making the main visual read like:
Maps may still appear as secondary props when useful, but they should rarely be the main visual idea for fictional, alternate-history, extreme-route, supernatural, symbolic, or strange event assets.
$imagegen for generated symbolic or fictional assetsUse Codex's official $imagegen skill by default for:
hoi4_portrait_creator)When creating generated assets, follow the $imagegen skill workflow. Do not define a separate image generation route in this skill.
For transparent icons, ask $imagegen for the required transparent output and follow the $imagegen skill's transparent image workflow. The final PNG must have real transparency, no fake checkerboard, no white halo, no white outline, and no opaque square background unless the asset type explicitly uses a painted backdrop.
If $imagegen is unavailable, report that clearly and stop before using an alternate route.
For generated animated assets, use $imagegen through hoi4-frame-animation. Each animation frame must be generated or edited as its own source frame according to a frame plan. Do not use local filters, transforms, glow pulses, or offsets as the source of final motion.
Report images, news images, and custom feature images may be either internet-sourced or generated.
Use internet-sourced imagery when the asset must show a real photographed person, specific real battle, real place, real object, real newspaper, real poster, real map, real archive item, or other verifiable historical material.
Use $imagegen when the event is fictional, alternate-history, symbolic, supernatural, extreme-route, or when a unique scene is more important than matching an existing archive image. Generated event-photo assets should be prompted as period-authentic documentary material, not modern cinematic concept art.
For generated Second World War-era report, news, or custom feature images:
Follow the repository web research rules from AGENTS.md when searching for source images.
For internet-sourced event photo assets that are meant to represent the Second World War era, search for period-matching source imagery from roughly 1936 to 1945 unless the feature spec gives a narrower date range. Prefer contemporary photographs, war correspondents' photographs, press agency images, propaganda posters, maps, newspapers, official records, government or military archive images, museum scans, library scans, and period illustrations. Do not use modern photographs, reenactment images, film stills, AI-looking reconstructions, postwar uniforms, streets, weapons, vehicles, buildings, colorized tourist photos, reenactments, or modern props when they do not fit the era. If no suitable period source can be found, either generate a period-authentic fictional/documentary image when the asset does not require a real source, or mark the asset as blocked or needs_user_review.
Record the image source, source link, author or archive if available, license or public domain status if available, estimated date or date range, why the image fits the Second World War era, and any uncertainty in the manifest.
Do not generate a leader portrait for a real person.
For real people, use a real source image from the internet or a user-provided image, then create the exact crop and document it before handing the source and person-only prompt to hoi4_portrait_creator. Use the repository web research tools when a source image is needed, and prefer public domain, archival, official, or clearly licensed images. If the person belongs to the Second World War setting, prefer contemporary portraits, wartime photographs, news photographs, official portraits, military archive images, passport or identity photos, or archival illustrations. Do not use modern actors, reenactors, statues, cosplay, later fictional depictions, postwar images, or modern images that do not fit the era unless the user explicitly approves them as placeholders.
Real leader portraits preserve the immutable source and exact crop. When the project portrait provider is enabled, hand the source and person-only prompt to hoi4_portrait_creator for the pinned provider route and its reviewed final output. When Disabled or temporarily unavailable, use only the source-based crop, deterministic resize, and normal DDS fallback; never apply a local filter, repaint, or improvised HOI4-style pass.
Record the source link, author or archive if available, license or public domain status if available, source image path, processed PNG path, final DDS path when applicable, and sprite name.
For generated or sourced one-person leader portraits, the asset handoff must identify the portrait's gender presentation and any matching leader-name pool requirement. Female-presenting portraits must not be paired with male names and should require female = yes where a country leader is created directly. Male-presenting portraits must not be paired with female names or female = yes. Council, board, office, crowd, and symbolic-institution portraits should keep institutional leader names instead of personal random-name pools.
When the project portrait provider is enabled, fictional leaders, invented councils, collective bodies, supernatural leaders, and symbolic regime portraits use native ImageGen under the parent brief and never use the ComfyUI portrait workflow. When Disabled, do not fabricate a replacement through this general asset worker; use an approved source-based asset or mark the missing source blocked.
Portrait-worker output should follow HOI4 leader portrait conventions: 156x210 final DDS unless an existing sprite uses another size, bust or upper-torso framing, strong face or governing-body focal point, subdued painterly finish, period-appropriate uniform or civilian clothing, transparent or HOI4-compatible portrait background as required by the existing asset pattern, and no text, labels, watermarks, modern UI, or meme-like exaggeration.
For generated one-person leader portraits, record the portrait's apparent gender presentation in the manifest and handoff. Female-presenting portraits require female leader-name pools and female leader metadata where the implementation surface supports it. Male-presenting portraits require male leader-name pools and must not be paired with female metadata. Never hand off a portrait in a way that lets implementation randomly assign names from the opposite gender pool. Council, committee, junta, crowd, office, or symbolic-body portraits should be marked as institutional leaders and use institutional names instead of personal random-name pools.
For council or collective leaders, use one clear symbolic council portrait rather than a cluttered crowd. Keep the subject readable at leader portrait size and document that the leader is fictional or collective.
If the user provides an image, treat it as a source asset.
Record that the image was user-provided in the manifest.
Still crop, resize, convert, place, wire, and document it like any other source asset.
This skill uses the shared canonical vanilla HOI4 visual-reference library. Read the library rules and catalog before generating, sourcing, processing, or wiring an asset.
Start with:
README.mdCATALOG.mdEvery semantic reference directory contains a labeled contact_sheet.png.
There is no shared contact_sheets/ directory.
Contact sheets are review aids, not final assets. Common icon families target 15 references; other tracked families target at least 5.
Canonical portrait paths:
portraits/leaders/portraits/commanders/portraits/operatives/Canonical flag and event-art paths:
flags/normal/, flags/medium/, and flags/small/event_art/report/event_art/news/Canonical gameplay-icon paths:
icons/national_focus/icons/ideas/icons/decisions/icons/missions/icons/decision_categories/icons/achievements/icons/officer_corps_spirits/icons/technologies/icons/special_projects/icons/balance_of_power/icons/intelligence_agency/ and icons/intelligence_operations/icons/icons/Canonical unit-visual paths:
units/equipment/technology_art/units/land/counters_large/units/land/map_counters/units/land/division_template_emblems/units/air/map_counters/units/naval/map_counters/units/models_3d/These families are not interchangeable. Follow the cataloged native canvas, transparency, frame order, and owning .gfx, .gui, .asset, or .mesh definition. Reference PNGs are never final assets: do not copy, wire, recolor, or trace them. The only reusable achievement overlay is icons/achievements/overlay.png within the canonical root.
If no category matches, inspect the closest canonical category plus direct vanilla or established repository precedents before choosing a style.
Do not create core artwork from simple shapes, placeholders, contact sheets, layout-only mockups, empty UI boxes, or generated charts. Final art must be real generated, sourced, or user-provided artwork, not circles, rectangles, lines, gradients, geometric diagrams, or other primitive-shape stand-ins.
For custom feature images, this rule is strict: final art must be a real scene, archival image, painted illustration, or generated documentary-style image. Do not use symbolic diagrams, flat icons, abstract geometry, title cards, or UI-like compositions as the final custom feature image unless the user explicitly requests that exact visual approach and the exception is documented.
Use $imagegen for generated artwork and follow the $imagegen skill workflow for the source image.
Generated artwork must be real source art that can be processed into the final game asset. Final assets must be clean: must not have sticking artifacts, an icon is centered in the image, etc. Do not use contact sheets, review boards, or layout drafts as final source art.
Small gameplay icons must be readable at their final in-game size.
For every generated icon, follow the $imagegen skill's transparent image workflow. Preserve the original generated image, create a processed PNG preview, convert to DDS, and validate the final appearance over a checker background before treating the icon as complete.
The final icon should have transparent unused canvas, no fake checker or matte pixels, no transparent holes inside the painted subject, a slight black outline, a subtle drop shadow, and a centered subject that remains readable at final size.
Generated icon packages must keep visible $imagegen source evidence: save the source atlas or source PNGs, record the prompt and source mode in the manifest, process to real transparent backgrounds, and include a contact sheet that shows final alignment, dimensions, transparency, and absence of white matte or opaque square backgrounds. Do not mark a generated icon complete if the final art is a primitive local drawing, a resized unrelated icon, or a locally assembled shape substitute instead of imagegen or sourced artwork.
Focus, idea, national-spirit, officer-corps, decision, mission, decision-category, achievement, technology, special-project, balance-of-power, intelligence-agency, intelligence-operation, commander-trait, medal, military-raid, state-modifier, MIO, faction, building, and modifier icons are separate asset types.
Never treat focus, idea, and decision icons as interchangeable.
Do not create focus icons first and then satisfy idea icons or decision icons by resizing, cropping, shrinking, recoloring, padding, or lightly editing the focus icon. This is not a valid asset workflow.
Each icon type must have its own asset-type-specific brief, reference inspection, source artwork, prompt or source choice, crop, target size, filename prefix, manifest entry, and final DDS output.
Shared visual themes are allowed only when every icon is still designed for its own in-game use:
If a mechanic needs matching focus, idea, and decision visuals, build them as a coordinated icon family. A coordinated family can share subject matter, symbols, colors, and lore cues, but each member still needs separate source art or a separate generated output designed for its target size and UI role.
The manifest must record the exact asset type for every icon and should note when icons are part of a coordinated family. Do not mark an icon complete if it only exists as a resized version of another icon type.
For every asset package:
$imagegenhoi4-frame-animation before ordinary static processing. Write the animation brief and frame plan, create or approve the static fallback, generate or source every frame, then normalize the frame sequence.$imagegen assets, write a specific image generation prompt and create the base artwork by following the official $imagegen skill.gfx_handoff.md for any asset that needs a sprite definition.Do not mark assets complete until the DDS files exist, the manifest is written, and the main agent has enough handoff information to wire every sprite without guessing.
When an improvement addendum asks for richer presentation, the asset handoff should name the visual states instead of asking for generic polish. A good asset request says what the player sees before activation, while active, when locked, when dangerous, when complete, and when the route has failed.
For scripted GUI, plan asset families. A panel usually needs a background, header, button states, value icons, warning indicators, progress frames, locked overlays, selected overlays, hover states, and any animated glow, particle, float, or pulse layers. The main agent owns .gui and .gfx wiring, but the asset package must provide clear sprite names, sizes, frame counts, static fallbacks, and contact sheets.
When creating a new asset package, use a stable working folder.
Recommended working structure:
docs/assets/<feature_slug>/
manifest.md
prompts/
source_png/
processed_png/
contact_sheets/
notes/
Final DDS files must be moved into the correct gameplay asset folders.
Do not keep final assets under docs/assets/.
Every asset package must include a markdown manifest.
Recommended path:
docs/assets/<feature_slug>/manifest.md
The manifest must list every asset.
Each asset entry should include:
$imagegen, internet source image, or user-provided source image$imagegen.gfx fileUse not_needed, planned, sourced, generated, processed, converted, handed_off, wired, complete, needs_user_review, or blocked as asset statuses.
Before any asset completion claim, create or refresh a row-level coverage crosswalk from every accepted asset requirement in the current specs, manifest plans, and animation plans. Do not start from the assets that happen to be live. Each accepted row must identify:
.gfx sprite or texture, engine lookup id, or other owning definition as applicableFor every animation family, also record the purpose and the direction or state semantics that distinguish the family, together with its frame, timing, and loop evidence. Frame totals, live animation-family totals, and registered sprite totals are not coverage proof.
Audit exact rows, not counts. An extra asset or animation cannot satisfy an absent accepted row unless an explicit accepted design amendment identifies that row and names the replacement; link that amendment in the crosswalk. Any missing source package, runtime registration, live consumer, required state or visibility binding, or current audit record leaves the row incomplete.
After a late user correction or accepted spec, manifest-plan, or animation-plan change, rebuild the crosswalk against the current repository and attach a fresh coverage diff listing added, removed or replaced, changed, and still-uncovered rows. Do not reuse the prior audit or its totals for the completion claim.
Use these sizes unless the feature spec or an existing repo pattern gives a better project-specific requirement.
Use other sizes when the feature UI or asset type requires it.
Treat every unit visual as a domain-and-surface-specific pipeline. Inspect the matching catalog entry, contact sheet, and owning vanilla definition before deciding what the task needs.
units/equipment/technology_art/ contains flat 2D equipment illustrations used by equipment and technology sprites. Native canvases vary; follow the owning interface/*.gfx sprite.units/land/counters_large/ contains large frame-aware land-unit strips. Preserve the cataloged noOfFrames, frame order, per-frame footprint, and transparent bounds.units/land/map_counters/ contains land map-counter art. It is not a large division-designer strip.units/land/division_template_emblems/ contains division-template identity emblems. It is not equipment art or map-counter art.units/air/map_counters/ and units/naval/map_counters/ contain domain-specific map-counter art. Do not substitute land counters or resized equipment art.units/models_3d/land_materials/, units/models_3d/air_materials/, and units/models_3d/naval_materials/ contain UV model materials paired with cataloged .mesh, .asset, and entity definitions. They are not 2D icons, finished renders, or concept sheets.Classify the requested deliverable before creating art: equipment/technology illustration, large land counter, land/air/naval map counter, division-template emblem, or land/air/naval 3D model package. Give each class its own brief, source art, native canvas or UV layout, frame metadata, final path, and handoff. A 3D task must keep model geometry, materials, entity wiring, and any separately produced concept reference distinct. Do not derive one unit pipeline by resizing, relabeling, or recoloring another.
Route 3D model production to hoi4-3d-model-pipeline and hoi4_3d_model_pipeline. This is a separate pipeline from 2D equipment art, map counters, division emblems, and frame-sheet animation.
Before any provider or paid work, and only when the feature actually needs 3D output, the 3D route must pass the MESHY_API_KEY gate, run the autonomous bootstrap, and verify the selected pinned Meshy MCP route, generated Blender MCP route or verified narrow adapter, installed Blender version, and checksum-locked io_pdx_mesh setup.
When a ready reference is absent, the route creates exactly one clean meshy_input.png for the asset. Never create or send side-profile sheets, turnaround boards, collages, or multi-view boards to Meshy. Contact sheets and Blender renders are QA evidence only.
Every 3D asset brief must identify the asset profile, deterministic job root, provider task lineage, reference checksum, named vanilla mesh and entity precedent, source geometry height, entity scale, effective runtime height, axes, origin, contact plane, required actions, root-motion policy, PDX material channels, texture dimensions, .mesh and .anim outputs, reimport proof, runtime hashes, and live consumer.
For humanoid units, calibrate against the installed vanilla infantry source mesh and entity rather than an assumed real-world height or arbitrary entity scale. Apply the entity scale exactly once and record the source-height-to-runtime-height crosswalk.
Provider source files are immutable evidence. Working geometry must be repaired so it has no holes, loose or non-manifold geometry, degenerate triangles, missing components, or zero-weight deforming vertices. Use the verified PDX shader and packed specular map convention; never route raw grayscale roughness into the PDX specular channel because that creates chrome-black surfaces.
For animated units, provider actions are candidates that must be cleaned, retargeted or authored, baked, checked for root policy, grounded contacts, deformation, FPS, frame range, and loop behavior, then exported and reimported as real .anim files. A static image or still mesh is not an acceptable substitute for a requested skeletal action.
The asset worker owns source files, checkpoints, processed textures, previews, exports, manifests, reports, reimport evidence, and a runtime handoff. The main implementation agent owns .asset, entity, .gfx, unit/building/gameplay wiring, final runtime synchronization, and in-game screenshots.
When unsure, inspect the existing repository pattern and vanilla HOI4 assets before choosing.
Use lowercase snake_case.
Keep names stable once they are wired into .gfx.
Recommended filename prefixes:
idea_goal_decision_decision_category_report_event_news_event_presentation_achievement_leader_For feature-specific assets, include the feature slug where useful. For example, all idea assets related to a feature should go into one folder for that feature.
Every $imagegen prompt should be specific enough to produce usable game art.
A good prompt should include:
Do not ask for vague "cool icon" style outputs.
Do not rely on text inside generated images. Generated text is unreliable.
Prefer strong symbols, clear silhouettes, and readable composition.
For transparent icon prompts, explicitly request a transparent canvas, no fake checkerboard, no white rim, no white/colored outline, no glow, no sticker border, no opaque square background, and a clean silhouette suitable for HOI4 UI.
When using internet source images:
For public-facing or uncertain assets, keep the manifest honest about the source status, date uncertainty, and Second World War-era fit uncertainty.
Report event images may use internet-sourced imagery or generated period-documentary imagery. Prefer generated report images when the event needs a unique fictional or alternate-history scene, staged document, invented location, or more specific visual than archive search can reliably provide. Use real sources when the image must depict a real person, real historical scene, or real archival document.
Report event images should look like documentary-style photographs, field documentation, or period documentary material.
For Second World War-era subjects, prefer contemporary photographs, war correspondents' photographs, press agency images, propaganda posters, newspapers, maps, official records, military archive images, museum or library scans, or period illustrations. Do not use modern reenactment photos or modern documentary photos that visually belong to a later era.
Use:
Target size:
210x176
Report event images must be black and white with sepia applied. Do not leave report event images in full colour unless the user explicitly requests a colour exception, and record that exception in the manifest.
Report-event images use a finished 210x176 RGBA canvas. The source photograph is processed as a slightly tilted documentary card with transparent edge space and a soft drop shadow. The transparent corners are part of the style.
Do not ask $imagegen to create the tilted card. Generate or source the documentary photograph first, then apply the card treatment locally. This keeps the tilt, shadow, and margins consistent.
python -B .agents/skills/hoi4-feature-assets/tools/process_report_event_image.py source.png processed_report_event.png
python -B .agents/skills/hoi4-feature-assets/tools/process_report_event_image.py source_folder processed_folder
The script performs cover crop, black-and-white conversion, sepia application, grain, paper border, deterministic tilt, transparent canvas margin, and soft shadow. It writes RGBA PNG output. Convert the processed PNG to DDS through the normal repo workflow.
Validation:
210x176210x176Generated report images must still receive this local report-card treatment.
News event images may use internet-sourced imagery or generated period-news imagery. Prefer generated news images when the event needs a unique fictional or alternate-history scene, invented crisis, or scene that is unlikely to exist in archives. Use real sources when the image must depict a real person, real historical scene, or real archival item.
News images should look like black-and-white documentary photographs or period news illustrations.
For Second World War-era subjects, prefer contemporary newspapers, news photographs, war correspondents' photographs, press agency images, propaganda posters, maps, official visual records, military archive images, museum or library scans, or period illustrations. Do not use modern reenactment photos, modern news photos, film stills, or later images that do not fit the era.
Use:
Target size:
397x153
News images must be black and white.
Generated news images must be converted to black and white during processing, with period press contrast/grain and no modern color remnants. Record the source link and license or public domain status for internet-sourced images, or the generation prompt and source-mode rationale for generated images.
Large feature presentation images may use internet-sourced imagery or generated art. Prefer generated custom feature images for fictional, alternate-history, symbolic, supernatural, extreme-route, or emotionally specific moments where a unique composed image better fits the feature role. Use internet sources when the image must depict a real historical person, real photographed event, or real archival artifact.
Large feature presentation images should have:
Target size:
Use the exact target size required by the repository UI surface, image slot, or parent prompt. Do not assume a fixed custom-presentation size when the repository has no matching surface.
If sourced quote, remark, or audio research needs music, use hoi4-text-audio-research and research suitable public domain or clearly licensed music. Use feature-scoped paths such as music/<feature_slug>/ and sound/<feature_slug>/ only when the repository uses that convention or the parent requests it. Never create final music or audio from generated test tones, primitive waveforms, beeps, noise beds, or local oscillator output; that includes sine, square, triangle, and sawtooth waveforms.
For each track, document:
Do not claim public domain status without checking.
If the license is unclear, mark it as uncertain or unsuitable.
Idea and national spirit icons should look like compact HOI4-style icon art.
They should have:
Target size:
64x64
Use idea_ filename prefix.
These icons usually do not need the full focus icon frame.
Do not derive idea or national spirit icons from focus icons. They must be designed as 64x64 spirit-style icons from their own prompt or source art, even when they share a theme with a focus.
Use $imagegen for the base artwork unless the user provides or requests a specific source image.
Follow the $imagegen skill's transparent image workflow when the icon should have a transparent background.
Inspect icons/ideas/ and the matching row in CATALOG.md before generating or processing idea icons.
Focus icons should look like normal HOI4 focus icons.
They should have:
Target size:
94x86
Use goal_ filename prefix.
Do not make focus icons look like generic generated thumbnails.
Do not create a focus icon as the master artwork for idea icons, decision icons, or other smaller icon types. A focus icon can share a theme with those icons, but it must remain a separate focus-specific asset.
Every focus icon should support the focus tree's story, ideology, or gameplay purpose.
Use $imagegen for the base artwork unless the user provides or requests a specific source image.
Follow the $imagegen skill's transparent image workflow when the icon should have a transparent background.
Inspect icons/national_focus/ and the matching row in CATALOG.md before generating or processing focus icons. Do not force every focus source onto an older nominal canvas when the owning sprite and current vanilla precedent use a different native canvas.
Decision icons must remain readable at very small size.
Use:
Target size:
32x32
Use decision_ filename prefix.
Do not derive decision icons from focus icons or idea icons. They must be composed for 32x32 readability from their own prompt or source art.
Decision category icons may use:
decision_category_
Use $imagegen for the base artwork unless the user provides or requests a specific source image.
Follow the $imagegen skill's transparent image workflow when the icon should have a transparent background.
Inspect icons/decisions/, icons/missions/, or icons/decision_categories/ as appropriate before generating or processing decision-system icons. Missions use the decision icon pipeline but still need mission-specific semantic readability.
Route additional icon work by the exact UI surface:
icons/intelligence_agency/ and icons/intelligence_operations/icons/commander_traits/ and icons/medals/icons/military_raids/ and icons/state_modifiers/icons/military_industrial_organizations/, icons/factions/, and icons/buildings/icons/modifiers/Read the matching canonical catalog entries and inspect the owning .gfx, .gui, or database definition before choosing canvas, frame layout, transparency, or filename. These families are not reskinned decision or idea icons. When a source is a strip or contains several UI states, preserve its frame semantics and document them in the manifest and handoff.
Achievement icons should be compact and readable at 64x64.
Generate the completed achievement icon first with $imagegen.
Then create:
icons/achievements/overlay.png on topThe variants may be created after the completed icon exists.
Do not create not-eligible achievement icons by red-tinting, filtering, darkening, recoloring, or manually redrawing the grey icon. If the overlay file is missing or cannot be applied cleanly, stop and report the asset as blocked instead of substituting another treatment.
Target size:
64x64
Use an achievement_ prefix for source or intermediate art when it helps distinguish the asset type.
For final files, achievements are a root-only exception. Put completed, grey, and not-eligible DDS files directly under gfx/achievements/, and name them after the exact achievement id registered in common/achievements/:
gfx/achievements/<achievement_id>.dds
gfx/achievements/<achievement_id>_grey.dds
gfx/achievements/<achievement_id>_not_eligible.dds
When renaming or adding achievement ids, update common/achievements/, localisation/english/<mod_namespace>_achievements_l_english.yml, interface/<mod_namespace>_achievements.gfx, the three DDS variants in gfx/achievements/, and any docs or manifests that list the final DDS paths. If the achievement registry owns a single unique_id, keep it as one root-level registry file and group feature-owned achievements by feature section inside the file instead of splitting it into per-feature achievement files.
Inspect icons/achievements/ before generating or processing achievement icons.
Flags should use clean symbolic designs that look like intentional flag art, not simple-shape placeholders, palette swaps, ugly filters, or flipped/recolored variants.
They must remain readable at HOI4 sizes.
Required flag sizes:
HOI4 flag TGAs must use the same origin/header convention as vanilla flags. Validate with file; completed flag TGAs should read as Targa image data at the correct size and must not end with - top. If a flag displays upside down in-game while the artwork looks correct in an image viewer, fix the TGA encoding/origin on the flag files themselves. Do not add custom UI sprites, scripted-localisation routing, DDS display copies, or other workarounds for flag orientation.
Avoid overly detailed symbols.
Avoid generated text unless the design absolutely requires it and the final output is manually checked.
Always use $imagegen for fictional flags and user-provided or internet source images for historical or real-world flags.
For existing countries that already have game-provided or repository-approved base flags, do not replace the no-suffix base flag as part of an ideology pass. Keep the base flag unchanged, or restore it from the approved prior asset if an asset pass damaged it, unless the user explicitly asks for that base flag to be redone or the country receives a deliberate focus/event/cosmetic-tag transformation. Ideology variants should be separate assets for _communism, _democratic, _fascism, and _neutrality, not mutations of the base flag with one small shape, a palette swap, a color filter, a vertical flip, or a copied emblem.
For focus-tree or event route flag changes, use explicit cosmetic tags or route-specific flag files and document the trigger/focus that changes the flag. Do not create default flag overrides or new base flags for vanilla-supported or already-existing countries just because they participate in an event.
Historical or historically grounded flags must use sourced motifs, documented heraldry, period symbols, or clearly explained alternate-history synthesis. If no directly attested flag exists, state that in the manifest and produce a historically grounded design from relevant motifs instead of inventing unrelated symbols.
Generated fictional or alternate-history flag variants must come from generated/source artwork and then be processed into final flag sizes. Do not hand-draw final flags from basic rectangles, circles, stars, arrows, or random emblems unless those shapes are part of a researched or generated source design.
Before marking any flag complete, verify normal, medium, and small TGA files:
file output must not show - topChoose the canonical reference family before production:
portraits/leaders/portraits/commanders/portraits/operatives/portraits/advisors/Grounded real, historical, restored, separatist, regional, indigenous, dynastic, or otherwise plausibly historical identities use an attributed real-person source. One-person generated portraits are reserved for wholly fictional, impossible, or supernatural identities. Missing or contradictory identity classification fails closed.
For a real person, preserve the unchanged archival master and create the
explicit head-and-shoulders crop with
.agents/skills/hoi4-feature-assets/tools/extract_portrait_source_crop.py.
Retain its exact-pixel JSON evidence and hand the source and person-only prompt
to hoi4_portrait_creator when the project provider is enabled. Require an
independent likeness, style, and provenance review before DDS conversion or
wiring. A raw photograph, generic filter, illustration used as an identity
master, face replacement, or weak likeness is not a provider-backed final;
simple resize and normal DDS conversion are allowed only for the source-based
fallback when Disabled or temporarily unavailable.
Record source URL, author or archive, rights status when available, source and candidate hashes, crop coordinates, review evidence, processed PNG, final DDS, runtime sprite, and the durable source/prompt pair from section 2.3.
For fictional people and impossible or supernatural entities, use native ImageGen under the parent brief after the identity gate permits it. Never use the portrait provider or a ComfyUI text-to-image graph for these subjects. Reject generic, modern, meme, gore, stereotyped, text-bearing, or interchangeable output. If Disabled, use an approved source-based asset or mark the missing source blocked.
Full country-leader, commander, and operative textures are 156x210. Never
manufacture a smaller commander source merely because one UI view displays it
at a smaller apparent size.
Advisor, theorist, military-high-command, officer-corps, and army-small dossier
portraits are a distinct native 65x67 asset family. Inspect
assets/vanilla_reference/portraits/advisors/ and its contact sheet before
production. Do not satisfy an advisor requirement by shrinking a 156x210
leader texture or by reusing an unrelated icon.
Apply the same identity gate. A grounded real subject first needs an independently approved full portrait candidate and retained attribution. An allowed fictional subject needs its own full-resolution generated master; do not reuse a leader crop. Institutional or collective briefs must state whether the card is people-free or depicts a governing group.
Use the bundled compositor:
python -B .agents/skills/hoi4-feature-assets/tools/create_advisor_icon.py `
--source <approved_portrait> `
--portrait-size <width> <height> `
--rotation <degrees> `
--portrait-offset <right> <down> `
--preview <review.png> `
--output <runtime.dds>
The tool resizes the complete source to a native intermediate, applies the
reviewed size, rotation, and opening-center offset, then composites the exact
advisor_template.png once as the untouched top layer. Use a placement study
when the first transform does not fit. Do not redraw the frame, paper, seal,
bevel, patina, or shadows.
Record source and template hashes, complete-source resize, transformed
dimensions, center, offset, rotation, sepia strength, preview hash, DDS hash,
runtime path, and independent reviewer. Review at native size and at 4x
nearest-neighbour scale. Automated dimension and alpha checks are evidence,
not visual approval.
When a character defines army.large and army.small, keep the approved
156x210 commander texture for large and create a separate native 65x67
dossier portrait for small. Validate and document both sprites independently.
Leader portraits can be animated for special routes, extreme-route leaders, supernatural leaders, rare formables, major transformations, or dramatic council reveals. They should not be required for every normal country leader.
Animated leader portrait packages must include:
For UI panels, investigation windows, ledgers, and similar assets, separate artwork from functional UI.
Use $imagegen for:
Use normal UI editing for:
Do not let generated art decide exact interactive layout.
The implementation must still follow HOI4 UI rules and existing repo patterns.
For a decision category with a scripted GUI or mechanic window, the asset handoff should cover the full interface state set.
When the asset package belongs to a focus-tree or scripted-GUI change, use the corresponding MCP inspect and render tools after placement to verify references and produce a deterministic review artifact. For technology or doctrine icons, use hoi4.tech_inspect in explain or lint mode to verify sprite and texture references, then use the assets or affected folder view in hoi4.tech_render. This skill still owns source art, processing, DDS conversion, placement, manifests, and .gfx/.gui handoff.
Useful assets include:
The asset prompt should state which sprites are decorative and which represent mechanic state. State-driven sprites need clear names that match the mechanic value or route state.
Progression-state variants may include:
Progression-state variants should use the same target size as the base asset.
Every formable nation needs visible identity assets.
Asset planning should cover:
Historical or culturally attested formable symbols need source review. Fictional, alternate-history, supernatural, and extreme-route variants may use generated art with clear manifest notes.
Use hoi4-frame-animation for every final animated visual asset. Some mod mechanics should have animated visual layers when motion improves readability, atmosphere, or feedback. Examples include floating seals, glowing route emblems, particle drift, meter pulses, warning frames, active-button glows, occult pressure effects, sponsor influence networks, and final formable proclamations.
Animated leader portraits should be handled as major identity assets by
hoi4_portrait_creator plus hoi4-frame-animation. Real people require
sourced base images; fictional or impossible leaders use native ImageGen under
the parent brief and never use the portrait provider. The asset handoff must say whether the animation is subtle,
such as breathing light or smoke, or symbolic, such as eye glow, map shadow,
glitch, or spectral overlay. The portrait should still read clearly at in-game
size.
Final animated assets must be built from planned source frames. Do not create final animation by taking one still image and shifting, scaling, rotating, warping, blurring, recoloring, brightening, or pulsing it with a script. Local scripts may normalize, align, crop, resize, assemble sheets, create previews, and convert frames after the real frames exist.
Final PNG assets must be converted to DDS using the repository's standard DDS conversion workflow.
Use the bundled deterministic converter:
python -B .agents/skills/hoi4-feature-assets/tools/convert_to_dds.py --input <processed.png> --output <final.dds> [--width <pixels> --height <pixels>]
The output must be compatible with the mod's expected 32-bit BGRA or B8G8R8A8-style DDS workflow.
If conversion fails, stop and report the error. Do not invent another conversion route unless the user approves it.
After conversion, confirm that:
.gfx path points to the DDSDo not leave only PNG files when the game expects DDS.
.gfx handoff and main-agent wiringAsset subagents do not edit .gfx files by default.
When an asset needs a sprite definition, the asset package must include a handoff note for the main agent.
Recommended path:
docs/assets/<feature_slug>/gfx_handoff.md
The handoff must include:
.gfx file.If the main agent already registered .gfx sprites or texture paths before requesting art, the asset subagent must follow those filenames, sprite names, DDS paths, and target sizes exactly. It should only propose names or paths when they were not provided.
The main agent then:
.gfx file if one exists.When wiring feature-owned sprite-backed art, the texture path should point to the feature-scoped folder for that asset category. If an asset must stay root-only, document the engine reason in the handoff or manifest.
Do not create a new .gfx file if an existing one is clearly the right place. If a new .gfx file is needed, the main agent must name it consistently and document why.
When generated or sourced assets are part of a feature or mechanic, update the relevant docs.
The docs should mention:
.gfx file the main agent should use or has usedDo not leave the docs describing old or missing assets.
When an asset package contains many generated or sourced images, create a contact sheet for review.
Contact sheets are for review only.
Do not use contact sheets as final game assets.
The contact sheet should make it easy to see:
If an asset cannot be created or processed cleanly, mark it as blocked.
Record:
Do not invent a substitute asset unless the user explicitly approves it.
Before finishing, confirm:
$imagegen for approved generated symbolic, fictional, alternate-history, or unique report, news, or large presentation assets; attributed sources for real historical material and every grounded real-person portrait; the selected provider route for final sourced character portraits; native ImageGen for non-sourced fictional or impossible portraits.gfx_handoff.md exists for every asset that needs a sprite definition, and the main agent has enough information to wire it.hoi4-frame-animation, has real source frames, has a static fallback, and has no transform-only final motion..mesh/.anim reimport, hash-aware runtime synchronization, parent-owned wiring, and a live consumer.65x67 advisor workflow, the exact accepted template, retained transforms and hashes, and independent native/4x review; it is not a shrunken leader texture.docs/assets/portraits/<feature_slug>/, a recorded provider replacement state, no invented prompt details, and no runtime reference into that archive.When the installed hoi4-super-events workflow is selected, read its runtime templates and use the declared 457x328 presentation image size. Define the exact role, subject, tone, focal hierarchy, symbolism, source mode, safe text area, prohibited content, final DDS path, and sprite purpose before production. Use sourced archival material for real people, events, places, documents, or objects; use approved generation for fictional, alternate-history, symbolic, or supernatural scenes that do not claim to be historical photographs.
Keep source material, processed previews, provenance, licenses, uncertainty, final DDS output, and GFX handoff together. Review the image at runtime size in the complete popup, then let the main agent wire the sprite, localisation branches, caller, and registration. The examples bundled with hoi4-super-events are composition references only and must not be registered as project art.