Files
joke-app/docs/games/apple.md

127 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.
# 사과 게임 (`apple`)
> 마일스톤: M9 · 인원: 최소 1 ~ 최대 8명 · 예상 시간: 약 1~3분 · 난이도: 쉬움
## 1. 개요
- 웹에서 유행한 "사과 게임"(원작 Fruit Box, 일본 플래시 게임). 17×10 칸에 1~9가 적힌 사과가 가득하고, 마우스로 직사각형을 그어 그 안의 숫자 합이 **딱 10**이면 사과가 사라진다. 2분 동안 많이 지울수록 높은 점수.
- 원작은 혼자 하는 점수 도전이다. 우리 사이트에서는 **모두 같은 판(같은 시드)** 을 각자 따로 동시에 풀고, 시간이 끝났을 때 점수로 순위를 매기는 "경주"로 만든다. 혼자서도 할 수 있다(요트 다이스처럼 1명 허용).
- 인원 근거: 원작 1인. 판이 사람마다 따로라 인원 제한은 화면(점수 목록) 크기 때문이며, 다른 실시간 게임(도블)과 같은 최대 8명으로 정했다.
## 2. 모드와 옵션
| 옵션 키 | 설명 | 선택지 | 기본값 |
|---|---|---|---|
| `timeLimitSec` | 제한 시간 | 60(1분) / 120(2분) / 180(3분) / 무제한 | 120 (원작) |
- 판 크기는 원작의 17×10으로 **고정**한다(단순하게). 휴대폰에서는 판을 돌려서 보여 주므로 작은 판 옵션은 넣지 않았다.
## 3. 구성물
- 가로 17칸 × 세로 10줄, 사과 170개. 사과마다 1~9 숫자.
## 4. 준비(셋업)
1. 시드 RNG로 170칸에 1~9를 고르게 뽑는다.
2. 원작처럼 **전체 합이 10의 배수**가 되게, 합이 맞을 때까지 RNG로 고른 칸 하나를 다시 뽑는다(결정적).
3. 모든 사람에게 같은 판을 복사해 준다. 자리 순서는 입장 순서 그대로(턴이 없으니 의미 없음).
4. 3초 카운트다운 뒤 동시에 시작. 카운트다운 동안에는 판을 보여 주지 않는다(먼저 보는 사람이 없게).
## 5. 진행 규칙
- 턴이 없다. 시작 후 마감 전까지 누구나 언제든 자기 판에서 직사각형을 고를 수 있다.
- 직사각형 = 두 꼭짓점 칸(어느 순서든). 그 안의 **사과 숫자 합이 정확히 10**이면 안의 사과가 모두 사라지고, 사라진 개수만큼 점수.
- 지운 자리는 빈 칸. **빈 칸은 합에 영향이 없다** → 사이가 비면 멀리 떨어진 사과끼리도 묶을 수 있다.
- 직사각형 안에 사과가 0개면 무효.
- 합이 10이 아니면 **아무 일도 없다(벌점 없음)**. 서버는 그 행동을 거절하고(`합이 N이에요…`), 화면은 손을 뗄 때 합이 10이 아니면 아예 보내지 않고 "합 N · 10이 아니에요"만 잠깐 보여 준다.
- 내 판에 합 10 묶음이 더 없으면 "막힘"(`stuck`): 더 고를 수 없고 시간이 끝날 때까지 기다린다. 모두 막히면(혹은 남은 사람이 전부 막히면) 시간 전에 끝난다(원작에는 없음, 혼자 할 때 기다리지 않게).
- 무제한 스톱워치(2026-10-14): 시작(카운트다운 끝)부터 그 사람이 막히거나(`stuck` = 더 지울 사과 없음) 「여기까지」를 누를 때까지의 시간을 서버 시계로 잰다(`finishedAt`). 화면 위에 `0:00.0`(0.1초 단위)으로 흐르고, 끝나면 멈춘다. 제한 시간이 있는 방에는 없다.
- 무제한 힌트(2026-10-14): [💡 힌트]를 누르면 내 판에서 합이 10인 묶음 하나(전부 중 무작위)를 노란 점선 상자로 나에게만 보여 준다. 그 상자가 아직 10인 동안은 다시 받을 수 없고(횟수 중복 없음), 지우거나 다른 곳을 지워 10이 아니게 되면 사라진다. 받은 횟수를 센다.
## 6. 승패와 점수 계산
- 점수 = 지운 사과 개수(= 내 판의 빈 칸 수).
- 순위: 점수 높은 순, **같은 점수는 같은 순위**. 중간에 나간 사람은 남은 사람 모두보다 아래(그 안에서도 점수 순).
- 결과 화면 점수 문구: `사과 N개`, 무제한이면 `사과 N개 · 걸린 시간 3분 05.4초`(+ 힌트를 받았으면 ` · 힌트 2번`). 혼자 한 판의 요약에도 같은 꼬리가 붙는다. 순위는 그대로 개수만 본다. `GameResult.scores` = 지운 개수.
## 7. 지역 룰 / 하우스 룰
- 없음. 원작 변형(작은 판, 시간 보너스, 연쇄 점수 등)은 넣지 않았다.
## 8. 엔진 설계
### 8.1 상태(State)
```ts
interface AppleState {
options: { timeLimitSec: 60 | 120 | 180 | null }; // null = 무제한
order: PlayerId[];
initial: string; // 170자 '1'..'9' (행 우선), 공용 시작 판
boards: Record<PlayerId, string>; // 각자 판, 지운 칸은 '0'
score: Record<PlayerId, number>;
clears: Record<PlayerId, number>; // 지운 횟수
status: Record<PlayerId, 'playing' | 'stuck' | 'done' | 'left'>; // done = 무제한에서 「여기까지」
recent: Record<PlayerId, number[]>; // 최근 고르기 서버 시각(속도 제한)
phase: 'countdown' | 'playing' | 'ended';
countdownEndsAt: number;
endsAt: number | null; // countdownEndsAt + timeLimitSec (무제한이면 null)
final: AppleFinal | null;
}
```
판을 숫자 배열이 아닌 170자 문자열로 둬서 상태·view가 작다.
### 8.2 액션
| type | payload | 누가 / 언제 | 검증 조건 |
|---|---|---|---|
| `select` | `r0, c0, r1, c1` (행 0~9, 열 0~16, 정수) | 게임 중인 사람, 카운트다운 끝 ~ 마감 전 | 나가지 않음, 막히지 않음, 1초에 5번 이하, 안에 사과 1개 이상, 합 = 10 |
| `stop` | — | 「여기까지」, 무제한 방에서 게임 중인 사람 | 시작 뒤, 아직 `playing` |
| `hint` | — | 💡 힌트, 무제한 방에서 게임 중인 사람 | 시작 뒤, 아직 `playing`, 지금 보이는 힌트가 없음(있어도 더는 10이 아니면 됨) |
| `tick` | — | 서버 타이머 전용(스키마에 없음) | — |
| `leave` | — | 서버(나가기) 전용 | 아직 게임 중 |
- 카운트다운이 끝났는데 방 타이머가 아직 안 돌았어도(`now ≥ countdownEndsAt`) `select`는 받는다. `apply`가 먼저 단계를 시계에 맞춘다(`catchUp`: 카운트다운 → 진행 → 마감).
- 속도 제한: 그림 맞히기와 같은 방식(`recent` 최근 5개, `ctx.now` 기준 1초). 사람은 1초에 2~3번이 한계라 정상 플레이에는 걸리지 않는다. 클라이언트가 보낸 고르기만 막고, 서버 판정은 언제나 서버 판 기준.
### 8.3 공개/비공개 정보 (view)
- 내 view: 내 판(`cells`, 170자) + 모든 사람의 점수·지운 횟수·상태 + 시간. **다른 사람 판은 보내지 않는다**(같은 판이라 숨길 정보는 없지만 view를 작게, 남의 진행 모양을 엿보지 않게).
- 관전자: 판 없이 점수만.
- 무제한: 모든 사람의 걸린 시간(`timeMs`, 끝낸 뒤에만)과 힌트 횟수(`hints`)는 모두에게, 힌트 상자(`hint`)는 받은 사람에게만.
- 카운트다운 동안에는 누구에게도 판을 보내지 않는다(`secretsOf` = 카운트다운 중 `initial`).
### 8.4 랜덤 요소
- `setup`의 판 생성과 힌트로 보여 줄 묶음 고르기(`apply`의 `ctx.rng`, 다시 보기에서도 같음). 모두 같은 판이라 운의 차이가 없다. 컴퓨터 운(셔플 여러 번 중 고르기)도 적용하지 않는다(턴 게임 전략에만 적용, `luckApplies`).
### 8.5 타이머·시간 초과·연결 끊김
- `deadline`: 카운트다운 중 `countdownEndsAt`, 진행 중 `endsAt`(서버 시계). 마감 `tick`으로 끝난다. 마감 뒤 도착한 `select`는 `시간이 다 됐어요.`로 거절. 무제한이면 진행 중 마감이 없고, 모두 막히거나 「여기까지」(`stop`)를 누르면 끝난다. 연결이 끊긴 채 방의 유예 시간이 지난 사람은 `tick`으로 `done` 처리된다.
- `timeoutPlayers`: 게임 중인 모두(막힌 사람 포함).
- `timeoutNotBefore` = `deadline`: 연결이 끊긴 사람도 **일찍 시간 초과되지 않는다**(할 행동이 없음). 그 사람 점수는 그대로 남고 마감 때 순위에 들어간다.
- 나가기: `leave` → 상태 `left`, 더는 못 고름. 여러 명으로 시작했는데 남은 사람이 1명이면 그 사람이 이긴 것으로 바로 끝, 아무도 안 남으면 끝.
### 8.6 종료 조건과 결과
- `time`: 마감. `cleared`: 남은 사람이 모두 막힘. `left`: 혼자 남음/모두 나감.
- 요약: 여러 명 `시간이 다 됐어요. 사과를 가장 많이 지운 사람이 이겼어요`(+ `공동 1등 N명`), 혼자 `시간이 다 됐어요. 사과 N개를 지웠어요`.
## 9. UI/UX
- PC: 판(17×10, 화면 높이에 맞춰 최대 약 980px) 위에 남은 시간·내 점수·"합 N / 10" 표시, 그 아래 다른 사람 점수 칩(실시간, 순위순). 오른쪽 패널에 순위표.
- 휴대폰(폭 640px 이하): 판을 시계 방향 90도로 돌려 **10열 × 17줄**로 보여 준다. 폭 390px에서 칸 약 35px, 320px에서도 최소 28px(판 최소 폭 280px).
- 조작: 포인터 이벤트(마우스·터치·펜 공통). 누른 칸 ~ 지금 칸이 직사각형. 드래그 중 합계를 실시간 표시, 합이 10이면 초록, 넘으면 빨강, 모자라면 파랑. 손을 떼서 10이면 바로 지운 것처럼 보이고(낙관적 표시, 서버가 거절하면 되돌림) 사과가 튀어 오르며 사라진다. 판에는 `touch-action: none`(드래그 중 스크롤 안 됨).
- 키보드: 판에 포커스 → 화살표로 칸 이동(점선 커서), 스페이스/Enter로 시작점, 한 번 더 눌러 끝점(합 10이면 지움), Esc 취소. 스크린리더는 칸 위치·숫자·지금 합을 aria-live로 읽어 준다.
- 사과 그림은 SVG(이미지 파일 없음). 다크 모드에서는 판 바탕만 어두운 나무색.
## 10. 테스트 체크리스트
- [x] 판: 170칸 1~9, 합 10의 배수, 같은 시드 = 같은 판, 모두 같은 판으로 시작
- [x] `findMoves`(가장 좁은 합 10 직사각형 전부) = 무차별 계산과 같음, 빈 칸 너머 묶음 포함
- [x] 카운트다운 중 판 숨김·고르기 거절, 카운트다운 끝 직후(타이머 전) 고르기 인정
- [x] 합 10 → 지우고 개수만큼 점수, 모서리 순서 무관, 빈 칸은 합에 영향 없음, 사과 0개·합≠10 거절
- [x] 속도 제한(1초 5번), 마감 뒤 거절, 마감 tick으로 끝, 동점 같은 순위
- [x] 혼자 하기 요약, 막힘 → 모두 막히면 조기 종료, 나가기 → 혼자 남으면 끝·나간 사람 맨 아래
- [x] 엔진 `randomPlayout`(유출·JSON·결정성) 1·2·5·8명
- [x] 방 통합: 연습방에서 사람 + 컴퓨터가 끝까지(서버 시계), 합≠10 거절, 끊긴 사람 조기 시간 초과 없음
- [x] E2E: PC 마우스 드래그 + 키보드, 휴대폰 실제 터치(CDP) 드래그, 돌린 판 = 같은 판, 상대 점수 반영, 1분 뒤 결과까지
## 11. 참고 자료
- 원작: Fruit Box (フルーツボックス), 2분 · 17×10 · 합 10 규칙.
## 12. 메모
- 원작 이름 대신 한국에서 통하는 "사과 게임"으로 표시.
## 13. 컴퓨터 상대
- 실시간 게임이라 원래는 컴퓨터를 넣지 않았지만(도블·할리갈리), 이 게임은 **각자 자기 판을 푸는 경주**라 컴퓨터가 남의 판을 방해하거나 반응 속도로 이길 수 없다. 그래서 마피아처럼 **live 전략**(`LIVE_BOT_STRATEGIES.apple`)으로 넣었다: 서버가 컴퓨터마다 자기 타이머로 계속 물어보고, 컴퓨터는 자기 view(자기 판)만 본다.
- 레벨(1~60, live 전략에도 `level` 전달)에 따라:
- 찾는 시간: 레벨 1 평균 약 6초 → 레벨 60 약 2초(±40% 흔들림, 컴퓨터마다 빠르기 `pace`가 조금씩 다름).
- 시야: 약한 컴퓨터는 붙어 있는 작은 묶음 위주로 보고, 강할수록 넓은 직사각형까지 본다.
- 놓침: 레벨 1은 약 30% 확률로 한 번 볼 때 못 찾고 그냥 지나감, 레벨 60은 0%.
- 고르기: 강할수록 사과가 많은 묶음을 우선(점수), 약하면 보이는 것 중 아무거나.
- 같은 판 10번 평균(2분): 레벨 1 약 28개, 20 약 57, 30 약 70, 40 약 84, 60 약 99개. 잘하는 사람(100개 안팎)과 비슷한 수준이 최고.