문서 업데이트: 레거시 엔진 아키텍처 및 명령 카탈로그 추가

2025-12-26 19:06:33 +00:00
parent 475772240c
commit f41c50b9c1
7 changed files with 580 additions and 0 deletions
@@ -0,0 +1,91 @@
+# Legacy General Model and Action Stack
+
+This document captures how `General` aggregates modifiers, computes stats, and
+exposes trigger hooks. The main reference is `legacy/hwe/sammo/General.php`.
+
+## Construction and Core State
+
+- `General` builds from raw DB rows (general, city, nation, rank, access log).
+- `last_turn` is parsed into `LastTurn`, and a separate `resultTurn` is
+  maintained for updates.
+- `penalty` JSON is decoded into `PenaltyKey -> value` map.
+- Rank data is tracked with:
+  - `rankVarRead` (current read view)
+  - `rankVarIncrease` (increment queue)
+  - `rankVarSet` (explicit set queue)
+
+## Action Objects (`iAction`)
+
+`General` composes action sources into a single list:
+
+1. Nation type (`buildNationTypeClass`)
+2. Officer level (`TriggerOfficerLevel`)
+3. Domestic special (`buildGeneralSpecialDomesticClass`)
+4. War special (`buildGeneralSpecialWarClass`)
+5. Personality (`buildPersonalityClass`)
+6. Crew type (`GameUnitConst::byID`)
+7. Inheritance buff (`TriggerInheritBuff`)
+8. Scenario effect (`buildScenarioEffectClass`)
+9. Items: horse / weapon / book / item (`buildItemClass`)
+
+`getActionList()` returns this merged list and is the core entry point for
+modifiers and triggers.
+
+## Stat Computation
+
+`getStatValue()` applies layered modifiers:
+
+- Base stat from raw value
+- Injury multiplier
+- Cross-stat adjust (strength/intel + 1/4 of the other stat)
+- Clamp to `GameConst::$maxLevel`
+- `onCalcStat()` from every action object
+- Cached by `(statName, injury, action, adjust)` tuple
+
+Convenience wrappers:
+- `getLeadership()`, `getStrength()`, `getIntel()`
+
+## Turn Reservation and LastTurn
+
+- `getReservedTurn(turnIdx)` reads from `general_turn`.
+- When no entry exists, `buildGeneralCommandClass(null)` creates `휴식`.
+- `LastTurn` holds `{ command, arg, term, seq }` and is used by
+  `BaseCommand::addTermStack()` to advance multi-turn commands.
+- `applyDB()` persists updated fields and writes `last_turn` if it changed.
+
+## Trigger and Modifier Hooks
+
+`General` delegates calculations and trigger lists through action objects:
+
+- Economy/strategy: `onCalcDomestic`, `onCalcStrategic`,
+  `onCalcNationalIncome`
+- Combat modifiers: `onCalcStat`, `onCalcOpposeStat`, `getWarPowerMultiplier`
+- Arbitrary actions: `onArbitraryAction` (used in city conquest)
+
+Turn-prep triggers:
+
+- `getPreTurnExecuteTriggerList()` merges trigger lists from every action
+  object. `TurnExecutionHelper::preprocessCommand()` adds
+  `che_부상경감` + `che_병력군량소모` on top.
+
+Battle triggers:
+
+- `getBattleInitSkillTriggerList()` merges per-action battle-init triggers.
+- `getBattlePhaseSkillTriggerList()` includes base phase triggers:
+  - `che_필살시도`, `che_필살발동`
+  - `che_회피시도`, `che_회피발동`
+  - `che_계략시도`, `che_계략발동`, `che_계략실패`
+  - plus any action-specific additions.
+
+## Rank and Access Log Updates
+
+- `increaseRankVar()` / `setRankVar()` queue updates until `applyDB()`.
+- `applyDB()` updates `general` and `rank_data`, then flushes logs.
+- `checkStatChange()` uses `*_exp` thresholds to increase/decrease stats and
+  logs level changes.
+
+## Open Questions / Follow-ups
+
+- `PenaltyKey` effects and how penalties are applied are outside this file.
+- `GeneralBase` and `LazyVarAndAuxUpdater` may contain additional state
+  conventions for new code to mirror.