Files
joke-app/docs/games/connect-four.md
EJClaw 5e1e74da18 오목·사목·오델로·바둑 소리·움직임, 바둑 사석 확인 무제한
- 공통(보드게임 8종용) board-motion: 직전 판 비교(useMoveDiff), 끝난 잔상 치우기(useAnimOver), 내려앉기·미끄러지기·사라지기·고리·반짝임 클래스
- 오목: 돌 내려앉기, 마지막 수 고리, 무르기 돌 사라짐, 승리 줄 차례로 반짝임, 금수 누르면 작은 소리, 돌 그림자
- 사목: 바닥에 닿아 한 번 튀기, 닿는 순간에 맞춘 "탁" 소리, 마지막 수 점은 닿은 뒤, 이긴 줄 차례로 깜빡임
- 오델로: 놓은 돌 먼저 내려앉고 뒤집기(들리며 뒤집힘), 뒤집힐 때마다 딸깍, 패스·무르기 소리, 마지막 수 고리
- 바둑: 돌 내려앉기, 따낸 돌 한 알씩 사라짐+딸깍, 패스 소리, 무르기 되돌림, 사석 표시 바뀜 소리
- 바둑 사석 확인 제한 시간에 무제한(0) 추가(기본 3분 그대로), 테스트·문서
- 숨은 탭 내 차례 소리는 방 화면이 이미 내므로 게임 쪽 중복 제거
- games E2E에 오목 기본 계획 추가

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 04:21:25 +09:00

136 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 커넥트 포 (사목) (`connect-four`)
> 마일스톤: M9 · 인원: 최소 2 ~ 최대 2명 · 예상 시간: 약 3~10분 · 난이도: 쉬움
## 1. 개요
- 세워 놓은 판의 열을 골라 돌을 떨어뜨리고, 가로·세로·대각선으로 내 돌 4개를 먼저 잇는 2인 게임. 1974년 밀턴 브래들리(하워드 웩슬러·네드 스트롱긴) 출시. 규칙이 10초면 설명되고 5분이면 끝나 아이와도 자주 한다.
- 인원 근거: 원작이 빨강·노랑 2인 게임. 최소 2, 최대 2.
- 표시 이름은 **커넥트 포**(일반 이름 "사목"은 카탈로그 소개 문구에 함께 적음). 친구끼리 쓰는 사이트라 원래 이름을 그대로 쓰는 방침(`README.md` 5절)을 따른다.
- 완전 정보 게임. view에서 뺄 것이 없다(`secretsOf` 없음).
- 참고: 7×6 판은 1988년에 완전히 풀렸다(먼저 두는 쪽이 가운데 열부터 완벽하게 두면 이긴다). 그래서 컴퓨터 상대는 단계별로 일부러 실수를 섞는다(8.7).
## 2. 모드와 옵션
| 옵션 키 | 설명 | 선택지 | 기본값 |
|---|---|---|---|
| `boardSize` | 판 크기(가로 열 × 세로 줄) | `7x6` / `8x7` / `9x7` | `7x6` |
| `colorAssignment` | 먼저 두는 사람(빨강) 정하기 — 오목·오셀로와 같은 관례 | `random` / `hostRed`(방장이 먼저) / `hostYellow`(방장이 나중) / `alternate`(판마다 번갈아, `gameNo` 홀수 판은 방장이 빨강) | `random` |
| `timeControl.kind` | 시간 방식 | `none` / `perMove` / `fischer` | `perMove` |
| `timeControl.perMoveSec` | 한 수당 제한 | 10 / 20 / 30 / 60 (5~600) | 30 |
| `timeControl.baseSec` / `incSec` | 전체 시간 / 수당 추가 | 1분+2초, 3분+2초, 5분+3초 | 3분+2초 |
| `timeoutPolicy` | `perMove` 시간 초과 처리 | `autoMove` / `lose` | `autoMove` |
| `autoMoveLimit` | 연속 자동 두기 허용 횟수(넘으면 시간패) | 0~20 | 2 |
## 3. 구성물
- 세워 놓은 판: 7열 × 6줄(42칸). 옵션으로 8×7(56칸), 9×7(63칸).
- 빨강·노랑 원반. 원작은 21개씩이지만 엔진은 개수를 세지 않는다(칸 수가 상한이고 번갈아 두므로 자연히 반씩).
- 좌표: 열은 왼쪽부터 1, 2, 3…(화면·기보 표기 "4열"), 줄은 아래에서부터 센다. 내부 `(x, y)`는 `x` 0부터, `y` 0이 맨 위 줄(판 배열 `y*cols + x`).
## 4. 준비(셋업)
1. 빈 판.
2. `colorAssignment`로 빨강(먼저)·노랑(나중)을 정한다.
3. 빨강이 먼저 둔다.
## 5. 진행 규칙
- 차례에 꽉 차지 않은 열 하나를 고른다. 원반은 그 열의 가장 아래 빈칸으로 떨어진다.
- 꽉 찬 열은 고를 수 없다("그 줄은 꽉 찼어요."). 패스는 없다(판이 다 차기 전엔 항상 둘 곳이 있다).
- 번갈아 계속한다.
- 예시: 맨 아래 줄 2·3·4열에 내 원반이 있고 1열과 5열이 비어 있으면, 상대가 한쪽을 막아도 반대쪽이 남아 다음 차례에 4개가 이어진다.
## 6. 승패와 점수 계산
- 놓은 원반을 포함해 가로·세로·대각선 중 하나로 같은 색 4개 이상이 이어지면 그 즉시 승리. 5개 이상 이어져도 승리(원작과 같음).
- 모든 칸이 찼는데 아무도 못 이으면 무승부.
- 점수는 없다(결과 화면에 `scoreText` 없음, `result-score.test.ts`의 NO_SCORE).
- 그 외 종료: 기권, 시간패. 무승부 합의는 없다(7절).
## 7. 지역 룰 / 하우스 룰 (옵션으로 켜고 끄기)
- 판 크기 8×7, 9×7: 원작 변형 판(대형판)에 맞춘 크기. 규칙은 같고 이기기 조건도 4개.
- **일부러 뺀 것**
- 무르기, 무승부 제안: 한 판이 몇 분이고 판이 차면 저절로 비기므로 넣지 않았다(오목·오셀로와 다른 점).
- "Pop Out"(맨 아래 원반 빼기), "5개 잇기" 같은 변형: 원작 기본 규칙만.
- 처음 몇 수를 정해 두는 대회식 오프닝: 친구끼리 하는 사이트라 넣지 않음.
## 8. 엔진 설계
### 8.1 상태(State)
```ts
type Color = 'red' | 'yellow'; // 빨강 = 디스크 1 = 먼저
type Cell = 0 | 1 | 2;
interface ConnectFourState {
options: ConnectFourOptions;
cols: number; rows: number; // 7×6 / 8×7 / 9×7
board: Cell[]; // y*cols + x, y = 0 이 맨 위 줄
players: Record<Color, PlayerId>;
turn: Color;
moves: { color: Color; x: number; y: number; at: number; auto: boolean }[];
phase: 'playing' | 'finished';
winLine: { x: number; y: number }[] | null; // 이긴 줄(4개 이상, 두 줄을 동시에 만들면 둘 다)
clock: { remainingMs: Record<Color, number>; turnStartedAt: number; autoMoveStreak: Record<Color, number> };
result: { winner: Color | null; reason: 'four' | 'boardFull' | 'resign' | 'timeLoss'; moveCount: number; summary: string } | null;
}
```
### 8.2 액션
| type | payload | 누가 / 언제 | 검증 조건 |
|---|---|---|---|
| `drop` | `{ col }` | 차례인 플레이어, `playing` | `0 ≤ col < cols`("판 밖이에요."), 맨 위 칸이 비어 있음("그 줄은 꽉 찼어요.") |
| `resign` | `{}` | 플레이어, 언제든(상대 차례에도) | — |
| `timeout` | `{}` | 시스템 | 8.5 |
- 이벤트: `dropped { color, x, y, auto }`(떨어지는 애니메이션·소리), `win`, `draw`, `timeoutAutoMove`, `timeLoss`, `resigned`.
### 8.3 공개/비공개 정보 (view)
- 모두 공개: 판, 차례, 내 색(`myColor`, 관전자는 null), 마지막 수, 기보(`moves`, 시각 제외), 이긴 줄, 시계, 결과.
### 8.4 랜덤 요소 (시드 RNG 사용 지점)
1. `colorAssignment=random`.
2. 자동 두기에서 같은 우선순위의 열이 여러 개일 때 고르기.
### 8.5 타이머·시간 초과·연결 끊김 시 자동 행동
- `deadline`: `perMove` → `turnStartedAt + perMoveSec*1000`, `fischer` → `turnStartedAt + remainingMs[turn]`, `none` → `null`.
- `onTimeout` → `{ type: 'timeout' }`.
- `perMove + autoMove`이고 연속 자동 두기가 `autoMoveLimit` 미만: 자동 두기. 순서: ① 내가 바로 4개를 잇는 열 ② 상대가 바로 4개를 잇는 열 막기 ③ 그 위 칸에서 상대가 이기게 받쳐 주지 않는 열 중 가운데에 가장 가까운 열(같으면 시드 RNG) ④ 아무 열.
- 그 외(`lose`, `fischer`, 횟수 초과): 시간패.
- `fischer`: `drop` 때 쓴 시간을 빼고 0 이하면 시간패, 아니면 `incSec` 더함.
- 나가기(`onLeave`) = 기권.
### 8.6 종료 조건과 결과(GameResult)
- `four`(4개 연결) / `boardFull`(무승부) → `reason: 'normal'`, `resign` → `'resign'`, `timeLoss` → `'timeout'`.
- 순위: 승자 1등, 패자 2등. 무승부는 둘 다 1등.
- 요약(`summary`): "빨강 승 (4개 연결, 17수)", "노랑 기권으로 빨강 승", "빨강 시간패로 노랑 승", "무승부 (42칸이 모두 찼어요)".
### 8.7 컴퓨터 상대 (`bot.ts`, `search.ts`)
- 탐색: 네가맥스 알파베타 + 반복 심화 + 치환표(조브리스트 해시 64비트, 2^17칸, 판마다 세대 표시로 초기화). 열 순서는 가운데부터, 치환표의 최선 수를 먼저.
- 모든 노드에서 먼저 "지금 4개를 잇는 열"(바로 승리)과 "상대가 지금 4개를 잇는 열"을 본다. 상대 위협이 2곳이면 진 판, 1곳이면 그 열만 둔다(강제 수).
- 평가: 4칸짜리 줄(창) 전부를 한쪽 색만 들어 있을 때 1개 1점·2개 4점·3개 16점, 3개짜리 줄의 빈칸이 그 색에 유리한 줄(빨강은 아래에서 홀수 번째 줄, 노랑은 짝수 번째 줄 — 끝까지 가면 그 칸을 차지하는 쪽)이면 +24, 가운데 열 원반 +3. 창 값은 돌을 놓고 뺄 때마다 바뀐 창만 다시 계산(증분)해서 한 노드가 빠르다.
- 단계(1~60): 읽는 깊이 = `1 + round((레벨-1)×9/59)` 수(레벨 1은 자기 수만, 10 → 2수, 30 → 5수, 50 → 8수, 60 → 10수). 어려움(41~)은 빈칸이 24개 이하로 줄면 끝까지 읽기를 시도한다. 한 수에 볼 수 있는 국면은 5만 개(`MAX_NODES`)로 제한하고, 그 안에 못 끝낸 깊이는 버리고 바로 앞 깊이 결과를 쓴다.
- 사람 같은 실수: 루트의 열 점수를 공통 `humanBest`(쉬움은 자주 조금 못한 수, 가끔 실수)에 넘긴다. 내 4목·상대 4목 막기는 "꼭 둬야 하는 수"로 표시해, 낮은 단계는 정해진 확률(`miss`, 레벨 1 약 20%, 10 약 12%, 30 약 3%, 50 이상 0%)로 못 보고 지나친다.
- 측정(이 서버, 7×6, 레벨 60, 한 수): 평균 약 4ms, 최악 약 20~30ms. 9×7도 최악 30ms 안쪽(`BOT_SLOW_MS` = 50ms). 단계별 대결(각 30판, 색 번갈아): 60 vs 10 → 29승 0패, 60 vs 30 → 26승 2패, 60 vs 45 → 21승 5패, 45 vs 30 → 21승 5패, 30 vs 10 → 26승 4패.
- 운(카드 섞기) 조정은 쓰지 않는다(`luck.ts`의 NO_LUCK — 정보가 다 보이는 판 게임).
## 9. UI/UX
- 판: 파란 틀에 구멍이 뚫린 세워진 판(SVG 마스크). 원반은 틀 뒤에 그려 떨어질 때 구멍 사이로 보인다. 맨 위에 "넣을 열" 미리 보기 원반, 떨어질 칸에 점선 동그라미, 아래에 열 번호 1~N.
- 떨어지는 애니메이션: 새 원반만, 떨어지는 높이에 비례해 0.2~0.6초. `prefers-reduced-motion`이면 애니메이션 없음(이긴 줄 깜빡임도 끔). 처음 들어오거나 새로 고침했을 땐 애니메이션 없음.
- 열 전체(미리 보기 줄 포함)가 터치 영역 — 7×6 판이 휴대폰 390px에서 열 너비 약 50px. 마우스는 한 번 누르면 바로 넣기(올려 두면 미리 보기). 터치는 "한 번 더 누르기 확인" 설정이 켜져 있으면 처음 누르면 미리 보기, 같은 열을 다시 누르거나 [N열에 넣기]로 확정.
- 키보드: 판(`role="grid"`)에 초점 → ←·→로 열 고르기, Home·End로 끝 열, Enter·Space로 넣기. 꽉 찬 열이면 스크린리더에 "N열은 꽉 찼어요" 안내. 둘 때마다 "빨강이 4열에 넣었어요. 아래에서 2번째 칸이에요." 읽어 줌.
- 마지막 수에 흰 점(원반이 닿은 뒤 나타남), 이긴 줄은 흰 고리로 강조(줄 순서대로 번갈아 깜빡임).
- 소리·움직임(2026-10-13): 원반은 떨어져 바닥에 닿은 뒤 한 번 살짝 튀고 멈춘다. 소리는 손을 떠날 때 작은 달그락, 바닥에 닿는 순간 플라스틱 "탁"과 작은 두 번째 탁(떨어지는 시간에 맞춤). 꽉 찬 열을 누르면 작은 `sfx.bad`. 상대·컴퓨터의 수에도 똑같이 나온다.
- 오른쪽 패널(휴대폰은 판 아래): 두 사람(색, 먼저/나중, 남은 시간), 기권 버튼(확인 창), 기보("1. 🔴 4열", 자동 두기는 *).
- 다크 모드: 틀 색을 조금 어둡게, 구멍은 배경색.
- 30초 요약 3장: 열 골라 넣기 / 4개 이으면 승리 / 3개면 꼭 막기. [?] 도움말: 차례, 꽉 찬 열, 첫 수 가운데 팁, 3개 막기 팁.
## 10. 테스트 체크리스트
- [x] 판 크기 3종, 먼저 두는 사람 4가지(번갈아는 `gameNo` 홀짝).
- [x] 원반이 맨 아래 빈칸으로 떨어지고 쌓임. 꽉 찬 열·판 밖·남의 차례·관전자 거부.
- [x] 가로·세로·두 대각선 4개 즉시 승리, 3개는 계속, 5개 연결은 다섯 칸 모두 강조.
- [x] 42칸이 다 차면 무승부(순위 공동 1등).
- [x] 기권(상대 차례에도), 나가기 = 기권.
- [x] 시간: 수마다 마감 갱신, 자동 두기 승리 > 막기 > 받쳐 주지 않는 가운데 열, 같은 시드 같은 수, 허용 횟수 넘으면 시간패, `lose`·`autoMoveLimit 0`, 피셔 증가·초과패, 제한 없음.
- [x] 무작위 대국(판 크기별) 끝까지·결정적·빠름.
- [x] 컴퓨터: 첫 수 가운데, 이기는 수 > 막기, 4목 막기, 상대 승리 칸 밑에 안 두기, 양쪽 열린 3 미리 막기, 강한 단계는 몇 수 앞 강제 승 찾기, 레벨별 깊이, 낮은 단계만 막기를 가끔 놓침, 강한 단계가 약한 단계를 이김, 모든 판 크기에서 한 수 100ms 미만(실제 수십 ms 안쪽).
- [x] E2E(`e2e/games.e2e.ts` `connect-four`): PC 방장 키보드 + 휴대폰 친구 터치로 13수, 꽉 찬 열 누름 무시, 맨 아래 줄 5개로 빨강 승, 이긴 줄 5칸 강조, 결과 창.
## 11. 참고 자료
- 원작 규칙서(Hasbro Connect 4), 존 트롬프(John Tromp)의 7×6 해 풀이, 빅터 앨리스(Victor Allis) "A Knowledge-based Approach of Connect-Four"(1988, 홀짝 줄 위협 규칙).
## 12. 메모 (상표·법적 주의 등)
- "Connect 4"는 해즈브로 상표. `README.md` 5절 방침대로 이름은 "커넥트 포"를 쓰고, 일반 이름 "사목"을 소개 문구에 함께 적어 둔다. 표시 이름은 관리자 사이트에서 언제든 바꿀 수 있다. 판·원반 그림은 직접 만든 SVG.