Menu
Use when designing, implementing, auditing, or fixing Hearts of Iron IV decisions, missions, timed objectives, decision categories, and mission localisation.
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-decisions-missions |
| description | Use when designing, implementing, auditing, or fixing Hearts of Iron IV decisions, missions, timed objectives, decision categories, and mission localisation. |
Use this skill when a task touches decisions, missions, timed objectives, decision categories, mission UI, costs, trigger tooltips, scripted localisation, AI decision behavior, or balance around decision-driven systems.
This skill is for implementation and cleanup. For broader event wiring, use hoi4-events. For focus trees, use hoi4-focus-trees. For visual assets, use hoi4-feature-assets.
For large or reworked decision systems, spawn hoi4_decision_mission_auditor after implementation and before completion. The subagent is patch-capable by default inside the current task scope. It should audit objective quality, costs, tooltips, AI validity, cleanup, duplicate missions, route integration, fairy-dust rewards, exploit risk, localisation, and balance evidence. It may directly patch small decision, mission, tooltip, dynamic localisation, AI, cleanup, cooldown, visibility, and existing formable requirement issues when the fix is local and clearly safer.
Before editing decisions or missions, read:
AGENTS.mdparadox_wiki/<HOI4_INSTALL_DIR>/<HOI4_INSTALL_DIR>/documentationDo not rely on memory when syntax or UI behavior is documented.
A decision or mission should represent something the country is actually doing. Decisions should also connect to focus routes and wider mechanics instead of sitting as isolated buttons.
Avoid turning decisions into a store where the player spends political power for small modifiers. Do not make a decision category feel like a tray of tiny stat dust. A good decision or mission usually asks the player to commit resources, move units, hold a location, secure supply, manage foreign access, spend equipment, accept risk, meet a deadline, or change a living pressure system.
A mission should feel like an order or objective. A decision should feel like a meaningful choice.
Use the right tool for the job.
Use clickable decisions when the player chooses to start an action, spend resources, accept risk, begin a project, send aid, escalate, negotiate, or select a target.
Clickable decisions should have clear costs, clear requirements, and clear consequences.
Use timed missions when the player needs to achieve something before a deadline.
Timed missions are good for:
Use goal-style missions when the player should not click again after doing the work.
If the objective is “place divisions here,” “hold this capital,” “secure this rail hub,” or “reach this influence threshold,” it should auto-complete when conditions are met.
Do not make the player pay a second click after already satisfying the goal.
Everything that acts like cost, duration, cooldown, support, chance, pressure, threat, reward, mission difficulty, influence, aid amount, or AI willingness should be dynamic by default.
A fixed value can be a tuning anchor, but the system should explain what changes it.
Useful factors:
Do not copy the same cost or duration across every country unless the story and balance justify it.
Do not fill decision systems, missions, scripted GUI buttons, or formable routes with tiny bonuses that feel meaningless. Small values such as plus 1 percent, plus 2 percent, minus 3 percent, tiny political power, tiny stability, tiny war support, small generic stockpiles, or slight production nudges do not count as meaningful design by themselves.
A decision or mission reward should usually do at least one meaningful thing:
Tiny modifiers are allowed only when they belong to a visible stacking system, frequent tick, temporary crisis push, dynamic scaling formula, or larger effect package. They should never be the whole reward for an important decision, mission, GUI button, formable step, route unlock, or crisis response.
If a decision family has many small rewards, combine them into fewer stronger actions, convert them into staged idea upgrades, make them change a visible mechanic value, or replace them with missions, map objectives, units, advisors, buildings, route access, or diplomatic consequences. Do not scatter small bonuses across a category to create the appearance of progress.
Starting penalties and negative mission outcomes must also matter. A failed objective, broken authority value, bad crisis decision, or starting debuff should create pressure the player must answer. Harmless negative modifiers that can be ignored are not valid crisis design.
Scripted GUI presentation cannot compensate for weak gameplay. Do not use glowing buttons, animated seals, long tooltips, or dramatic localisation to make a tiny effect look important. If the action is important enough to receive custom presentation, its gameplay effect must be important too.
Political power and command power are allowed, but they should not be the default answer.
Use varied costs that fit the action:
A military crackdown may use command power, but it should also strain units, consume equipment, risk stability, or affect local resistance when appropriate.
A foreign aid decision may use political power, but it should also require relations, convoys, equipment, route access, consumer goods burden, intelligence exposure, or patronage risk.
A mobilisation decision may require manpower, equipment, training time, supply, local support, or unit placement.
Cost localisation should be short, readable, and icon-first.
Do not prefix every blocked cost line with words like Requires or Needed. In most cases, show only the value and the matching text icon.
Good examples:
2,000 <infantry_equipment_texticon>20 <army_xp_texticon> 20 <command_power_texticon>200 <support_equipment_texticon>Depot controlDo not add filler words between costs.
Use:
20 <army_xp_texticon> 20 <command_power_texticon>
Do not use:
20 <army_xp_texticon> and 20 <command_power_texticon>
If the country does not meet a requirement, show the missing or unmet cost in red. If the country meets the requirement, show it normally.
If a decision has more than three or four simultaneous costs or requirements, do not show all of them inline. Use a short scripted localisation summary:
Requirements met§RRequirements not met§!Then put the full requirement list in a tooltip. The tooltip should still use short icon-first entries. Missing requirements should be red, while satisfied requirements should display normally.
Long triggers should not be exposed raw to the player.
Use:
Avoid showing huge trigger blocks inside the UI.
Any requirement involving places must name the places or a clear named region.
Bad:
required statesborder statessome divisionssufficient troopsenough equipmentGood:
Place 8 supplied divisions in Smolensk, Gomel, and Bryansk.Hold Kyiv and Minsk for 120 days.If the list is dynamic, scripted localisation must print the current targets or explain the named region.
Every named region should have a tooltip or documentation entry explaining which states belong to it.
Do not create passive checklist missions that the player already satisfies.
Bad missions:
Good missions:
Even easy missions should require real action. Easy should mean lower risk or shorter scope, not passive.
Timed missions need enough time for the player and AI to act.
Use varied durations based on mission difficulty.
Recommended bands:
Emergency missions can be shorter only when the event story clearly justifies immediate danger.
Do not give every mission the same timer.
Success and failure must use distinct effect logic.
A successful stabilising mission should lower or stabilise the relevant pressure. It should not raise the main threat by accident.
Failure should create consequences, such as:
Partial success is useful when a mission has mixed outcomes.
Example:
A heavy-handed success may lower one pressure while raising another. The tooltip must explain the tradeoff.
Do not overload a decision category with too many active missions.
When a system has many possible missions, use:
Only show the most relevant active missions. A player should not see a wall of similar objectives.
If the spec defines a cap, respect it.
Before claiming completion, audit for duplicates.
Duplicate warning signs:
Create or update a mission audit for large systems.
Suggested audit table:
| Mission | Owner | Category | Region | Requirement | Duration | Success effect | Failure effect | Duplicate risk |
|---|
Merge, remove, or rewrite duplicates.
Foreign intervention should be action-based, not passive stockpile checking.
Good influence decisions include:
Influence should be tracked per sponsor and per target where relevant.
Useful influence categories:
If one sponsor dominates, puppet pressure or dependency risk should rise. If several sponsors balance each other, the target should gain more independence resilience.
Some missions should improve existing ideas rather than create new ones.
Stackable mission ideas can represent:
A base idea can be weak at first and mature through mission success.
Example recognition progression:
Do not create a separate idea for every mission if the same institution is clearly growing.
Focuses and decisions should be designed together.
A decision system should not feel detached from the focus tree. Focuses should unlock new decision families, expand existing mechanics, change decision costs, alter mission success conditions, add new targets, or open new diplomatic, military, industry, or expansion choices.
Common patterns:
When a focus unlocks decisions, document:
When a decision family is route-locked, localisation should explain which political, expansion, industry, military, diplomacy, or league route enabled it.
Industry decision families should generally do real map work, such as building or repairing factories, railways, forts, anti-air, airbases, infrastructure, supply hubs, ports, or resources.
Expansion decision families should generally create real strategic options, such as claims, cores, war goals, protectorates, leagues, declarations, border incidents, treaties, ultimatums, or postwar settlement choices.
Decision categories should evolve as the focus tree develops.
A decision category should not remain a static list of buttons after a country changes ideology, builds an industry route, joins a league, chooses an expansion path, or accepts foreign influence.
Focus progress can change decision systems by:
Examples:
If a focus branch says it changes the country, the decision layer should reflect that change.
A decision family unlocked by a focus path must have enough content to matter.
A route-unlocked decision family should usually include:
Expansion decision families should include postwar handling when they create conflict. War goals, declarations, ultimatums, and border incidents should connect to occupation, integration, protectorate, puppet, resistance, league, faction, or settlement decisions.
Industry decision families should be geographically grounded where possible. Construction, rail, supply, anti-air, fort, airbase, dockyard, port, and resource decisions should name states or regions, and they should change the map or production system.
Political decision families should interact with leaders, advisors, parties, laws, ideology, legitimacy, councils, internal factions, cosmetic names, or flags when the focus route changes politics.
Advisor, leader, and council decisions should match the route that unlocked them. Do not unlock generic advisors unrelated to the route identity.
Decision families can include achievement tracking when they support difficult route completions, rare combinations, expansion victories, internal reform, or survival under extreme-route conditions.
Decision categories unlocked by focuses should progress over time.
Decision families should have tradeoffs. A powerful decision should cost or risk something that fits the action: equipment, manpower, stability, war support, consumer goods burden, foreign dependency, legitimacy, faction cohesion, unit commitment, fuel, convoys, or crisis pressure.
Do not overuse mutually exclusive decision paths. Use them when the choices represent incompatible policy, route identity, foreign alignment, or institutional structure. Support actions should usually coexist unless the design says otherwise.
Important decision families should define failure states. Failed reforms, failed influence balancing, failed expansion, failed military centralisation, failed construction, or failed diplomacy should create visible follow-up problems where the mechanic supports it.
Decision localisation should describe the visible baseline effect of the decision. Do not reveal hidden outcomes, secret variables, hidden follow-up events, or future surprise branches. The player should understand the public action and likely visible direction without being spoiled.
Large decision and mission systems should interact with special mechanic values.
Special mechanic values can include legitimacy, authority, influence, faction cohesion, command obedience, public panic, regional control, military readiness, industrial capacity, corruption, foreign penetration, balance-of-power position, league cohesion, or sponsor pressure.
Decisions and missions should change these values through visible actions. Do not make a mechanic where values only drift passively or change through a few flat hidden effects.
Good examples:
If a mechanic has a total value made from several components, the UI should show a readable breakdown through scripted localisation or tooltips. Each important component should be named and use a consistent colour identity.
Examples of colour identities:
Use project-appropriate colours, but keep each value consistent across decisions, missions, events, tooltips, and UI summaries.
Balance-of-power or equivalent internal struggle mechanics should be considered when a country has competing power centers. Decisions and missions should push the balance, create risks, unlock branch content, and affect leaders, laws, advisors, events, or crises.
When a decision system creates or manages a faction, league, bloc, coalition, compact, or alliance, define its goals and rules. Include membership conditions, joining logic, refusal logic, expulsion or removal logic where relevant, shared decisions, war goals, AI behavior, victory conditions, and failure conditions.
Important feature-created factions should usually have a mechanic such as cohesion, shared command, war council support, joint reserves, recognition, member confidence, sponsor pressure, or strategic goals. Decisions and missions should interact with that mechanic.
A faction should not form just because one country exists. Use minimum membership, crisis pressure, ideological compatibility, war state, diplomatic preparation, or regional logic.
Special mechanic values must be visible somewhere the player can understand them. A decision category can show values in its header, a custom scripted GUI, a progress meter, a scripted localisation tooltip, or national spirit tooltips
When a mechanic uses a scripted GUI, consider whether it needs visual state changes. Useful presentation can include progress bars, meter fill variants, status icons, warning frames, selected and locked frames, animated frames, or frame-by-frame changes. Use visual motion or variants only when they clarify the mechanic.
Special mechanics can hide future surprises, but should not hide basic cause and effect. If a visible value rises or falls, the player should understand the public reason and the broad response available.
Faction, league, bloc, or coalition goals need rewards and failure states. A successful faction goal can unlock shared decisions, war goals, legitimacy, cohesion, member rewards, postwar settlements, or new faction leadership. A failed goal can reduce cohesion, trigger member exits, invite foreign pressure, start leadership contests, weaken shared defenses, or open emergency missions.
AI strategy must respect route and decision validity. AI should not take decisions that require missing states, dead sponsors, non-existent factions, unavailable ideologies, disabled escalation variants, impossible borders, absent enemies, invalid targets, or closed routes. Invalid actions should be hidden, bypassed, or weighted to zero.
Decision systems for shared trees or shared mechanics must still feel country-specific. Use scripted localisation, country-specific targets, country-specific AI weights, local leaders, regional decisions, and route-specific rewards to prevent every country from playing the same.
Important thresholds, caps, gains, losses, duration bands, AI weights, and scaling values should be centralized in script constants or a documented tuning file. Do not scatter magic numbers across decision files, events, focuses, scripted effects, and scripted triggers.
Avoid one-time reward dumps as the main decision or mission design. A decision or mission can give units, equipment, factories, buildings, resources, or influence, but important decisions should usually connect to a repeatable system, timed objective family, mechanic value, advisor path, route branch, or long-term gameplay loop.
A large decision system should not become a sequence of buttons that only give free rewards.
A large decision system should also not become a sequence of tiny fairy-dusted rewards. Repeated minor modifiers, token stockpiles, small stability changes, and tiny production nudges are not better than reward dumps when they do not change play. Treat low-impact reward dust as a design failure unless it is part of a visible cumulative system with clear thresholds and consequences.
Balance review must include exploit checks and impact checks. The question is not only whether the decision can be abused. The question is also whether a reasonable player would notice the reward, care about the failure, and plan around the system.
Check for:
Fix exploits with route locks, flags, cooldowns, dynamic costs, limited targets, escalating costs, one-time completion flags, scripted triggers, AI limits, or cleanup effects.
Large decision systems should not show every possible decision at once.
Use phases, caps, priorities, regional pools, route locks, mechanic thresholds, or crisis-state filters so the player sees decisions that matter in the current situation.
A decision category should feel curated by current state, not like a debug menu.
Good clutter-control patterns:
For large targeted decision families, prefer a separate target-management category over dumping every target row into the main mechanic category. Use a compact Show Decisions for [FROM.GetName] / Hide Decisions for [FROM.GetName] flow when the human player only needs to inspect or act on one target at a time. AI should still see all decisions at once.
The reusable selected-target pattern is:
FROMDo not leave stale, invalid, or irrelevant decisions visible simply because their scripted trigger is easy to write.
Use decisions for formable nations when the player should prove control over land, complete a political route, or spend resources before changing the country identity. A formable decision should feel like a proclamation, settlement, congress, coronation, constitutional act, annexation settlement, liberation charter, or administrative project. It should not be only a hidden tag switch.
A formable decision must define:
State requirements must be readable. Use named state groups and custom trigger tooltips. Do not expose raw state id lists to the player unless the existing UI pattern already does that cleanly. If several alternate maps can qualify, create clear requirement groups.
Hidden formables need extra care. A hidden formable can be locked behind an event, secret focus, rare ideology, high escalation, special leader, historical artifact, quote, remark, audio, achievement route, or scripted GUI investigation. Hidden does not mean undocumented. The implementation handoff must still define all triggers, effects, assets, and cleanup.
Large formables should usually need post-formation work. Use missions or decision chains for integration when instant cores would be too strong.
Good formation follow-ups include:
Formation systems should support partial success and failure. A country can form the title but gain only claims, delay core grants, create dissatisfied regions, trigger rival reactions, or open emergency missions.
When a decision category controls a major mechanic, consider attaching a scripted GUI or opening a custom mechanic window from a category button. This is appropriate when the player needs to manage values, targets, meters, factions, sponsors, province groups, formable requirements, investment tracks, or competing internal blocs.
When the category or mission package is connected to a focus tree, scripted GUI, or map change, use the corresponding MCP inspect, render, and rewrite tools. Keep the decision costs, triggers, AI, localisation, cleanup, and balance rules in this skill.
Use hoi4.gui_inspect to map linked layout, states, resolutions, click regions, localisation, sprites, fonts, and animation, then call hoi4.gui_render for deterministic normal, cropped, annotated, state, resolution, click-region, hierarchy, and comparison views. MCP diagnostics expose bad alignment, uneven spacing, overlapping controls, clipping, overflow, broken click regions, state mismatches, resolution drift, missing assets, and other layout defects. Use hoi4.gui_rewrite for an in-scope GUI change after reviewing those diagnostics and the render fidelity report.
A scripted GUI or custom window must have a gameplay reason. It should expose useful choices, not merely decorate a category.
Interactive GUI design should define:
When buttons spend resources, show the cost clearly. Use icon-first cost localisation. If the GUI button has more than a few requirements, show a short requirement summary and put details in a tooltip.
Do not use GUI buttons to bypass decision balance. GUI buttons should call the same scripted effect families, cost logic, validation triggers, logging, and cleanup that the normal decision system would use.
Decision categories and mechanic windows can use animated sprites when motion improves readability or atmosphere. Suitable uses include:
Use static fallback sprites for every animated element. Keep animations subtle unless the route is deliberately supernatural or extreme-route. Do not animate every icon in a category. Too much movement makes the UI harder to read.
The decision implementation handoff should list animated sprite names, static fallback names, target sizes, frame counts if known, loop behavior, file paths, source mode, and whether the animation is purely decorative or tied to a mechanic state.
Every important decision family and mission family needs AI behavior.
AI should understand:
Avoid flat ai_will_do when campaign state matters.
For complex decision or mission weights, use hoi4.probability_inspect to find required inputs, hoi4.probability_evaluate for named campaign states, hoi4.probability_sweep for thresholds and rank reversals, and hoi4.probability_compare after a source change. Use hoi4.probability_simulate only for explicitly declared uncertain inputs, and use hoi4.probability_render when the ranking, matrix, sensitivity, comparison, or unresolved view improves review. Decision and mission ai_will_do results are willingness scores, so do not present them as click probabilities. Include availability, target, cost, cooldown, and route state where relevant, and retain unresolved engine state in the result.
AI should not take suicidal or nonsensical decisions just because they are available.
Decision categories and missions should have lifecycle cleanup.
When the crisis, war, target, or country state ends:
Do not leave stale missions active after the system they refer to has ended.
For every decision or mission, provide:
Do not leave placeholder localisation.
Player-facing text should describe the world state, not implementation history.
Avoid phrases such as:
For large decision and mission systems, balance review is required.
Review:
Document test scenarios or observations. Do not only say “balanced.”
When an improvement addendum proposes decision depth, scripted GUI, or mechanic windows, translate the design into active play. The decision category should show the mechanic clearly, but the gameplay should still live in decisions, missions, scripted effects, scripted triggers, AI rules, and cleanup logic.
Use scripted GUI when the player needs to read or manage values that would otherwise be buried in tooltips. Good uses include influence boards, federation congresses, formable progress, patron leverage, resource routing, public fear, occult pressure, faction cohesion, reform votes, target cards, and timed crisis panels.
A GUI button should be treated like a decision. It needs cost logic, requirement logic, tooltips, scripted effects, AI equivalents, state cleanup, and a visible result. Animated buttons, glowing meters, floating seals, and warning pulses should clarify state changes. Do not use animation to hide the cost or make a weak action look important.
For formables, the decision should verify the map state. Focuses may reveal claims, prepare institutions, or reduce costs, but the formation decision should prove control, legitimacy, recognition, or integration when those are central to the idea.
Decision and mission subagents are active small-patch agents by default inside the current task scope. They can patch varied costs, clearer dynamic localisation, custom trigger tooltips, AI target checks, cleanup hooks, visibility checks, cooldown fixes, scripted GUI button text, narrow helper call sites, and existing formable requirement fixes without waiting for a separate permission prompt.
They should not expand a whole decision system, create a new mechanic window, add a new event chain, or invent a formable suite. When the gap is broad, they should write an improvement plan under docs/plans/<feature_slug>/ and leave implementation to the main agent.
Every patch must write a handoff with changed files, changed decision or mission ids, localisation keys, behavior before and after, meaningful validation, skipped task-specific validation, and remaining design risks.
A decision or mission task is complete only when:
If anything was simplified, skipped, approximated, replaced with a weaker substitute, or reduced to tiny low-impact modifiers, report it clearly.
If nothing was simplified, say so and provide evidence.