From 07587b103eda456a4e18a8626f08ea4860e22f93 Mon Sep 17 00:00:00 2001 From: tolelom <98kimsungmin@naver.com> Date: Wed, 25 Mar 2026 11:58:34 +0900 Subject: [PATCH] docs: add game enhancement design spec Comprehensive enhancement plan for Catacombs covering 4 phases: UI refactoring, combat/dungeon expansion, retention systems, and operational stability. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../2026-03-25-game-enhancement-design.md | 181 ++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 docs/superpowers/specs/2026-03-25-game-enhancement-design.md diff --git a/docs/superpowers/specs/2026-03-25-game-enhancement-design.md b/docs/superpowers/specs/2026-03-25-game-enhancement-design.md new file mode 100644 index 0000000..78f4117 --- /dev/null +++ b/docs/superpowers/specs/2026-03-25-game-enhancement-design.md @@ -0,0 +1,181 @@ +# Catacombs Game Enhancement Design + +## Overview + +Catacombs 멀티플레이 로그라이크 던전 크롤러의 종합 고도화 설계. +실제 유저 운영(소규모 10~30명 커뮤니티) 목표로, 재미/리텐션/안정성 중심. + +접근 방식: **기반 정비 → 콘텐츠 → 리텐션 → 운영** (접근 A) + +## Current State + +- Go + Bubble Tea TUI, SSH(:2222) + WebSocket(:8080) 듀얼 접속 +- 4 클래스(Warrior/Mage/Healer/Rogue), 8 몬스터 + 4 보스, 20층 던전 +- 턴제 전투(5초 타임아웃), 상점, 업적 10개, 리더보드 +- BoltDB 영속화, SSH 핑거프린트 재접속 +- `ui/model.go` ~19K 라인 (모든 화면 로직 집중) + +## Phase 1: Foundation + Chat + +### 1-1. UI Refactoring + +**Problem:** `ui/model.go`가 ~19K 라인으로 모든 화면 상태를 단일 파일에서 관리. 새 기능 추가 시 버그 위험 증가, 유지보수 곤란. + +**Design:** +- 각 화면의 `Update`/`View` 로직을 해당 `*_view.go` 파일로 이동 +- 각 화면을 독립적인 Bubble Tea `Model` 인터페이스로 추출 (`LobbyModel`, `GameModel`, `ShopModel` 등) +- 메인 `Model`은 화면 간 라우팅만 담당하는 컨테이너 역할 +- 공유 상태(게임 세션, DB, 뷰포트 크기 등)는 공통 `Context` 구조체로 추출 + +**Success criteria:** `model.go` 500라인 이하의 라우터로 축소. + +### 1-2. In-game Chat + +**Problem:** 멀티플레이에서 소통 수단이 없어 협동의 재미가 크게 떨어짐. + +**Design:** +- `game/chat.go` — 채팅 메시지 브로드캐스트 (룸 내 플레이어 간) +- 게임 화면 하단에 채팅 로그 영역 추가 +- `/` 키로 채팅 입력 모드 전환 +- 이모트 프리셋 (`/hi`, `/gg` 등) + +**Affected packages:** `game/`, `ui/` + +## Phase 2: Combat & Dungeon Enhancement + +### 2-1. Combat System Expansion + +**Skill Tree:** +- 클래스별 3갈래 특성 트리 (예: Warrior → 탱커/버서커/전술가) +- 층 클리어 시 포인트 획득, 런 내에서만 유효 (로그라이크 특성 유지) +- `entity/skill_tree.go` — 트리 정의 및 포인트 적용 로직 + +**Combo Skills:** +- 2인 이상이 같은 턴에 특정 조합 사용 시 연계 효과 발동 +- 예: Mage 빙결 + Warrior 강타 = 빙쇄 대미지 +- `combat/combo.go` — 연계 조건 판정 및 효과 적용 + +**Elite Monsters:** +- 일반 몬스터의 강화 변종, 특수 접두사 (맹독의/불타는/흡혈의 등) +- 보스가 아닌 층에서 긴장감 추가 +- `entity/elite.go` — 접두사 시스템 및 스탯 변형 + +**Status Effects Expansion:** +- 기존: 독, 화상 +- 추가: 빙결(행동 불가), 출혈(턴마다 누적), 저주(회복량 감소) +- `entity/status.go` 확장 + +**Affected packages:** `entity/`, `combat/`, `game/` + +### 2-2. Dungeon Event Diversification + +**Random Event Rooms:** +- 선택지 기반 이벤트 (예: "수상한 제단 발견" → 제물 바치기/무시/파괴) +- 각 선택지마다 다른 보상/페널티 +- `game/random_event.go` — 이벤트 풀 및 결과 처리 + +**Secret Rooms:** +- 낮은 확률(~10%)로 생성, 희귀 아이템/렐릭 보상 +- `dungeon/generator.go` 확장 + +**Floor Themes:** +- 5층 단위로 환경 효과 + - 1~5층 습지: 독 대미지 증가 + - 6~10층 화산: 화상 대미지 증가 + - 11~15층 얼음: 빙결 확률 증가 + - 16~20층 지옥: 모든 상태이상 강화 +- `dungeon/theme.go` — 테마별 환경 효과 정의 + +**Mini-boss Rooms:** +- 보스 층 직전(4, 9, 14, 19층)에 미니보스 등장 +- 보스 전 준비 테스트 역할 + +**Affected packages:** `dungeon/`, `game/`, `entity/` + +## Phase 3: Retention Systems + +### 3-1. Daily Challenge + +- 날짜 기반 시드로 동일한 던전 구조/몬스터 배치 생성 +- 일일 전용 리더보드 +- 참여 시 포인트 적립, 연속 참여 보너스 +- `game/daily.go` — 시드 생성 및 일일 세션 관리 +- `store/daily.go` — 일일 기록 및 연속 참여 추적 + +### 3-2. Meta Progression + +**Unlock System Expansion:** +- 현재 업적 10개 → 조건부 언락 콘텐츠 추가 + - "10층 이상 클리어" → 5번째 클래스 해금 + - "3인 이상 클리어" → 하드 모드 해금 +- `store/unlocks.go` — 언락 조건 및 상태 관리 + +**Player Titles:** +- 업적/기록 기반 칭호 부여 +- 로비에서 닉네임 옆에 표시 +- `store/titles.go` — 칭호 정의 및 부여 로직 + +**Codex System:** +- 조우한 몬스터/획득한 아이템/발견한 이벤트 기록 +- 도감 완성률 표시 +- `store/codex.go` — 도감 데이터 관리 +- `ui/codex_view.go` — 도감 화면 + +### 3-3. Difficulty System + +**Hard Mode:** +- 몬스터 스탯 1.5배, 상점 가격 2배, 회복량 절반 +- 언락 조건 충족 시 선택 가능 + +**Weekly Mutations:** +- 매주 바뀌는 특수 규칙 + - "스킬 사용 불가", "엘리트만 등장", "상점 없음" 등 +- `game/mutation.go` — 주간 변이 규칙 정의 및 적용 + +**Affected packages:** `game/`, `store/`, `ui/` + +## Phase 4: Operational Stability + +### 4-1. Logging & Monitoring + +- `log/slog` (Go 표준) 도입, JSON 형식 구조화 로깅 +- 이벤트: 접속, 게임 시작, 전투, 종료, 에러 +- `/admin` HTTP 엔드포인트 — 접속자 수, 활성 방, 오늘의 런 수, 평균 클리어 층수 +- 패닉 리커버리 미들웨어 — 세션 크래시 격리 + +**Affected packages:** `server/`, `web/`, `game/` + +### 4-2. Data Safety + +- 설정 가능한 주기로 DB 파일 자동 백업 (`./data/backup/`) +- 그레이스풀 셧다운: SIGTERM 시 진행 중인 세션 저장 후 종료 +- 재시작 시 미완료 세션 정리 + +**Affected packages:** `store/`, `main.go` + +### 4-3. Configuration Externalization + +- `config.yaml` — 서버 포트, 턴 타임아웃, 몬스터 스케일링, 상점 가격 배율 등 +- 밸런스 조정 시 재빌드 없이 설정 파일만 수정 +- `config/config.go` — YAML 파싱 및 기본값 관리 + +**Affected packages:** 전체 (상수 참조 부분) + +## Dependencies Between Phases + +``` +Phase 1 (Foundation) + └── Phase 2 (Combat/Dungeon) — UI 리팩토링 완료 후 새 화면 추가가 용이 + └── Phase 3 (Retention) — 전투/던전 콘텐츠 위에 메타 시스템 구축 + └── Phase 4 (Operations) — 전체 기능 완성 후 운영 도구 보강 +``` + +Phase 4의 로깅/설정 외부화는 독립적이므로, 필요 시 Phase 2~3과 병행 가능. + +## Out of Scope + +- 대규모(100+) 스케일링 (분산 서버, 로드밸런싱) +- 모바일/데스크톱 네이티브 클라이언트 +- 유료 결제/과금 시스템 +- PvP 대전 모드 +- 외부 DB 마이그레이션 (BoltDB 유지)