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

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 Auctions and Betting
 This document covers the auction and betting systems: how auctions open/close,
 what resources they trade, and how betting payouts are calculated. References
 include `legacy/hwe/sammo/Auction*.php`, `legacy/hwe/func_auction.php`, and
 `legacy/hwe/sammo/Betting.php`.
 ## Auction Types and Entry Points
 - `Auction` (base class): shared bid logic and close-date extensions.
 - `AuctionBuyRice`: sell rice for gold.
 - `AuctionSellRice`: sell gold for rice.
 - `AuctionUniqueItem`: bids use inheritance points for unique items.
 - `processAuction()` in `legacy/hwe/func_auction.php` closes finished auctions.
 - `registerAuction()` creates neutral (NPC-hosted) buy/sell auctions.
 ## Auction Data Model
 Primary tables:
 - `ng_auction`: auction metadata (type, target, host, close date, detail).
 - `ng_auction_bid`: per-bid rows for each auction.
 The `AuctionInfo` and `AuctionInfoDetail` DTOs are serialized into
 `ng_auction` columns for structured access.
 ## Core Auction Flow
 1. **Open**
   - `AuctionBasicResource::openResourceAuction()` validates amounts and
     host resources, then inserts `ng_auction`.
   - `AuctionUniqueItem::openItemAuction()` checks availability, reserves
     unique items, and posts a global history notice.
 2. **Bid**
   - Bids are inserted into `ng_auction_bid` and can extend the close date.
   - Reverse auctions (when `detail->isReverse`) sort by lowest bid.
 3. **Close** (`tryFinish()` from the concrete auction)
   - If no bids: `rollbackAuction()` returns resources to host and logs.
   - With bids: `finishAuction()` transfers resources, logs, and sends messages.
 4. **Processing**
   - `processAuction()` scans auctions past `close_date` and finishes them.
 ## Unique Item Auctions
 - Currency: inheritance points (`ResourceType::inheritancePoint`).
 - Host identity is obfuscated using `genObfuscatedName()` and a deterministic
  shuffled name pool stored in `game_env.obfuscatedNamePool`.
 - Limits and availability are enforced against `GameConst::$allItems` and
  existing ownership in `general` rows.
 ## Betting System
 Betting is an independent KV-backed system:
 - `Betting::openBetting()` stores `BettingInfo` in KV storage (`betting`).
 - `Betting::bet()` inserts or updates `ng_betting` rows and charges either
  gold or inheritance points.
 - `Betting::giveReward()` distributes payouts to winners (exclusive or shared).
 Event actions controlling lifecycle:
 - `OpenNationBetting`: opens a nation-strength bet and registers a
  `DESTROY_NATION` event to close it.
 - `FinishNationBetting`: evaluates winners when only N nations remain.
 ## RNG Notes
 - `Auction::genObfuscatedName()` uses `hiddenSeed + 'obfuscatedNamePool'` to
  shuffle the name pool once and reuse it from `game_env`.
 - `registerAuction()` relies on an injected RNG to randomize neutral auctions.
 ## Open Questions / Follow-ups
 - The exact schedule for `registerAuction()` is outside this file; it is
  likely called from monthly or timed maintenance.
 - Unique-item auction close-date extension limits depend on
  `AuctionUniqueItem` constants and `turnterm`; verify scenarios that override
  auction timing.
@@ -0,0 +1,48 @@
 # Legacy City Data and Helpers
 This document describes how city data is defined and accessed in the legacy
 engine. References include `legacy/hwe/sammo/CityConstBase.php`,
 `legacy/hwe/sammo/CityInitialDetail.php`, and `legacy/hwe/sammo/CityHelper.php`.
 ## City Constants (CityConst)
 `CityConstBase` defines default city data and lookup helpers:
 - `CityConstBase::$initCity` includes:
  - id, name, level, population, agri/comm/secu/def/wall,
    region, coordinates, and path connections.
 - Region and level maps convert labels to numeric codes.
 - `CityConstBase::byID()` and `byName()` return `CityInitialDetail` objects.
 During scenario build, the engine generates `d_setting/CityConst.php` from the
 scenario map file, replacing or extending these defaults.
 ## CityInitialDetail
 `CityInitialDetail` is a plain data object containing the initial
 static attributes for each city:
 - `id`, `name`, `level`, `population`
 - `agriculture`, `commerce`, `security`, `defence`, `wall`
 - `region`, `posX`, `posY`, `path` (adjacent city ids)
 ## CityHelper Cache
 `CityHelper` caches live DB city rows for fast lookup:
 - `getAllCities()` returns a map keyed by city id.
 - `getAllNationCities($nationID)` returns all cities for a nation.
 - `getCityByName()` resolves a name to a DB row (with a warning if missing).
 Cache invalidation is manual via `CityHelper::flushCache()`.
 ## Path Connectivity
 City connectivity (used for supply and movement) is defined by the
 `path` list in `CityConst` and referenced by systems like
 `UpdateCitySupply` to traverse same-nation city graphs.
 ## Open Questions / Follow-ups
 - Scenario-specific map files (`legacy/hwe/scenario/map/*.php`) override city
  data; document per-map deltas when needed.
@@ -0,0 +1,58 @@
 # Legacy Game Constants and Unit Sets
 This document summarizes the static configuration layers that define game
 rules and unit sets. References include `legacy/hwe/sammo/GameConstBase.php`,
 `legacy/hwe/sammo/GameUnitConstBase.php`, `legacy/hwe/sammo/GameUnitDetail.php`,
 and `legacy/hwe/sammo/GameUnitConstraint/*`.
 ## GameConst (Rules)
 `GameConstBase` defines the default rule set:
 - Turn limits, stat caps, and progression thresholds.
 - Resource floors (`basegold`, `baserice`) and maintenance coefficients.
 - Command lists (`availableGeneralCommand`, `availableChiefCommand`).
 - Availability lists for specials, items, and nation types.
 - Scenario overrides apply via `Scenario::buildConf()`.
 During scenario build, the engine generates `d_setting/GameConst.php` from
 `GameConstBase` and scenario overrides (see
 `docs/architecture/legacy-scenarios.md`).
 ## Unit Sets (GameUnitConst)
 `GameUnitConstBase` defines the base unit list and their combat properties:
 - Unit identifiers, arm types, and labels.
 - Base attack/defence stats, speed, avoid, magic coefficients.
 - Cost and rice consumption.
 - Attack/defence coefficients vs. other arm types.
 - Attached trigger lists (`initSkillTrigger`, `phaseSkillTrigger`).
 - Requirements via `GameUnitConstraint` objects.
 Scenario build emits `d_setting/GameUnitConst.php` based on the selected
 `unitSet` (`scenario/unit/*.php`).
 ## GameUnitDetail
 `GameUnitDetail` is the runtime representation of a crew type:
 - Computes derived attack/defence using general stats and tech (`getTechAbil`).
 - Calculates resource costs (`costWithTech`, `riceWithTech`).
 - Applies attack/defence multipliers by opponent crew type.
 - Can include an `iActionList` (crew-type-specific action modules).
 Crew types are also `iAction` providers, enabling triggers and stat modifiers
 through `General::getActionList()`.
 ## Unit Constraints
 Unit availability is controlled by `GameUnitConstraint` implementations:
 - `ReqTech`, `ReqCities`, `ReqRegions`, `ReqMinRelYear`, `Impossible`, etc.
 - Each constraint exposes `test(...)` and `getInfo()` for UI display.
 ## Open Questions / Follow-ups
 - Scenario-specific overrides may redefine available units or unit sets;
  document those deltas per scenario when needed.
@@ -0,0 +1,53 @@
 # Legacy Constraint System
 This document describes the constraint framework used to validate command
 preconditions. References include `legacy/hwe/sammo/Constraint/Constraint.php`
 and `legacy/hwe/sammo/Constraint/ConstraintHelper.php`.
 ## Core Concepts
 Constraints are reusable predicate classes that validate a command’s inputs and
 state. They are built per-command and executed in order:
 - Each constraint extends `Constraint` and implements `test()`.
 - `Constraint::testAll()` iterates a list of constraints and returns the first
  failure `[constraintName, reason]` or `null` for success.
 - `BaseCommand::hasFullConditionMet()` uses these to decide command validity.
 ## Required Input Flags
 Constraints declare required inputs using bit flags:
 - `REQ_GENERAL`, `REQ_CITY`, `REQ_NATION`
 - `REQ_DEST_GENERAL`, `REQ_DEST_CITY`, `REQ_DEST_NATION`
 - `REQ_ARG` with typed sub-flags:
  - `REQ_STRING_ARG`, `REQ_INT_ARG`, `REQ_NUMERIC_ARG`, `REQ_BOOLEAN_ARG`,
    `REQ_ARRAY_ARG`, `REQ_BACKED_ENUM_ARG`
 `Constraint::checkInputValues()` enforces these expectations and throws if
 inputs are missing or malformed.
 ## Constraint Helper DSL
 `ConstraintHelper` provides factory-style helpers used in command definitions:
 - Examples: `AllowWar()`, `NearCity($distance)`, `ReqGeneralGold($amount)`,
  `NotOccupiedDestCity()`, `AllowDiplomacyStatus(...)`, etc.
 - These helpers return `[ConstraintName, arg]` tuples consumed by
  `Constraint::testAll()`.
 ## Common Constraint Classes
 Constraints are organized by domain:
 - **Diplomacy**: `AllowDiplomacyStatus`, `AllowDiplomacyBetweenStatus`.
 - **Nation/City**: `OccupiedCity`, `NotCapital`, `RemainCityCapacity`.
 - **General**: `ReqGeneralCrew`, `ReqGeneralGold`, `MustBeTroopLeader`.
 - **Routing**: `HasRoute`, `HasRouteWithEnemy`.
 Each constraint sets a failure reason string used by UI and logs.
 ## Open Questions / Follow-ups
 - Some constraints rely on `env` values (`turnterm`, `year`, etc.); document
  each command’s exact `env` payload when porting.
@@ -0,0 +1,55 @@
 # Legacy Diplomacy and Messaging
 This document summarizes the legacy message system and how diplomatic messages
 trigger nation command flows. References include
 `legacy/hwe/sammo/Message.php`, `legacy/hwe/sammo/DiplomaticMessage.php`,
 `legacy/hwe/sammo/MessageTarget.php`, and `legacy/hwe/sammo/Target.php`.
 ## Message Types and Mailboxes
 `Message` supports multiple mailbox types:
 - **Public**: `MAILBOX_PUBLIC` (global announcements).
 - **National**: `MAILBOX_NATIONAL + nationID` for diplomacy/nation mail.
 - **Private**: mailbox id is the receiver general id.
 Message types (`MessageType`) include `public`, `national`, `private`,
 and `diplomacy`.
 ## Message Lifecycle
 - `Message::send()` (not shown here) writes to the `message` table.
 - `Message::getMessagesFromMailBox()` reads by mailbox/type with validity
  filtering (`valid_until > now`).
 - `Message::buildFromArray()` instantiates:
  - `DiplomaticMessage` when type is diplomacy.
  - `ScoutMessage` or `RaiseInvaderMessage` when `option.action` matches.
 ## DiplomaticMessage Flow
 `DiplomaticMessage` wraps diplomacy requests and accepts/rejects them:
 - Supported actions:
  - `TYPE_NO_AGGRESSION` (불가침)
  - `TYPE_CANCEL_NA` (불가침 파기)
  - `TYPE_STOP_WAR` (종전)
 - `agreeMessage()` validates:
  - message is still valid
  - receiver is a valid diplomacy officer
 - On accept, builds and runs the matching nation command:
  - `che_불가침수락`, `che_불가침파기수락`, `che_종전수락`
  - Uses `NoRNG` to avoid randomness in acceptance.
 Each acceptance updates `diplomacyDetail` with command briefs and writes logs.
 ## Message Targets
 `MessageTarget` and `Target` provide lightweight identifiers:
 - `MessageTarget` includes general/nation names, colors, and icons.
 - Helper constructors (`buildQuick`, `buildFromGeneralObj`) resolve from DB.
 ## Open Questions / Follow-ups
 - The full list of `MessageType` values and message table schema live outside
  this file and can be documented alongside the UI mailbox APIs.
@@ -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.
@@ -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.
@@ -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.
@@ -0,0 +1,36 @@
 # Legacy Logging and Versioning
 This document summarizes logging utilities and version helpers. References
 include `legacy/hwe/sammo/ActionLogger.php`, `legacy/hwe/sammo/UserLogger.php`,
 and `legacy/hwe/sammo/VersionGitDynamic.php`.
 ## ActionLogger
 `ActionLogger` aggregates logs for a general, nation, and global context:
 - Buffers multiple log channels:
  - General history/action/battle logs
  - National history logs
  - Global history/action logs
 - Supports formatted prefixes (`PLAIN`, `YEAR_MONTH`, `NOTICE`, etc.).
 - `flush()` emits buffered logs via helper functions
  (`pushGeneralHistoryLog`, `pushGlobalHistoryLog`, etc.).
 It is used throughout command execution, battle resolution, and event actions.
 ## UserLogger
 `UserLogger` writes user-scoped logs to `user_record`:
 - Used for inheritance point spending/awards and other user-level events.
 - `push($text, $type)` buffers entries; `flush()` inserts into DB with
  `{user_id, server_id, year, month, date, text}`.
 ## Version Helpers
 `VersionGitDynamic` exposes runtime Git metadata:
 - `getVersion()` calls `git describe --long --tags` and `git branch`.
 - `getHash()` calls `git rev-parse HEAD`.
 These are used for diagnostic display and do not affect gameplay logic.
@@ -0,0 +1,43 @@
 # Legacy General Pools
 This document summarizes the general pool system used for character selection
 and event-driven recruitment. References include `legacy/hwe/sammo/AbsGeneralPool.php`,
 `legacy/hwe/sammo/AbsFromUserPool.php`, and `legacy/hwe/sammo/GeneralPool/*`.
 ## Core Abstractions
 - `AbsGeneralPool`
  - Wraps a `Scenario\GeneralBuilder` and a raw `info` payload.
  - Provides `getGeneralBuilder()`, `getInfo()`, and `occupyGeneralName()`.
  - Abstract method: `pickGeneralFromPool(...)`.
 - `AbsFromUserPool`
  - Implements reservation logic backed by the `select_pool` table.
  - Reserves candidates for a user (`owner`) until `reserved_until`.
  - On selection, clears reservation and binds `general_id`.
 ## Pool Implementations
 - `GeneralPool/RandomNameGeneral`
  - Generates random names using `GameConst::$randGen*` lists.
  - Checks duplicate counts and appends suffixes if needed.
  - Inserts reservation rows into `select_pool` for user selection.
 - `GeneralPool/SPoolUnderU30`
  - Loads a curated pool from `GeneralPool/Pool/UnderS30.json`.
  - Inserts rows into `select_pool` with pre-defined stats and specials.
 ## Data Model
 `select_pool` table fields (observed usage):
 - `unique_name` (pool key)
 - `info` (JSON: stats, portrait, specials, dex, etc.)
 - `owner` (reservation user id)
 - `reserved_until` (reservation expiry)
 - `general_id` (assigned after creation)
 ## RNG Notes
 Pool selection uses injected `RandUtil` to choose candidates and generate
 random names; deterministic seeding depends on caller context.
@@ -0,0 +1,25 @@
 # Legacy Server Environment
 This document captures the legacy server-level environment settings and
 utilities. References include `legacy/hwe/sammo/ServerDefaultEnv.php`,
 `legacy/hwe/sammo/ServerEnv.php`, and `legacy/hwe/sammo/ServerTool.php`.
 ## Server Environment
 - `ServerDefaultEnv` holds server-wide constants (e.g.,
  `maxGeneralsPerMinute`).
 - `ServerEnv` extends `ServerDefaultEnv` and is overridden by
  `d_setting/ServerEnv.php` when present.
 ## Turn Term Management
 `ServerTool::changeServerTerm($turnterm)` adjusts the global turn length:
 1. Validates that `turnterm` divides 120 minutes.
 2. Acquires the game lock (`tryLock()`), unless `ignoreLock` is set.
 3. Recomputes each general's `turntime` based on the new interval.
 4. Updates `game_env.turnterm` and `game_env.starttime`.
 5. Broadcasts a global history notice about the change.
 This is a direct mutation of runtime schedule and should be treated as an
 administrative operation.
@@ -45,3 +45,14 @@ organization rather than endpoint-first routing.
 - Command catalog: `docs/architecture/legacy-commands.md`
 - Scenario system and rule sets: `docs/architecture/legacy-scenarios.md`
 - Inheritance points (유산 포인트): `docs/architecture/legacy-inherit-points.md`
 - Event system (dynamic/static): `docs/architecture/legacy-engine-events.md`
 - Economy and monthly updates: `docs/architecture/legacy-engine-economy.md`
 - Auctions and betting: `docs/architecture/legacy-engine-auction.md`
 - Items, specials, and traits: `docs/architecture/legacy-engine-items.md`
 - City data and helpers: `docs/architecture/legacy-engine-city.md`
 - Diplomacy and messaging: `docs/architecture/legacy-engine-diplomacy.md`
 - Constraint system: `docs/architecture/legacy-engine-constraints.md`
 - Game constants and unit sets: `docs/architecture/legacy-engine-constants.md`
 - Server environment tools: `docs/architecture/legacy-engine-server-env.md`
 - Logging and versioning: `docs/architecture/legacy-engine-logging.md`
 - General pools: `docs/architecture/legacy-engine-pools.md`
@@ -35,3 +35,5 @@ Move items into the main docs once they are finalized.
 - [AI suggestion] Expand monthly pipeline details (`preUpdateMonthly`, `postUpdateMonthly`, `turnDate`, `checkStatistic`) with concrete side effects and tables touched.
 - [AI suggestion] Document `ConquerCity()` resolution paths (nation collapse, officer handling, reward/penalty rules).
 - [AI suggestion] Clarify command prefix semantics (`che_`, `cr_`, `event_`) and add per-command effect summaries.
 - [AI suggestion] Document `event` table schema and the static event handler map (`GameConst::$staticEventHandlers`) with command hook examples.
 - [AI suggestion] Document auction scheduling (`registerAuction` call sites) and lifecycle timing rules.