- 난이도 1~60(쉬움 1~20·보통 21~40·어려움 41~60): 넣을 때 랜덤, 방장이 대기실에서 [랜덤][쉬움][보통][어려움] 선택(botLevel) → 범위 안 무작위 - 다음 판마다 -2~+2, 처음 단계 ±5·같은 범위 안(drift); 말투는 처음 단계(>30 존댓말) - humanBest 확률을 단계별로 보간(BOT_PLAY_ANCHORS: 1·10·30·50·60) - 운(-1~+1): 카드·주사위 게임에서 시작 전에 시드 후보 1~5개를 작업 스레드에서 끝까지 둬 보고 운에 맞는 것을 고름(luck.ts, luck-worker.ts). 해시 공개는 그대로 - 결과 화면 공정성 확인에 컴퓨터별 단계·운, 섞어 본 후보 수 - 업데이트 알림: 빌드 ID meta + /api/version + welcome.build → 상단 팝업 [지금 새로고침하기] [✕] - 문서 03·04 §5.1·06 §12·07 §11.1·09 §9.1, 테스트(bot-level.room, luck, version, e2e bots·pwa) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
18 KiB
18 KiB
09. 게임 엔진 공통 설계
1. 목표
- 게임 규칙은 순수 함수 모듈로 만들고, 방·네트워크·저장은 공통 코드(GameRunner)가 맡는다. 새 게임 추가 = 규칙 모듈 + 화면 컴포넌트만 작성.
- 같은 입력이면 항상 같은 결과(결정적). 그래서 기록 재생, 버그 재현, 무작위 대국 테스트가 가능하다.
2. 인터페이스 (packages/engine/src/types.ts)
export type PlayerId = string;
export interface Rng {
next(): number; // [0,1)
int(maxExclusive: number): number;
shuffle<T>(arr: readonly T[]): T[];
}
export interface GameEvent { type: string; [k: string]: unknown } // 애니메이션·로그용, 공개 정보만
export interface GameResult {
ranking: PlayerId[][]; // [[1등], [공동 2등, 공동 2등], ...]
scores?: Record<PlayerId, number>;
scoreText?: Record<PlayerId, string>; // 결과 화면의 최종 점수 "35점", "1,200칩", "카드 12장" (점수 없는 게임은 생략)
summary: string; // "흑 5목 완성으로 OO님 승리"
reason: 'normal' | 'resign' | 'timeout' | 'abandoned' | 'draw-agreed';
}
export interface GameDefinition<S, A, V, O> {
id: string;
nameKo: string;
minPlayers: number;
maxPlayers: number;
stateVersion: number;
defaultOptions: O;
optionsSchema: ZodType<O>;
actionSchema: ZodType<A>; // 서버 입력 검증(모양만), 규칙 검증은 validate
playersFor?(options: O): { min: number; max: number }; // 모드별 인원이 다를 때
setup(ctx: { players: PlayerId[]; options: O; rng: Rng; now: number; gameNo?: number }): S; // players는 방장 자리부터 시계 방향
validate(state: S, actor: PlayerId, action: A, ctx?: { now: number }): { ok: true } | { ok: false; reason: string }; // now: 서버가 넘김(레이트 리밋용)
apply(state: S, actor: PlayerId, action: A, ctx: { rng: Rng; now: number }): { state: S; events: GameEvent[] };
view(state: S, viewer: PlayerId | null): V;
activePlayers(state: S): PlayerId[];
deadline?(state: S): number | null;
timeoutPlayers?(state: S): PlayerId[]; // 마감이 적용되는 사람(기본: activePlayers)
timeoutNotBefore?(state: S): number | null; // 자리 비움이어도 이 시각 전에는 시간 초과 처리 안 함(실시간 게임)
disconnectGraceMs?(state: S): number | null; // 연결 끊긴 마감 대상의 유예 시간(ms), null이면 방의 graceSec
isStreamAction?(action: A): boolean; // 그림 획처럼 잦은 행동: 이벤트만 'stream' 메시지로 중계, 저장은 묶어서
syncView?(state: S, viewer: PlayerId | null): V; // (재)접속·sync 때 보내는 전체 view(기본: view)
onTimeout(state: S, player: PlayerId): A;
onLeave?(state: S, player: PlayerId): A | null; // 기권·자리 비움 처리
result(state: S): GameResult | null;
migrate?(old: unknown, fromVersion: number): S;
}
규칙
- 옵션 메타 필수:
optionsSchema의 모든 항목에.meta({ title: '한국어 제목', labels: { 값: '표시 이름' } })를 붙인다. 관리자 사이트가 이 정보로 입력 화면을 자동으로 만든다(14-admin.md4절). 규칙 코드 안의 고정 숫자도 가능한 한 옵션으로 꺼낸다. apply는validate가 통과한 행동만 받는다.apply안에서도 불변식이 깨지면 예외를 던진다(GameRunner가 잡음).- 상태는 불변 객체처럼 다룬다(새 객체 반환). 구현은
structuredClone후 수정해도 된다(상태가 작음). - 상태는 JSON으로 직렬화 가능해야 한다(Map/Set/클래스 금지). 저장·복구가 그대로 된다.
view는 숨김 정보를 빼고, 화면에 필요한 계산 결과(예: 둘 수 있는 칸 목록legal, 현재 족보 이름)를 넣어 준다. 클라이언트가 규칙을 몰라도 그릴 수 있어야 한다.- 차례 확인을 포함한 모든 합법성 판단은
validate가 한다.activePlayers는 "지금 행동을 기다리는 사람"(화면 표시·타이머용)일 뿐, 러너가 이것으로 행동을 막지 않는다(기권·무르기 요청처럼 차례와 무관한 행동이 있기 때문). onTimeout이 만드는 시스템 전용 행동(예:{type:'timeout'})은actionSchema에 넣지 않는다. 그래서 클라이언트는 보낼 수 없고 서버 타이머만 만든다.- 시간은
ctx.now로만 받는다. 타이머가 필요한 게임은 상태에turnStartedAt,timeLeft같은 값을 둔다.
3. 결정적 난수
- 알고리즘: ChaCha20(RFC 8439, 상태
[키 8개, 블록 번호, 쓴 개수, 0]). 시드는 서버가crypto.getRandomValues로 256비트 생성(2026-10-11). 32비트 4개 상태·128비트 시드는 예전 sfc32로 읽어 옛 게임 다시 보기·저장된 판이 그대로다(테스트 시드seedN도 sfc32). - GameRunner가 저장된 RNG 상태로
Rng를 만들어ctx.rng로 넘기고, 호출이 끝나면 새 RNG 상태를 저장한다. 게임 모듈은 RNG 상태를 직접 들고 있지 않는다. - 셔플은 Fisher–Yates,
rng.int는 거부 샘플링으로 편향 없이.
4. GameRunner (서버, apps/server/src/rooms/game-runner.ts)
handleAction(actor, cs, action):
if dedupe(actor, cs) return
parsed = def.actionSchema.safeParse(action) → 실패: reject
v = def.validate(state, actor, parsed) → 실패: reject(v.reason) (차례 확인 포함)
{state', events} = def.apply(state, actor, parsed, {rng, now}) (try/catch)
persist(log + state') (동기 트랜잭션)
state = state'; seq++
broadcast views; reschedule timer; if result → finish()
onTimer():
마감 = min(def.deadline(state), 연결 끊긴 사람이면 끊긴 시각 + 방의 유예 시간)
for p in timeoutPlayers where 마감 지남:
a = def.onTimeout(state, p) → handleAction(p, system, a) 와 같은 경로(검증 포함)
- "언제나 행동 가능" 행동(할리갈리 종 치기, 도블 정답, 마작 울기 선언, 무르기 요청)은
validate가 허용하면 된다(특수 경로 없음). - 시간 설정(한 수 제한, 개인 시계 등)은 게임 옵션으로 각 게임 문서에서 정한다. 방 설정에는 연결 끊김 유예 시간(
graceSec, 기본 60초)만 있다. - 서버 재시작 후에는 마감을 "복구 시각 + 30초" 이전에는 집행하지 않는다(재접속 시간).
5. 공통 유틸 (packages/engine)
| 모듈 | 내용 |
|---|---|
rng.ts |
ChaCha20(새 게임)·sfc32(옛 게임), 시드 생성/직렬화, shuffle |
cards/standard.ts |
52장 + 조커 트럼프 카드 ID("S-A", "H-10", "JK1"), 무늬·숫자 파싱 |
cards/hwatu.ts |
화투 48장(+보너스패) ID와 속성(월, 광/열끗/띠/피, 쌍피 등). 섯다·고스톱 공용 |
turns.ts |
시계 방향 다음 사람, 살아 있는 사람만 돌기, 선 정하기 |
betting.ts |
베팅 라운드 엔진: 한국식(삥/체크/콜/따당/쿼터/하프/풀/다이) + 노리밋/팟리밋. 사이드 팟 계산. 포커 모든 모드와 섯다가 공유 |
grid.ts |
격자 좌표, 방향, 연속 개수 세기(오목·오셀로·바둑 공용) |
testing.ts |
무작위 대국 러너, 정보 유출 검사기, 직렬화 왕복 검사 |
6. 클라이언트 쪽 게임 모듈 (apps/web/src/games/<id>/)
export interface GameUI<V> {
id: string;
Board: React.ComponentType<{ view: V; me: PlayerId | null; act: (a: unknown) => void; pending: boolean }>;
statusText(view: V, me: PlayerId | null): string; // "내 차례예요" 등
OptionsForm?: React.ComponentType<...>; // 대기실 옵션(기본은 스키마로 자동 생성)
Rules: React.ComponentType; // 규칙 설명
}
games/registry.ts에서lazy(() => import('./omok'))형태로 등록 → 게임 화면 코드는 그 게임을 할 때만 내려받는다.- 게임 목록 메타데이터(이름, 인원, 썸네일, 난이도, 예상 시간)는
packages/shared/src/catalog.ts하나에서 관리하고 서버·웹이 같이 쓴다.
7. 공통 테스트 도구 (모든 게임 필수)
- 규칙 단위 테스트: 게임 문서 10절의 시나리오를 그대로 테스트로.
- 무작위 대국: 시드 1,000개 × 게임 끝까지 무작위 합법 행동(각 게임은 테스트용
legalActions(state, p)제공). 매 단계 확인:- 예외 없음,
apply5ms 이내 - JSON 직렬화 왕복 후 같은 상태
- 같은 시드·같은 행동이면 같은 결과(결정성)
- 게임이 상한 턴 안에 끝남
- 게임별 불변식(카드 총수 보존, 칩 총합 보존 등)
- 예외 없음,
- 정보 유출 검사: 매 단계 각 플레이어 view의 JSON에 남의 비공개 카드 ID가 없는지(게임이
secretsOf(state, player)를 테스트용으로 제공). - 시간 초과 테스트: 모든 상태에서
onTimeout이 합법 행동을 돌려주는지.
8. 게임 기록 다시 보기 (apps/server/src/rooms/replay.ts, apps/web/src/pages/ReplayPage.tsx)
- 다시 만들기: 끝난 게임을 공개된 시드 +
room_log의act/auto기록으로 처음부터 다시 돌린다.setup(시작 시각)과 각apply(그 행동을 적용한 정확한now, 로그의at)를 방과 똑같이 부르고 RNG도 이어서 쓰므로 결과가 방에서 끝난 상태와 한 글자도 다르지 않다.start로그에stateVersion을 남긴다. - 보이는 것: 그 판에 앉았던 플레이어만 볼 수 있고(관전자·남은 403), 각자 게임 중에 받던 자기
view(있으면syncView)만 받는다. 시드와 원본 로그는 서버 밖으로 나가지 않는다. 응답은private, no-store. - 장면: 스트리밍 행동(그림 맞히기 선)이 아닌 행동 하나가 한 장면. 첫 장면만 view 전체, 나머지는 앞 장면과의 차이(
packages/shared/src/view-patch.ts)만 보낸다. 다시 만든 결과가 저장된 결과와 다르면 보여 주지 않는다. - 같은 결과인지 비교(2026-10-11): 순위·점수·끝난 이유·요약만 비교한다(
sameOutcome). 저장할 때 붙는practice표시와 화면용scoreText는 뺀다. 전에는 JSON 전체를 비교해서 컴퓨터와 한 판, 그리고 점수 문구가 생기기 전에 끝난 점수 게임(라스베가스·요트·할리갈리·도블 등)이 모두 "다시 볼 수 없어요"였다(운영 DB 44판 중 21판 → 0판). 예전 게임은 다시 만든scoreText를 붙여 보여 준다. - 못 보는 경우(410, 한국어 안내): 90일이 지나 로그가 지워짐, 그 뒤로 게임 규칙 버전(
stateVersion)이 바뀜, 다시 만든 결과가 다름. - API:
GET /api/me/games?before=&limit=(내가 끝까지 한 게임, 최신순),GET /api/replays/:gamePk. 다시 만든 결과는 잠깐(10분, 32개) 캐시하고, 한 번에 하나씩 조금씩 끊어 만들어 방 처리를 막지 않는다. - 화면: 게임의
Board/Side를 그대로 쓰되 읽기 전용(act는 아무것도 안 함, 판 안의 누르기·키 입력은 막음). 처음 / 이전 / 재생·멈춤 / 다음 / 끝 버튼, 슬라이더, "n번째 / 전체 n번", 장면 설명(누가 움직였는지, 자동 진행). 키보드 ←/→/Home/End. 들어가는 곳: 결과 화면 ▶ 다시 보기, 내 정보 › 내 게임 기록 [다시 보기]. - 테스트: 모든 게임을 실제
Room으로 끝까지(무작위 행동, 시간 초과, 나가기) 둔 뒤 다시 만든 상태·결과가 같은지, 모든 장면이 그 플레이어가 받은 view와 같은지(replay.test.ts), 권한(replay-api.test.ts), 브라우저(e2e/replay.e2e.ts).
9. 컴퓨터 상대 (packages/games/src/bots/, 06 §12)
- 게임마다
<게임>/bot.ts의 전략 하나:(입력: { me, view, legal, random }) => 행동.view는view(state, me),legal은legalActions(state, me). 게임 상태는 넘기지 않는다(비공개 정보 차단). decideBotAction이 고른 수를validate로 다시 검사하고, 틀리면 다른 합법 수로 바꾼다. 서버는 그래도 실패하면 게임의onTimeout행동을 쓴다.- 라이브 봇(
LIVE_BOT_STRATEGIES, 마피아): 모두가 동시에 시계에 맞춰 움직이고 말하는 게임. 전략은({ me, view, now, persona, names, memory }) => { action | null, next }로, 서버가 컴퓨터마다 따로nextms 뒤에 다시 묻는다.persona(bots/persona.ts)는 똑똑한 편/허술한 편(§9.1)과 빠르기,memory는 이번 판에 이미 한 일(서버가 다시 켜지면 비워짐). 테스트 도우미bots/live-playout.ts. - 테스트(
bots/bots.test.ts): 게임마다 "사람 1명은 시간 초과만, 나머지는 컴퓨터"와 "컴퓨터끼리" 판을 끝까지 돌려, 모든 수가 합법이고 컴퓨터 때문에 멈추지 않으며 한 수가 충분히 빠른지 본다.
9.1 컴퓨터 난이도와 난수 (2026-10-11)
난수. 서버가 고르는 것은 모두 OS 보안 난수(crypto.getRandomValues)를 쓴다. Math.random은 서버에 남아 있지 않다.
| 무엇 | 난수 |
|---|---|
| 카드 섞기·주사위·타일 뽑기 | 판마다 256비트 OS 시드 + ChaCha20(§3). 컴퓨터가 있으면 운에 맞춰 후보 시드 중 하나(04 §5.1) |
| 컴퓨터의 수 고르기, 생각 시간, 채팅 여부, 방 코드, 마감 유예 | secureRandom()(packages/engine/src/rng.ts, OS 난수 53비트 실수) |
| 컴퓨터의 난이도 단계·운, 다음 판의 단계 변화 | secureRandom() (apps/server/src/rooms/bot-profile.ts) |
브라우저의 닉네임 추천과 재연결 대기 시간은 보안과 상관없어 그대로 둔다.
난이도 1~60단계. 1이 가장 약하고 60이 가장 세다.
| 이름 | 단계 | 고르는 법 |
|---|---|---|
| 랜덤 (처음) | 1~60 | 컴퓨터를 넣을 때 고르게 무작위 |
| 쉬움 | 1~20 | 방장이 [쉬움]을 누르면 이 안에서 무작위 |
| 보통 | 21~40 | 〃 |
| 어려움 | 41~60 | 〃 |
- 방은 컴퓨터마다
{ pick, base, level, luck, played }를 저장한다(RoomSnapshot.bots, 서버가 다시 켜져도 그대로).base는 고를 때 나온 단계,level은 지금 단계. - 판마다 조금씩: 첫 판은
base그대로, 그다음 판부터 시작할 때마다 -2~+2단계 움직인다(drift). 단,base±5 안, 그리고base가 속한 범위(쉬움/보통/어려움) 안에서만. 그래서 60은 다음 판에 58이 될 수는 있어도 41이 되지는 않는다. 난이도를 다시 고르면 새base에서 다시 시작한다. - 보이는 것: 대기실에는 방장이 고른 이름(랜덤/쉬움/보통/어려움)만, 게임이 끝나면 결과 화면 "공정성 확인"에 그 판의 단계와 운이 보인다(
RoomView.lastBots). 게임 중에는 단계를 보내지 않는다. - 말투(
smart):base가 30보다 크면 똑똑한 편·존댓말, 아니면 허술한 편·반말. 랜덤으로 넣은 컴퓨터는 반반이고(마피아 §13 그대로), 쉬움은 모두 반말, 어려움은 모두 존댓말이다. 판마다 단계가 움직여도 말투는 바뀌지 않는다. - 저장된 단계가 없는 예전 방의 컴퓨터는 id의 무작위 부분으로 단계를 정한다(
idLevel). - 운: 컴퓨터마다 -1~+1. 카드·패·주사위 게임에서 시작 배분에 영향을 준다. 방법과 효과는 04 §5.1.
사람처럼 두기(humanBest, bots/policy.ts). 오목·체스·장기·오델로·바둑 컴퓨터는 수마다 점수를 매긴 뒤 늘 1등 수만 두지 않는다. 한 수마다 확률(botPlay(단계))은 아래 기준 단계(BOT_PLAY_ANCHORS) 사이를 단계에 따라 고르게 이어 붙인 값이다. 각 범위의 가운데(10·30·50)는 예전 쉬움·보통·어려움과 같다.
| 단계 | 1등 수 | 비슷한 수 (점수 차 small×창 이내, 상위 5개) |
사고 (점수 차 small×8 이내, 상위 8개) |
꼭 둬야 할 수를 놓침 |
|---|---|---|---|---|
| 1 | 약 45% | 45% (창 ×3) | 10% | 20% |
| 10 | 약 59% | 35% (창 ×2) | 6% | 12% |
| 30 | 약 78% | 20% (창 ×1) | 2% | 3% |
| 50 | 약 91.5% | 8% (창 ×0.5) | 0.5% | 0% |
| 60 | 약 97% | 3% (창 ×0.25) | 0% | 0% |
- 범위 안에 고를 다른 수가 없으면 1등 수를 둔다. 아무리 사고여도
small×8보다 나쁜 수(퀸을 그냥 주기, 바로 지는 수 등)는 두지 않는다. - "꼭 둬야 할 수"는 점수가
critical이상인 1등 수다. 놓치면 그다음으로 좋아 보이는 수 3개 중 하나를 둔다. - 게임별 기준:
| 게임 | small (작은 실수 한 번의 크기) |
critical (꼭 둬야 할 수) |
|---|---|---|
| 오목 | 150 (열린 2 하나 정도) | 50,000: 오목 완성, 상대 오목 막기 |
| 체스 | 40 (폰 0.4개) | 100,000: 메이트 |
| 장기 | 40 (기물 점수 0.4) | 100,000: 외통, 이기는 점수 판정 |
| 오델로 | 3 (상대가 둘 곳 2개 더) | 90: 빈 귀 잡기 |
| 바둑 | 1.5 (모양 점수) | 24: 돌 3개 이상 따내기·살리기 |
- 다른 게임(카드·주사위 등)은 수 고르기는 그대로이고, 대신 컴퓨터의 운이 배분에 영향을 준다(04 §5.1). 생각 시간은 06 §12대로 가끔(12%) 1~3초 더 멈칫한다.
- 컴퓨터끼리 대국(무작위 시드, 선후 번갈아, 단계 50·30·10으로 잰 값): 오목 어려움 대 쉬움 100판 84승 16패, 보통 대 쉬움 60판 42승 18패, 어려움 대 예전(늘 1등 수) 60판 34승 26패. 체스 어려움 대 쉬움 40판 18승 10패 12무.
- 테스트:
bots/level.test.ts(보안 난수 분포, id 단계 1~60 고르게·말투 반반,botPlay기준값·단조,humanBest확률),bots/bots.test.ts(다섯 게임 모두 1단계·60단계 컴퓨터끼리 끝까지 둠),apps/server/src/rooms/bot-level.room.test.ts(범위별 단계, 방장만 고름, 판마다 변화 폭, 끝난 뒤에만 공개, 재시작 뒤 유지).