docs: 온라인 보드게임 사이트 계획서 (공통 14편 + 게임 26종)

- 개요, 조사(BGA·한국 인기 보드게임·UI/UX), 아키텍처, 실시간 프로토콜, 안정성·보안, 계정, 로비·방, UI/UX, 데이터 모델, 게임 엔진, 테스트, 배포·운영, 로드맵(M0~M9), 사용자 결정 항목 - 게임별 규칙·엔진 설계·UI·테스트 체크리스트 26종 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-04 04:18:29 +09:00
parent b4a3c51201
commit f4d63e1544
43 changed files with 8948 additions and 0 deletions
--- a/docs/games/gostop.md
+++ b/docs/games/gostop.md
@@ -0,0 +1,424 @@
+# 고스톱 / 맞고 (`gostop`)
+
+> 마일스톤: M5 · 인원: 최소 2 ~ 최대 5명 (2인 맞고, 3인 고스톱, 4~5인은 3명만 치고 나머지는 광팔기) · 예상 시간: 1판 약 3분, 기본 10판 약 30분 · 난이도: 보통
+
+## 1. 개요
+- 화투 48장으로 바닥 패와 같은 월(月)을 맞춰 가져오고, 가져온 패로 점수 족보(광·열끗·띠·피)를 만들어 먼저 기준 점수에 이르면 "고"(계속) 또는 "스톱"(끝내기)을 고르는 한국의 대표 화투 게임이다. 명절·가족 모임에서 남녀노소 모두 알고, 2인용인 맞고는 온라인에서 가장 많이 하는 형태다.
+- 인원 근거: 고스톱은 원래 3인 게임이다. 2인은 맞고로 정착한 변형이다. 4~5인은 전통적으로 3명만 치고 나머지가 "광을 파는" 방식이다. 그래서 최소 2명, 최대 5명이다.
+  - 2명 → 맞고 모드, 3명 → 고스톱 모드, 4~5명 → 고스톱 + 광팔기.
+- **점수는 방 안에서만 쓰는 가상 점수**다. 판이 끝나면 방 점수판에 더하고 빼기만 하며, 돈·재화·환전·저장 포인트와 전혀 연결하지 않는다(12장 참조).
+- 지역마다 규칙이 크게 다르다. 이 문서는 나무위키·주요 온라인 맞고에서 흔히 쓰는 규칙을 기본값으로 정하고, 나머지는 옵션으로 둔다.
+
+## 2. 모드와 옵션
+| 옵션 키 | 설명 | 선택지 | 기본값 |
+|---|---|---|---|
+| `rounds` | 세트 판 수(나가리 판도 1판으로 셈) | 1 / 3 / 5 / 10 / 20 | 10 |
+| `bonusCards` | 보너스패 구성 | `none` / `2+1`(2피 2장 + 3피 1장) / `3+1`(2피 3장 + 3피 1장) | 맞고 `2+1` / 고스톱 `none` |
+| `winScore` | 고·스톱 기준 점수 | 정수 | 맞고 7 / 고스톱 3 |
+| `piBakLimit` | 피박이 되는 패자의 피 장수(피 값) 상한 | 정수 | 맞고 7 / 고스톱 5 |
+| `piBakZeroExempt` | 패자 피 0장이면 피박 면제 | true / false | true |
+| `gwangBak` | 광박 | true / false | true |
+| `meongTta` | 멍따: 승자 열끗 7장 이상이면 x2 | true / false | true |
+| `meongBak` | 멍박: 멍따 승리 시 패자 열끗 0장이면 x2 | true / false | false |
+| `goBak` | 고박(맞고 x2 / 3인 독박) | true / false | true |
+| `biGwangThree` | 비광 포함 3광 점수 | `2`(2점) / `0`(불인정) | `2` |
+| `ogwangPoints` | 5광 점수 | 15 / 30 | 15 |
+| `gukjinMode` | 9월 열끗(국진) 처리 | `auto`(점수에 유리하게 자동) / `ask`(판 끝에 본인 선택) / `yeolOnly`(열끗 고정) | `auto` |
+| `shake` | 흔들기(x2) | true / false | true |
+| `bomb` | 폭탄(x2, 피 1장씩) | true / false | true |
+| `chongtong` | 총통 처리 | `win`(즉시 승리) / `redeal`(다시 돌림) / `off`(그냥 진행) | `win` |
+| `chongtongPoints` | 총통 승리 점수 | 정수 | 맞고 10 / 고스톱 5 |
+| `ppeokBonus` | 첫뻑·연뻑 즉시 보너스, 삼뻑 즉시 승리 | true / false | true |
+| `jaPpeokSteal` | 자뻑 때 상대마다 뺏는 피 장수 | 1 / 2 | 2 |
+| `lastTurnSweepBonus` | 마지막 턴의 쓸·쪽 피 뺏기 인정 | true / false | false |
+| `naturalThreeSteal` | 처음 바닥에 깔린 같은 월 3장을 먹을 때 피 뺏기 | true / false | true |
+| `nagariMultiplier` | 나가리 다음 판 배수(연속이면 누적) | `x2` / `none` | `x2` |
+| `nagariMaxMultiplier` | 연속 나가리 배수 상한 | 2 / 4 / 8 | 8 |
+| `gwangPalgi` | 4~5인 광팔기 허용 | true / false | true |
+| `gwangPrice` | 광팔기 1장당 값 | 1 / 2 / 3 | 1 |
+| `gwangPayer` | 광값 내는 사람 | `nonDealerPlayers`(선 제외 참가자 각자) / `allPlayers`(참가자 3명 각자) | `nonDealerPlayers` |
+| `gwangSellCards` | 팔 수 있는 패 | `gwang`(광만) / `gwangPlus`(광 + 쌍피·국진·보너스) | `gwang` |
+| `turnSeconds` | 1턴 제한 시간 | 5~60 | 15 |
+| `decisionSeconds` | 고/스톱·선택 제한 시간 | 5~30 | 10 |
+| `hints` | 먹을 수 있는 패·족보 진행 힌트 | true / false | true |
+
+모드(맞고/고스톱)는 `setup`의 인원 수로 정한다. 2명이면 맞고 기본값, 3~5명이면 고스톱 기본값을 쓴다.
+
+## 3. 구성물
+
+### 3.1 화투 48장 (12개월 x 4장)
+| 월 | 이름 | 카드 ID | 구성 |
+|---|---|---|---|
+| 1 | 송학(소나무) | 0 / 1 / 2 / 3 | 광(학) / 홍단 / 피 / 피 |
+| 2 | 매조(매화) | 4 / 5 / 6 / 7 | 열끗(꾀꼬리, 고도리) / 홍단 / 피 / 피 |
+| 3 | 벚꽃 | 8 / 9 / 10 / 11 | 광(벚꽃) / 홍단 / 피 / 피 |
+| 4 | 흑싸리 | 12 / 13 / 14 / 15 | 열끗(두견새, 고도리) / 초단 / 피 / 피 |
+| 5 | 난초 | 16 / 17 / 18 / 19 | 열끗(다리) / 초단 / 피 / 피 |
+| 6 | 모란 | 20 / 21 / 22 / 23 | 열끗(나비) / 청단 / 피 / 피 |
+| 7 | 홍싸리 | 24 / 25 / 26 / 27 | 열끗(멧돼지) / 초단 / 피 / 피 |
+| 8 | 공산(억새) | 28 / 29 / 30 / 31 | 광(보름달) / 열끗(기러기, 고도리) / 피 / 피 |
+| 9 | 국진(국화) | 32 / 33 / 34 / 35 | 열끗(술잔, 국진: 쌍피로도 쓸 수 있음) / 청단 / 피 / 피 |
+| 10 | 단풍 | 36 / 37 / 38 / 39 | 열끗(사슴) / 청단 / 피 / 피 |
+| 11 | 오동(똥) | 40 / 41 / 42 / 43 | 광(봉황) / 쌍피 / 피 / 피 |
+| 12 | 비 | 44 / 45 / 46 / 47 | 광(비광) / 열끗(제비) / 띠(비띠, 단 아님) / 쌍피 |
+
+- 합계: 광 5장, 열끗 9장, 띠 10장, 피 24장(그중 쌍피 2장: 41, 47).
+- 피 값: 일반 피 1, 쌍피 2. 국진을 쌍피로 쓰면 2.
+- 보너스패(옵션): ID 48·49(·50) = 2피(피 값 2), 마지막 ID = 3피(피 값 3). 월이 없다.
+
+### 3.2 용어
+- 바닥: 가운데 앞면으로 깔린 패. 더미: 뒤집어 쌓은 남은 패. 먹은 패: 각자 앞에 종류별로 모아 둔 패(모두 공개).
+- 선: 그 판에 먼저 시작하는 사람. 진행 방향은 반시계(선 → 선의 오른쪽 사람 → …).
+
+## 4. 준비(셋업)
+1. 첫 판의 선: RNG로 정한다(연출로 "패 뽑기"를 보여 줄 수 있음). 다음 판부터는 직전 판 승자가 선이다. 나가리면 선을 유지한다.
+2. 패 섞기: 48장(+보너스)을 RNG로 섞는다.
+3. 패 돌리기(서버는 배열에서 순서대로 나눠 주고, 화면에서만 전통 방식으로 연출):
+   - 맞고(2인): 손패 각 10장, 바닥 8장, 더미 나머지(보너스 없으면 20장). 연출: 바닥 4 → 상대 5 → 선 5 → 바닥 4 → 상대 5 → 선 5.
+   - 고스톱(3인): 손패 각 7장, 바닥 6장, 더미 21장. 연출: 바닥 3 → 각 4 → 바닥 3 → 각 3.
+   - 4~5인(광팔기): 모두에게 7장씩, 바닥 6장. 그 뒤 광팔기 단계(5.8)를 거쳐 판 사람들의 손패를 더미와 함께 RNG로 다시 섞는다. 더미는 항상 21장(+보너스)이 된다.
+4. 바닥 정리:
+   - 바닥에 보너스패가 있으면 선이 먹은 패로 가져가고, 더미 맨 위에서 1장을 바닥에 채운다(또 보너스면 반복).
+   - 바닥에 같은 월 4장이 깔리면 **다시 섞어서 돌린다**(선 유지, 나가리 아님, 판 수 증가 없음).
+   - 바닥에 같은 월 3장이면 한 무더기로 쌓아 둔다(자연 뻑). 나머지 1장을 가진 사람이 4장을 모두 가져간다.
+5. 총통 확인(5.7).
+6. 선부터 첫 턴을 시작한다.
+
+## 5. 진행 규칙
+
+### 5.1 한 턴의 흐름
+1. **손패 1장 내기**(또는 폭탄·폭탄 빈패·보너스패, 5.4~5.6)
+2. **더미 맨 위 1장 뒤집기**
+3. **먹기 판정**(5.2) → 피 뺏기 처리(5.3)
+4. **점수 확인**: 지금 점수가 `winScore` 이상이고, 이번 판에 고를 한 적이 없거나 마지막 고를 부를 때보다 점수가 높으면 **고/스톱 선택**(5.9)을 한다.
+5. 다음 사람 턴. 모두의 손패가 0장이고 더미가 비면 판이 끝난다(5.10).
+
+### 5.2 먹기 판정 (정확한 알고리즘)
+손에서 낸 패를 H(월 m1), 뒤집은 패를 F(월 m2)라 하고, H를 내기 직전 바닥에 있던 m1월 패 수를 k라 한다.
+
+**H 처리**
+| k | 결과 |
+|---|---|
+| 0 | H를 바닥에 놓는다. |
+| 1 | H와 그 패를 짝으로 잡아 둔다(임시). |
+| 2 | 둘 중 하나를 골라 짝으로 잡는다. 두 장의 종류·피 값이 같으면 자동 선택. 고르는 것은 `play` 액션의 `target`으로 함께 보낸다. |
+| 3 | 쌓인 3장(뻑 또는 자연 뻑)과 H, 4장을 모두 가져온다. 뻑 먹기 피 뺏기(5.3). |
+
+**F 처리** (F가 보너스패면 내 먹은 패에 넣고 1장 더 뒤집어 그 패를 F로 다시 처리)
+- m2 = m1인 경우(같은 월이 연달아 나옴):
+  - k = 0 → **쪽**: H와 F를 가져온다. 상대마다 피 1장.
+  - k = 1 → **뻑**: H, 바닥 1장, F 3장이 바닥에 한 무더기로 남는다. 아무것도 못 먹는다. 무더기에 "뻑 낸 사람 = 나"를 기록한다.
+  - k = 2 → **따닥**: 바닥 2장 + H + F, 4장을 모두 가져온다. 상대마다 피 1장.
+- m2 ≠ m1인 경우: H 처리 결과를 확정하고(k=1·2면 짝을 가져옴), F를 바닥의 m2월 패 수 j로 처리한다.
+  - j = 0 → F를 바닥에 놓는다.
+  - j = 1 → F와 그 패를 가져온다.
+  - j = 2 → 둘 중 하나를 고른다(종류가 같으면 자동). 이때만 별도 선택 단계(`chooseFlip`)가 생긴다.
+  - j = 3 → 4장을 모두 가져온다. 뻑 먹기 피 뺏기.
+- **쓸(싹쓸이)**: 이번 턴 처리가 끝난 뒤 바닥이 비면 상대마다 피 1장.
+- `lastTurnSweepBonus=false`면 그 판의 마지막 턴(더미 마지막 장을 뒤집는 턴)에서 쓸·쪽의 피 뺏기를 하지 않는다. 따닥·뻑 먹기는 그대로 인정한다.
+
+### 5.3 피 뺏기
+- 쪽, 따닥, 쓸, 남의 뻑 먹기, 자연 뻑 먹기(`naturalThreeSteal`), 폭탄: 상대마다 피 1장.
+- 자뻑(내가 만든 뻑 무더기를 내가 먹음): 상대마다 `jaPpeokSteal`장(기본 2).
+- 한 턴에 여러 개가 겹치면 모두 더한다. 예: 따닥과 쓸이 함께 나오면 상대마다 2장.
+- 어떤 피를 주나: 상대가 가진 피 중 **값이 가장 낮은 것부터** 준다(일반 피 → 쌍피·2피 → 3피). 같은 값이면 ID가 작은 것부터. 피가 없으면 주지 않는다(빚 없음). 거스름은 없다.
+- 국진이 열끗 자리에 있는 동안은 피로 보지 않으므로 뺏기지 않는다(`gukjinMode=auto/ask`일 때 판 중에는 열끗으로 둔다).
+
+### 5.4 흔들기 (`shake`)
+- 손에 같은 월 3장이 있고 바닥에 그 월이 0장일 때, 그중 1장을 내면서 "흔들기"를 선언할 수 있다.
+- 3장을 모두에게 공개한다. 남은 2장은 손에 있지만 공개 상태로 표시한다.
+- 이 판을 내가 이기면 흔들기 1번마다 x2. 2번 흔들면 x4.
+- 선언하지 않고 그냥 내도 된다. 한 월에 1번만 할 수 있다.
+
+### 5.5 폭탄 (`bomb`)
+- 손에 같은 월 3장이 있고 바닥에 그 월이 1장 있을 때, 3장을 한꺼번에 내서 바닥 1장과 함께 4장을 모두 가져온다. 상대마다 피 1장. 흔들기와 같은 x2 배수를 1번 받는다.
+- 그 뒤 손에 **폭탄 빈패 2장**을 받는다. 다음 턴부터 빈패를 내면 손패를 쓰지 않고 더미만 뒤집는다. 빈패는 아무 때나 쓸 수 있고 판이 끝날 때 남아 있으면 그냥 사라진다.
+- 폭탄 턴에도 더미를 뒤집어 F 처리를 한다(F는 m1월일 수 없음).
+- 바닥 1장이 뻑 무더기일 수는 없다(4장 한계).
+
+### 5.6 보너스패 (`bonusCards`)
+- 손에 있는 보너스패: 내 턴에 언제든 낼 수 있다. 바로 내 먹은 패(피 영역)로 가고, 더미 맨 위 1장을 손에 가져온 뒤 **같은 턴에 다시 손패 1장을 낸다**(턴 소모 없음).
+- 더미에서 뒤집힌 보너스패: 내가 먹고 1장을 더 뒤집는다.
+- 바닥에 깔린 보너스패: 셋업 단계에서 선이 가져간다.
+- 보너스패 1장은 정확히 더미 1장을 더 쓰게 하므로 손패와 더미 장수는 항상 맞아떨어진다.
+
+### 5.7 총통 (`chongtong`)
+- 패를 돌린 직후(광팔기 뒤) 손에 같은 월 4장을 가진 사람은 총통을 선언할 수 있다.
+- `win`: 선언하면 즉시 판이 끝나고 `chongtongPoints`점(기본 맞고 10, 고스톱 5)을 상대마다 받는다. 박·흔들기 배수는 없고 나가리 배수만 적용한다. 선언하지 않고 진행해도 된다. 진행하면 그 월로 흔들기·폭탄을 할 수 있다.
+- 여러 명이 총통이면 선부터 진행 순서로 먼저인 사람만 선언할 수 있다.
+- `redeal`: 다시 섞어 돌린다(선 유지). `off`: 아무 일도 없다.
+
+### 5.8 광팔기 (4~5인, `gwangPalgi`)
+- 모두 7장씩 받은 뒤 **선의 다음 사람부터 진행 순서대로** "치기" 또는 "죽기(광 팔기)"를 고른다. 선은 반드시 친다.
+- 치기 3명(선 포함)이 정해지면 나머지는 자동으로 죽는다. 죽는 사람이 (인원 - 3)명이 되면 나머지는 자동으로 친다.
+- 죽는 사람은 손패 중 팔 수 있는 패(`gwangSellCards`, 기본 광만)를 공개하고 그 장수 x `gwangPrice`점을 광값으로 받는다. 내는 사람은 `gwangPayer`에 따른다(기본: 선을 뺀 참가자 2명이 각자). 광이 없으면 그냥 빠진다.
+- 죽은 사람의 손패는 공개한 패까지 포함해 모두 더미와 함께 RNG로 섞는다.
+- 광값은 판 결과와 상관없이(나가리여도) 그 시점에 바로 정산한다.
+
+### 5.9 고 / 스톱
+- 내 턴 처리가 끝났을 때 내 점수(6.1)가 `winScore` 이상이면 선택한다. 이미 고를 한 적이 있으면 **마지막 고 때 점수보다 커야** 다시 선택할 수 있다(같거나 작으면 그냥 다음 턴).
+- **스톱**: 판이 끝나고 내가 이긴다(6장 정산).
+- **고**: 고 횟수 +1, 판을 계속한다. 이때 점수를 "마지막 고 점수"로 기록한다.
+- 내 손패가 0장이 되는 마지막 턴(빈패만 남은 경우 포함)에 조건이 되면 고를 할 수 없고 **자동 스톱**이다.
+- 3인에서 다른 사람이 고를 부른 뒤에도 각자 자기 턴에 조건이 되면 스톱할 수 있다(먼저 스톱한 사람이 승자).
+
+### 5.10 판 끝
+- 누군가 스톱 → 그 사람 승리.
+- 총통 선언, 삼뻑 → 즉시 승리.
+- 손패와 더미를 모두 쓴 마지막 턴까지 아무도 스톱하지 않음(아무도 기준 점수를 못 넘었거나, 고를 부른 사람이 그 뒤 점수를 더 내지 못함) → **나가리**. 점수 이동 없음, 선 유지, 다음 판 배수 x2(연속이면 누적, 상한 `nagariMaxMultiplier`).
+
+### 5.11 첫뻑·연뻑·삼뻑 (`ppeokBonus`)
+- 첫뻑: 자기 첫 턴에 뻑을 내면 즉시 상대마다 3점을 받는다.
+- 연뻑: 자기 첫 턴과 둘째 턴에 연달아 뻑을 내면 둘째 턴에 상대마다 6점을 더 받는다(누적 9점).
+- 삼뻑: 한 판에서 같은 사람이 뻑을 3번 내면 판이 즉시 끝나고 그 사람이 이긴다. 점수 = `chongtongPoints`와 같은 값(박·흔들기 배수 없음, 나가리 배수 적용). 첫뻑·연뻑으로 받은 점수는 돌려주지 않는다.
+- 첫뻑·연뻑 보너스는 판 승패와 상관없이 바로 방 점수에 반영한다. 나가리가 되어도 돌려주지 않는다.
+
+## 6. 승패와 점수 계산
+
+### 6.1 기본 점수(족보 합)
+| 족보 | 조건 | 점수 |
+|---|---|---|
+| 오광 | 광 5장 | 15 (`ogwangPoints`) |
+| 사광 | 광 4장(비광 포함 여부 무관) | 4 |
+| 삼광 | 비광 없이 광 3장 | 3 |
+| 비삼광 | 비광 포함 광 3장 | 2 (`biGwangThree`) |
+| 열끗 | 5장 1점, 이후 1장마다 +1 | 장수 - 4 |
+| 고도리 | 2·4·8월 열끗(새 3마리) | +5 |
+| 띠 | 5장 1점, 이후 1장마다 +1(비띠 포함) | 장수 - 4 |
+| 홍단 | 1·2·3월 띠 | +3 |
+| 청단 | 6·9·10월 띠 | +3 |
+| 초단 | 4·5·7월 띠 | +3 |
+| 피 | 피 값 합 10에 1점, 이후 1마다 +1 | 피 값 - 9 |
+
+- 고도리 카드는 열끗 장수에도 들어가고, 단 카드는 띠 장수에도 들어간다(중복 인정).
+- 피 값: 일반 피 1, 쌍피 2, 2피 보너스 2, 3피 보너스 3, 국진(쌍피로 쓸 때) 2.
+- 국진(`gukjinMode=auto`): 점수를 계산할 때마다 열끗 1장으로 셀 때와 피 값 2로 셀 때를 모두 계산해 **주인에게 유리한 쪽**을 쓴다. 승자는 최종 받을 점수가 큰 쪽, 패자는 낼 점수가 작은 쪽(피박·멍박 회피 포함)이다. 기준 점수 도달 판정에도 큰 쪽을 쓴다. `ask`면 판 끝 정산 직전에 본인이 고르고, 시간이 지나면 `auto` 규칙으로 정한다.
+
+### 6.2 최종 점수 공식
+```
+T = (기본 점수 + 고 횟수) x 고 배수 x 2^(흔들기 횟수 + 폭탄 횟수) x 멍따 배수 x 나가리 배수
+  고 배수 = 1 (고 0~2회), 2^(고 횟수 - 2) (고 3회 이상: 3고 x2, 4고 x4, 5고 x8 …)
+  멍따 배수 = 2 (meongTta이고 승자 열끗 7장 이상), 아니면 1
+  나가리 배수 = 2^(직전 연속 나가리 수), 상한 nagariMaxMultiplier
+
+패자 L이 낼 점수 = T x 피박(2) x 광박(2) x 멍박(2)   (해당하는 것만 곱함)
+```
+- **피박**: 승자의 피 점수가 1점 이상(피 값 10 이상)이고, 패자의 피 값이 1 ~ `piBakLimit`(맞고 7, 고스톱 5). 피 0이면 `piBakZeroExempt`에 따라 면제(기본 면제).
+- **광박**: 승자가 광 족보 점수(삼광·비삼광·사광·오광)를 받았고 패자 광이 0장.
+- **멍박**(옵션): 승자가 멍따이고 패자 열끗이 0장.
+- **고박**(`goBak`): 이번 판에 고를 불렀다가 다른 사람이 이긴 패자.
+  - 맞고: 그 패자의 낼 점수 x2.
+  - 3인: **독박** — 고를 부른 패자가 자기 몫과 다른 패자 몫을 모두 낸다. 다른 패자는 0점. 고를 부른 패자가 2명이면 마지막에 고를 부른 사람이 독박이다.
+- 박이 여러 개면 모두 곱한다. 3인에서는 패자마다 박 여부를 따로 판정한다.
+- 판 정산: 승자 방 점수 += 패자들이 낸 합, 각 패자 -= 자기가 낸 점수. 총통·삼뻑 승리는 `점수 x 나가리 배수`를 패자마다 받는다.
+
+### 6.3 계산 예시
+1. 맞고 기본 스톱: 광 1·3·8월(삼광 3점) + 피 값 12(3점) + 띠 5장(1점) = 7점, 고 없이 스톱. 상대 광 0장, 피 6장 → 피박·광박. 7 x 2 x 2 = **28점**.
+2. 비삼광: 광 1·3·12월 = 2점(비삼광). 광 4장(1·3·8·12) = 4점.
+3. 고 배수: 맞고, 기본 9점에서 3고 후 스톱, 흔들기 1회. (9 + 3) x 2 x 2 = **48점**. 상대 피박이면 96점.
+4. 고 점수 비교: 맞고 7점에서 1고. 다음 턴 피를 뺏겨 6점이 됐다가 다시 7점 → 7은 마지막 고 점수(7)보다 크지 않으므로 선택 없음. 8점이 되면 선택. 그때 스톱하면 (8 + 1) = **9점**.
+5. 3인 독박: A가 3점에서 1고. B가 홍단 3 + 띠 5장 1 + 피 값 11(2) = 6점으로 스톱(고 없음). C 피 4장(피박), A 피 8장. C 몫 6 x 2 = 12, A 몫 6. A 독박 → A가 18점, C 0점, B +18.
+6. 국진 자동: 승자 열끗 5장(국진 포함)·피 값 9 → 국진을 열끗으로 보면 열끗 1 + 피 0 = 1점, 쌍피로 보면 열끗 0(4장) + 피 값 11 → 2점. 쌍피로 계산.
+7. 나가리 다음 판: 직전 판 나가리, 이번 판 7점 스톱, 박 없음 → 7 x 2 = **14점**. 2판 연속 나가리 뒤면 x4.
+8. 멍따: 열끗 7장(고도리 포함) → 열끗 3점 + 고도리 5점 = 8점, 멍따 x2 → 16점.
+
+### 6.4 세트 결과와 동점
+- `rounds` 판이 끝나면 방 점수 합계(판 점수 + 광값 + 첫뻑·연뻑 보너스)로 순위를 매긴다.
+- 동점은 같은 순위로 처리한다(공동 순위). 다음 순위는 건너뛴다(1, 1, 3).
+- 판 점수는 제로섬이다(모든 플레이어 점수 합 = 0).
+
+## 7. 지역 룰 / 하우스 룰 (옵션으로 켜고 끄기)
+- 피박 기준 장수, 피 0장 면제: `piBakLimit`, `piBakZeroExempt`
+- 비광 3광 2점/불인정, 오광 15/30: `biGwangThree`, `ogwangPoints`
+- 멍따·멍박·고박·광박: 각 옵션
+- 국진 처리 방식: `gukjinMode`
+- 총통 즉시 승리 / 다시 돌림 / 무시, 총통 점수
+- 첫뻑·연뻑·삼뻑 보너스: `ppeokBonus`
+- 자뻑 피 1장/2장: `jaPpeokSteal`
+- 마지막 턴 쓸·쪽 인정: `lastTurnSweepBonus`
+- 나가리 배수: `nagariMultiplier`, `nagariMaxMultiplier`
+- 보너스패 구성: `bonusCards`
+- 광팔기 가격·지불자·팔 수 있는 패: `gwangPrice`, `gwangPayer`, `gwangSellCards`
+- 지원하지 않는 변형(향후 후보): 2장 폭탄, 흔들기 후 폭탄 추가 배수, 9월 열끗 판 중 이동, "고 선언 후 스톱 시 상대 독박 면제" 같은 동네 규칙, 섯다식 땡값. 규칙 충돌이 커서 1차 범위에서 뺀다.
+
+## 8. 엔진 설계
+
+### 8.1 상태(State)
+```ts
+type CardId = number;                  // 0..47 화투, 48.. 보너스
+type Month = 1|2|3|4|5|6|7|8|9|10|11|12;
+interface CardInfo {                    // 상수 테이블(3.1)
+  id: CardId; month: Month | null;
+  kind: 'gwang' | 'yeol' | 'tti' | 'pi';
+  piValue: 0 | 1 | 2 | 3;
+  bi?: true; godori?: true; dan?: 'hong' | 'cheong' | 'cho'; gukjin?: true; bonus?: true;
+}
+
+interface GostopOptions { /* 2장 표의 키 전부 */ }
+
+interface FloorGroup { cards: CardId[]; ppeokBy: number | null; natural: boolean } // cards 0..3장
+
+interface RoundState {
+  participants: number[];              // 이번 판 치는 player index, 진행 순서(선부터)
+  sellers: Array<{ idx: number; shown: CardId[]; paid: number }>;
+  hands: CardId[][];                   // player index별(판 밖 사람은 [])
+  bombDummies: number[];
+  revealed: CardId[][];                // 흔들어서 공개된 손패
+  deck: CardId[];                      // 0번이 맨 위
+  floor: Partial<Record<Month, FloorGroup>>;
+  captured: CardId[][];
+  gukjinChoice: (null | 'yeol' | 'pi')[];
+  goCount: number[]; lastGoScore: number[]; goOrder: number[]; // 고 부른 순서(독박 판정)
+  shakes: number[]; bombs: number[];
+  ppeokCount: number[]; ppeokOnTurn: boolean[][]; // [player][턴번호]
+  turnsTaken: number[];
+  turn: number;                        // player index
+  step: 'gwangSelling' | 'chongtong' | 'play' | 'chooseFlip' | 'goStop' | 'gukjin' | 'done';
+  pendingTurn: null | {                // chooseFlip 대기 중 보관
+    played: CardId[]; flipped: CardId; heldPair: CardId[]; stealCount: number;
+  };
+  sellOrder: number[]; sellCursor: number;
+  multiplierNagari: number;            // 이 판에 적용되는 나가리 배수
+  lastTurn: boolean;
+  outcome: null | RoundOutcome;
+}
+
+interface RoundOutcome {
+  type: 'stop' | 'chongtong' | 'samppeok' | 'nagari';
+  winner: number | null;
+  baseScore: number;                   // 족보 합
+  breakdown: Array<{ name: string; points: number }>;
+  multipliers: Array<{ name: string; factor: number }>;
+  payments: Array<{ from: number; amount: number; baks: Array<'pi' | 'gwang' | 'meong' | 'go'> }>;
+}
+
+interface GostopState {
+  options: GostopOptions;
+  mode: 'matgo' | 'gostop';
+  players: PlayerId[];                 // 착석 순서 = 진행 순서
+  rng: RngState;
+  totals: number[];                    // 방 점수(세트 누적)
+  roundNo: number;                     // 1부터
+  dealer: number;
+  nagariStreak: number;
+  round: RoundState | null;
+  phase: 'playing' | 'roundResult' | 'finished';
+  ready: number[];
+  autoPilot: boolean[];
+  timeoutStreak: number[];
+  deadline: number | null;
+  log: RoundOutcome[];
+}
+```
+
+### 8.2 액션
+| type | payload | 누가 / 언제 | 검증 조건 |
+|---|---|---|---|
+| `sell` | `{ sell: boolean }` | 광팔기 단계, `sellOrder[sellCursor]` | 결정 차례인 사람만. 선은 sell=true 불가. 치기 3명 또는 죽기 (인원-3)명이 이미 채워진 뒤의 사람은 자동 결정되므로 액션을 받지 않음 |
+| `chongtong` | `{ declare: boolean }` | `step='chongtong'`, 총통 보유자 중 우선순위 1명 | 손에 같은 월 4장 |
+| `play` | `{ card: CardId \| 'dummy'; target?: CardId; shake?: boolean; bomb?: boolean }` | `step='play'`, 차례인 사람 | card가 손에 있음(dummy면 빈패 ≥1). 바닥 같은 월 2장이고 종류가 다르면 target 필수이며 그 2장 중 하나. `shake`: 같은 월 3장 보유 + 바닥 0장 + 그 월 미흔듦. `bomb`: 같은 월 3장 보유 + 바닥 1장(이때 card는 그중 아무 1장, 3장 모두 냄). 보너스패면 target/shake/bomb 없음 |
+| `chooseFlip` | `{ target: CardId }` | `step='chooseFlip'`, 차례인 사람 | target이 바닥의 F 월 2장 중 하나 |
+| `goStop` | `{ decision: 'go' \| 'stop' }` | `step='goStop'`, 차례인 사람 | 마지막 턴이면 go 불가 |
+| `gukjin` | `{ as: 'yeol' \| 'pi' }` | `gukjinMode='ask'`, 판 끝 정산 직전, 국진 보유자 | 국진 보유 |
+| `ready` | `{}` | `phase='roundResult'`, 모든 플레이어 | 아직 ready 안 함 |
+
+- `validate` 실패 사유 예: "지금은 당신 차례가 아닙니다", "손에 없는 패입니다", "가져올 패를 골라 주세요", "흔들기는 같은 월 3장을 가지고 있고 바닥에 그 월이 없을 때만 할 수 있습니다", "폭탄은 같은 월 3장과 바닥 1장이 있어야 합니다", "선은 광을 팔 수 없습니다", "마지막 턴에는 고를 할 수 없습니다".
+- `apply` 이벤트: `dealt`, `bonusTaken`, `played`, `flipped`, `captured`, `ppeok`, `jjok`, `ttadak`, `sseul`, `bomb`, `shake`(공개 패 포함), `piStolen`, `scoreUpdate`, `goStopPrompt`(본인), `go`, `stop`, `nagari`, `chongtong`, `gwangSold`, `roundEnded`, `setEnded`.
+- 보너스패를 내면 `step`은 그대로 `play`이고 같은 사람이 다시 낸다.
+- `activePlayers`: 광팔기면 결정할 1명, `chongtong`/`play`/`chooseFlip`/`goStop`이면 차례인 1명, `gukjin`이면 국진 보유자, `roundResult`면 ready 안 한 사람들.
+
+### 8.3 공개/비공개 정보 (view)
+- 모두(관전자 포함): 바닥 전체(뻑 무더기 표시), 더미 장수, 각자 먹은 패(종류별 분류), 각자 현재 족보 점수와 진행도(예: 홍단 2/3), 고 횟수, 흔들기·폭탄 횟수, 뻑 횟수, 손패 장수, 빈패 수, 흔들기로 공개된 패, 광팔이가 공개한 광, 방 점수, 판 번호, 선, 나가리 배수, 마감 시각.
+- 본인만: 내 손패, 내 합법 행동(먹을 수 있는 패 하이라이트용 매칭 정보, 흔들기·폭탄 가능 여부), 고/스톱 선택지, 내 국진 선택지.
+- 절대 보내지 않음: 더미 순서(다음 뒤집을 패 포함), 남의 손패(흔든 패 제외), 광팔이의 공개하지 않은 패, 섞기 전 패 배열, RNG 상태.
+- 판 끝: 남은 손패는 공개하지 않는다(정산에 필요 없음). 정산 내역(족보·배수·박)은 공개한다.
+- 관전자는 `viewer=null`로 공개 정보만 받는다.
+
+### 8.4 랜덤 요소 (시드 RNG 사용 지점)
+1. 첫 판 선 정하기.
+2. 매 판 패 섞기(Fisher–Yates).
+3. 바닥 같은 월 4장, 총통 `redeal` 때 다시 섞기.
+4. 광팔기 뒤 죽은 사람 손패 + 더미 다시 섞기.
+- 그 밖에는 RNG를 쓰지 않는다. 자동 행동은 결정적이다.
+
+### 8.5 타이머·시간 초과·연결 끊김 시 자동 행동
+- `deadline`: 턴(`play`) = `turnSeconds`, 선택 단계(`chooseFlip`, `goStop`, `chongtong`, `sell`, `gukjin`) = `decisionSeconds`, 결과 화면 = 10초.
+- `onTimeout(state, player)` (모두 결정적):
+  - `play`: 빈패가 있으면 빈패를 낸다. 없으면 보너스패가 있으면 그것부터. 그 밖에는 바닥과 맞는 패 중 가져올 바닥 패 가치가 가장 큰 것(광 > 열끗 > 띠 > 쌍피 > 피, 같으면 낮은 ID), 맞는 패가 없으면 손패 중 가치가 가장 낮은 패(같으면 낮은 ID). target은 가치 큰 쪽. 흔들기·폭탄은 선언하지 않는다.
+  - `chooseFlip`: 가치 큰 쪽.
+  - `goStop`: **스톱**.
+  - `chongtong`: `declare: true`.
+  - `sell`: 죽기(sell=true)가 가능하면 죽기, 아니면 치기.
+  - `gukjin`: `auto` 규칙.
+  - `roundResult`: `ready`.
+- 연속 2회 시간 초과나 연결 끊김이면 `autoPilot=true`가 되고 마감을 2초로 줄인다. 액션 1회로 해제된다.
+- 서버는 도착 순서대로 처리하고, 마감 이후 도착한 액션은 버린다.
+
+### 8.6 종료 조건과 결과(GameResult)
+- `rounds`판을 마치면(나가리 포함) `finished`. 플레이어가 나가면 그 자리는 autoPilot으로 남은 판을 진행한다.
+```ts
+interface GostopResult {
+  ranking: Array<{ player: PlayerId; rank: number; total: number }>;  // 동점 = 같은 rank
+  summary: {
+    rounds: number; nagari: number;
+    bestRound: { player: PlayerId; amount: number; roundNo: number; breakdown: string[] } | null;
+    perPlayer: Array<{ player: PlayerId; wins: number; goCalls: number; piBakGiven: number; gwangSold: number }>;
+  };
+}
+```
+
+## 9. UI/UX
+- 모바일 세로 배치(위 → 아래)
+  - 상대 영역: 이름, 방 점수, 손패 장수(뒷면), 먹은 패를 종류별로 겹친 묶음(광/열끗/띠/피, 탭하면 펼침), 현재 점수 배지, 고 횟수 배지.
+  - 바닥: 월별로 묶어 3x4 격자에 배치(같은 월은 겹침). 뻑 무더기는 빨간 테두리. 더미는 가운데 옆에 남은 장수와 함께.
+  - 내 먹은 패: 종류별 묶음 + 족보 진행도("홍단 2/3", "피 8/10").
+  - 내 손패: 10장(맞고)이 2줄로 배치되어 카드 1장 너비가 60px 이상이 되게 한다. 카드 높이 84px 이상.
+- 조작: 손패를 탭하면 바로 낸다(화투는 실수 부담이 마작보다 작다). 설정에서 "두 번 탭해서 내기"를 고를 수 있다. 바닥 2장 중 고르기는 두 카드를 크게 띄우고 탭.
+- 합법 수 하이라이트: 바닥과 맞는 손패에 초록 테두리, 낼 경우 가져올 바닥 패를 함께 깜빡임. 흔들기·폭탄 가능 패에는 배지.
+- 고/스톱 화면: 화면 가운데 큰 버튼 2개(각 높이 72px 이상). 지금 점수, 고 하면 바뀌는 배수, 상대가 박 대상인지 미리 보여 준다(예: "지금 스톱하면 28점: 피박 x2, 광박 x2").
+- 애니메이션: 패 날아가기 200ms, 쪽·따닥·뻑·쓸·폭탄은 큰 글자와 효과음, 피 뺏기는 카드가 상대에게서 날아옴. "애니메이션 줄이기" 설정 제공.
+- 카드 그림: 전통 화투 도안을 새로 그린 자체 일러스트. 모서리에 월 숫자와 종류 글자(광/열/띠/피, 쌍피는 "피2")를 크게 표시해 어르신·아이도 구분하기 쉽게.
+- 초보자 도움말: [규칙 보기]에 월별 카드표, 족보표, 박 설명, 그림 예시. `hints` on이면 "이 패를 내면 홍단 완성" 같은 한 줄 힌트(본인 손패와 공개 정보만 사용).
+- 판 결과 화면: 족보별 점수 → 고 가산 → 배수 → 박 순으로 한 줄씩 계산 과정을 보여 준다.
+
+## 10. 테스트 체크리스트
+- [ ] 셋업: 같은 시드면 같은 배분. 맞고 손 10/바닥 8/더미 20(+보너스 수), 3인 7/6/21, 4·5인 광팔기 뒤 더미 21.
+- [ ] 바닥 4장 같은 월 → 다시 섞기, 선·판 번호 유지. 바닥 3장 같은 월 → 한 무더기, 4번째로 먹으면 피 1장씩.
+- [ ] 바닥 보너스패 → 선이 가져가고 더미에서 보충, 보충패도 보너스면 반복.
+- [ ] 쪽: 바닥에 없는 월을 냈는데 같은 월이 뒤집힘 → 2장 먹고 상대마다 피 1장.
+- [ ] 뻑: 바닥 1장과 짝 + 같은 월 뒤집힘 → 3장 무더기, 아무것도 못 먹음, ppeokBy 기록. 다른 사람이 4번째로 먹으면 피 1장, 본인이 먹으면(자뻑) 피 2장씩.
+- [ ] 따닥: 바닥 2장 + 손 1장 + 같은 월 뒤집힘 → 4장 먹고 피 1장씩.
+- [ ] 쓸: 턴 끝에 바닥이 비면 피 1장씩. 마지막 턴 쓸은 `lastTurnSweepBonus=false`일 때 피 뺏기 없음.
+- [ ] 두 장 중 고르기: 손패가 맞는 바닥 2장이 광/피면 target 없이 내면 거부. 뒤집은 패가 바닥 2장과 맞으면 `chooseFlip` 단계. 종류가 같으면 자동.
+- [ ] 폭탄: 3장 + 바닥 1장 → 4장 먹고 피 1장씩, 빈패 2장 지급, 빈패 내면 더미만 뒤집음, 판 끝 x2.
+- [ ] 흔들기: 공개된 패가 상대 view에 보이고 나머지 손패는 안 보임. 2번 흔들고 이기면 x4. 지면 배수 없음.
+- [ ] 총통: 손에 같은 월 4장 → 선언 시 맞고 10점(나가리 배수만 적용). 미선언 시 진행 가능.
+- [ ] 피 뺏기 순서: 상대가 일반 피 0장·쌍피 1장이면 쌍피를 준다. 피가 0장이면 아무것도 안 줌.
+- [ ] 점수: 비삼광 2점, 사광 4점(비광 포함), 오광 15점, 고도리 5 + 열끗 장수 점수 중복, 띠 5장 1점 + 홍단 3점 중복, 피 값 10에 1점(쌍피·보너스 반영).
+- [ ] 국진 auto: 6.3 예시 6. 패자 국진이 피박 회피에 쓰임(피 값 5 → 7, 맞고 기준 7이면 여전히 피박, 3인 기준 5→7이면 피박 면제).
+- [ ] 고 규칙: 마지막 고 점수와 같으면 선택 프롬프트 없음, 커지면 프롬프트. 마지막 턴 조건 충족 → 자동 스톱. 3고 x2, 4고 x4, 1·2고 가산만.
+- [ ] 최종 공식: 6.3 예시 1(28), 3(48), 5(독박 18), 7(나가리 14), 8(멍따 16)과 같다.
+- [ ] 박: 피박 경계값(맞고 7장 피박 / 8장 아님, 3인 5/6), 피 0장 면제, 광박은 승자가 광 점수가 있을 때만, 고박 맞고 x2.
+- [ ] 나가리: 고를 부른 사람이 끝까지 점수를 더 못 냄 → 나가리, 선 유지, 다음 판 x2, 연속 나가리 x4, 상한 x8.
+- [ ] 첫뻑 3점 즉시, 연뻑 추가 6점, 삼뻑 즉시 승리. 나가리여도 첫뻑 점수 유지.
+- [ ] 광팔기(4인): 선 다음 사람부터 결정, 선은 sell 불가, 치기 3명 확정 시 나머지 자동 죽기, 광 2장 공개 → 선 제외 참가자 2명이 각 2점(가격 1). 죽은 사람 손패가 더미에 섞여 더미 21장.
+- [ ] 보너스패: 손에서 내면 먹고 1장 보충 후 같은 턴 계속. 판 끝까지 손패·더미 장수가 맞는다(더미 부족 없음).
+- [ ] 시간 초과: play 자동 행동이 결정적(같은 상태 → 같은 카드). goStop 시간 초과 → 스톱. 2회 연속 → autoPilot, 마감 2초.
+- [ ] 연결 끊김: 끊긴 사람 턴이 2초 안에 자동 처리되어 판이 멈추지 않는다. 재접속 후 액션으로 autoPilot 해제.
+- [ ] 정보 누출: 상대·관전자 view JSON에 내 손패 ID, 더미 순서, 광팔이 미공개 패가 없다. 흔든 패만 보인다. 이벤트 `flipped`는 뒤집힌 뒤에만 카드 ID를 담는다.
+- [ ] 제로섬: 각 판 정산 후 방 점수 합 = 0(광값·첫뻑 포함).
+- [ ] 재현성: 같은 시드 + 같은 액션 로그 → 같은 결과.
+
+## 11. 참고 자료
+- 나무위키 "고스톱"(패 돌리기, 뻑·쪽·따닥·쓸·폭탄·흔들기·총통, 점수, 박, 고 배수, 나가리, 국진): https://namu.wiki/w/고스톱
+- 나무위키 "맞고"(2인 배분 10/8/20, 7점, 피박 7장, 총통·보너스패 플랫폼별 차이): https://namu.wiki/w/맞고
+- Pagat.com "Go-Stop"(월별 카드 구성, 광팔기 절차, 첫뻑·삼뻑, 폭탄 후 뒤집기 턴, 고박): https://www.pagat.com/fishing/gostop.html
+- Wikipedia "Go-Stop"(배분, 쪽·따닥·뻑, 점수, 고 배수, 피박·광박): https://en.wikipedia.org/wiki/Go-Stop
+
+## 12. 메모 (상표·법적 주의 등)
+- 상표: "고스톱", "맞고", "화투"는 일반 명칭이다. 다만 "한게임 신맞고", "피망 뉴맞고", "넷마블 맞고" 등 서비스명은 상표이므로 쓰지 않는다. 표시 이름 후보: "고스톱", "맞고(2인 고스톱)".
+- 그림: 시판 화투나 기존 온라인 게임 카드 그림을 그대로 쓰지 않는다. 전통 도안(월별 꽃·동물 모티프)을 바탕으로 새로 그린 자체 일러스트를 쓴다.
+- **법적 주의(중요)**:
+  - 점수는 방 안 가상 점수로만 쓰고, 유료 구매·충전·선물·환전·순위 보상과 연결하지 않는다. 연결하면 「게임산업진흥에 관한 법률」 제28조(사행성 조장 금지)·제32조(환전·환전 알선 금지)와 형법 제246조(도박) 문제가 생긴다.
+  - 고스톱·포커류 같은 웹보드 게임은 게임물관리위원회 등급분류에서 대체로 **청소년이용불가**로 분류된다. 유료 재화가 있으면 웹보드게임 규제(게임산업법 시행령 별표 2: 월 결제 한도, 1회 베팅 한도, 본인인증 등)도 적용된다. 이 사이트는 아이도 대상이므로 출시 전에 (a) 고스톱 방에 연령 확인·성인 전용 표시를 할지, (b) 등급분류를 받을지와 면제 대상인지를 확인해야 한다.
+  - 화면 문구에 "돈", "판돈", "점당 얼마" 같은 표현을 쓰지 않는다. "점수"만 쓴다.