From f6fe5b0cafe36e90bf00536ac657b3ccd882d2c6 Mon Sep 17 00:00:00 2001 From: Hide_D Date: Tue, 30 Dec 2025 13:33:16 +0000 Subject: [PATCH] feat: update architecture TODOs with detailed implementation suggestions for turn engine and related systems --- docs/architecture/todo.md | 42 +++++++++++++++++++++++---------------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/docs/architecture/todo.md b/docs/architecture/todo.md index 8fdc4a1..b068c16 100644 --- a/docs/architecture/todo.md +++ b/docs/architecture/todo.md @@ -5,13 +5,25 @@ Move items into the main docs once they are finalized. ## Runtime and Operations -- Turn daemon scheduling details and preemption rules +- [AI suggestion] Implement full turn engine pipeline parity with legacy: time gate, distributed lock, catch-up monthly loop, partial progress persistence, and post-turn maintenance (traffic/statistics/auction/tournament). +- [AI suggestion] Implement command continuation/alternate flow (LastTurn/term stack/pre/post requirements/next_execute) and integrate into reserved turn processing. +- [AI suggestion] Integrate trigger preprocessing + attempt/execute phases into turn resolution (parity with legacy trigger composition). +- [AI suggestion] Add AI/autorun and inactivity (killturn/block) handling with NPC takeover/deletion policies. +- [AI suggestion] Add an event execution pipeline (initial + monthly + conditional) tied to tick/month transitions with deterministic RNG seeding. +- [AI suggestion] Add monthly economy/city/nation updates and hook them into the turn calendar handler. +- [AI suggestion] Implement diplomacy/state transitions and monthly/command-based updates beyond read-only maps. +- [AI suggestion] Integrate war/battle pipeline into turn processing (troop movement/war resolution hooks, not just isolated sim jobs). +- [AI suggestion] Expand turn command catalog beyond the current subset (general/nation commands). +- [AI suggestion] Replace in-memory control queue with distributed control/lock primitives for multi-instance daemon operation. + +## Runtime and Operations (Lower Priority) + +- Document current turn daemon scheduling details and preemption rules (based on TurnDaemonLifecycle). +- Document in-memory state lifecycle and DB flush checkpoints (current InMemoryTurnWorld + databaseHooks flow). +- Document existing status/health endpoint requirements for ops and the current daemon loop behavior. +- Document tick budget settings (wall time, max generals, catch-up cap) and partial progress persistence. +- Document admin controls (pause/resume/manual run) and how they interact with lock/state. - Turn daemon vs API server priority policy under load -- In-memory state lifecycle and DBMS flush checkpoints -- [AI suggestion] Specify the turn daemon main loop (distributed lock, `runUntil(now)` catch-up, checkpoint/resume cursor, release lock) and define a status/health endpoint for ops. -- [AI suggestion] Define tick budget settings (wall time, max generals, catch-up cap) to replace PHP `max_execution_time` behavior and clarify partial progress persistence. -- [AI suggestion] Define admin controls (pause/resume, manual run, force-catch-up) and their interaction with the lock/state. -- [AI suggestion] Define a constraint evaluation contract with explicit data requirements and a tri-state result (allow/deny/unknown) to support DB-backed prechecks vs in-memory full checks. - Recovery behavior after partial flush or crash - Observability: metrics, logs, and alerts for turn processing - [AI suggestion] Define a stable in-memory AI state contract (snapshot + delta invalidation rules) aligned with `GeneralAI` inputs. @@ -19,32 +31,28 @@ Move items into the main docs once they are finalized. ## Game Logic and Testing - Input snapshot format (seed, scenario, trigger inputs, game time) +- Deterministic RNG test harness guidelines - Output comparison rules (sorting, tolerances, diff granularity) - Unit test vs simulation test split and responsibilities -- Deterministic RNG test harness guidelines ## Trigger System - Example trigger sets per scenario or rule pack -## Data and Profiles +## Data and Profiles (Lower Priority) -- "Next-turn intent" (예턴) data schema and lifecycle - Profile selection workflow and deployment mapping -- [AI suggestion] Define a scenario bootstrap pipeline that turns scenario/map/unit set inputs into a world snapshot or DB seed payload. -- [AI suggestion] Implement a DB-backed world loader for turn daemon startup (nation/city/general + scenario config). -- [AI suggestion] Add map/unit set loaders that normalize legacy `CityConstBase`/`GameUnitConstBase` into `MapDefinition`/`UnitSetDefinition` inputs. -- [AI suggestion] Add a DB seed writer that converts `WorldSeedPayload` into DB inserts with defaults and audit logs. +- "Next-turn intent" (예턴) data schema and lifecycle -## Legacy Engine Docs +## Legacy Engine Docs (Lower Priority) - [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] Add per-command effect summaries (inputs, resource deltas, logs). - [AI suggestion] Document `event` table schema and the static event handler map (`GameConst::$staticEventHandlers`) with command hook examples. +- [AI suggestion] Add per-command effect summaries (inputs, resource deltas, logs). +- [AI suggestion] Document per-command `Constraint` env payload keys and lifecycle. +- [AI suggestion] Document `ConquerCity()` resolution paths (nation collapse, officer handling, reward/penalty rules). - [AI suggestion] Document auction scheduling (`registerAuction` call sites) and lifecycle timing rules. - [AI suggestion] Document scenario-specific unit/map overrides and per-map city deltas. -- [AI suggestion] Document per-command `Constraint` env payload keys and lifecycle. - [AI suggestion] Document `MessageType` values and message table schema used by diplomacy/mailbox flows. - [AI suggestion] Document `PenaltyKey` effects and the `GeneralBase` / `LazyVarAndAuxUpdater` state conventions. - [AI suggestion] Document personality/special selection RNG thresholds and scenario overrides.