القائمة
Use when designing, implementing, auditing, or fixing Hearts of Iron IV national focus trees.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
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-focus-trees |
| description | Use when designing, implementing, auditing, or fixing Hearts of Iron IV national focus trees. |
Use this skill when a task touches national focus trees, focus-tree loading, focus effects, focus layout, focus localisation, focus icons, focus AI, focus-tree documentation, or feature-created country trees.
This skill is the detailed focus-tree source of truth for AGENTS.md. Keep the root AGENTS.md concise and put reusable focus-tree design, implementation, audit, and completion standards here.
Use this skill together with:
AGENTS.md for repository-wide ruleshoi4-events when the tree belongs to an eventhoi4-decisions-missions when focuses unlock, modify, or depend on decisions and missionshoi4-feature-assets when focus icons, leader portraits, flags, or idea icons are requiredimprovement-loop when a tree needs broader route depth or a near-completion anti-bloat passsubagents before routing focus audits, improvement plans, or active small patcheshoi4-agent-tools MCP server for hoi4.focus_inspect, hoi4.focus_render, and bounded hoi4.focus_rewrite work. Use it to inspect, render, lint, compare, and improve focus-tree structure, then review every returned layout and diagnostic. MCP supports this skill and does not replace required source, wiki, vanilla, balance, localisation, asset, or AI review.Before editing focus files:
<HOI4_INSTALL_DIR>/documentation.AGENTS.md.hoi4-decisions-missions when focuses unlock decisions, timed objectives, missions, or dynamic mechanics.Do not rely on memory for prerequisite behavior, layout behavior, AI syntax, or search filters.
Use hoi4.focus_inspect and hoi4.focus_render before major layout work or complex audits. Use bounded hoi4.focus_rewrite only after the route design and ownership are clear. Review the returned source diff, diagnostics, and rendered artifacts before accepting any MCP write.
HOI4 focus prerequisites are easy to invert.
This means OR:
prerequisite = { focus = a focus = b }
This means AND:
prerequisite = { focus = a }
prerequisite = { focus = b }
Use vanilla examples before changing complex prerequisite and mutual-exclusion structures.
A focus tree is the playable identity of a country. It should define what problems matter, which strategies solve them, and what kind of state the player builds.
A good focus tree gives the country:
A tree should not stay politically static unless the country is intentionally fixed by its concept.
Do not begin a country with a long stack of focus-tree-owned national spirits, currencies, decision categories, and unrelated penalties merely to create work for the opening branches.
For a new or focus-tree-owned country setup, prefer zero to two starting national spirits. Use a third only when all three represent separate problems or institutions that the player can understand immediately. The hard simultaneous limit in section 9 still applies. Established countries can retain historically necessary starting systems, but their opening presentation should still identify the few pressures that matter first.
Choose one to three strategic constraints that define the opening. Good constraints include resource shortage, weak supply, limited civilian capacity, disputed legitimacy, dependence on a sponsor, an underdeveloped officer corps, or vulnerable borders. Each constraint must create choices and have more than one credible response. Do not use a long stack of debuffs as a substitute for country identity.
The starting army, navy, air force, economy, and decision layer should be simple enough that the player can understand the country's immediate problem in one pass. A large historical empire can remain geographically complex, but the tree should still give it a clear first priority and delay secondary problems until they matter.
Do not remove all scarcity in the opening focuses. Scarcity can create the reason to trade, industrialize, seek a patron, change laws, build logistics, or expand. The tree should let different routes solve or exploit the same constraint in different ways.
A large tree can contain many routes without presenting all of them on day one. Required route coverage applies to the complete tree, not to the number of root focuses visible at game start.
Use a narrow opening by default:
More opening choices are allowed when the country genuinely begins with several simultaneous emergencies, but each visible option must answer a different urgent question. Do not create an octopus root where the player must inspect the whole tree before unpausing.
The first few focuses should establish the campaign plan. Good early choices distinguish short-term mobilization, medium-term institution building, and long-term transformation. Bad early choices grant interchangeable small bonuses and only become meaningful several focuses later.
Complexity should expand downward. Later branches can become intricate after the player understands the country, its constraints, and the consequences of the first commitment.
Do not add political routes to satisfy an ideology checklist. A focus tree does not need democratic, communist, fascist, monarchist, anarchist, religious, and military routes merely because those labels exist.
A political route earns a place only when it has:
Omit a route when it would be a short filler branch with generic party popularity, political power, and one cosmetic change. Political variety can come from rival institutions, leaders, factions, constitutional models, patron relationships, or methods of rule inside the same broad ideology.
Route coverage tables compare the accepted spec with the implementation. They are not a generic ideology quota. A deliberately omitted ideology is not a defect when the country concept and source design do not support it.
Use this test before expanding a route map or accepting an implementation.
A strong tree usually:
Reject or redesign a tree when it:
2-5% bonuses or other low-impact rewardsThis test is a design gate, not a rigid template. A direct factory or equipment reward can be good. A 70-day focus can be good. A peaceful country can omit early war. The tree must still provide clear choices, visible progress, meaningful interaction, and a payoff that fits its identity.
Use path-level design unless the user explicitly asks for a focus-by-focus blueprint.
The spec usually defines:
The implementation agent owns:
The final tree must preserve the route logic and gameplay intent from the spec.
Large, playable, long-lived, or feature-created countries need real focus trees.
A major tree should usually include:
Do not collapse everything into one political ladder.
Every major tree should identify the country's opening constraint and the actions it creates. A shortage of steel, fuel, convoys, trained officers, supply, legitimacy, civilian capacity, recognition, or secure borders can be good design when the player can respond through several strategies.
Do not make the first branch simply erase every weakness. Different routes should answer the constraint differently. Examples include domestic substitution, foreign trade, patron aid, legal reform, infrastructure, military seizure, limited expansion, or accepting dependency in exchange for speed.
Domestic-development and foreign-integration routes must use different mechanics and incentives. Different factory totals alone do not create distinct routes. A domestic route can emphasize resource surveys, substitution, savings, law interactions, construction burdens, or slower self-sufficiency. A foreign route can use relations, investment, market access, technology exchange, convoys, sponsor pressure, or dependency risk.
The tree should provide an active play opportunity early. Depending on country identity, this can be a limited conflict, border intervention, diplomatic campaign, construction program, military preparation mission, internal political contest, or resource strategy. The player should not have to complete years of filler before the country begins doing what its campaign concept promises.
Use a payoff ladder:
When a payoff requires compliance, stockpiles, relations, state control, laws, unit placement, or another non-focus condition, the route must provide tools that help the player reach it. A requirement without supporting gameplay is obstruction, not depth.
Political, industry, and expansion are the minimum branch families, not a full large-country tree. Important countries should usually also have military, diplomacy, internal faction, intelligence or security, special mechanic, and late-game branches when their identity supports them.
Branches should not be isolated columns. Political choices should alter which expansion, industry, military, diplomacy, and decision paths are available. Industry should support military or expansion. Expansion should create political consequences. Diplomacy should affect both foreign aid and war options.
Every major branch needs a clear payoff.
Examples:
A focus should usually unlock new gameplay, not only stats. Strong focus rewards unlock decisions, missions, units, advisors, leaders, laws, claims, cores, war goals, buildings, events, mechanics, route access, or AI behavior. Flat modifiers are supporting rewards, not the main design.
Political routes should update the visible country package where relevant:
Leader changes require portrait handling. Real leaders use sourced portraits. Fictional leaders, councils, symbolic leaders, or extreme authorities can use generated portraits through the asset skill.
Expansion branches should create consequences. Claims, cores, and war goals should usually interact with diplomacy, factions, resistance, foreign guarantees, local leagues, legitimacy, threat, or postwar settlement decisions.
Industry branches should usually create visible map or production changes: factories, infrastructure, railways, supply hubs, forts, anti-air, airbases, dockyards, resources, production lines, or construction decisions.
Decision categories should evolve with focus progress. Early focuses may unlock basic decisions. Later focuses should add new targets, stronger actions, cheaper costs, new risks, or new mission families. A decision category should feel different after a route develops.
The fixed-purpose exception is narrow. A country is fixed-purpose only when its concept clearly cannot support normal politics, such as a death-state, machine-state, plague-state, or pure destruction actor. It still needs meaningful internal branches around method, hierarchy, economy, recruitment, expansion, and endgame.
A branch does not count as a real branch unless it has enough content to change gameplay.
A real branch should usually include:
A branch made of one or two generic focuses is not a branch. It is a support node.
Large-country branches should not be shallow labels. If a tree says it has a political branch, industry branch, expansion branch, military branch, or diplomacy branch, each of those branches must have enough content to be felt in play.
Do not leave large focus trees full of dead ends. A terminal focus is acceptable only when it is a real capstone, convergence point, failure state, route lock, formable completion, settlement outcome, late-game ambition, or deliberately optional side payoff.
A focus line has failed if it stops after a small modifier, an isolated national spirit, a token equipment grant, a generic stability reward, or a decorative political power payout. Side branches can end, but their final focus must feed back into the country identity, a decision family, a mechanic value, a new unit path, a map change, an advisor set, an expansion route, or another visible route payoff.
Do not create one-focus or two-focus spurs just to fill space. Merge them into a nearby branch, turn them into decisions, make them part of an idea lifecycle, or build them into a real side path with a clear purpose.
Every major branch should answer what the player does after finishing it. Good answers include a stronger decision category, a new diplomatic stance, a changed army system, postwar integration work, a formable route, a crisis response loop, a new expansion policy, or a late-game convergence path. A finished branch that only leaves the player with passive numbers is not enough.
Every major route needs route-specific AI strategy. AI should not only have generic focus weights.
AI should understand:
Every major route also needs a distinct localisation tone. A socialist route, military route, democratic route, nationalist route, religious route, machine route, death-state route, foreign client route, and extreme route should not sound the same.
Focus titles and descriptions should make the route identity clear without using generic filler language.
Expansion branches must define what happens after victory.
War goals alone are not enough. Expansion routes should include postwar handling such as:
Industry branches should be geographically grounded. Important factories, resources, ports, railways, supply hubs, forts, anti-air, and airbases should be tied to relevant states or named regions when possible, not granted only as abstract country-wide bonuses.
Advisor unlocks should match route identity.
Examples:
Large focus trees should include achievement hooks for difficult route completions, rare branch combinations, expansion outcomes, successful internal reform, avoiding foreign dependency, forming leagues, surviving extreme paths, or completing hard late-game ambitions.
For every major focus tree, the completion report must include a route coverage table comparing the spec's required routes against implemented routes.
Required table columns:
| Required route | Implemented route or focus branch | Status | Notes |
|---|
Missing, renamed, merged, simplified, fallback, or replaced routes must be reported.
A major route should leave visible evidence in the game. This can include map changes, new decisions, new units, new advisors, changed leader, changed flag, changed cosmetic name, new faction behavior, new focus availability, changed diplomacy, or a visible mechanic. A route that only changes hidden variables or tiny modifiers is not meaningful.
Large focus trees should have early, middle, and late pacing.
Every major route should have a tradeoff. A military route may reduce freedom or legitimacy. A foreign-aid route may increase dependency. An expansion route may create resistance or foreign backlash. An industry route may consume civilian capacity or weaken short-term defense. A extreme route may give power while damaging stability, diplomacy, or normal politics.
Do not overuse mutual exclusions. Mutually exclusive paths should represent real identity changes, strategic commitments, or incompatible institutions. Support branches like industry, army, diplomacy, and logistics should usually coexist unless the route logic says otherwise.
Important routes should define failure states. A failed political reform can empower radicals. Failed expansion can trigger backlash or settlement. Failed industry can create dependency. Failed foreign-aid balancing can create a client state. Failed military centralization can create rogue generals or militias.
Focus and decision localisation should tell the player the visible baseline effect of the route or action. It should not reveal hidden effects, secret outcomes, hidden variables, or future surprises. The player should understand what the focus visibly does, such as moving toward military rule, opening an industry program, unlocking a public diplomatic route, forming a League office, or preparing border claims, without being told about hidden follow-up effects.
Large focus trees should interact with the event or country special mechanic. A major tree should not sit beside the mechanic without changing it.
Special mechanic values can include:
Focuses should affect mechanic values directly when the country has such a mechanic. Political focuses can change legitimacy, balance of power, party strength, faction cohesion, or authority. Industry focuses can change industrial capacity, construction pressure, resource control, or economic recovery. Military focuses can change readiness, command obedience, recruitment, or defensive preparedness. Diplomacy focuses can change influence, recognition, sponsor pressure, faction cohesion, or foreign penetration. Expansion focuses can change threat, legitimacy, claims, resistance, local support, or faction goals.
Mechanic values should unlock or block content. A value should not only be a number. Values should affect focuses, decisions, missions, events, advisors, leaders, laws, factions, war goals, reforms, crises, or endings.
Important internal struggles should consider a balance of power or equivalent mechanic. Good balance-of-power conflicts include army versus parliament, factory councils versus ministries, monarchists versus republicans, foreign patrons versus national independence, security service versus civilian cabinet, or cult authority versus military command. Focuses and decisions should push the balance and unlock branch content, risks, leaders, laws, advisors, or events.
When a focus tree creates or leads a faction, league, bloc, compact, coalition, or alliance, that faction needs goals and rules. Define membership conditions, joining logic, refusal logic, expulsion logic where relevant, war goals, shared decisions, 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.
Factions should not form too easily. Define minimum membership, crisis conditions, ideological compatibility, war pressure, diplomatic preparation, and regional logic.
Special mechanics must be visible somewhere the player can understand them. A mechanic can appear in a decision category header, custom scripted GUI, progress meter, scripted localisation tooltip, focus tooltip, national spirit tooltip, or a combination of these.
When a mechanic is important enough for a custom scripted GUI, consider visual presentation beyond static text. Useful presentation can include progress bars, meter fill variants, state icons, status frames, warning frames, selected and locked variants, animated frames, or frame-by-frame visual changes that make the mechanic feel alive. The visuals should clarify the mechanic, not clutter it.
Special mechanics can hide future surprises, but they should not hide basic cause and effect. The player should understand why a visible value rose or fell, which public action changed it, and what broad type of response is available.
AI strategy must respect route validity. AI should not pick a branch that requires a missing state, dead sponsor, non-existent faction, unavailable ideology, disabled event variant, impossible border, or absent enemy. Invalid routes should be hidden, bypassed, or weighted to zero.
A new playable country package must not be generic. It needs a specific identity, starting problem, political direction, map role, military style, economy, diplomacy, AI behavior, and at least one mechanic or decision family that makes it play differently from other new countries.
Shared trees are allowed, but they must be adapted. Shared trees need country-specific localisation, route names, decisions, AI weights, leaders, rewards, icons, and scripted localisation where relevant. If every country using a shared tree reads and plays the same, the tree has failed.
When a route changes leader, ideology, faction, cosmetic name, flag, advisor roster, or special mechanic identity, the focus-tree spec and implementation should account for the needed visible assets and whether they are reused, sourced, generated, or blocked.
Important mechanic thresholds, caps, gains, losses, duration bands, AI weights, and scaling values should be centralized in script constants or a clearly documented tuning file. Do not scatter magic numbers across focus files, decisions, events, scripted effects, and scripted triggers.
Avoid one-time reward dumps as the main design. A focus can give factories, units, equipment, resources, or buildings, but important focuses should often unlock a repeatable decision, timed mission family, production route, advisor, mechanic, route branch, or long-term gameplay system.
A one-time reward is acceptable when it fits the story and balance, but it should not be the main reward pattern of a large tree.
Before claiming completion, review the tree for exploits:
If an exploit is possible, fix it with limits, flags, dynamic costs, cooldowns, route locks, scripted triggers, AI limits, or one-time completion flags.
Focus trees that unlock many decisions should also define how those decisions are staged.
Do not unlock every possible decision at once. Large decision systems should use phases, caps, priorities, regional pools, route locks, or crisis-state filters so the player sees the decisions that matter now.
A decision category should feel curated by the current country route and campaign state, not like a debug menu.
Focuses can control clutter by:
Focus duration should match the decision value and campaign tempo. Duration is not a reward-strength number and should not be forced into the general round-value rule. Established weekly focus cadences such as 7, 14, 21, 28, 35, 56, and 70 days are valid when the role of the focus justifies them.
A short focus is useful when it does one of these things:
A short focus is click tax when it only divides one ordinary reward into several pieces. Do not split a 70-day factory, research, or modifier reward into two 35-day focuses unless the first half changes the player's decision or creates a meaningful intermediate state.
Use 7-day transition focuses sparingly for immediate political resolutions, route conversions, emergency responses, or post-event handoffs. Do not use them for large unconditional reward dumps. Use longer focuses for major institutions, strategic preparations, and capstones when the delay itself creates planning pressure.
As a normal target, a major tree should present a meaningful choice within the first 70 days and an active route interaction within the first 180 days. This is a pacing target, not a universal hard gate. A deliberate exception must explain what the player is doing during the delay and why the delay belongs to the country concept.
Meaningful bonuses can be large. Balance strong effects with costs, timing, risk, or counterplay instead of reducing every reward to a small modifier.
Useful prices include:
Short-term, medium-term, and long-term options should feel different in play. An immediate mobilization path can deliver fast factories or units with a later hangover. A permanent-output path can be slower and narrower. A long-war path can improve research, doctrine, logistics, or scaling while leaving the opening weaker. Do not make one horizon strictly dominate the others in every plausible campaign.
High-risk focuses can be optional. Do not force every player through a powerful temporary boom and its penalty merely to reach unrelated content. The tooltip must explain the visible price and duration without exposing hidden follow-up events.
When a strong tradeoff represents an ongoing policy, consider letting the player suspend, replace, or reverse it through a decision, law, or later focus. Irreversible institutions can justify permanent commitment. Permanent penalties are appropriate when the route is an identity commitment. They are not appropriate merely because no off-switch was designed.
Every large focus tree should have a distinct expansion, reunification, liberation, federation, settlement, or regional ambition branch.
This branch must be separate from the main political tree and separate from the industry tree.
The expansion branch should actually change the map or diplomatic order. It should not be a line of generic bonuses.
Good expansion branch effects include:
Expansion should follow the country's ideology, geography, trauma, economy, military doctrine, foreign patron, crisis state, or special identity.
Bad expansion branches:
When the country's concept includes expansion, intervention, border revision, or reunification, consider an early high-risk route and a slower preparation route. The early route should let the player act before the wider war when geography and balance support it. The long route can build alliances, compliance tools, logistics, recognition, or overwhelming strength.
Early action does not require unrestricted total war. Limited-conflict systems can make small-country expansion playable without forcing an immediate fight to total capitulation against a major power. A limited conflict should define:
A limited conflict must not become a cheap annexation shortcut. The objective should be narrow, the settlement should match what was achieved, and repeated use should create costs, resistance, diplomatic pressure, or stronger opposition.
When a branch represents war fervor, mobilization pressure, or a public promise to fight, prefer a visible timed commitment over several instant war-support rewards. The commitment can build readiness or war support over time, then ask the player to begin the promised action before a deadline. Failure should create route-appropriate political backlash, lost legitimacy, demobilization, or a harder settlement. Do not default to a generic civil war merely because the deadline was missed.
Not every country needs an early war. A country without a plausible conflict route still needs early active play through diplomacy, internal politics, resource policy, construction, military objectives, or another system that fits its identity.
Expansion should usually answer a real strategic need such as resources, secure borders, ports, supply access, diaspora protection, ideological goals, or regional legitimacy. Map growth without a country-specific reason is not a branch identity.
Large focus trees must alter politics directly.
Political branches should include meaningful changes such as:
A country should not remain politically static through a major focus tree unless that is the explicit concept.
Examples of route families:
Fixed-purpose special feature-created countries can have narrower political design. For example, a country whose entire identity is death, plague, machine rule, or total destruction may have one ideological purpose. Even then, its tree should still create mechanical choices inside that purpose, such as doctrine, expansion method, internal hierarchy, recruitment, economy, and endgame ambition.
When a political route centers on choosing or creating a leader, regent, council, junta, cabinet, or symbolic authority, consider letting the player construct that identity through events or decisions. Avoid granting one fixed trait package when personal construction is central to the route.
A leader-construction sequence should normally offer a small number of consequential choices, such as economic priority, military temperament, constitutional relationship, diplomatic posture, or personal doctrine. The choices should:
Do not add leader customization to every tree. Use it when personal rule, a regency, a council struggle, or a constructed political identity is central to the country concept.
Focus rewards must be concrete and varied.
Do not make most focuses grant:
Use effects that change play.
Good rewards include:
When a focus grants, unlocks, removes, or redirects a technology, doctrine, or research bonus, use hoi4.tech_inspect in impact, unlocks, or bonus_coverage mode to verify the linked graph and references. Render the affected folder or branch with hoi4.tech_render, then use hoi4.tech_compare after source edits. Treat missing assets, disconnected prerequisites, misplaced items, exclusivity errors, and unresolved dynamic behavior as implementation findings instead of guessing.
Small numeric modifiers can support a focus, but they should not be the main point of most focuses.
Fairy-dusted values are prohibited. Do not spread many tiny bonuses across a focus tree and present them as depth. Values such as +2%, +3%, +7%, 12, 18, tiny political power grants, tiny stability or war support changes, token equipment, and slight generic production bonuses are completion-blocking defects unless an engine-defined formula or hard technical constraint requires that exact value.
Use round balance values in multiples of 5 wherever the value is authored for gameplay tuning. Prefer values such as 5, 10, 15, 20, 25, and corresponding percentage values. Do not use arbitrary-looking values such as 2, 3, 7, 12, 18, or 23 for focus rewards, mechanic gains or losses, thresholds, caps, durations, AI weights, or costs without a documented reason. Engine-required values, binary flags, coordinate values, dates, state ids, and formula-derived results are exempt.
A focus tree with repeated fairy-dusted rewards must be rejected during audit. Do not excuse the pattern because each individual value is technically useful. Merge weak rewards, strengthen them into meaningful round values, turn them into staged upgrades, or replace them with decisions, missions, map changes, units, advisors, laws, mechanics, or route access.
A focus reward should usually do at least one of these things:
If a focus mainly gives a small flat modifier, the implementation must justify why that modifier matters. It can be acceptable as one part of a larger reward package, a frequent stack, a temporary crisis push, or a final adjustment to an existing mechanic. It is not acceptable as the whole reward for an important focus.
Do not scatter many tiny modifiers across a tree to create the appearance of progression. Combine weak rewards into fewer stronger focuses, convert them into staged idea upgrades, or replace them with decisions, missions, map changes, unit paths, advisors, mechanic thresholds, or route access.
Completion reports and focus audits must flag fairy-dust rewards. A route with many tiny standalone rewards should be treated as incomplete until the rewards are merged, strengthened, connected to a mechanic, or replaced with visible gameplay.
Do not create a new idea in every focus.
Use an idea only when it represents a lasting institution, doctrine, route identity, military structure, economic system, or crisis condition.
When an idea already represents the institution, later focuses should usually:
New or unstable countries should often start with a few negative or mixed ideas, then solve or transform them through the tree.
Examples:
Every important starting idea should have a lifecycle:
A focus tree must never grant or maintain more than three focus-tree-created national spirits at the same time for one country. This is a hard maximum, not a target.
Before adding a fourth spirit, the implementation must upgrade, replace, merge, transform, or remove one of the existing three. Starting national spirits that belong to the same focus-tree package count toward this limit when the tree is responsible for their lifecycle. Temporary timed modifiers do not count when they are clearly short-lived and are not being used to evade the limit.
Prefer one staged national spirit with several lifecycle forms over several separate spirits covering closely related themes. Political institutions, military structures, economic systems, foreign dependence, legitimacy crises, and similar systems should usually evolve through replacement or modification chains.
Audits and completion reports must list the maximum number of simultaneously active focus-tree-created national spirits for every major route. A route exceeding three is incomplete until the spirits are consolidated.
Do not use national spirits as easy badges for completing shallow focus lines. A national spirit should represent an institution, doctrine, crisis condition, political identity, economic system, military structure, foreign relationship, or special mechanic that changes how the country plays.
A major national spirit should not be earned by one easy focus with no cost, risk, prerequisite, route commitment, decision follow-up, or mechanic interaction. If the spirit is powerful, it should usually require a real path commitment, a branch milestone, a mission success, a crisis choice, a reform chain, a formable step, or a meaningful sacrifice. If the spirit is easy to obtain, it should be modest, temporary, narrow, or part of a larger staged system.
A national spirit is unrewarding when it has only a flat modifier and no lifecycle. Before adding a new spirit, decide whether the existing idea can be upgraded, modified, replaced, worsened, temporarily strengthened, or tied to decisions. Prefer a smaller number of deep spirits over a long list of shallow spirits.
Important national spirits should usually have at least two of these:
Reject a tree if it has many easy-to-achieve national spirits that feel unrelated, passive, or unrewarding. Merge them into one staged institution, convert some into timed modifiers, move some effects into decisions or missions, or require a stronger route commitment before granting them.
Focus trees and decision systems must not feel separate.
Focuses should unlock, modify, improve, or restrict decisions and missions.
Examples:
A focus that unlocks a decision family should state:
A decision family unlocked by focuses should reference the relevant route in docs and localisation.
A focus tree should sometimes require the player to do something outside the focus interface before continuing. Good interaction checkpoints include:
The checkpoint must be thematic, visible, achievable, and connected to the reward. It should make the player adapt a plan. Passive waiting for a number the country already satisfies does not qualify. Nonstandard requirements need clear custom tooltips or scripted localisation.
Prefer making existing HOI4 systems matter before inventing a bespoke meter or button. A good focus can recontextualize laws, relations, trade, markets, stockpiles, ships, air wings, state control, compliance, or production through a clear reward and tradeoff. Use a custom mechanic when the route needs information or choices that existing systems cannot present cleanly.
A route that asks for an unusual condition must provide supporting tools. If a capstone requires compliance, the branch should unlock compliance, occupation, or integration actions. If it requires trucks, ships, or aircraft, earlier content should explain why and give the player enough time or production support to prepare.
Use interaction checkpoints at branch milestones, not on every node. Too many gates create chores. Too few can turn the tree into an automatic click conveyor where the player reads only the reward line.
A focus can also open an event choice with several valid results. The event should present real alternatives that fit the route, carry different costs or time horizons, and remain valid for AI.
A focus tree can prepare, reveal, enable, or stabilize a formable nation, but the final formation should usually be handled by a decision when state control matters. Use focuses to build the political claim. Use decisions to verify the map and perform the formation.
A formation route in a focus tree should define:
Do not make a formable route a linear claim ladder by default. The best formation routes usually combine legitimacy, state control, diplomatic recognition, military readiness, local integration, and a visible identity change.
When mapping a focus tree that can form countries, include a formation lane or route overlay in the architecture map.
Useful formation lane structure:
The tree should state whether the formable is:
For shared feature-created trees, formables must use origin and package checks so unrelated countries do not receive the wrong route.
Focus rewards can:
Focus rewards should not:
Focus trees should consider animated portraits or animated route emblems for major political transformations. Use them for route payoffs such as a supernatural leader reveal, a restored dynasty, a revolutionary cult, a final formable proclamation, or an extreme route state identity.
Animated portraits need static fallbacks. They should be assigned through the same leader, character, or cosmetic identity logic as the route itself. Real historical portraits require sourced material and careful treatment. Fictional or symbolic leaders can use generated animated portrait packages through the asset skill.
Do not make every leader animated. Animation should signal a special route, an extreme route identity, sourced quote, remark, or audio research-level transformation, or a rare hidden outcome.
Use mutual exclusions when the country's identity changes.
Good mutual exclusions include:
Do not use mutual exclusions for branches that should logically coexist, such as army and industry.
When a route becomes impossible, use bypasses or availability logic cleanly.
A route that depends on another country, war, faction, event, leader, or historical sequence must define four things:
Prefer role-based conditions when the identity of the counterpart is not essential. A route can target the regional hegemon, colonial holder, faction leader, sponsor, border enemy, or controller of named states instead of one hardcoded tag. Use a specific tag when the relationship with that exact country is the point of the route.
Do not leave a substantial branch permanently locked because an external country chose an alternate-history path, disappeared, changed faction, lost the relevant states, or never fired one event. Historical routes may depend on historical sequences in historical mode, but alternate-history and multiplayer campaigns need coherent route validity.
A bypass should preserve pacing and prevent dead content. It must not grant incompatible rewards for free or let the player collect both the original and replacement branches.
Do not use the generic civil-war pattern as the default way to make politics dramatic. Random or opaque division and territory splits can remove player agency, destroy carefully built forces, and make the route feel punitive instead of strategic.
Prefer alternatives when they fit the conflict:
When a true civil war is central to the route, define the split clearly. The player should understand the threatened states, likely units, stockpile treatment, leaders, preparation choices, and victory consequences before commitment. Earlier focuses and decisions should let the player influence loyalty, territory, equipment, or timing. The aftermath must restore or integrate surviving institutions and prevent repeated reward collection across both sides.
The tree must be readable in game.
Use the MCP focus tools to find layout deformities before rewriting. hoi4.focus_inspect and hoi4.focus_render report overlapping focus boxes, excessive gaps, cramped spacing, connector crossings, path lines that run through focuses or stretch too far, dangling connectors, bad prerequisite presentation, unbalanced branches, off-center layouts, and related diagnostics. Review the artifacts, then call hoi4.focus_rewrite with layoutMode: "compact" for cleanup or a complete route plan for creation. Review the rewritten artifacts and source diff. MCP supplies shared parsing, layout, rendering, and writes, while this skill owns design, prerequisites, localisation, AI, icons, balance, and completion.
Required layout checks:
If an available = { has_completed_focus = ... } condition gates a focus, decide whether it should also be a visible prerequisite. Do not add a visible prerequisite if it creates crossing lines. Move the branch or redesign the gate.
When an event creates or releases a country, set a flag showing that the event created that country.
Only load or replace a runtime focus tree if the event actually created the country.
Existing countries with their own meaningful tree should usually receive additive crisis branches, decisions, ideas, or events, not a blind tree replacement.
For every feature-created country, verify:
Every major route needs AI behavior.
AI should consider:
Avoid flat AI weights when campaign state matters.
When focus selection probabilities, route dominance, or starvation matter, use hoi4.probability_inspect to identify the candidate pool and required scenario inputs. Evaluate named campaign states with hoi4.probability_evaluate, sweep thresholds and rank reversals with hoi4.probability_sweep, compare a proposed change with hoi4.probability_compare, and use hoi4.probability_simulate only for explicitly declared uncertain inputs. Use hoi4.probability_render when a ranking, matrix, sensitivity, comparison, or unresolved view is clearer than a compact trace. The focus adapter models the verified independent score race, not weight divided by the sum of weights. Supply the complete available-focus pool and declare prerequisite, bypass, strategy, and external factors; keep anything the analyzer cannot resolve visible as uncertainty. Use the result as balance evidence while this skill retains ownership of route design and tuning decisions.
AI should not accidentally choose suicidal or nonsensical routes just because they are visible.
Focus-tree assets must not reuse one uniform colour palette across the whole tree. Political routes, military routes, industry routes, diplomacy routes, expansion routes, crisis routes, and hidden or extreme paths should use visibly distinct palette families where their identities differ. Separate branches should not look like recoloured copies of the same icon set.
Do not solve asset variety by taking the same composition and changing only its hue. Vary subject matter, framing, lighting, contrast, symbols, materials, and background treatment while keeping the tree visually coherent and readable in the HOI4 interface.
Every focus needs:
Every political route needs localisation that makes the route identity clear.
Leader changes require leader portraits. Real leaders use sourced portraits. Fictional leaders and symbolic councils can use generated portraits through the asset skill.
Flag or cosmetic-name changes require flag and localisation coverage.
When an improvement addendum deepens a focus tree, preserve the route idea before adding nodes. The goal is not a longer tree. The goal is a sharper country identity, stronger branch interaction, clearer route locks, better rewards, stronger AI, and more visible consequences.
Formation routes should usually combine focus preparation with a decision that verifies state control. Focuses can discover old claims, call a congress, unlock a seal, prepare integration, recruit elites, expose a hidden identity, or open the formation decision. The decision then checks the map and performs the formation.
Hidden formables can be routed through secret focuses, events, leader changes, campaign-state tiers, ancient artifacts, internal factions, or custom GUI investigation. Hidden content should still have a full implementation handoff. It needs reveal logic, visibility rules, localisation, assets, AI handling, post-formation gameplay, and disqualifiers.
Animated leader portraits and animated route emblems should be reserved for major transformations. Use them when the route payoff changes the country's identity, reveals an extreme route leader, forms a new state, or completes a dramatic ideological break. Keep a static fallback and ensure the animation has a clear trigger and cleanup state.
Focus tree subagents are active small-patch agents by default inside the current task scope. They can patch prerequisite fixes, mutual exclusion fixes, bypasses, route locks, AI weights, icon references, focus filters, localisation keys, small reward variety, existing decision hooks, and existing formable unlock hooks without waiting for a separate permission prompt.
They should not redesign a whole tree, add a full route family, create a new formable chain, or change the country identity. When the tree needs broader depth, 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 focus ids, route behavior before and after, meaningful validation, skipped task-specific validation, and remaining route risks.
For large focus-tree work, update documentation.
Include:
Before completion, audit:
A focus tree task is complete only when:
+2%, +3%, +7%, 12, or 18 are absent unless their exact use is documented and justifiedIf a tree uses a fallback tree where the spec requires a bespoke tree, report it as a simplification.
If no simplifications were made, say so and provide evidence.