update
This commit is contained in:
@@ -93,3 +93,7 @@ These are placeholders to align teams; adjust once packages exist.
|
||||
- Legacy engine map: `docs/architecture/legacy-engine.md`.
|
||||
- TypeScript rewrite plan: `docs/architecture/rewrite-plan.md`.
|
||||
- Runtime and build profiles: `docs/architecture/runtime.md`.
|
||||
|
||||
## Documentation Workflow
|
||||
- When AI proposes future improvements or expansions, record them in
|
||||
`docs/architecture/todo.md` with an "AI suggestion" label.
|
||||
|
||||
@@ -28,3 +28,7 @@ monorepo plan is prepared alongside it.
|
||||
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.
|
||||
|
||||
## Documentation TODOs
|
||||
|
||||
- Pending follow-ups: `docs/architecture/todo.md`.
|
||||
|
||||
@@ -21,6 +21,42 @@ deployments predictable.
|
||||
- API server responsibilities: query/command intake, validation, response shaping
|
||||
- Concurrency model between daemon and API server
|
||||
|
||||
## Engine Runtime Flow (Draft)
|
||||
|
||||
### Turn Daemon Loop
|
||||
|
||||
- The turn daemon runs as a single-threaded loop.
|
||||
- The daemon engine uses in-memory state as the primary working set.
|
||||
- The daemon waits on two conditions during the event loop.
|
||||
- Query/command requests from the external API server.
|
||||
- The scheduled start time of the next turn.
|
||||
- External requests are processed until the next turn start time is reached.
|
||||
- If no requests arrive, the daemon waits until the next turn start time.
|
||||
- When the next turn start time arrives, the daemon starts turn processing
|
||||
immediately even if requests remain queued.
|
||||
- While the daemon is resolving a turn, the API server queues incoming requests.
|
||||
|
||||
### API Server Flow
|
||||
|
||||
- The API server validates queries/commands and writes them to Redis Streams.
|
||||
- After a request is processed, the API server returns the result to clients.
|
||||
- Read-only queries may access the DBMS directly.
|
||||
|
||||
### Queue and Rate Limits
|
||||
|
||||
- API server requests are delivered to the daemon via Redis Streams.
|
||||
- Redis Stream mutation requests are rate-limited per user.
|
||||
- Each user can have up to 30 pending mutation requests.
|
||||
- Additional requests are rejected once the limit is exceeded.
|
||||
|
||||
### In-Memory and DBMS Flush
|
||||
|
||||
- The daemon processes actions against in-memory state by default.
|
||||
- DBMS writes are flushed in bulk after turn processing completes.
|
||||
- Frequently changing "next-turn intent" data is stored separately.
|
||||
- The API server persists this data in the DBMS.
|
||||
- The daemon loads only this data when the next turn begins.
|
||||
|
||||
## Turn Daemon vs API Query Priority (Outline)
|
||||
|
||||
- Expected priority order under load
|
||||
@@ -37,3 +73,24 @@ deployments predictable.
|
||||
|
||||
- Metrics and logs required to validate scheduling and flush behavior
|
||||
- Suggested test scenarios for concurrency and consistency
|
||||
|
||||
## Game Logic Testing (Draft)
|
||||
|
||||
### Deterministic Inputs
|
||||
|
||||
- RNG seed composition (hidden server seed, turn info, general info).
|
||||
- Scenario selection and scenario data.
|
||||
- Trigger set inputs: nation, general, and city state.
|
||||
- Game time and tick schedule.
|
||||
|
||||
### Recommended Unit Test Flow
|
||||
|
||||
- Prepare a deterministic test fixture (mock DB or in-memory state snapshot).
|
||||
- Execute game logic unit tests with fixed inputs and seeds.
|
||||
- Compare expected outputs against the pre-flush change set that would be
|
||||
written to the DBMS.
|
||||
|
||||
### Notes
|
||||
|
||||
- Deterministic RNG makes output comparison stable and repeatable.
|
||||
- Prefer snapshotting inputs/outputs so regressions are easy to track.
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
# Architecture TODOs
|
||||
|
||||
This list tracks optional extensions and follow-up items for documentation.
|
||||
Move items into the main docs once they are finalized.
|
||||
|
||||
## Runtime and Operations
|
||||
|
||||
- Turn daemon scheduling details and preemption rules
|
||||
- Turn daemon vs API server priority policy under load
|
||||
- In-memory state lifecycle and DBMS flush checkpoints
|
||||
- Recovery behavior after partial flush or crash
|
||||
- Observability: metrics, logs, and alerts for turn processing
|
||||
|
||||
## Game Logic and Testing
|
||||
|
||||
- Input snapshot format (seed, scenario, trigger inputs, game time)
|
||||
- Output comparison rules (sorting, tolerances, diff granularity)
|
||||
- Unit test vs simulation test split and responsibilities
|
||||
- Deterministic RNG test harness guidelines
|
||||
|
||||
## Trigger System
|
||||
|
||||
- Trigger evaluation order and priority conflicts
|
||||
- Composition rules across traits, specials, and scenario effects
|
||||
- Example trigger sets per scenario or rule pack
|
||||
|
||||
## Data and Profiles
|
||||
|
||||
- "Next-turn intent" (예턴) data schema and lifecycle
|
||||
- Profile selection workflow and deployment mapping
|
||||
@@ -1,66 +0,0 @@
|
||||
다음 내용을 기반으로 프로젝트를 다시 분석해서, AGENTS.md 파일을 작성해줘. 폴더나 기본 파일 정도는 생성해도 돼.
|
||||
|
||||
## 개요
|
||||
|
||||
- 이 프로젝트의 목표는 legacy 폴더에 있는 내용을 TypeScript, pnpm 기반의 monorepo로 재 작성하는 것임
|
||||
|
||||
## 게임 로직 설명
|
||||
|
||||
- 이 게임은 삼국지 모의전투라는 웹 게임임. 여러명의 장수(플레이어 및 NPC)가 있으며, 이들이 모여 국가를 이루고, 고정된 지도 내의 도시를 점유하고, 서로 도시를 발전시킨 다음, 선전포고 후 전쟁을 하여 최종적으로 하나의 국가가 모든 도시를 점령하면 이기는 게임임.
|
||||
- 게임에서는 플레이어의 턴은 일정시간마다 한번씩 실행된다. 가령 60분턴이면, 60분사이에 다른 플레이어들의 턴이 모두 실행된 후, 다시 해당 플레이어의 턴이 돌아오는 방식임.
|
||||
- 현재 시도된 적이 있는 턴 시간 방식은 120분, 60분, 30분, 20분, 10분, 5분, 2분, 1분. 이며, 실험적으로 밤에는 120분턴, 낮 일부 시간은 30분턴으로 하여 하루에 24턴을 유지하는 형태도 시도된 바 있음.
|
||||
- 시도해보진 않았지만, 1분 미만의 턴 시간도 고려해보긴 하였음.
|
||||
- 단 NPC 턴의 경우 CPU 부하가 있어서, 기존 php 기반 서버에서는 1분 미만의 턴 시간은 불가능했음. 이론상으로 잘 최적화된다면 30초 서버같은 것도 가능은 할 것으로 예상함.
|
||||
- 장수의 경우 현재 통솔, 무력, 지력의 3가지 스탯을 가지고 있음.
|
||||
- 통솔의 경우 통솔 관련 내정, 그리고 전쟁 시 병력의 최대 숫자에 영향을 줌.
|
||||
- 훈련, 사기진작과 같은 커맨드는 통솔 스탯과 현재 보유중인 병력 수에 영향을 받음. 통솔이 높고, 병력 수가 적다면 훈련, 사기진작 커맨드로 올라가는 수치는 비교적 높음.
|
||||
- 무력의 경우 무력관련 내정, 무장 병종의 공격력, 방어력에 영향을 줌.
|
||||
- 지력의 경우 지력관련 내정, 지장 병종의 공격력, 방어력에 영향을 주며, 지장 병종의 특수 스킬인 '책략'의 시도 확률에 영향을 줌.
|
||||
- 각 행동에 영향을 줄 수 있는 다양한 요소가 있음
|
||||
- 국가의 성향.
|
||||
- 장수의 성격, 내정 특기(내특), 전술 특기(전특)
|
||||
- 병종의 특성
|
||||
- 소속 도시의 특성
|
||||
- 보유중인 아이템
|
||||
- 수뇌 특성
|
||||
- 기타 등
|
||||
- 이들 요소는 로직 내에서 Trigger 라는 시스템으로 운용되며, 내부적으로 특정 조건이 만족하는지 선행 검사하는 로직, 다른 로직에서 다른 로직이 평가중인 경우 추가로 참여하며, 최종 결과에 따라 로직이 실행되는 구조를 가짐
|
||||
- 'A 시도', 'A 실행' 형태가 되며, 일반적으로 시도가 우선순위가 높고, 실행이 후순위임.
|
||||
- Trigger 는 여러개가 동시에 평가될 수 있으며, 이 경우 우선순위에 따라 순차적으로 평가됨.
|
||||
- 각각의 게임은 '시나리오' 라는 형태로 구성되며, 시나리오에 따라 맵, 도시 배치, NPC 장수 및 국가 배치, 초기 자원 등이 결정됨.
|
||||
- 시나리오는 고정된 형태로 제공되며, 현재는 유저가 직접 시나리오를 제작하는 기능은 없음.
|
||||
- 패치로 시나리오가 추가되거나 변경될 수는 있음.
|
||||
- 단 향후 모드 지원을 고려하여, 시나리오 로딩 및 규칙 적용 부분은 별도의 모듈로 분리되어 있음.
|
||||
- 또한 '유닛 팩'(병종 타입) 이라는 형태로, 장수 및 병종의 그래픽 리소스, 음성 리소스, 일부 특수 효과 등이 묶여서 제공됨.
|
||||
- 시나리오마다 유닛 팩이 다를 수 있음.
|
||||
|
||||
## 기술 스택
|
||||
- DBMS의 경우 기존에는 MariaDB(MySQL)을 기반으로 하였으나, 재작성 이후에는 PostgreSQL을 기반으로 할 예정임.
|
||||
- 세션의 경우 PHP에서는 file 기반이었으나, 재작성 이후에는 Redis 기반으로 할 예정임.
|
||||
- 백엔드는 Node.js 기반의 Fastify 프레임워크를 사용할 예정임.
|
||||
- ORM으로는 Prisma를 사용할 예정임.
|
||||
- 대부분은 API 서버로만 동작하며, 일부 서버는 SSR도 담당할 예정임.
|
||||
- API 서버로는 tRPC와 zod를 사용할 예정임.
|
||||
- 번들러로는 Vite를 사용할 예정임.
|
||||
- 프론트엔드는 Vue 3 기반으로 작성할 예정임.
|
||||
- 상태 관리는 Pinia를 사용할 예정임.
|
||||
- 라우팅은 Vue Router를 사용할 예정임.
|
||||
- 스타일링은 TailwindCSS를 사용할 예정임.
|
||||
- 테스트 프레임워크는 Vitest를 사용할 예정임.
|
||||
- 패키지 매니저는 pnpm을 사용할 예정임.
|
||||
- 개념적으로 Gateway와 각각의 서버(che, kwe, pwe, twe, nya, pya)가 있음.
|
||||
- 각각의 서버는 클라이언트, API 서버, 게임 엔진 서버(턴 데몬)으로 구성됨.
|
||||
- 단 서버의 경우 기본적으로 backward compatibility를 유지하는 별도의 브랜치, 혹은 프리뷰 서버로 각각이 운영될 수 있음.
|
||||
- 이를 위해 실제 서버는 프로파일을 이용한 서버 빌드를 통해 `/dist/{서버이름}` 형태로 빌드된 후, 서버가 구동될 것임
|
||||
|
||||
|
||||
|
||||
## 폴더 구성
|
||||
- `/packages/common`: 공통 유틸리티, 타입 정의 등이 위치함.
|
||||
- `/packages/logic`: 게임 로직이 위치함. DB 등의 요소는 포함하지 않으며, 순수 게임 로직만 포함함. DB가 필요하다면 DI 혹은 Interface로만 제공될 것임.
|
||||
- `/app/gateway-frontend`: Gateway 프론트엔드 애플리케이션이 위치함.
|
||||
- `/app/gateway-api`: Gateway 백엔드 애플리케이션이 위치함.
|
||||
- `/app/game-frontend`: 게임 프론트엔드 애플리케이션이 위치함.
|
||||
- `/app/game-api`: 각각의 게임 서버 백엔드 애플리케이션이 위치함.
|
||||
- `/app/game-engine`: 각각의 게임 서버 게임 엔진(턴 데몬) 애플리케이션이 위치함.
|
||||
- `/tools/build-scripts`: 빌드 스크립트가 위치함.
|
||||
Reference in New Issue
Block a user