Files
joke-app/docs/games/tumblin-monkeys.md

8.5 KiB
Raw Blame History

텀블링 몽키 (tumblin-monkeys)

마일스톤: 미정(사용자 확인 후 시작) · 인원: 최소 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, docs/reports/tumblin-monkeys-physics-20261011.md): 한 걸음 약 0.2ms, 막대 하나 평균 약 11~14ms(상한 600걸음 ≈ 120ms). 같은 시드로 두 번 돌린 최종 위치 해시가 같았고, 스냅숏 저장 → 복원 후 계산도 같았다. 실제 모양으로 바꾸면 다시 잰다.
  • 상태에는 물리 세계를 통째로 넣지 않고(스냅숏 약 130KB), 멈춘 원숭이 위치·회전과 남은 막대만 넣는다. 매 차례 그것으로 세계를 다시 만들어 계산한다. 결과는 이 값에만 달려 있으니 다시 보기·재시작에도 똑같다.
  • 물리 모듈은 packages/games의 서버 전용 파일로 둔다. 웹 번들에 Rapier(약 4MB)가 들어가지 않게 웹은 이 파일을 가져오지 않는다.

8.2 상태(State)

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. 참고 자료

12. 메모

  • 친구끼리 쓰는 사이트라 원래 이름을 쓴다(README 5절). 그림·3D 모양은 직접 만든다.
  • 가장 큰 위험은 물리 모양 조정이다. 첫 시험에서는 대충 만든 모양이라 붓자마자 30마리 중 21마리가 떨어졌다. 갈고리 모양·막대 간격·마찰을 맞춰 "처음엔 잘 걸리고, 뽑을수록 우르르"가 되게 하는 데 시간이 가장 많이 든다.