문서 추가: 레거시 엔진 아키텍처에 대한 상세 설명 및 관련 정보 추가

2025-12-26 19:51:17 +00:00
parent a0fd36765f
commit 21e7c8ddff
13 changed files with 661 additions and 0 deletions
@@ -0,0 +1,88 @@
+# Legacy Economy and Monthly Updates
+
+This document summarizes the legacy economic pipeline: monthly income,
+maintenance, population growth, city supply recalculation, and nation level
+updates. References include `legacy/hwe/func_time_event.php`,
+`legacy/hwe/sammo/Event/Action/*`, and `legacy/hwe/sammo/TurnExecutionHelper.php`.
+
+## Entry Points
+
+- `TurnExecutionHelper::executeAllCommand()`
+  - Calls `runEventHandler(PRE_MONTH)` → `preUpdateMonthly()` → `turnDate()` →
+    `runEventHandler(MONTH)` → `postUpdateMonthly()`.
+- Event actions under `legacy/hwe/sammo/Event/Action/` execute concrete
+  economic updates.
+
+## Monthly Income (ProcessIncome)
+
+`Event/Action/ProcessIncome` distributes **gold** and **rice** on schedule:
+
+- Collects all nations and cities, groups generals per nation.
+- Computes income using:
+  - `getGoldIncome()` / `getRiceIncome()` from `func_time_event.php`.
+  - `getWallIncome()` for rice from walls (same file).
+- Applies nation tax rate (`rate_tmp`) and salary ratio (`bill`).
+- Pays generals by `dedication` via `getBill()`.
+- Updates `nation_env.prev_income_{gold|rice}` and logs to history.
+
+Key dependencies:
+- `GameConst::$basegold`, `GameConst::$baserice` for minimum reserves.
+- `GameConst::$resourceActionAmountGuide` for action amounts.
+- `iAction::onCalcNationalIncome()` for nation-type modifiers.
+
+## Semiannual Maintenance (ProcessSemiAnnual)
+
+`Event/Action/ProcessSemiAnnual` applies upkeep and growth:
+
+- City stats decay by 1% (agri/comm/secu/def/wall).
+- Population growth via `popIncrease()`:
+  - Uses tax rate (`rate_tmp`) and security.
+  - Nation type can adjust via `onCalcNationalIncome('pop', ...)`.
+- General and nation resources decay (1–5% bands based on thresholds).
+
+## War Income and Casualties (ProcessWarIncome)
+
+`Event/Action/ProcessWarIncome`:
+
+- Converts `city.dead` into national gold income (supply-based war income).
+- Returns 20% of `dead` to population (`pop += dead * 0.2`), then clears `dead`.
+
+## City Supply and Isolation (UpdateCitySupply)
+
+`Event/Action/UpdateCitySupply`:
+
+- BFS from each nation capital through `CityConst` paths to mark `supply = 1`.
+- Unsupplied cities (`supply = 0`) receive 10% stat/pop loss monthly.
+- Generals in unsupplied cities lose 5% crew/train/atmos.
+- Cities with `trust < 30` become neutral (nation = 0), and officers are reset.
+
+## Nation Level Updates (UpdateNationLevel)
+
+`Event/Action/UpdateNationLevel`:
+
+- Nation level increases based on number of level≥4 cities.
+- On level-up:
+  - Grants gold/rice bonus.
+  - Logs global and national history.
+  - Initializes `nation_turn` rows for new chief levels.
+  - Runs a unique-item lottery (deterministic RNG tagged `nationLevelUp`).
+
+## City Trade Rates (RandomizeCityTradeRate)
+
+- Once per month, adjusts `city.trade` with deterministic RNG:
+  - Probability depends on city level.
+  - Trade rate ranges 95–105 when triggered.
+
+## RNG Notes
+
+Economic events using RNG seed with `UniqueConst::$hiddenSeed` and a
+feature-specific tag:
+
+- `RandomizeCityTradeRate`: `hiddenSeed + 'randomizeCityTradeRate' + year + month`
+- `UpdateNationLevel`: `hiddenSeed + 'nationLevelUp' + year + month + nationID`
+
+## Open Questions / Follow-ups
+
+- `preUpdateMonthly()`, `postUpdateMonthly()`, and `turnDate()` live in
+  `legacy/hwe/func_time_event.php` and `legacy/hwe/func.php`; their full
+  side effects should be expanded alongside this document.