- [다음 판]은 딜러 카드가 다 놓여 결과가 보인 뒤에만 눌림(혼자 하는 판도 결과를 건너뛰지 않음) - 자리마다 테이블 폭을 무게(내 자리·스플릿 자리 더 넓게)로 나누고, 그 폭과 딜러 아래 높이에 맞춰 카드 크기 계산(최소 26px), 손패 3개 이상이면 두 줄 - 좁은 자리는 아바타 없이 이름만, 손패 정보 줄바꿈 - 엔진 테스트: 처음 나눠 주기·딜러 차례 연출 시간이 제한 시간에 더해지는지(1인 판) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
121 lines
11 KiB
Markdown
121 lines
11 KiB
Markdown
# 블랙잭 (`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).
|