diff --git a/docs/architecture/legacy-engine-constants.md b/docs/architecture/legacy-engine-constants.md index 5f3644d..55cb03b 100644 --- a/docs/architecture/legacy-engine-constants.md +++ b/docs/architecture/legacy-engine-constants.md @@ -51,6 +51,8 @@ Unit availability is controlled by `GameUnitConstraint` implementations: - `ReqTech`, `ReqCities`, `ReqRegions`, `ReqMinRelYear`, `Impossible`, etc. - Each constraint exposes `test(...)` and `getInfo()` for UI display. +- `ReqNationAux` gates unit availability by `nation.aux` flags (e.g. research + unlocks like `can_화시병사용`), which are written by nation commands. ## Open Questions / Follow-ups diff --git a/docs/architecture/legacy-engine-constraints.md b/docs/architecture/legacy-engine-constraints.md index 418253f..2bc4441 100644 --- a/docs/architecture/legacy-engine-constraints.md +++ b/docs/architecture/legacy-engine-constraints.md @@ -27,6 +27,10 @@ Constraints declare required inputs using bit flags: `Constraint::checkInputValues()` enforces these expectations and throws if inputs are missing or malformed. +Some constraints expect `general.aux` to be preloaded as `auxVar`. Command +evaluation calls `General::unpackAux()` before constraint checks to satisfy +these requirements. + ## Constraint Helper DSL `ConstraintHelper` provides factory-style helpers used in command definitions: diff --git a/docs/architecture/legacy-engine-execution.md b/docs/architecture/legacy-engine-execution.md index 4102323..ccaff7e 100644 --- a/docs/architecture/legacy-engine-execution.md +++ b/docs/architecture/legacy-engine-execution.md @@ -76,8 +76,12 @@ For each general with `turntime < targetDate` (ordered by `turntime, no`): - Updates `killturn` based on NPC status, autorun, or `휴식`. 8. **Queue maintenance & turntime** - `pullNationCommand()` / `pullGeneralCommand()` advance queues. - - `updateTurnTime()` handles deletion/retirement and sets next `turntime`. - - Persist via `General::applyDB()`. + - `updateTurnTime()` handles deletion/retirement and sets next `turntime`. + - Persist via `General::applyDB()`. +9. **LastTurn persistence** + - General `LastTurn` lives in `general.last_turn` JSON. + - Nation `LastTurn` is stored in `nation_env` under `turn_last_{officer_level}`. + - `LastTurn.term` only advances when the same command + arg repeats across turns. ## Command Semantics (BaseCommand) @@ -100,6 +104,16 @@ For each general with `turntime < targetDate` (ordered by `turntime, no`): - **Scheduling**: next `turntime` is `addTurn(current, turnterm)` with optional `nextTurnTimeBase` override (aux var). +## killturn, block, autorun + +- `killturn` acts as an inactivity counter; it is reset to `game_env.killturn` + when a non-rest player action completes, and decremented for NPCs, autorun, + rest commands, or block states. +- `block >= 2` forces `killturn` decrement and logs a block message. +- When `killturn <= 0`, the general is converted to NPC (owner removed) or + deleted depending on NPC type and `deadyear`. +- `autorun_limit` is stored in general `aux` and used to decide AI takeover. + ## Deterministic RNG Seeds RNG uses `LiteHashDRBG` with `UniqueConst::$hiddenSeed`: diff --git a/docs/architecture/legacy-engine-general.md b/docs/architecture/legacy-engine-general.md index 18b3731..1ed115c 100644 --- a/docs/architecture/legacy-engine-general.md +++ b/docs/architecture/legacy-engine-general.md @@ -9,6 +9,7 @@ exposes trigger hooks. The main reference is `legacy/hwe/sammo/General.php`. - `last_turn` is parsed into `LastTurn`, and a separate `resultTurn` is maintained for updates. - `penalty` JSON is decoded into `PenaltyKey -> value` map. +- `aux` JSON is lazily decoded and only written when aux values change. - Rank data is tracked with: - `rankVarRead` (current read view) - `rankVarIncrease` (increment queue) @@ -53,6 +54,16 @@ Convenience wrappers: `BaseCommand::addTermStack()` to advance multi-turn commands. - `applyDB()` persists updated fields and writes `last_turn` if it changed. +## Aux and Penalty Behavior + +- `aux` is loaded on demand (`unpackAux()`), and `setAuxVar()` writes through to + `general.aux` only when values changed. +- Setting an aux value to `null` deletes the key from JSON. +- Command constraints that require aux values trigger `General::unpackAux()` + before evaluation. +- `penalty` is used in both `General` logic (AI and permission checks) and + API flows (messages, nation tools); runtime expiration is not automatic. + ## Trigger and Modifier Hooks `General` delegates calculations and trigger lists through action objects: