문서: 텀블링 몽키 진짜 3D 설계(서버 Rapier 결정적 물리 + three.js)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
117
docs/games/tumblin-monkeys.md
Normal file
117
docs/games/tumblin-monkeys.md
Normal file
@@ -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마리가 떨어졌다. 갈고리 모양·막대 간격·마찰을 맞춰 "처음엔 잘 걸리고, 뽑을수록 우르르"가 되게 하는 데 시간이 가장 많이 든다.
|
||||
Reference in New Issue
Block a user