Files
joke-app/docs/09-game-engine.md
EJClaw b98775b0a6 사과 게임: 같은 판(17×10) 합 10 만들기 경주, 1~8명·혼자 가능, 레벨별 컴퓨터(라이브 봇)
- 규칙 모듈 packages/games/src/apple: 시드로 만든 한 판(1~9, 합 10의 배수)을 모두 각자 풀고,
  직사각형 합이 딱 10이면 지운 개수만큼 점수. 빈 칸은 합에 영향 없음, 합≠10·빈 직사각형은 거절(벌점 없음).
  3초 카운트다운(판 숨김) → 제한 시간 1/2/3분(기본 2분), 서버 시계 마감(deadline = timeoutNotBefore,
  끊긴 사람 조기 시간 초과 없음), 1초 5번 속도 제한, 더 지울 게 없으면 막힘 → 모두 막히면 조기 종료,
  나가면 맨 아래 순위·혼자 남으면 끝. 동점은 같은 순위, 결과 "사과 N개".
- view는 내 판(170자 문자열)과 모두의 점수만(남의 판 없음). findMoves는 누적합으로 가장 좁은 합 10 직사각형 전부.
- 컴퓨터: 마피아처럼 LIVE_BOT_STRATEGIES.apple. live 전략에 level 전달(서버 bots.ts, live-playout).
  레벨 따라 찾는 시간(6초→2초)·시야·놓침(쉬움 30%)·고르기가 달라짐. 2분 평균 레벨1 약 28개 ~ 레벨60 약 99개.
- 화면 apps/web/src/games/apple: SVG 사과, 포인터 드래그(마우스·터치), 합계 실시간·10이면 초록,
  낙관적 지우기와 튀어 오르는 애니메이션, 휴대폰은 판을 돌려 10열×17줄, 키보드(화살표+스페이스 두 번, Esc),
  다른 사람 점수 칩, 다크 모드, 도움말·30초 요약.
- 등록(GAMES, CATALOG, BOT_GAMES, 화면 레지스트리, 아이콘·파티 탭), 문서 docs/games/apple.md, 09 §9 라이브 봇 줄.
- 테스트: 규칙 15개(무차별 대조, 무작위 대국 1·2·5·8명), 컴퓨터 5개, 도움말 2개, 방 통합 2개(컴퓨터와 끝까지),
  E2E(PC 마우스·키보드, 휴대폰 CDP 터치, 320px, 1분 뒤 결과).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 22:20:49 +09:00

194 lines
18 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.
# 09. 게임 엔진 공통 설계
## 1. 목표
- 게임 규칙은 **순수 함수 모듈**로 만들고, 방·네트워크·저장은 공통 코드(GameRunner)가 맡는다. 새 게임 추가 = 규칙 모듈 + 화면 컴포넌트만 작성.
- 같은 입력이면 항상 같은 결과(결정적). 그래서 기록 재생, 버그 재현, 무작위 대국 테스트가 가능하다.
## 2. 인터페이스 (`packages/engine/src/types.ts`)
```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.md` 4절). 규칙 코드 안의 고정 숫자도 가능한 한 옵션으로 꺼낸다.
- `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>/`)
```ts
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. 공통 테스트 도구 (모든 게임 필수)
1. **규칙 단위 테스트**: 게임 문서 10절의 시나리오를 그대로 테스트로.
2. **무작위 대국**: 시드 1,000개 × 게임 끝까지 무작위 합법 행동(각 게임은 테스트용 `legalActions(state, p)` 제공). 매 단계 확인:
- 예외 없음, `apply` 5ms 이내
- JSON 직렬화 왕복 후 같은 상태
- 같은 시드·같은 행동이면 같은 결과(결정성)
- 게임이 상한 턴 안에 끝남
- 게임별 불변식(카드 총수 보존, 칩 총합 보존 등)
3. **정보 유출 검사**: 매 단계 각 플레이어 view의 JSON에 남의 비공개 카드 ID가 없는지(게임이 `secretsOf(state, player)`를 테스트용으로 제공).
4. **시간 초과 테스트**: 모든 상태에서 `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. 들어가는 곳: 결과 화면 [▶ 다시 보기](`RoomView.lastGamePk`), 내 정보 › 내 게임 기록 [다시 보기].
- **테스트**: 모든 게임을 실제 `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, level, names, memory }) => { action | null, next }`로, 서버가 컴퓨터마다 따로 `next` ms 뒤에 다시 묻는다. `persona`(`bots/persona.ts`)는 똑똑한 편/허술한 편(§9.1)과 빠르기, `level`은 지금 레벨(1~60), `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`(범위별 단계, 방장만 고름, 판마다 변화 폭, 끝난 뒤에만 공개, 재시작 뒤 유지).