core2026/docs/architecture/legacy-engine-ai.md

Legacy General AI (GeneralAI)

This document summarizes how legacy/hwe/sammo/GeneralAI.php selects nation and general commands, which data fields it relies on, and how policies shape NPC behavior. It also outlines considerations for an in-memory rewrite of the AI loop.

Entry Points

• chooseNationTurn(NationCommand $reservedCommand)
• chooseInstantNationTurn(NationCommand $reservedCommand)
• chooseGeneralTurn(GeneralCommand $reservedCommand)

All three call updateInstance() first, which caches current state and derives key AI decisions (diplomacy state, general type, policy setup).

Deterministic RNG

GeneralAI uses LiteHashDRBG seeded with:

hiddenSeed + "GeneralAI" + year + month + generalID

This makes AI choices reproducible per turn. All random choices (choice, choiceUsingWeight, nextBool) flow through this RNG.

State Snapshot and Derived Fields

updateInstance() pulls and caches:

• game_env (via KVStorage): year, month, startyear, turnterm, develcost, init_year/init_month, killturn, global NPC policy defaults.
• city (current city row, from general -> city).
• nation (nation row, or fallback for neutral).
• nation_env (KVStorage): npc policy overrides, prev income, last attackable.
• nation['aux'] decoded JSON.
• general primary stats (leadership/strength/intel; both full and adjusted).
• baseDevelCost and maxResourceActionAmount.
• dipState, attackable, warTargetNation.
• genType (type flags derived from stats + policy thresholds).

Derived groupings are computed lazily:

• categorizeNationCities() => nationCities, frontCities, supplyCities, backupCities with per-city dev and important scores.
• categorizeNationGeneral() => user/NPC buckets, war/civil buckets, troop leaders, lost generals, chief list.

Diplomacy State (calcDiplomacyState)

Diplomacy state controls war/peace behavior:

• d평화: no war declarations, no active war.
• d선포: declaration in progress, no active war.
• d징병: pre-war recruitment window.
• d직전: immediate pre-war.
• d전쟁: active war, or recently lost a front (grace period).

Key inputs:

• diplomacy rows (state, term) for current nation.
• front cities with supply=1.
• year/month relative to startyear (early-game war lockout).

warTargetNation tracks eligible enemies:

• 2 = currently at war.
• 1 = declaration in progress / pre-war.
• 0 is used as "any neighbor" fallback when no active target exists.

General Type (calcGenType)

General type is a bitmask:

• t무장 (strength-leaning)
• t지장 (intelligence-leaning)
• t통솔장 (leadership threshold for war-capable NPCs)

Logic:

• Strength vs intel decides initial bias.
• If the weaker stat is within 80%, a probabilistic hybrid type can be added.
• t통솔장 is set when leadership >= nationPolicy->minNPCWarLeadership.

Policy Inputs (Autorun)

AutorunNationPolicy and AutorunGeneralPolicy are built from:

• per-user autorun options (env['autorun_user']['options'])
• nation_env overrides (npc_nation_policy, npc_general_policy)
• global defaults (env['npc_nation_policy'], env['npc_general_policy'])
• live nation + env snapshot

Policies provide:

• priority action lists
• can{Action} toggles
• thresholds (min crew, safe population ratio, resource floors, etc.)

Nation Turn Behavior (chooseNationTurn)

Nation-level choices run only for NPCs (npc >= 2) or for autorun users:

1. Apply quarterly promotions and tax/bill adjustments.
2. Honor reserved nation commands if valid.
3. Iterate policy priority, invoking matching do{Action}.
4. Fall back to neutral (empty) nation command if all fail.

Major Action Groups

• Troop movement
  • do부대전방발령, do부대후방발령, do부대구출발령
  • user/NPC versions to move generals between front/back/supply cities
  • checks frontCities, supplyCities, last발령, and war route.
• Resource distribution
  • do유저장포상, doNPC포상, doNPC몰수
  • uses resource floors (reqNation*, reqNPC*, reqHuman*)
  • sorts by each general's gold/rice, excludes inactive (killturn <= 5) targets, and preserves the legacy geometric-mean amounts and candidate weights.
• Diplomacy
  • do불가침제의: respond to assistance requests with NAP offer.
  • do선전포고: probabilistic declaration when strong enough.
• Capital relocation
  • do천도: moves capital based on population, dev, and connectivity.

General Turn Behavior (chooseGeneralTurn)

General-level decisions are layered:

1. NPC message broadcast if npcmsg and RNG triggers.
2. Reserved command is honored if valid (unless 휴식).
3. Immediate recovery if injury > cureThreshold.
4. Special cases:
   • A nationless NPC troop leader shortens killturn and keeps its reserved command; an affiliated type-5 leader refreshes killturn and uses 집합.
   • wandering lords decide on founding, one-edge movement toward a cached target, or disbanding.
5. Iterate policy priority, invoking do{Action}.
6. Fallback to do중립.

Major Action Groups

• Domestic development
  • do일반내정, do전쟁내정, do긴급내정
  • weighted by city dev rates and general type flags.
• War preparation
  • do징병, do전투준비, do출병
  • strict checks on crew, train, atmos, population and diplomacy state.
• Mobility
  • do전방워프, do후방워프, do내정워프, do귀환
  • uses front/supply/backup cities and population thresholds.
• Resource handling
  • do금쌀구매 (trade), doNPC헌납 (donation).
• Neutral behavior
  • do중립 selects between 물자조달, 인재탐색, 견문.

Data Fields Accessed (Representative)

GeneralAI reads or writes:

• Nation: nation, capital, gold, rice, tech, level, type, chief_set, rate, bill, aux.
• City: city, nation, supply, front, pop, pop_max, trust, agri/comm/secu/def/wall and *_max, trade, level, region.
• General: npc, officer_level, officer_city, killturn, injury, troop, crew, train, atmos, defence_train, gold, rice, belong, permission, npcmsg, dex1..dex5, armType, affinity, makelimit.
• KVStorage: npc_*_policy, prev_income_*, last_attackable, last천도Trial, resp_assist*.

In-Memory Rewrite Considerations

To port the AI to an in-memory state model without behavior drift:

• Snapshot-first
  • Build a per-turn GameSnapshot containing env, nation, cities, generals, diplomacy, and nation_env. GeneralAI should read only from this snapshot.
• Derived caches
  • Cache DiplomacyState, CityBuckets, GeneralBuckets, and WarRoute.
  • Use lazy recalculation and invalidate only the affected region/city/general after a command is applied.
• Deterministic ordering
  • For candidate lists, sort by ID before weighted RNG to preserve parity.
  • RNG seeding should keep the exact per-turn seed scheme to ensure replay.
• Command evaluation
  • Keep hasFullConditionMet() semantics intact by providing the same generalized context (general, city, nation, dest*).
• Policy snapshots
  • Cache policy values per turn and avoid reading KVStorage per action.
  • When policies change, treat it as an explicit state transition.

These guidelines mirror the current "derive once, then select via priority" pattern and minimize resimulation deltas in the rewrite.

Migrated decision-parity regression

app/game-engine/test/generalAiLegacyDecisionParity.test.ts records focused final-command expectations extracted from ref/sam ng_compare@fe9ae978. Its matrix varies diplomacy/war state, city development and population, technology/year ceilings, general gold/rice and casualty ranks, stats and affinity, reserved/special NPC state, nation treasury reserves, and command availability. It also asserts RNG-sensitive candidate weights where consuming the same random branch is part of the final decision.

This is compatibility evidence for the represented decision branches. The long-running NPC scenario suites remain smoke tests and are not a substitute for this branch-level matrix.