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

2025-12-26 19:51:17 +00:00
parent a0fd36765f
commit 21e7c8ddff
13 changed files with 661 additions and 0 deletions
@@ -0,0 +1,78 @@
+# Legacy Items, Traits, and Action Modules
+
+This document summarizes the legacy action modules that supply modifiers and
+triggers: items, specials, personalities, nation types, crew types, and
+scenario effects. Primary references include `legacy/hwe/sammo/iAction.php`,
+`legacy/hwe/sammo/BaseItem.php`, `legacy/hwe/sammo/BaseSpecial.php`,
+and `legacy/hwe/sammo/Action*/` directories.
+
+## Core Concept: `iAction`
+
+All traits/items/effects implement `iAction` and are merged by
+`General::getActionList()` (see `docs/architecture/legacy-engine-general.md`).
+They can:
+
+- Modify stats and command calculations (`onCalcStat`, `onCalcDomestic`, etc.).
+- Provide triggers (`getPreTurnExecuteTriggerList`, battle init/phase triggers).
+- Apply ad-hoc effects (`onArbitraryAction`).
+
+`DefaultAction` provides no-op implementations for all hooks.
+
+## Item System
+
+- Base class: `BaseItem` implements `iAction` and exposes:
+  - `getCost()`, `isConsumable()`, `isBuyable()`, `getReqSecu()`.
+- Stat items inherit `BaseStatItem` and apply a fixed stat bonus in
+  `onCalcStat()` based on class name tokens.
+- Item instances live on the general (`General::getItem()`); items can also
+  insert battle triggers (see `ActionItem/`).
+
+Items are configured via `GameConst::$allItems` and scenario overrides.
+
+## Specials (Domestic / War)
+
+- Base class: `BaseSpecial` (implements `iAction`).
+- `ActionSpecialDomestic/*` modifies domestic outcomes
+  (`onCalcDomestic`), e.g., cost/success/score adjustments.
+- `ActionSpecialWar/*` injects battle triggers or stat modifiers.
+- Weighting and eligibility are managed by `SpecialityHelper`:
+  - Uses `selectWeight` + stat/arm constraints to choose specials.
+  - Deterministic RNG affects special selection for NPCs or resets.
+
+## Personalities
+
+- Stored in `ActionPersonality/*` and also implement `iAction`.
+- Typically adjust core stats or apply small domestic bonuses.
+
+## Nation Types
+
+- `ActionNationType/*` extends `BaseNation`.
+- Provide global modifiers to income and domestic outcomes.
+- Injected per-nation via `buildNationTypeClass()`.
+
+## Crew Types (Units as Actions)
+
+- `ActionCrewType/*` defines per-crew `iAction` additions.
+- Crew types can alter battle order, apply triggers, or modify war stats.
+- For example, `che_성벽선제` forces city battle order to a high value.
+
+## Scenario Effects
+
+- `ActionScenarioEffect/*` provides scenario-wide modifiers
+  (e.g., attacker advantage, trigger overrides).
+- Bound to `GameConst::$scenarioEffect` during scenario build.
+
+## Interaction with Triggers
+
+Action modules often construct trigger callers:
+
+- Items and war specials can return `WarUnitTriggerCaller` with `BaseWarUnitTrigger`.
+- Some item triggers use `raiseType` to allow coexistence with non-item versions.
+
+See `docs/architecture/legacy-engine-triggers.md` for trigger execution rules.
+
+## Open Questions / Follow-ups
+
+- The precise selection rules for personalities and specials depend on
+  `SpecialityHelper` RNG thresholds and scenario overrides; capture those
+  when documenting specific rule packs.