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

2025-12-26 19:51:17 +00:00
parent a0fd36765f
commit 21e7c8ddff
13 changed files with 661 additions and 0 deletions
@@ -0,0 +1,86 @@
+# Legacy Event System
+
+This document summarizes how the legacy event system executes scenario- and
+turn-based events, and how static event hooks are wired into commands. Primary
+references include `legacy/hwe/sammo/TurnExecutionHelper.php`,
+`legacy/hwe/sammo/Event/*`, and `legacy/hwe/sammo/StaticEventHandler.php`.
+
+## Entry Points
+
+- `TurnExecutionHelper::runEventHandler(EventTarget $eventTarget)`
+  - Loads `event` table rows by target and priority, evaluates conditions, and
+    runs actions.
+- `StaticEventHandler::handleEvent(...)`
+  - Invoked by many commands and API handlers to run per-action static hooks.
+
+## Event Table Dispatch
+
+`runEventHandler()` drives the dynamic event pipeline:
+
+1. Query `event` rows with `target = {PRE_MONTH|MONTH|OCCUPY_CITY|DESTROY_NATION|UNITED}`
+   (ordered by `priority DESC, id ASC`).
+2. Decode `condition` and `action` JSON.
+3. Build a `Event\EventHandler` with condition + action lists.
+4. Execute `tryRunEvent($env)` where `$env` is `game_env` KV storage plus
+   `currentEventID`.
+
+Events are used inside the monthly pipeline and in special moments like
+city occupation (`EventTarget::OCCUPY_CITY`, called by some commands).
+
+## Condition and Action DSL
+
+`Event\Condition::build()` and `Event\Action::build()` decode JSON arrays into
+class instances:
+
+- **Condition**
+  - Supports logic combinators (`and`, `or`, `xor`, `not`) via
+    `Event\Condition\Logic`.
+  - Built-in condition types include:
+    - `Date`, `DateRelative`, `Interval`
+    - `RemainNation`
+    - `ConstBool`
+  - Conditions return `{ value, chain }` for tracing.
+
+- **Action**
+  - Actions are classes under `Event/Action/` with `run(array $env)`.
+  - The dispatcher instantiates them from `action` arrays like
+    `['ProcessIncome', 'gold']`.
+
+## Common Event Actions (Examples)
+
+These are the action modules observed in the legacy tree:
+
+- **Economy & upkeep**: `ProcessIncome`, `ProcessSemiAnnual`, `ProcessWarIncome`
+- **World state**: `UpdateCitySupply`, `UpdateNationLevel`, `RandomizeCityTradeRate`
+- **NPC/Invader flow**: `RaiseInvader`, `RaiseNPCNation`, `ProvideNPCTroopLeader`
+- **Betting & unique items**: `OpenNationBetting`, `FinishNationBetting`,
+  `LostUniqueItem`, `MergeInheritPointRank`
+- **Event lifecycle**: `DeleteEvent`, `NoticeToHistoryLog`
+
+All action execution uses the event environment (`year`, `month`, `startyear`,
+`turnterm`, etc.) coming from `game_env`.
+
+## Static Events (Command Hooks)
+
+Static events are hooks triggered directly by commands/APIs:
+
+- `StaticEventHandler::handleEvent()` looks up handler names from
+  `GameConst::$staticEventHandlers[$eventType]`.
+- Handlers live under `legacy/hwe/sammo/StaticEvent/` and implement
+  `BaseStaticEvent::run()`.
+- These hooks are used to extend command behavior without modifying the
+  command code itself (e.g., troop join/exit side effects).
+
+## RNG Notes
+
+Dynamic event actions can use deterministic RNG by constructing
+`LiteHashDRBG` with `UniqueConst::$hiddenSeed` and an event-specific tag.
+Examples include `RandomizeCityTradeRate` and `UpdateNationLevel`.
+
+## Open Questions / Follow-ups
+
+- `Event\Engine` is a stub with a TODO; it is not currently used in the main
+  turn pipeline.
+- The full mapping of `GameConst::$staticEventHandlers` to events should be
+  extracted from scenario configs and command usage when documenting specific
+  rule packs.