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

Legacy Battle and War Resolution

This document summarizes the legacy battle pipeline centered on legacy/hwe/process_war.php, legacy/hwe/sammo/WarUnit.php, legacy/hwe/sammo/WarUnitGeneral.php, and legacy/hwe/sammo/WarUnitCity.php.

Entry Point: processWar

Inputs:

• warSeed (string): battle RNG seed
• attackerGeneral: General
• rawAttackerNation: nation row (snapshot)
• rawDefenderCity: city row (snapshot)

Setup steps:

1. Initialize RNG with warSeed (LiteHashDRBG).
2. Load defender nation row (or default neutral nation if nation = 0).
3. Build WarUnitGeneral (attacker) and WarUnitCity (defender city).
4. Collect defender generals in the city, filter with extractBattleOrder().
5. Optionally append city as defender if city order > 0.
6. Sort defenders by battle order, iterate via getNextDefender().
7. Run processWar_NG(); update DB and nation/city stats.

Battle Order (extractBattleOrder)

For defender generals:

• Must have crew > 0
• Must have rice > crew/100
• train and atmos must meet defence_train
• Battle order uses:
  • totalStat = (realStat + fullStat) / 2
  • totalCrew = crew / 1_000_000 * (train * atmos) ^ 1.5
  • totalStat + totalCrew / 100

For cities:

• Uses attacker onCalcOpposeStat('cityBattleOrder', -1).

Battle Loop (processWar_NG)

1. Log start, include seed in battle logs.
2. If no defenders remain, set defender = city and switch to siege.
3. Initial engagement
   • setOppose() for attacker/defender
   • addTrain(1) for both
   • Fire battle-init triggers
4. Per phase
   • beginPhase() computes war power
   • Fire battle-phase triggers
   • calcDamage() on both sides
   • Clamp damage if it exceeds HP ratios
   • Apply damage, increase killed/dead counters
   • Log phase results
5. Continuation checks
   • continueWar() fails on no rice or HP <= 0
   • On retreat/defeat: log, apply win/lose, try wound
   • If defender removed, move to next defender (or city siege)
6. Finish
   • logBattleResult() for last phase if needed
   • finishBattle() for attacker/defender
   • City conflict tracking and history logs

Post-Battle Updates (processWar)

After processWar_NG():

• Apply attacker DB updates
• Update nation rice (supply and siege rules)
• Distribute city dead counts (40% attacker city, 60% defender city)
• Increase nation tech based on killed/dead and nation size adjustments
• Update diplomacy.dead for both sides
• If city conquered: call ConquerCity()

Conflict Tracking (city.conflict)

City conflict tracks which nations contributed to siege damage, used to resolve post-war ownership when multiple attackers participate.

Source: WarUnitCity::addConflict() in legacy/hwe/sammo/WarUnitCity.php.

• city.conflict is a JSON map { nationID: deadContribution }.
• Contribution amount is based on city dead (minimum 1).
• First/last hit bonus: if no conflict exists yet or city HP is 0, dead is multiplied by 1.05 ("선타, 막타 보너스").
• Contributions are sorted descending via arsort() after updates.
• addConflict() returns true when a new nation enters the conflict, which triggers the global "분쟁" log in processWar().
• getConquerNation() returns the first key of the sorted map to select the final owner.
• DeleteConflict($nation) removes a nation from all city conflicts, used on nation deletion and on the che_방랑 flow.

City Conquest Resolution (ConquerCity)

ConquerCity() finalizes city ownership, handles nation collapse, and applies post-siege side effects. It is deterministic with the conquest RNG seed noted below.

Common Flow

• Logs conquest to attacker (general/nation/global) and defender nation history.
• Runs EventTarget::OCCUPY_CITY handlers via TurnExecutionHelper::runEventHandler().
• Calls onArbitraryAction(..., 'ConquerCity') for each defender general in the city, then persists them.

Nation Collapse Path

Triggered when the defender nation owns exactly one city (the captured city):

• Calls deleteNation() using the defender lord (officer level 12).
• All defender generals lose 20–50% of gold and rice, -10% experience, and -50% dedication, with action logs. Loss amounts are aggregated.
• Optionally issues scout messages to fleeing generals (when join_mode allows).
• NPC defenders (NPC type 2–8 except 5) can auto-queue che_임관 to the attacker nation with a random delay (0–12 turns), gated by GameConst::$joinRuinedNPCProp.
• Attacker reward:
  • Half of defender nation gold/rice above base (GameConst::$basegold, GameConst::$baserice) plus half of the aggregated general losses.
  • Credited to attacker nation and logged to all chiefs (officer level >= 5).
• Runs EventTarget::DESTROY_NATION handlers.

Nation Survives Path

If the defender nation still has other cities:

• Demotes city officers (태수/군사/종사) to general:
  • officer_level = 1, officer_city = 0.
• If the city was the capital:
  • Picks a new capital via findNextCapital() (closest distance, highest pop).
  • Logs an emergency relocation message to global and all nation generals.
  • Sets nation.capital to new city and halves nation gold/rice.
  • Marks new capital as supply city; moves chiefs to it.
  • Applies 20% morale loss to all generals (atmos *= 0.8).
  • Refreshes cached nation static info.

Final Ownership + City Reset

getConquerNation() inspects city.conflict to decide final owner. If the attacker loses arbitration, the city is transferred to the conflict winner and logs are emitted for both nations.

City stats are reset after ownership is settled:

• supply = 1, term = 0, conflict = {}, nation = conquerNation, officer_set = 0.
• agri/comm/secu multiplied by 0.7.
• def/wall reset:
  • If level > 3: both set to GameConst::$defaultCityWall.
  • Else: set to def_max/2, wall_max/2.
• Frontline status recalculated for all nearby nations (SetNationFront()).

Deterministic RNG

Conquest RNG seed: hiddenSeed + 'ConquerCity' + year + month + attackerNationID + attackerID + cityID.

Used for:

• Defender general loss ratios (20–50%).
• Scout message chance and NPC auto-join chance.
• Randomized join turn delay (0–12).

WarUnitGeneral Highlights

• Train/atmos bonuses depend on city level and attacker/defender role.
• War power:
  • Base attack/defence from crew type + tech
  • Adjusted by train/atmos, dex (getDex()), crew type coefficients
  • Experience level scales war power and counter-scales opponent
  • General::getWarPowerMultiplier() applies special multipliers
• Rice consumption on kills: proportional to damage, tech cost, unit rice
• Wound chance: 5% unless 부상무효 / 퇴각부상무효 triggered
• finishBattle() updates rank stats, rounds values, and checks stat changes

WarUnitCity Highlights

• Uses DummyGeneral with CREWTYPE_CASTLE
• HP = def * 10
• Computed attack/defence = (def + wall * 9) / 500 + 200
• City train/atmos scales with elapsed years since startYear
• Siege state:
  • Non-siege battle ends after one exchange
  • Siege continues until HP <= 0
• heavyDecreaseWealth() halves agri/comm/secu on supply-based rout
• addConflict() records contribution in city.conflict JSON

Deterministic RNG

• Main battle uses warSeed directly.
• City conquest uses hiddenSeed + 'ConquerCity' + year + month + nationID + generalID + cityID.

Open Questions / Follow-ups

• No automatic decay for city.conflict is visible; confirm if any scheduled cleanup exists outside explicit reset paths.