Bellum Ingenium Game Design (To be Updated)

gistfile1.txt

# Grand Strategy AI Game — Complete Design Document

---

## Vision Statement

A grand strategy simulation where the economy is the engine of all military power. Every base on the map is a financial commitment. Every month of deficit is a countdown to visible military decay. Every conquest creates new obligations that must be paid for. The player's core challenge is not winning wars — it is staying solvent long enough to win them.

The AI acts as a world referee, not a guide. Other nations run identical economic logic and react to your weakness or strength in ways that feel historically plausible. The game tells emergent stories through numbers becoming consequences on a map.

---

## Setting & Presets

The game launches with alt-history presets that give immediate context. The flagship preset is **USSR Never Collapsed — 1995**, which places the player in charge of a superpower with massive military overhead, industrial decay, and urgent economic decisions to make before the deficit spiral begins. Other presets include Cold War NATO, Post-WW2 Europe, and Modern Multipolar World.

Each preset configures starting values for all economy variables, places bases on the map, and sets AI nation behavioral archetypes. The USSR 1995 preset always opens with the industrial revival action as the first AI suggestion, which is historically flavored and mechanically appropriate.

---

## Core Design Philosophy: Pressure Management

The game is not about conquest or diplomacy in isolation. It is about managing compounding pressures across time. Every decision either buys breathing room or creates a new obligation. Conquest gives immediate income but adds base costs. Trade deals boost income but temporarily destabilize domestic politics. Industrial investment boosts production but reduces exports. The player is always juggling, never optimizing a clean solution.

**The Core Rule:** Net Monthly Balance is the heartbeat of the country. Positive means breathing room and growth. Negative means slow, visible military decay that eventually invites invasion.

---

## Economy System

### Core Variables (per country)

Every nation, player and AI alike, tracks these values in real time:

**Treasury** is the current cash reserve. It absorbs monthly surplus or deficit and acts as a buffer. Running it to zero accelerates consequences.

**Tax Base** is income from population and owned provinces. It is stable and reliable but multiplied by Stability, meaning political decay directly reduces it.

**Industrial Capacity** is the production engine. It can be modernized through player actions or slowly damaged by neglect and deficit. It represents the long-term health of the economy.

**Trade Balance** is volatile external income with the highest upside and easiest to lose. Trade deals boost it temporarily. Political isolation or war collapses it.

**Stability** is a 0.0–1.0 multiplier applied to Tax. It falls during deficit months and rises slowly during sustained surplus. A destabilized nation pays less tax from the same provinces.

**Economic Base** is a slow-moving indicator of long-term structural health. It rises with sustained surplus and decays if ignored for many months. It acts as a floor under Industrial Capacity.

**Base Upkeep** is the sum of all active placed bases on the map. Every base type has a fixed monthly cost. Garrison bases are cheap. Artillery and land bases are medium. Airbases and naval bases are expensive.

**Army Upkeep** scales with unit count, technology level, and mobilization status. A fully mobilized large army costs significantly more than a peacetime garrison.

**Net Monthly** is the single most important number in the game. It equals (Tax × Stability + Production + Trade) minus (Base Upkeep + Army Upkeep + Debt Service). This number determines every downstream consequence.

**Prestige / Global Influence** is a 0–100 modifier representing diplomatic reputation. It gives small trade bonuses at high values and lowers the threshold for AI aggression at low values.

---

### Monthly Simulation Cycle

Every game tick after the player presses Play, the following sequence runs for every nation:

First, income is calculated as Tax multiplied by Stability, plus Production after active modifiers, plus Trade after active modifiers. Second, all active modifier timers are decremented and expired modifiers are removed. Third, costs are subtracted to produce Net Monthly. Fourth, Net Monthly is added or subtracted from Treasury. Fifth, surplus or deficit consequences are applied based on the running deficit month counter. Sixth, geographic exposure penalties are recalculated based on current active base positions. Seventh, Prestige is adjusted by +1 for healthy surplus months or -2 for deficit months.

---

### The Three Income Pillars and Their Friction

The three pillars are visible in the Economy panel but they are not independent. They pull against each other in ways that force the player to choose priorities.

When a player action boosts Production, a -10% Trade modifier applies for 3 months. Factories consume domestic resources and reduce export capacity. When a player action boosts Trade through a new agreement, a -5% Stability modifier applies for 2 months because political capital is spent externally rather than on domestic governance. When Army Upkeep exceeds 40% of total income, a -10% Production modifier applies dynamically because labor and resources are being diverted to military logistics.

These modifiers are tracked as an array of ActiveModifier objects with a target pillar, an amount, and a monthsRemaining counter. The Economy panel displays them as inline tags next to each pillar, for example: "Trade: 37,125 ▼ -10% (2mo)". The player always sees what is affecting their income and for how long.

---

### Surplus and Deficit Consequences

**In Surplus** the economy breathes. Economic Base slowly rises by a small amount each month. Stability recovers toward 1.0. Industrial Capacity gets a passive growth tick. Prestige rises by 1 per month. If Net exceeds +20,000 for multiple months, small long-term infrastructure gains compound silently.

**In Deficit** the following strike track runs. The player can always see their current Deficit Month counter in the panel, displayed as "Deficit Month: 3 / 6," and it resets to zero the moment Net turns positive.

At months 1 through 2, Military Readiness begins decaying. Supply range shortens. Combat effectiveness drops. The numbers shown on aircraft and ship icons on the map visually decrease. This is the early warning stage.

At months 2 through 3, random bases begin flashing "underfunded" and their projection circles on the map fade to semi-transparent, showing reduced coverage before full shutdown. The player can see which regions are losing protection in real time.

At months 4 through 6, bases begin shutting down in predictable batches of 10. The Economy panel shows a countdown bar labeled "Next 10 bases lost in X months." Shutdown bases turn gray and inactive on the map rather than disappearing entirely. The player can recover them later once Net turns positive using the "Re-activate Bases" action. This makes recovery feel earned rather than administrative.

Beyond month 6, automatic unit disbandment begins. Stability continues falling, which shrinks Tax, which worsens the deficit further. This is the spiral that cannot be ignored. A nation that reaches zero active bases and critically low Stability becomes a valid military target for aggressive AI neighbors.

---

### Emergency Reserve System

Once per calendar year, the player can take an Emergency Stabilization Loan. The loan amount scales with country size and provides temporary positive Net for 3 to 6 months. However, it adds a Debt Service cost to every subsequent month until repaid. This prevents instant total collapse and gives the player one last chance to buy time for structural reforms without making the emergency exit costless.

---

### Geographic Exposure System

Every region on the map has a coverage status calculated from the projection circles of active bases. A covered region has at least one active base's projection range overlapping it and generates full Tax and Production income. An exposed region has no active base covering it and generates 20% less Tax and Production because investment naturally flows toward secure areas.

Exposed regions are marked on the map with a subtle red tint or dashed border so the player can immediately see where their military presence has gaps. When a player conquers a new region, it begins as exposed until a base is placed. This makes post-conquest base placement a genuine strategic decision. Rapid expansion across multiple regions without consolidating base coverage will create a spreading exposure penalty that can tip a healthy Net into deficit.

---

### Base Priority Flags

Players can flag individual bases as Priority using a button in the base detail panel. During deficit-driven batch shutdowns, priority bases are the last to go offline. This lets the player protect strategically critical bases covering key regions or borders while accepting that peripheral bases will be sacrificed first to manage costs.

---

## Action System

### The Actions Panel

The Actions panel allows the player to queue decisions that become modifiers applied to the monthly simulation. It is not a menu of correct answers. It is a space for the player to direct their nation's strategy, with the AI acting as a referee on plausibility and cost.

### AI-Suggested Actions

The "Help brainstorm actions" button reads the current economic state and generates four contextual suggestions ranked by urgency. When Net is negative, the top suggestions are always economic rescue options: industrial revival, trade agreement, austerity measures, emergency asset sales, raise taxes. When Net is healthy, military and diplomacy options rise to the top: increase military readiness, propose alliance, fund technology research, launch domestic reforms.

The USSR 1995 preset always surfaces "Launch 5-year industrial revival: subsidize heavy industry, modernize energy, expand state-backed credit to boost production" as the first suggestion in deficit mode. This is both historically flavored and mechanically correct, and it is the kind of moment that makes the game feel like it knows what it is about.

### Player-Typed Action Adjudication

The free-text input is where the player authors their own strategy. When a player types and submits a custom action, the AI evaluates it against the current economic state and returns a structured adjudication before the action is queued. The response appears as a confirmation card showing the action name, the primary effect (which pillar changes, by how much, for how many months), the secondary cost (which pillar is penalized and for how long), and a risk level of Low, Medium, or High.

An example card might read: "Nationalize steel industry: +15% Production for 6 months | -10% Trade for 4 months | Stability -0.05 | Risk: Medium — Confirm?" The player clicks Confirm or Cancel. This is the most important interaction in the game because the player feels like they invented the strategy rather than selected it. The AI is a referee, not a guide.

---

## AI Nations

### Shared Economic Logic

Every AI-controlled nation runs the identical monthly economy cycle with simplified decision-making. They accumulate surpluses, fall into deficits, lose bases, and react to the world around them exactly as the player does. This is what makes the world feel alive without requiring separate AI systems.

### Behavioral Archetypes

Each AI nation has a behavioral bias that governs how it prioritizes decisions within the shared logic.

**Consolidator** nations like Germany prefer to hold surplus above all else. They will subsidize an ally by transferring treasury funds before considering any expansion. They will never expand if their Net is below +10,000. They are stable, wealthy, and reliable partners or patient rivals.

**Industrial Backer** nations like Russia and the USSR always attempt industrial revival actions before considering austerity when in deficit. Production is their priority pillar. They will absorb short-term Trade penalties to protect long-term industrial capacity.

**Trade Seeker** nations like Ukraine aggressively queue trade agreement actions when in deficit. They prioritize Trade pillar recovery above other options and will accept Stability penalties to restore income.

**Capitulator** minor nations below a threshold of active bases and territory will seek a protectorate arrangement with the nearest stronger nation before disbanding their last bases. This triggers a diplomatic event that the player can respond to, either accepting the protectorate (gaining a dependent state that pays tribute without adding base upkeep) or ignoring it (allowing the minor nation to collapse and become available for conquest by others).

### War Declaration Events

When an AI nation declares war due to the player's military collapse, a visible narrative event appears on screen. It reads something like: "Russia notices your military collapse in Donetsk Oblast. With no active bases remaining in the region and prior hostile diplomacy, Russia moves to occupy." The player sees the calculation that led to the attack. This transforms a mechanical consequence into a readable story beat and reinforces that the world is reacting to their decisions, not generating random events.

---

## Conquest and Expansion

Capturing a province gives an immediate boost to Tax Base and Industrial Capacity from that region. However, it also adds new base costs if the player wants the region covered, and the region begins as exposed until a base is placed. Army Upkeep may increase depending on how the territory was taken and whether it requires ongoing garrisoning.

The fundamental dilemma is that rapid expansion across multiple regions simultaneously creates spreading exposure penalties and rising base costs before the new Tax and Production income has time to stabilize. The player who conquers faster than they can consolidate will find their Net deteriorating even as their territory grows.

The puppet state option allows the player to extract tribute from a conquered or capitulating nation without paying their base upkeep directly. This is the conservative expansion path, slower income but no added maintenance burden.

---

## Map Visualization

The map is the primary display of economic health. Every piece of economic information has a corresponding visual state on the map so the player can read the state of their nation at a glance without opening panels.

Active bases show their type icon, projection circle, and upkeep contribution in a tooltip. Inactive bases are gray with no projection circle. Underfunded bases have a semi-transparent fading projection circle during the warning phase before shutdown. Exposed regions have a subtle red tint or dashed border. Covered regions are clean.

Aircraft and ship icons on the map show reduced numbers during readiness decay, giving the player a visceral sense of their military fading before they check the numbers. The combination of all these visual states means a healthy empire looks vibrant and detailed, and a collapsing one looks visually sparse and pale. The map tells the story.

---

## Strategic Loop Summary

The player's experience in any given session moves through a recurring cycle. They begin by reading the economic state and identifying the primary pressure, whether that is a deficit they inherited from the preset, an aggressive neighbor, or a recently conquered region creating new costs. They then act, either selecting a suggested action or typing a custom strategy, and see the projected tradeoff before committing. They watch the consequences unfold on the map over the following months, managing the modifier timers and watching coverage circles expand or fade. They react to AI nations making their own decisions in response to both their own economic states and the player's visible strength or weakness. Eventually they reach a moment of stability or crisis that forces the next major decision.

This loop has no clean ending state. The goal is always to stay ahead of your own deficit spiral while reading the board well enough to expand when the moment is right and consolidate when it is not. It rewards players who think in monthly timescales and understand compounding effects. It punishes players who treat the economy as a secondary concern.

That is the game.