Files
joke-app/docs/games/blackjack.md
EJClaw 0335a09eef 블랙잭: 카드 연출이 끝나기 전 [다음 판] 막기, 자리 폭 나누기와 카드 크기 맞추기로 겹침·잘림 없애기
- [다음 판]은 딜러 카드가 다 놓여 결과가 보인 뒤에만 눌림(혼자 하는 판도 결과를 건너뛰지 않음)
- 자리마다 테이블 폭을 무게(내 자리·스플릿 자리 더 넓게)로 나누고, 그 폭과 딜러 아래 높이에 맞춰 카드 크기 계산(최소 26px), 손패 3개 이상이면 두 줄
- 좁은 자리는 아바타 없이 이름만, 손패 정보 줄바꿈
- 엔진 테스트: 처음 나눠 주기·딜러 차례 연출 시간이 제한 시간에 더해지는지(1인 판)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 01:43:31 +09:00

121 lines
11 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.
# 블랙잭 (`blackjack`)
> 마일스톤: 2026-10 새 게임 · 인원: 최소 1 ~ 최대 7명 · 예상 시간: 약 10~20분 · 난이도: 쉬움
## 1. 개요
- 딜러(하우스)를 상대로 카드 합을 21에 가깝게 만드는 세계에서 가장 유명한 카지노 카드 게임. 플레이어끼리 겨루지 않고 각자 딜러와 승부한다.
- 놀이용 칩으로 베팅한다(docs/04 §6). 실제 돈과 무관하고 충전·환전이 없다.
- 인원: 혼자서도 딜러와 할 수 있고(1명), 카지노 테이블 자리 수에 맞춰 최대 7명까지. 딜러는 사람이 아니라 규칙대로 움직이는 하우스다.
## 2. 모드와 옵션
공식 규칙이 기본값이고, 한국에서 많이 쓰는 하우스 룰은 방 설정으로 켠다.
| 옵션 키 | 설명 | 선택지 | 기본값 |
|---|---|---|---|
| `decks` | 덱 수(슈) | 1 / 2 / 4 / 6 / 8 | 6 |
| `dealerSoft17` | 딜러 소프트 17 | stand(S17) / hit(H17) | stand |
| `blackjackPayout` | 블랙잭 배당 | 3:2 / 6:5 / 2:1 / 1:1 | 3:2 |
| `doubleRule` | 더블다운 허용 | any / 9to11 / 10to11 / none | any |
| `doubleAfterSplit` | 스플릿 후 더블(DAS) | 허용 / 불가 | 허용 |
| `splitMaxHands` | 스플릿 최대 손패 수 | 2 / 3 / 4 | 4 |
| `resplitAces` | 에이스 다시 스플릿 | 허용 / 불가 | 불가 |
| `hitSplitAces` | 에이스 스플릿 후 자유 히트 | 허용 / 한 장만 | 한 장만 |
| `surrender` | 서렌더 | none / late(레이트) | none |
| `insurance` | 인슈어런스(딜러 A) | 제공 / 없음 | 제공 |
| `charlie` | (하우스 룰) 카드 찰리 | off / six / five | off |
| `sevenTriple` | (하우스 룰) 7-7-7 보너스(3:1) | 켜기 / 끄기 | 끄기 |
| `startingChips` | 시작 칩 | 500 / 1,000 / 2,000 / 5,000 | 1,000 |
| `minBet` | 최소 베팅(단위) | 10 / 20 / 50 / 100 | 10 |
| `endCondition` | 게임 종료 | hands / lastStanding | hands |
| `handLimit` | 판 수(정해진 판 수) | 5 / 10 / 20 / 30 | 10 |
| `betSeconds` / `turnSeconds` | 베팅·행동 제한 시간(무제한 선택 가능) | 15/20/30(/60) / null | 20 |
| `handEndSeconds` | 결과 보여 주는 시간 | 3 / 4 / 6 / 10 | 4 |
## 3. 구성물
- 표준 52장 덱 × `decks`벌을 섞은 슈. 카드는 `components/cards/PlayingCard`로 그린다(그림카드·조커 실제 아트, CC0). 카드 id에는 섞을 때마다 바뀌는 접미사가 붙어 전역적으로 유일하다(`baseCard`로 벗겨 표시).
- 놀이용 칩.
## 4. 준비(셋업)
- 모두 `startingChips`로 시작. 슈를 섞는다.
- 매 판 시작 때 `minBet` 이상 걸 수 있는 사람만 참가한다. 슈가 25% 미만으로 줄면 다음 판 시작 때 새로 섞는다.
## 5. 진행 규칙
1. **베팅**: 참가자가 동시에 베팅(최소~가진 칩, 단위 `minBet`)을 건다.
2. **딜**: 참가자 2장(공개), 딜러는 1장 공개 + 1장(홀 카드) 뒤집어 받는다. A+10이면 내추럴 블랙잭.
3. **인슈어런스**(옵션): 딜러 공개 카드가 A면 참가자가 베팅 절반까지 인슈어런스를 건다. 모두 답하면 딜러가 블랙잭인지 확인한다. 딜러 공개 카드가 A/10이면 블랙잭 여부를 먼저 확인(peek)하고, 블랙잭이면 그 자리에서 정산한다.
4. **플레이**: 자리 순서대로 각자 손패에 대해
- **히트**(한 장 더), **스탠드**(멈춤)
- **더블**: 처음 두 장일 때 베팅을 두 배로 걸고 딱 한 장만 받는다(`doubleRule`·DAS 조건).
- **스플릿**: 같은 값 두 장을 두 손패로 나눈다(각각 한 장씩 받음, `splitMaxHands`까지). 에이스를 나누면 기본은 각 한 장만(`hitSplitAces`·`resplitAces`로 완화).
- **서렌더**: 레이트 서렌더가 켜져 있고 처음 두 장이면 베팅 절반만 잃고 포기.
- 21에 닿으면 자동 스탠드, 21 초과면 버스트(즉시 패). 찰리 수에 닿으면 자동 승(charlie).
5. **딜러**: 모두 끝나면 홀 카드를 공개하고 `dealerSoft17` 규칙대로 17까지(또는 소프트 17까지) 받는다. 살아 있는(스탠드) 손패가 없으면 받지 않는다.
6. **정산** 후 결과를 `handEndSeconds` 동안 보여 주고, 모두 [다음 판]을 누르면 다음 판으로.
## 6. 승패와 점수 계산
한 손패 기준(베팅 = 스테이크):
- 버스트/패: −베팅. 서렌더: −베팅/2.
- 내추럴 블랙잭: 딜러도 블랙잭이면 푸시, 아니면 `blackjackPayout`(3:2 → +1.5배).
- 딜러 블랙잭: 블랙잭이 아닌 모든 손패는 패.
- 찰리: +1배. 7-7-7 보너스(옵션): +3배.
- 그 외: 딜러 버스트거나 내 합 > 딜러 합 → +1배, 같으면 푸시, 작으면 패.
- 인슈어런스: 딜러 블랙잭이면 +2배(2:1), 아니면 −인슈어런스.
- 칩은 하우스를 상대로 오르내린다(플레이어끼리 보존되지 않음). 게임 종료 시 칩이 많은 순으로 등수, 결과 점수는 `"N 칩"`.
## 7. 지역 룰 / 하우스 룰 (옵션으로 켜고 끄기)
- **카드 찰리**(5장/6장): 버스트 없이 그 장수를 모으면 자동 승. 한국 집·동호회에서 흔한 룰.
- **7-7-7 보너스**: 7 세 장(21)이면 3:1. 한국에서 블랙잭 이상으로 쳐 주는 룰.
- **블랙잭 배당 2:1** 등 완화된 배당, **딜러 H17**, **서렌더/인슈어런스 끄기**도 방 설정으로 조절.
## 8. 엔진 설계
### 8.1 상태(State)
`packages/games/src/blackjack/types.ts`의 `BlackjackState`: `seats`(칩·상태), `shoe`(비공개)+`shoeGen`, `dealer`+`dealerDown`+`dealerBlackjack`, 참가자별 `rounds`(베팅·손패 배열·인슈어런스·ready), `order`, `turn`, `phase`(betting/insurance/playing/handEnd/finished), `handsPlayed`, 마감 시각, `log`, `result`.
### 8.2 액션
| type | payload | 누가 / 언제 | 검증 |
|---|---|---|---|
| `bet` | amount | 참가자 / 베팅 단계 | min~max, 단위 배수, 칩 충분 |
| `insurance` | take | 참가자 / 인슈어런스 단계 | 아직 미응답, (걸면)칩 충분 |
| `hit`/`stand` | — | 차례인 사람 / 플레이 | 활성 손패가 playing |
| `double` | — | 차례 / 플레이 | `canDouble` |
| `split` | — | 차례 / 플레이 | `canSplit` |
| `surrender` | — | 차례 / 플레이 | `canSurrender` |
| `ready` | — | 참가자 / 결과 단계 | 아직 미준비 |
| `timeout`/`leave` | — | 시스템 | — |
### 8.3 공개/비공개 정보 (view)
- 플레이어 손패는 모두 공개(앞면). 비공개는 **딜러 홀 카드**(공개 전)와 **슈 전체**뿐. `secretsOf`가 이 둘을 돌려주어 어떤 view에도 새지 않음을 테스트로 강제한다. 홀 카드는 공개 전 `null`로 표시.
### 8.4 랜덤 요소
- 슈 셔플(시드 RNG). (재)셔플마다 `shoeGen`을 올려 카드 id를 유일하게 유지.
### 8.5 타이머·시간 초과·연결 끊김
- 베팅 시간 초과 → 최소 베팅 자동, 인슈어런스 → 거절, 플레이 → 스탠드, 결과 → 자동 준비. 자리 비움(연속 시간 초과)은 `awaySeconds`로 짧게. `leave`는 들고 있던 단계를 자동 처리한다.
### 8.6 종료 조건과 결과(GameResult)
- `hands`: `handLimit`판을 마치면 종료. `lastStanding`: 최소 베팅이 가능한 사람이 1명 이하가 되면 종료. 칩 순 등수, `scoreText = "N 칩"`.
## 9. UI/UX
- 2026-10-17 다시 만듦(`apps/web/src/games/blackjack/board.tsx`): 모든 것을 가운데 판에서 보고 누른다(옆 패널은 칩 순위와 놀이용 칩 안내만).
- 테이블: 판 폭(최대 1180px)을 다 쓰는 반원 테이블. 위에 딜러 카드와 합, 오른쪽 위에 카드 슈(남은 벌 수), 가운데에 "BLACKJACK · 블랙잭 3:2 · 딜러 규칙" 인쇄. 참가자는 앞쪽 호를 따라 앉고(사람이 적으면 앞 가운데로 모임, 나눠 주는 순서는 오른쪽 → 왼쪽), 내 자리는 가운데 앞에 큰 카드로. 자리마다 손패(합 뱃지·건 칩·결과 뱃지), 판이 끝나면 +/- 칩, 이름표(아바타·칩). 차례 손패는 노란 테두리.
- 자리 폭: 자리마다 테이블 폭을 나눠 받고(내 자리·스플릿한 자리는 더 넓게), 그 폭과 딜러 카드 아래 높이 안에 들어가게 카드 크기를 줄인다(최소 26px). 손패가 3개 이상이면 두 줄. 폭이 좁으면 아바타는 빼고 이름만. 7명 + 스플릿, 혼자 4손패, 폰 390px 7명·4손패에서 자리끼리·딜러와 겹치지 않고 테이블 밖으로 나가지 않는 것을 확인(2026-10-17).
- 아래 조작판(흰 카드): 내 얼굴·칩·남은 시간 / 단계별 조작 / 판 정보(판 수·배당·S17/H17·슈·단축키). 내 차례면 파란 테두리와 "내 차례" 띠.
- 베팅: 숫자를 바로 적기(Enter로 걸기, 범위·단위가 틀리면 빨간 안내 후 가장 가까운 금액), −/+ 버튼, 판 위 마우스 휠(Shift는 10배)·↑↓ 키, 칩 버튼(+1·5·10·50단위), 최소·절반·최대·지난 베팅(이 기기에 저장), 막대(slider).
- 행동: 히트 H · 스탠드 S · 더블 D · 스플릿 P · 서렌더 R(키보드 단축키, 할 수 있는 것만 보임). 인슈어런스 걸기/안 함, 판 결과와 [다음 판]도 같은 자리.
- 카드 한 장씩: 서버가 여러 장을 한꺼번에 보내도(처음 나눠 주기, 딜러 차례) 화면은 실제 나눠 주는 순서(모두 1장 → 딜러 → 모두 2장 → 딜러 홀 카드)로 `BJ_DEAL_STEP_MS`(450ms) 간격으로 슈에서 날아와 놓이고, 딜러 홀 카드는 뒤집히며 펼쳐진다. 합은 놓인 카드만으로 세고, 승패·+/-와 [다음 판] 버튼은 카드가 다 놓인 뒤에 보이거나 눌린다(혼자 하는 판도 결과를 건너뛰지 못함). 엔진은 처음 나눠 주기와 딜러 차례에 그만큼(장당 450ms)을 다음 제한 시간에 더한다(`animLagMs`). 새 판이 시작되면 밀린 카드는 바로 보인다. 블랙잭·딜러 버스트 배너, 버스트 흔들림, 이기면 효과음.
- 초보자 도움: 30초 요약 3장(목표·행동·배당), `[?] 지금 할 수 있는 것`이 단계와 내 패에 맞춰 안내.
## 10. 테스트 체크리스트
- [x] `handValue` 소프트/하드 에이스, 덱 접미사 무시
- [x] 정산: 블랙잭 3:2·6:5, 푸시, 버스트, 서렌더, 딜러 버스트, 찰리, 7-7-7
- [x] 흐름: 베팅→딜→플레이→딜러→결과, 칩 비음 없음
- [x] 무작위 플레이(여러 옵션) JSON 왕복·비공개 정보 누출 없음·시간 초과 합법·종료
- [x] 봇: 1~60 레벨, 사람 1명 타임아웃 + 나머지 봇 전원이 판을 끝냄(bots.test)
- [x] 웹: 30초 요약·도움말, E2E `bun e2e/games.e2e.ts blackjack`(브라우저 2개로 한 세션)
## 11. 참고 자료
- 나무위키 "블랙잭(플레잉 카드)", 일반 카지노 공식 규칙(S17·3:2·peek), 한국 하우스 룰(5카드 찰리·7트리플).
## 12. 메모
- "블랙잭"은 일반 명칭으로 상표 문제 없음. 칩은 놀이용 점수로만 표기(돈 표현 금지, docs/04 §6).