문서 추가: 레거시 엔진 아키텍처에 대한 상세 설명 및 관련 정보 추가
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user