Files
joke-app/docs/games/blackjack.md
EJClaw 13a89a645e 새 게임 블랙잭: 딜러(하우스) 상대 1~7명·놀이용 칩. 공식 규칙(6벌 S17·블랙잭 3:2·A/10 peek·아무 두 장 더블·DAS·4손패 스플릿·에이스 한 장)을 기본값으로, 한국 하우스 룰(5·6카드 찰리, 7-7-7 보너스 3:1, 배당 6:5·2:1·1:1, H17, 더블 9~11·10~11, 에이스 자유 히트·다시 스플릿, 레이트 서렌더, 인슈어런스)을 방 설정으로
- 엔진 packages/games/src/blackjack/(options·types·rules·index·bot): 베팅→인슈어런스→플레이→딜러→결과 단계 상태 기계, 비공개는 딜러 홀 카드와 슈뿐(재셔플마다 카드 id 유일), 칩은 하우스 상대로 정산
- 컴퓨터: 기본 전략(S17 차트) + 레벨 1~60(쉬움은 딜러 흉내·인슈어런스 가끔, 어려움은 차트대로·인슈어런스 거절)
- 웹 apps/web/src/games/blackjack/: 초록 테이블·손패·단계별 버튼·방 설정 변형, 30초 요약·도움말, 표준 카드 아트 재사용
- 등록: GAMES·BOT_STRATEGIES·BOT_GAMES·CATALOG·GAME_UI·GAME_ICON·게임 탭, 문서(games/blackjack.md·README·로드맵·결정 사항), e2e/games.e2e.ts
- 검증: 엔진·봇 테스트, 무작위 플레이(여러 옵션) JSON 왕복·정보 누출 없음, 전체 테스트 2,611개·타입 검사·웹 빌드 통과, bun e2e/games.e2e.ts blackjack 통과

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-10-14 05:45:41 +09:00

8.5 KiB
Raw Blame History

블랙잭 (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

  • 가운데 초록 테이블: 위에 딜러(홀 카드 뒷면), 아래 참가자별 손패(합·베팅·결과 뱃지), 차례 손패는 노란 테두리. 오른쪽 패널: 내 칩, 단계별 버튼(베팅 ± / 히트·스탠드·더블·스플릿·서렌더 / 인슈어런스 걸기·안 함 / 다음 판), 자리별 칩 목록, 놀이용 칩 안내, 턴 타이머.
  • 초보자 도움: 30초 요약 3장(목표·행동·배당), [?] 지금 할 수 있는 것이 단계와 내 패에 맞춰 안내.

10. 테스트 체크리스트

  • handValue 소프트/하드 에이스, 덱 접미사 무시
  • 정산: 블랙잭 3:2·6:5, 푸시, 버스트, 서렌더, 딜러 버스트, 찰리, 7-7-7
  • 흐름: 베팅→딜→플레이→딜러→결과, 칩 비음 없음
  • 무작위 플레이(여러 옵션) JSON 왕복·비공개 정보 누출 없음·시간 초과 합법·종료
  • 봇: 1~60 레벨, 사람 1명 타임아웃 + 나머지 봇 전원이 판을 끝냄(bots.test)
  • 웹: 30초 요약·도움말, E2E bun e2e/games.e2e.ts blackjack(브라우저 2개로 한 세션)

11. 참고 자료

  • 나무위키 "블랙잭(플레잉 카드)", 일반 카지노 공식 규칙(S17·3:2·peek), 한국 하우스 룰(5카드 찰리·7트리플).

12. 메모

  • "블랙잭"은 일반 명칭으로 상표 문제 없음. 칩은 놀이용 점수로만 표기(돈 표현 금지, docs/04 §6).