Files
joke-app/docs/games/apple.md
EJClaw b98775b0a6 사과 게임: 같은 판(17×10) 합 10 만들기 경주, 1~8명·혼자 가능, 레벨별 컴퓨터(라이브 봇)
- 규칙 모듈 packages/games/src/apple: 시드로 만든 한 판(1~9, 합 10의 배수)을 모두 각자 풀고,
  직사각형 합이 딱 10이면 지운 개수만큼 점수. 빈 칸은 합에 영향 없음, 합≠10·빈 직사각형은 거절(벌점 없음).
  3초 카운트다운(판 숨김) → 제한 시간 1/2/3분(기본 2분), 서버 시계 마감(deadline = timeoutNotBefore,
  끊긴 사람 조기 시간 초과 없음), 1초 5번 속도 제한, 더 지울 게 없으면 막힘 → 모두 막히면 조기 종료,
  나가면 맨 아래 순위·혼자 남으면 끝. 동점은 같은 순위, 결과 "사과 N개".
- view는 내 판(170자 문자열)과 모두의 점수만(남의 판 없음). findMoves는 누적합으로 가장 좁은 합 10 직사각형 전부.
- 컴퓨터: 마피아처럼 LIVE_BOT_STRATEGIES.apple. live 전략에 level 전달(서버 bots.ts, live-playout).
  레벨 따라 찾는 시간(6초→2초)·시야·놓침(쉬움 30%)·고르기가 달라짐. 2분 평균 레벨1 약 28개 ~ 레벨60 약 99개.
- 화면 apps/web/src/games/apple: SVG 사과, 포인터 드래그(마우스·터치), 합계 실시간·10이면 초록,
  낙관적 지우기와 튀어 오르는 애니메이션, 휴대폰은 판을 돌려 10열×17줄, 키보드(화살표+스페이스 두 번, Esc),
  다른 사람 점수 칩, 다크 모드, 도움말·30초 요약.
- 등록(GAMES, CATALOG, BOT_GAMES, 화면 레지스트리, 아이콘·파티 탭), 문서 docs/games/apple.md, 09 §9 라이브 봇 줄.
- 테스트: 규칙 15개(무차별 대조, 무작위 대국 1·2·5·8명), 컴퓨터 5개, 도움말 2개, 방 통합 2개(컴퓨터와 끝까지),
  E2E(PC 마우스·키보드, 휴대폰 CDP 터치, 320px, 1분 뒤 결과).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 22:20:49 +09:00

122 lines
10 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`): 더 고를 수 없고 시간이 끝날 때까지 기다린다. 모두 막히면(혹은 남은 사람이 전부 막히면) 시간 전에 끝난다(원작에는 없음, 혼자 할 때 기다리지 않게).
## 6. 승패와 점수 계산
- 점수 = 지운 사과 개수(= 내 판의 빈 칸 수).
- 순위: 점수 높은 순, **같은 점수는 같은 순위**. 중간에 나간 사람은 남은 사람 모두보다 아래(그 안에서도 점수 순).
- 결과 화면 점수 문구: `사과 N개`. `GameResult.scores` = 지운 개수.
## 7. 지역 룰 / 하우스 룰
- 없음. 원작 변형(작은 판, 시간 보너스, 연쇄 점수 등)은 넣지 않았다.
## 8. 엔진 설계
### 8.1 상태(State)
```ts
interface AppleState {
options: { timeLimitSec: 60 | 120 | 180 };
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' | 'left'>;
recent: Record<PlayerId, number[]>; // 최근 고르기 서버 시각(속도 제한)
phase: 'countdown' | 'playing' | 'ended';
countdownEndsAt: number;
endsAt: number; // countdownEndsAt + timeLimitSec
final: AppleFinal | null;
}
```
판을 숫자 배열이 아닌 170자 문자열로 둬서 상태·view가 작다.
### 8.2 액션
| type | payload | 누가 / 언제 | 검증 조건 |
|---|---|---|---|
| `select` | `r0, c0, r1, c1` (행 0~9, 열 0~16, 정수) | 게임 중인 사람, 카운트다운 끝 ~ 마감 전 | 나가지 않음, 막히지 않음, 1초에 5번 이하, 안에 사과 1개 이상, 합 = 10 |
| `tick` | — | 서버 타이머 전용(스키마에 없음) | — |
| `leave` | — | 서버(나가기) 전용 | 아직 게임 중 |
- 카운트다운이 끝났는데 방 타이머가 아직 안 돌았어도(`now ≥ countdownEndsAt`) `select`는 받는다. `apply`가 먼저 단계를 시계에 맞춘다(`catchUp`: 카운트다운 → 진행 → 마감).
- 속도 제한: 그림 맞히기와 같은 방식(`recent` 최근 5개, `ctx.now` 기준 1초). 사람은 1초에 2~3번이 한계라 정상 플레이에는 걸리지 않는다. 클라이언트가 보낸 고르기만 막고, 서버 판정은 언제나 서버 판 기준.
### 8.3 공개/비공개 정보 (view)
- 내 view: 내 판(`cells`, 170자) + 모든 사람의 점수·지운 횟수·상태 + 시간. **다른 사람 판은 보내지 않는다**(같은 판이라 숨길 정보는 없지만 view를 작게, 남의 진행 모양을 엿보지 않게).
- 관전자: 판 없이 점수만.
- 카운트다운 동안에는 누구에게도 판을 보내지 않는다(`secretsOf` = 카운트다운 중 `initial`).
### 8.4 랜덤 요소
- `setup`의 판 생성만(`ctx.rng`). 모두 같은 판이라 운의 차이가 없다. 컴퓨터 운(셔플 여러 번 중 고르기)도 적용하지 않는다(턴 게임 전략에만 적용, `luckApplies`).
### 8.5 타이머·시간 초과·연결 끊김
- `deadline`: 카운트다운 중 `countdownEndsAt`, 진행 중 `endsAt`(서버 시계). 마감 `tick`으로 끝난다. 마감 뒤 도착한 `select`는 `시간이 다 됐어요.`로 거절.
- `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개 안팎)과 비슷한 수준이 최고.