Files
joke-app/docs/games/blackjack.md
EJClaw 02c2a8508c 블랙잭 화면 다시 만듦: 모든 조작을 가운데 판에, 큰 반원 테이블, 숫자·휠·칩 버튼 베팅, 카드 한 장씩 애니메이션
- board.tsx: 판 폭(최대 1180px) 반원 테이블(딜러·카드 슈·인쇄 문구·앞쪽 호의 자리, 내 자리는 가운데 앞 크게)
- 아래 조작판: 내 칩·시간 / 베팅(숫자 입력·Enter, −/+, 마우스 휠·↑↓(Shift 10배), 칩 버튼, 최소·절반·최대·지난 베팅, 막대) / 히트 H·스탠드 S·더블 D·스플릿 P·서렌더 R / 인슈어런스 / 결과·다음 판
- 옆 패널은 칩 순위와 놀이용 칩 안내만
- 카드는 나눠 주는 순서대로 450ms 간격으로 슈에서 날아오고 딜러 홀 카드는 뒤집힘, 합·결과는 카드가 놓인 뒤에
- 엔진: 처음 나눠 주기·딜러 차례에 장당 450ms를 다음 제한 시간에 더함(animLagMs)
- PlayingCard width 속성, 도움말·문서·e2e 스크린샷

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

10 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

  • 2026-10-17 다시 만듦(apps/web/src/games/blackjack/board.tsx): 모든 것을 가운데 판에서 보고 누른다(옆 패널은 칩 순위와 놀이용 칩 안내만).
    • 테이블: 판 폭(최대 1180px)을 다 쓰는 반원 테이블. 위에 딜러 카드와 합, 오른쪽 위에 카드 슈(남은 벌 수), 가운데에 "BLACKJACK · 블랙잭 3:2 · 딜러 규칙" 인쇄. 참가자는 앞쪽 호를 따라 앉고(사람이 적으면 앞 가운데로 모임, 나눠 주는 순서는 오른쪽 → 왼쪽), 내 자리는 가운데 앞에 큰 카드로. 자리마다 손패(합 뱃지·건 칩·결과 뱃지), 판이 끝나면 +/- 칩, 이름표(아바타·칩). 차례 손패는 노란 테두리.
    • 아래 조작판(흰 카드): 내 얼굴·칩·남은 시간 / 단계별 조작 / 판 정보(판 수·배당·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. 테스트 체크리스트

  • 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).