클라이언트 결정론적 lockstep 전환 조정

[dev-yunseong]

배경

현재 game server가 20 FPS 게임 시뮬레이션, 물리, 마법, 하수인 행동과 상태 전송을 모두 담당합니다. 이 구조는 서버 CPU 비용과 상태 동기화 트래픽을 키우고, A* 길찾기처럼 계산량이 큰 client-side gameplay 기능 도입을 제한합니다.

2026-04의 lockstep 구현은 client/server Phase 3를 한 번에 전환했고 자동 결정론 검증과 호환 전환 구간이 부족한 상태에서 merge 후 revert되었습니다. 기존 설계와 코드는 참고하되 그대로 재적용하지 않습니다.

목표

• PVP의 모든 client가 동일한 초기 상태와 확정 입력으로 동일한 deterministic simulation을 실행합니다.
• game server는 versioned session bootstrap, frame input 수집/정렬/중계, peer hash 비교, 연결/결과 저장만 담당합니다.
• Practice/PVE는 단일 client simulation과 결과를 신뢰합니다.
• 단계별 feature flag와 구 protocol 병행으로 rollback 가능한 전환을 수행합니다.

공유 계약

SessionStart

• protocolVersion, simulationVersion, configVersion
• rngSeed, initialFrame
• 플레이어/deck과 결정적으로 정렬된 initial prefab spawn 목록
• PVE scenario event 목록

FrameSubmission

• frameNum, userId, 순서가 고정된 inputs
• previousFrameHash

ConfirmedFrame

• frameNum, canonical ordering을 적용한 모든 player inputs
• 제출된 peer hashes와 hashMatched

서버는 simulation 정답 hash를 계산하지 않습니다. PVP에서 같은 frame의 client hash를 비교해 desync만 탐지합니다. 단일 client session에서는 hash/result를 신뢰합니다.

결정론 규칙

• 고정 timestep과 fixed-point 수학
• session seed 기반 단일 deterministic RNG 규약
• frame/user/input/object/component 실행 순서 명시
• runtime/locale에 독립적인 canonical snapshot serialization과 hash
• Unity MonoBehaviour, Transform, Unity Physics를 simulation core에서 분리

단계

1. Client deterministic foundation과 BEPU integer physics Unity 2022/WebGL spike
2. Game server versioned relay/hash protocol을 기존 protocol과 병행
3. Client gameplay/PVE/Practice 포팅 및 two-client golden replay 검증
4. session별 feature flag cutover
5. 안정화 후 server simulation과 구 state DTO 제거

브랜치 및 worktree 정책

• root, client, game 각각 장기 통합 브랜치 feature/lockstep을 둡니다.
• 각 child issue는 별도 Git worktree와 feature/<issue-number> 브랜치에서 작업합니다.
• child PR의 base는 main이 아니라 해당 저장소의 feature/lockstep입니다.
• 구현 중에는 client/game child branch를 통합 브랜치에만 합치고 main에는 합치지 않습니다.
• 각 통합 브랜치는 주기적으로 최신 main 변경을 반영합니다.
• client/game integration commit을 먼저 push한 뒤 root feature/lockstep에서 published submodule pointer만 기록합니다.
• deterministic replay, PVP, Practice, PVE, WebGL, rollback, cutover 검증이 모두 통과한 뒤에만 client/game feature/lockstep을 각 main에 합칩니다.
• 마지막으로 root submodule pointer를 검증한 뒤 root feature/lockstep을 root main에 합칩니다.

Child issues

• 결정론적 simulation core와 physics 기반 검증 WordOnlineClient#347 — deterministic foundation/physics spike
• versioned lockstep input relay와 peer hash 비교 추가 WordOnlineServer#291 — versioned relay/hash protocol
• 게임 로직을 deterministic client simulation으로 포팅 WordOnlineClient#348 — gameplay/PVE/Practice port
• lockstep 전환 후 authoritative simulation 제거 WordOnlineServer#290 — cutover and authoritative simulation cleanup

완료 조건

• 같은 fixture/seed/input log를 독립 실행한 두 simulation이 모든 checkpoint에서 같은 hash를 생성합니다.
• PVP 두 client가 지연/재전송 조건에서도 같은 confirmed frame을 한 번만 적용합니다.
• hash mismatch가 frame/session/client 정보와 함께 탐지되고 정책대로 session을 중단합니다.
• Practice/PVE가 server simulation 없이 시작, prefab spawn, 게임 종료, 결과 저장까지 완료됩니다.
• 구 protocol로 즉시 rollback 가능한 호환 기간과 release order가 문서화됩니다.
• client/game child issue와 PR이 이 coordination issue를 참조합니다.

비목표

• 서버가 client simulation을 재실행해 정답을 판정하는 authoritative validation
• 완전한 치팅 방지
• 첫 단계에서 모든 기존 simulation 코드를 삭제하는 big-bang 전환

관련 과거 작업

• Server #232
• Client #265
• Server PR #235
• Client PR #274 및 revert PR #275