# Catacombs — Design Spec

SSH 멀티플레이어 협동 로그라이크 터미널 게임

## Overview

Go + Charm 스택 기반의 SSH 접속 멀티플레이어 협동 로그라이크. 2~4인 파티가 절차적 생성 던전을 탐험하며, 반실시간 턴제 전투와 클래스 기반 역할 분담으로 20층 던전을 클리어하는 게임.

- **접속:** SSH 메인 (`ssh catacombs.tolelom.xyz`), 웹 터미널 추후 추가
- **한 판:** 30~45분, 고정 20층
- **인원:** 2~4인 협동
- **시각:** 박스 드로잉 + ANSI 컬러

## Architecture

단일 Go 바이너리 모놀리스, Docker 컨테이너 하나로 배포.

```
┌─────────────────────────────────────────┐
│           Docker Container              │
│                                         │
│  ┌─────────────┐   ┌────────────────┐   │
│  │  Wish SSH   │──▶│  Bubble Tea    │   │
│  │  Server     │   │  TUI Engine    │   │
│  │  :2222      │   └───────┬────────┘   │
│  └─────────────┘           │            │
│                    ┌───────▼────────┐   │
│                    │  Game Engine   │   │
│                    │  - Lobby       │   │
│                    │  - Dungeon     │   │
│                    │  - Combat      │   │
│                    │  - Turn Timer  │   │
│                    └───────┬────────┘   │
│                    ┌───────▼────────┐   │
│                    │  BoltDB        │   │
│                    │  (랭킹, 통계)   │   │
│                    └────────────────┘   │
└─────────────────────────────────────────┘
```

### Dependencies

- `charmbracelet/wish` — SSH 서버
- `charmbracelet/bubbletea` — TUI 프레임워크
- `charmbracelet/lipgloss` — 스타일링 (색상, 박스 드로잉)
- `go.etcd.io/bbolt` — 경량 임베디드 DB (랭킹/통계)

### Multiplayer State Sync

각 게임 세션(파티)마다 하나의 `GameSession` goroutine이 중앙 게임 루프를 돌린다.

```
                     ┌──────────────┐
  Player A (SSH) ──▶ │              │ ──▶ tea.Msg to A
  Player B (SSH) ──▶ │ GameSession  │ ──▶ tea.Msg to B
  Player C (SSH) ──▶ │  goroutine   │ ──▶ tea.Msg to C
                     └──────────────┘
```

- 각 플레이어의 Bubble Tea 프로그램은 입력을 `GameSession`의 채널로 전송
- `GameSession`은 턴 타이머 관리, 입력 수집, 게임 상태 갱신을 담당
- 상태 갱신 후 각 플레이어의 `tea.Program.Send()`로 `StateUpdateMsg` 브로드캐스트
- 게임 상태는 `GameSession`이 단독 소유 (lock-free, 채널 기반)
- 플레이어의 TUI 모델은 수신한 `StateUpdateMsg`를 렌더링만 함 (읽기 전용 뷰)

### Deployment

- Docker 이미지 빌드, Mac Mini에서 `docker compose up`
- SSH 포트(2222)는 Docker에서 직접 호스트 포트로 노출 (Caddy 불필요 — SSH는 TCP라 L7 프록시 대상 아님)
- `ssh -p 2222 tolelom.xyz`
- 플레이어 식별: SSH 공개키 fingerprint 기반. 최초 접속 시 닉네임 설정, BoltDB에 저장

## Game Flow

```
SSH 접속 → 타이틀 → 로비 (방 생성/참가) → 클래스 선택 → 던전 탐험
  → 이벤트 (전투/상점/보물) → 다음 층 or 사망 → 결과 화면 → 랭킹
```

### Movement Model

- **파티 단위 이동**: 파티는 하나의 유닛으로 방-to-방(room-to-room) 이동
- 탐험 중에는 자유 이동 (턴 타이머 없음), 아무 파티원이 방향 선택 가능
- 전투방 진입 시 자동으로 턴 모드 전환
- 전투 중 이동은 턴 액션 소모 (이동 OR 공격, 둘 다는 불가)
- 전투 중 이동은 도주 판정 (50% 확률 성공, 실패 시 턴 낭비)

### Turn System (반실시간)

전투 중에만 활성화. 탐험 중에는 자유 이동.

1. 서버가 "행동 입력 대기" 상태 시작, 5초 타이머
2. 각 플레이어가 공격/스킬/아이템/도주/대기 중 선택
3. 타이머 종료 시 미입력 플레이어는 대기(방어 자세)
4. 모든 입력 수집 → 동시 실행 → 결과 렌더링
5. 적 턴 자동 실행 → 다음 턴

## Classes

| 클래스 | HP | ATK | DEF | 역할 | 특수 스킬 |
|--------|-----|-----|-----|------|-----------|
| 전사 | 120 | 12 | 8 | 탱커 | 도발 (적 어그로 2턴 집중) |
| 마법사 | 70 | 20 | 3 | 딜러 | 화염구 (전체 적 0.8x 데미지) |
| 힐러 | 90 | 8 | 5 | 서포터 | 치유 (아군 1명 HP 30 회복) |
| 도적 | 85 | 15 | 4 | 유틸 | 정찰 (다음 방 미리보기) |

## Combat System

- 파티 vs 몬스터 그룹 (1~5마리)
- 행동 선택: `[공격] [스킬] [아이템] [도주] [대기]`
- 타겟 지정: 방향키/번호로 적 선택
- 데미지 계산: `max(1, ATK × 스킬배율 - DEF) × 랜덤(0.85~1.15)`
- 협동 보너스: 같은 적을 2명 이상 단일 대상 공격 시, 2번째 이후 공격자에게 10% 추가 데미지 (DEF 감산 후 적용). AoE 스킬은 협동 보너스 트리거/대상에서 제외

### Monster Stats (기준)

| 몬스터 | HP | ATK | DEF | 등장 층 |
|--------|-----|-----|-----|---------|
| 슬라임 | 20 | 5 | 1 | 1~5 |
| 스켈레톤 | 35 | 10 | 4 | 3~10 |
| 오크 | 55 | 14 | 6 | 6~14 |
| 다크나이트 | 80 | 18 | 10 | 12~20 |
| 보스 (5층) | 150 | 15 | 8 | 5 |
| 보스 (10층) | 250 | 22 | 12 | 10 |
| 보스 (15층) | 400 | 30 | 16 | 15 |
| 최종 보스 | 600 | 40 | 20 | 20 |

일반 몬스터는 층마다 HP/ATK +15% 스케일링 (기준값 × 1.15^(현재층-등장시작층)).

### Monster AI

- 기본: 가장 가까운 플레이어 공격
- 도발 상태의 전사가 있으면 전사에게 집중 (2턴)
- HP 가장 낮은 아군이 있으면 30% 확률로 타겟 변경
- 보스: 매 3턴마다 전체 공격 (0.5x 데미지). 도발은 단일 대상 공격만 유도, AoE는 도발 무시

### Economy

| 항목 | 가격 |
|------|------|
| 몬스터 처치 골드 | 5~15 (층에 비례) |
| 소모품 (HP 포션) | 20 |
| 무기 (ATK+3~8) | 40~80 |
| 방어구 (DEF+2~5) | 30~60 |
| 유물 | 100~150 |

### Progression

- 레벨업 없음 (로그라이크)
- 성장은 아이템 의존 — 무기, 방어구, 소모품, 특수 유물
- 층마다 상점 등장 확률 30%, 골드로 아이템 구매
- 유물은 패시브 효과 (예: "적 처치 시 HP 5 회복")

## Dungeon Generation

- BSP(Binary Space Partitioning)로 층마다 맵 생성
- 한 층: 5~8개 방 + 복도로 연결
- 맵 크기: 약 60×30 타일

### Room Types

| 타입 | 확률 | 내용 |
|------|------|------|
| 일반 전투 | 45% | 몬스터 조우 |
| 보물방 | 15% | 아이템 획득 |
| 상점 | 10% | 골드로 아이템 구매 |
| 이벤트 | 15% | 랜덤 이벤트 (함정, 축복 등) |
| 빈 방 | 15% | 안전지대 |

보스방은 확률과 별개로 매 층 1개 고정 배치. 나머지 4~7개 방에 위 확률 적용.

### Field of View

- 전장의 안개(Fog of War) — 파티 주변만 보임
- 도적의 정찰 스킬로 시야 확장 가능
- 방문한 방은 희미하게 표시

## Rendering

```
┌─ Catacombs B3 ──────────── Party: 4/4 ─┐
│                                         │
│  ┌─────┐   ┌─────┐                     │
│  │.....│───│..$..│                     │
│  │..@..│   │.....│   ░░░░░             │
│  │..♦..│   └─────┘   ░░░░░             │
│  └──┬──┘              ░░░░░             │
│     │                                   │
│  ┌──┴──┐   ┌─────┐                     │
│  │..D..│───│.....│                     │
│  │.....│   │..?..│                     │
│  └─────┘   └─────┘                     │
│                                         │
├─────────────────────────────────────────┤
│ HP ██████░░ 65/100  │ 골드: 120        │
│ [1]이동 [2]공격 [3]스킬 [4]아이템      │
│ ⏱ 4.2s                                 │
└─────────────────────────────────────────┘
```

`@` 플레이어 `♦` 아군 `D` 몬스터 `$` 아이템 `?` 이벤트 `░` 미탐사

최소 터미널 크기: 80×24. UI는 고정 너비 (80컬럼). 터미널이 작으면 접속 시 경고 표시.

## Difficulty & Balance

### Floor Scaling

- 몬스터 HP/ATK가 층마다 ~15% 증가
- 5층, 10층, 15층, 20층에 보스 등장
- 보스 처치 시 유물 확정 드랍

### Difficulty Curve

| 구간 | 층 | 특징 |
|------|-----|------|
| 초반 | 1~5 | 튜토리얼 느낌, 쉬운 적, 기본 아이템 수급 |
| 중반 | 6~12 | 역할 분담 중요해짐, 자원 관리 시작 |
| 후반 | 13~18 | 강적 등장, 유물 시너지로 승부 |
| 최종 | 19~20 | 최종 보스, 파티 연계 필수 |

### Death

- 개인 사망 → 해당 층에서는 관전 모드 (맵/채팅 가능, 행동 불가). 다음 층 시작 시 HP 30%로 부활
- 전멸 → 게임 오버, 결과 화면
- 세이브 없음 (로그라이크)

### Gold & Communication

- 골드는 개인 소유. 몬스터 처치 시 파티원 전원에게 동일 골드 지급
- 간이 채팅: 턴 입력 중 `/` 키로 한 줄 메시지 전송 (파티 전체에 표시)

### Disconnect Handling

- 접속 끊김 시 해당 플레이어는 자동 대기 모드 (매 턴 방어 자세)
- 60초 내 재접속 시 SSH 공개키로 식별하여 세션 복귀
- 60초 초과 시 파티에서 제거, 남은 인원으로 계속 진행

### Lobby

- 방 목록 표시 (방 이름, 현재 인원, 상태)
- 방 생성 시 4자리 코드 부여 (예: `ABCD`)
- 코드 입력으로 참가 또는 목록에서 선택
- 최소 1인으로 시작 가능. 솔로 시 몬스터 HP 50%로 감소 (의도적 하드모드는 아님)
- 동시 게임 세션 제한 없음 (서버 리소스 한도 내)

## Project Structure

```
catacombs/
├── main.go              # 진입점, SSH 서버 시작
├── server/
│   └── ssh.go           # Wish SSH 설정, 세션 관리
├── game/
│   ├── lobby.go         # 로비, 방 생성/참가
│   ├── session.go       # 게임 세션 (파티 상태 관리)
│   ├── turn.go          # 턴 타이머, 입력 수집, 실행
│   └── event.go         # 이벤트 처리 (전투, 상점, 보물 등)
├── dungeon/
│   ├── generator.go     # BSP 던전 생성
│   ├── room.go          # 방 타입, 내용물 배치
│   └── fov.go           # 시야 계산
├── entity/
│   ├── player.go        # 플레이어, 클래스, 인벤토리
│   ├── monster.go       # 몬스터 정의, AI
│   └── item.go          # 아이템, 유물
├── combat/
│   └── combat.go        # 데미지 계산, 전투 로직
├── ui/
│   ├── model.go         # Bubble Tea 메인 모델
│   ├── title.go         # 타이틀 화면
│   ├── lobby_view.go    # 로비 뷰
│   ├── game_view.go     # 던전/전투 뷰
│   └── result_view.go   # 결과 화면
├── store/
│   └── db.go            # BoltDB 랭킹/통계
├── Dockerfile
└── docker-compose.yml
```