From 0e5a092eac80fc9adbbdce7630ad2ec15d6b0072 Mon Sep 17 00:00:00 2001 From: Hide_D Date: Fri, 26 Dec 2025 17:38:56 +0000 Subject: [PATCH] architecture --- AGENTS.md | 15 +++++------- docs/architecture/legacy-engine.md | 36 +++++++++++++++++++++++++++ docs/architecture/overview.md | 30 +++++++++++++++++++++++ docs/architecture/rewrite-plan.md | 28 +++++++++++++++++++++ docs/architecture/runtime.md | 39 ++++++++++++++++++++++++++++++ 5 files changed, 139 insertions(+), 9 deletions(-) create mode 100644 docs/architecture/legacy-engine.md create mode 100644 docs/architecture/overview.md create mode 100644 docs/architecture/rewrite-plan.md create mode 100644 docs/architecture/runtime.md diff --git a/AGENTS.md b/AGENTS.md index 1433744..2774e35 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,15 +9,6 @@ - PHP entry points live under `legacy/` and `legacy/hwe/` (for example `legacy/index.php`, `legacy/hwe/index.php`). - `legacy/` is mostly a shell; `legacy/src/` is largely unused. - Core PHP domain logic lives under `legacy/hwe/sammo/` (PSR-4 `sammo\\` namespace). -- `legacy/hwe/sammo/` is the game engine core, organized by domain concerns rather than endpoints. - - `Command/` contains turn actions (general/nation commands) and their resolution rules. - - `API/` exposes engine operations for UI and automation (general, nation, command, message, auction, etc.). - - `Event/` and `StaticEvent/` implement dynamic and scheduled event processing. - - `General*`, `Nation*`, `WarUnit*`, `City*` classes model game entities and combat/city state. - - `Action*` and `Special*` capture traits, personalities, special actions, and scenario effects. - - `Trigger*` and `*Trigger` manage conditional logic for units, generals, and state changes. - - `Scenario/` and `Scenario.php` define scenario loading and rulesets. - - `DTO/`, `VO/`, `Enums/`, `Constraint/` are shared types and validation rules. - Frontend TypeScript/Vue sources are in `legacy/hwe/ts/` with shared components in `legacy/hwe/ts/components/`. - Styles are split between `legacy/css/` and SCSS in `legacy/hwe/scss/`. - Tests: PHPUnit in `legacy/tests/`, TypeScript tests in `legacy/hwe/test-ts/`. @@ -96,3 +87,9 @@ These are placeholders to align teams; adjust once packages exist. ## Commit & Pull Request Guidelines - Git history is minimal and does not define a strict convention; use short, imperative messages (e.g., "Fix map cache loading"). - PRs should include a concise description, testing notes/commands, and screenshots for UI changes. + +## Architecture References +- Overview: `docs/architecture/overview.md`. +- Legacy engine map: `docs/architecture/legacy-engine.md`. +- TypeScript rewrite plan: `docs/architecture/rewrite-plan.md`. +- Runtime and build profiles: `docs/architecture/runtime.md`. diff --git a/docs/architecture/legacy-engine.md b/docs/architecture/legacy-engine.md new file mode 100644 index 0000000..ce3eba9 --- /dev/null +++ b/docs/architecture/legacy-engine.md @@ -0,0 +1,36 @@ +# Legacy Engine Map + +The legacy engine lives in `legacy/hwe/sammo/` and follows domain-first +organization rather than endpoint-first routing. + +## Core Domains + +- `Command/`: turn actions (general/nation commands) and resolution rules +- `API/`: engine operations for UI and automation +- `Event/`, `StaticEvent/`: dynamic and scheduled event processing +- `General*`, `Nation*`, `WarUnit*`, `City*`: entities and combat/city state +- `Action*`, `Special*`: traits, personalities, special actions, scenario effects +- `Trigger*`, `*Trigger`: conditional logic and state transitions +- `Scenario/`, `Scenario.php`: scenario loading and rulesets +- `DTO/`, `VO/`, `Enums/`, `Constraint/`: shared types and validation + +## Endpoint Patterns + +- JSON APIs: `legacy/hwe/j_*.php` +- Vue multi-entry pages: `legacy/hwe/v_*.php` +- PHP + jQuery pages: `legacy/hwe/b_*.php` and handlers `legacy/hwe/c_*.php` +- Modern router: `legacy/hwe/api.php` dispatches into `legacy/hwe/API/` + +## Frontend and Assets + +- Vue/TypeScript UI: `legacy/hwe/ts/` +- Shared components: `legacy/hwe/ts/components/` +- Styles: `legacy/css/` and `legacy/hwe/scss/` +- Templates: `legacy/hwe/templates/` + +## Trigger Composition for Generals (Outline) + +- Trigger evaluation order and priority rules +- "attempt" then "execute" phases +- Common trigger categories (traits, specials, scenario effects) +- How triggers combine when multiple sources apply diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md new file mode 100644 index 0000000..75ace7c --- /dev/null +++ b/docs/architecture/overview.md @@ -0,0 +1,30 @@ +# Architecture Overview + +This repository contains both the active legacy PHP game and an in-progress +TypeScript rewrite. The legacy engine remains the source of truth while the +monorepo plan is prepared alongside it. + +## Layers + +- Legacy runtime: PHP entry points under `legacy/` and `legacy/hwe/` +- Legacy engine core: domain logic under `legacy/hwe/sammo/` +- Legacy frontend: Vue/TypeScript under `legacy/hwe/ts/` +- Rewrite (planned): pnpm workspace monorepo under `packages/` and `app/` + +## Data and State + +- PHP engine owns authoritative gameplay state today +- Scenario and unit pack data are loaded from `legacy/hwe/scenario/` +- Deterministic RNG is required for gameplay outcomes + +## Cross-Cutting Policies + +- No ad-hoc randomness for gameplay; use deterministic RNG +- Keep domain logic independent of endpoints or UI +- Prefer clear Korean comments in core gameplay logic for maintainers + +## Runtime Processing (Outline) + +This document links to detailed runtime behavior in `docs/architecture/runtime.md`. +Use that document for turn daemon scheduling, API request handling, and +persistence sequencing. diff --git a/docs/architecture/rewrite-plan.md b/docs/architecture/rewrite-plan.md new file mode 100644 index 0000000..3479e96 --- /dev/null +++ b/docs/architecture/rewrite-plan.md @@ -0,0 +1,28 @@ +# TypeScript Rewrite Plan + +The rewrite targets a pnpm workspace-based monorepo with Node.js services and +Vue 3 frontends. + +## Planned Layout + +- `/packages/common`: shared utilities and type definitions +- `/packages/logic`: pure game logic with DI and interfaces +- `/app/gateway-frontend`: gateway UI +- `/app/gateway-api`: gateway service +- `/app/game-frontend`: game UI +- `/app/game-api`: game backend per server profile +- `/app/game-engine`: turn daemon per server profile +- `/tools/build-scripts`: build and deployment scripts + +## Runtime Stack (Planned) + +- Backend: Node.js + Fastify +- API: tRPC + zod +- ORM: Prisma +- Frontend: Vue 3, Pinia, Vue Router, TailwindCSS, Vite +- Data: PostgreSQL, Redis sessions +- Testing: Vitest + +## Profiles (Planned) + +- `che`, `kwe`, `pwe`, `twe`, `nya`, `pya` diff --git a/docs/architecture/runtime.md b/docs/architecture/runtime.md new file mode 100644 index 0000000..04351eb --- /dev/null +++ b/docs/architecture/runtime.md @@ -0,0 +1,39 @@ +# Runtime and Build Profiles + +Build outputs should be emitted to `/dist/{serverName}` per profile to keep +deployments predictable. + +## Suggested Build Pattern + +- Wrapper script under `tools/build-scripts` +- `pnpm build:server --profile che` +- CI-friendly: `PROFILE=che pnpm build:server` + +## Deterministic RNG Policy + +- Gameplay randomness must be reproducible from a deterministic seed +- Prefer `legacy/hwe/ts/util/LiteHashDRBG.ts` and `legacy/hwe/ts/util/RNG.ts` +- Seed composition should include hidden base seed plus action context + +## Turn Daemon and API Server Behavior (Outline) + +- Turn daemon responsibilities: scheduling, turn resolution, state persistence +- API server responsibilities: query/command intake, validation, response shaping +- Concurrency model between daemon and API server + +## Turn Daemon vs API Query Priority (Outline) + +- Expected priority order under load +- Rules for preemption or deferral +- Handling of write-heavy operations during turn resolution + +## In-Memory Processing and DBMS Flush (Outline) + +- When in-memory state is authoritative +- Flush checkpoints and transactional boundaries +- Recovery strategy after crash during flush + +## Testing and Observability (Outline) + +- Metrics and logs required to validate scheduling and flush behavior +- Suggested test scenarios for concurrency and consistency