diff --git a/docs/games/tumblin-monkeys.md b/docs/games/tumblin-monkeys.md new file mode 100644 index 0000000..5e90429 --- /dev/null +++ b/docs/games/tumblin-monkeys.md @@ -0,0 +1,117 @@ +# 텀블링 몽키 (`tumblin-monkeys`) + +> 마일스톤: 미정(새 게임 후보 52번, 사용자 확인 후 시작) · 인원: 최소 2 ~ 최대 4명 · 예상 시간: 약 5~10분 · 난이도: 쉬움 + +## 1. 개요 +- 나무 기둥 구멍에 색 막대를 꽂고 위에서 원숭이를 쏟아 걸어 둔다. 차례마다 주사위 색에 맞는 막대를 하나 뽑고, 그때 떨어진 원숭이는 뽑은 사람이 가진다. 끝났을 때 원숭이가 가장 적은 사람이 이긴다. +- **진짜 3D**로 만든다. 서버가 3D 물리 엔진으로 원숭이가 걸리고 떨어지는 것을 계산하고, 화면은 그 결과를 3D로 그대로 보여 준다(규칙을 단순화한 2D 판정은 쓰지 않는다). +- 인원 근거: 원작(Mattel/Milton Bradley) 박스 2~4인. + +## 2. 모드와 옵션 +| 옵션 키 | 설명 | 선택지 | 기본값 | +|---|---|---|---| +| `topFirst` | 나온 색 막대 중 가장 높은 층부터 뽑기(원작 규칙) | on / off | on | +| `freePick` | 주사위 없이 아무 막대나 고르기(여행용판 규칙) | on / off | off | +| `turnSec` | 차례 제한 시간(초과 시 자동 행동) | 15 / 30 / 60 | 30 | + +## 3. 구성물 +- 나무 1그루: 속이 빈 기둥, 5층, 층마다 막대 구멍 6개. +- 막대 30개: 3색(빨강·노랑·파랑) × 10개. 층마다 색마다 2개. +- 원숭이 30마리: 팔이 위로 굽은 갈고리 모양. +- 색 주사위 1개: 6면, 색마다 2면(원작 주사위 면 구성은 아직 확인하지 못했다. 확인되면 고친다). + +## 4. 준비(셋업) +1. 층마다 6개 구멍에 색마다 2개씩 RNG로 꽂는다. 구멍 각도도 층마다 RNG로 조금 돌린다. +2. 원숭이 30마리를 위쪽 입구에서 RNG 위치·방향으로 몇 마리씩 떨어뜨리고 멈출 때까지 물리 계산. +3. 기둥 밖으로 떨어진 원숭이는 다시 넣는다(원작 "떨어지면 다시 넣는다"). 최대 5번 반복, 그래도 떨어지면 그 원숭이는 위쪽 막대 위에 올려놓는다. +4. 첫 플레이어 RNG(재대국은 번갈아). + +## 5. 진행 규칙 +- 차례: **주사위 굴리기 → 막대 뽑기**. +- 굴린 색 막대만 뽑을 수 있다. `topFirst`면 그 색 중 가장 높은 층의 막대만. +- 그 색 막대가 모두 빠졌으면 차례를 넘긴다(원작 "운이 좋아 쉬어 간다"). +- 막대를 뽑으면 물리 계산으로 원숭이가 떨어진다. 기둥 아래(받침)까지 떨어진 원숭이는 뽑은 사람 것. +- `freePick`이면 주사위 없이 남은 막대 아무거나. + +## 6. 승패와 점수 계산 +- 원숭이가 모두 떨어지거나 막대가 모두 빠지면 끝난다. 막대가 다 빠졌는데 남은 원숭이(걸려 멈춘 것)는 아무도 가지지 않는다. +- 가진 원숭이가 적을수록 높은 순위. 같으면 공동 순위. 점수 문구: "원숭이 7마리". + +## 7. 지역 룰 / 하우스 룰 +- `topFirst`, `freePick`(2절). + +## 8. 엔진 설계 +### 8.1 물리 엔진과 결정성 +- **Rapier 결정적 빌드**(`@dimforge/rapier3d-deterministic-compat`, WASM)를 서버에서만 쓴다. 같은 입력이면 어느 컴퓨터에서든 같은 결과가 나오도록 만든 빌드다. +- 고정 시간 간격(1/60초), 한 번 뽑을 때 최대 6초(360걸음)까지 계산. 모든 원숭이가 멈추면 일찍 끝낸다. +- 시험(2026-10-11, 이 서버, 원숭이 30·막대 24): 한 걸음 약 0.2ms, 막대 하나 뽑을 때 수십 ms. 같은 시드로 두 번 돌리면 모든 원숭이 위치가 비트 단위로 같았다. 스냅숏 저장 → 복원 후 계산도 같았다. +- 상태에는 물리 세계를 통째로 넣지 않고(스냅숏 약 130KB), **멈춘 원숭이 위치·회전과 남은 막대**만 넣는다. 매 차례 그것으로 세계를 다시 만들어 계산한다. 결과는 이 값에만 달려 있으니 다시 보기·재시작에도 똑같다. +- 물리 모듈은 `packages/games`의 서버 전용 파일로 둔다. 웹 번들에 Rapier(약 4MB)가 들어가지 않게 웹은 이 파일을 가져오지 않는다. + +### 8.2 상태(State) +```ts +interface TmState { + players: PlayerId[]; turn: number; phase: 'roll' | 'pull' | 'over'; + sticks: { id: number; level: 0|1|2|3|4; hole: number; color: 'r'|'y'|'b'; angle: number; out: boolean }[]; + monkeys: { id: number; pos: [number, number, number]; rot: [number, number, number, number]; owner: PlayerId | null }[]; + die: 'r' | 'y' | 'b' | null; deadline: number | null; options: TmOptions; +} +``` + +### 8.3 액션 +| type | payload | 누가 / 언제 | 검증 조건 | +|---|---|---|---| +| `roll` | 없음 | 차례인 사람, `phase='roll'` | — | +| `pull` | `{ stickId }` | 차례인 사람, `phase='pull'` | 빠지지 않은 막대, 주사위 색, `topFirst`면 그 색 최고층 | + +### 8.4 공개/비공개 정보 (view) +- 모두 공개(실물도 기둥이 다 보인다). 막대·원숭이 위치, 각자 원숭이 수, 주사위. + +### 8.5 애니메이션 이벤트 +- `pull` 이벤트에 움직인 원숭이만 초당 30장면으로 위치(1mm)·회전(소수 3자리)을 담는다. 예상 크기 수~수십 KB. +- 화면은 이 장면을 그대로 재생하고, 끝나면 view의 멈춘 위치로 맞춘다. 화면에서 물리를 다시 계산하지 않는다. + +### 8.6 랜덤 요소 +- 막대 배치·각도, 원숭이 붓는 위치·방향, 주사위, 첫 플레이어. 모두 기존 시드 RNG. 물리 계산 자체에는 난수가 없다. + +### 8.7 시간 초과·연결 끊김 +- `roll` 시간 초과: 자동 굴림. `pull` 시간 초과: 뽑을 수 있는 막대 중 RNG로 하나. +- 나가면 그 사람 차례는 자동 진행, 가진 원숭이는 그대로. + +### 8.8 서버 부하 +- 물리 계산은 동기라 방 처리를 잠깐 막는다. 한 번에 최대 6초 분량(약 75ms 이하 목표)으로 묶고, 실제 측정해서 넘으면 워커 스레드로 옮긴다. +- 다시 보기는 판 전체를 다시 계산(막대 30개 × 수십 ms)한다. 기존처럼 조금씩 끊어 만든다. + +### 8.9 컴퓨터 상대 +- 낮은 단계: 뽑을 수 있는 막대 중 아무거나. +- 높은 단계: 막대마다 닿아 있는 원숭이 수(물리 엔진 접촉 정보)를 세어 적은 것을 고르고, 가장 높은 단계는 후보 2~3개만 실제로 계산해 본다(워커에서). +- 기존 `humanBest`로 늘 1등 수만 고르지 않게 한다. + +### 8.10 종료와 결과(GameResult) +- 6절. `scoreText`는 "원숭이 n마리". + +## 9. UI/UX +- **three.js**로 3D 장면을 그린다. 이 게임 화면에 들어갈 때만 따로 내려받는다(다른 게임 화면은 그대로). +- 가운데 나무, 아래 받침, 둘레에 각자 바구니(떨어진 원숭이가 쌓인다). 오른쪽 패널: 차례, 주사위, 각자 원숭이 수. +- 조작: 끌어서 나무 둘레 돌려 보기, 휠로 확대. 굴린 색 막대 중 뽑을 수 있는 것만 빛나고, 누르면 막대가 빠지는 장면 뒤 원숭이가 떨어진다. +- 원숭이·나무·막대 모양은 물리 모양(캡슐·원기둥 조합)과 같은 치수로 직접 만든다. 보이는 것과 계산이 어긋나지 않게 한다. +- 낮은 사양: 그림자·안티에일리어싱 끄기. WebGL이 없으면 "이 기기에서는 3D를 그릴 수 없어요" 안내. + +## 10. 테스트 체크리스트 +- [ ] 같은 시드·같은 행동 → 모든 원숭이 위치가 비트 단위로 같다(두 번 실행, 다시 보기). +- [ ] 셋업 후 기둥 밖 원숭이 0마리. +- [ ] 막대 하나 뽑을 때 평균 1~3마리, 처음 몇 개는 거의 안 떨어지는지(물리 모양 조정 기준). +- [ ] 색·최고층 검증, 다 빠진 색이면 차례 넘김, 시간 초과 자동 행동. +- [ ] 막대·원숭이가 모두 끝나면 종료, 동점 처리. +- [ ] 한 번 뽑기 계산 시간 상한(서버), 이벤트 크기 상한. +- [ ] 웹 번들에 Rapier가 들어가지 않는다. +- [ ] 브라우저: 3D 화면이 뜨고, 막대를 눌러 뽑고, 떨어지는 장면이 끝까지 재생된다. + +## 11. 참고 자료 +- 규칙: https://ultraboardgames.com/tumblin-monkeys/game-rules.php +- 여행용판 설명서(주사위 없이 고르기): https://service.mattel.com//instruction_sheets/GMM92-Eng.pdf +- Rapier 결정적 빌드: https://rapier.rs/docs/user_guides/javascript/determinism + +## 12. 메모 +- 친구끼리 쓰는 사이트라 원래 이름을 쓴다(README 5절). 그림·3D 모양은 직접 만든다. +- 가장 큰 위험은 물리 모양 조정이다. 첫 시험에서는 대충 만든 모양이라 붓자마자 30마리 중 21마리가 떨어졌다. 갈고리 모양·막대 간격·마찰을 맞춰 "처음엔 잘 걸리고, 뽑을수록 우르르"가 되게 하는 데 시간이 가장 많이 든다.