HANPAN — Additive 씬 전환 안정화 스냅샷

1. 주요 변경사항

• GameManager가 추가되어 Boot 이후 Matching을 Additive로 올리고, 앱 생명주기 단위의 씬 전환 책임을 갖기 시작했다.
• NetworkSceneTransition이 Single 로드에서 NGO Additive 로드·언로드 흐름으로 변경되었다. 개인 복귀와 전체 강제 복귀를 분리하려는 방향은 타당하다.
• BlackAndWhite 게임 진입 시 Matching 씬을 plain SceneManager로 언로드하고, 종료 버튼은 로컬 복귀 경로를 사용하도록 수정되었다.
• Docs/SceneArchitecture.md가 큰 폭으로 갱신되어 씬 구조, GC 발생 구간, 필수 셋업을 설명하기 시작했다.

2. 코드 품질 리뷰

이번 변경은 방향 자체는 좋다. Boot, Matching, Game을 명시적인 상태로 보고 Additive 씬 스택을 관리하려는 판단은 Unity 멀티플레이 프로젝트에서 필요한 전환이다. 특히 Lobby와 Room을 씬 전환이 아니라 SetActive로 다루는 선택은 GC 스파이크를 줄이는 데 합리적이다.

다만 현재 구현은 “동작하는 시나리오”에 맞춰 빠르게 봉합된 흔적이 강하다. 가장 위험한 지점은 강제 복귀가 ClientRpc 내부의 서버 조건문에 걸려 있다는 점이다.

void AbortGameClientRpc()
{
    OnGameAborted?.Invoke();
    if (IsServer) NetworkSceneTransition.ReturnToMatching(returnToRoom: false);
}

Host 환경에서는 우연히 맞을 수 있지만, dedicated server나 실행 모드가 달라지면 서버가 이 ClientRpc 본문을 실행하지 않는 구조가 될 수 있다. 네트워크 씬 전환은 클라이언트 알림 함수 안에서 역으로 발생시키면 안 된다. 서버 권한 함수에서 ReturnToMatching을 먼저 호출하고, 클라이언트에는 UI 정리만 RPC로 내려야 한다.

또 하나의 위험 신호는 조용한 실패다. GameManager.Instance?.ReturnToMatchingLocal(...)는 Instance가 없을 때 버튼이 아무 일도 하지 않는다. Boot에서는 null을 에러로 찍는데, 게임 종료 UI에서는 침묵한다. 같은 실패를 한쪽은 에러, 한쪽은 무시로 처리하면 QA가 재현 로그를 확보하기 어렵다. GameManager는 Additive 중복 로드 방지, 로딩 중 플래그, 실패 로그를 가진 단일 진입점으로 보강해야 한다.

3. 진행도 평가

이전 대비 기술 아키텍처는 분명히 전진했다. 씬 전환 방향이 문서와 코드에 들어왔고, Player1 먼저 퇴장 시 Player2 복귀 불가 같은 실제 멀티플레이 버그를 해결하려는 커밋도 확인된다. 그러나 8개 커밋 대부분이 fix이고, 핵심 변경 영역이 NGO 씬 관리라 리스크가 작지 않다.

현재 진행도는 42%로 본다. 플레이 가능한 핵심 루프 일부는 존재하지만, 반복 게임 시작·개인 복귀·상대 퇴장·강제 중단 같은 멀티플레이 필수 경로가 자동 검증되지 않았다. 이 상태에서 미니게임을 늘리면 디버깅 비용이 급격히 증가한다.

4. 다음 권장사항

• AbortGameClientRpc에서 씬 전환을 빼고, 서버 권한 함수가 직접 NetworkSceneTransition.ReturnToMatching을 호출하게 수정해야 한다.
• GameManager.ReturnToMatchingLocal에 중복 로드 방지, 로딩 중 상태, null 실패 로그를 추가해야 한다.
• 2인 반복 플레이 PlayMode 테스트를 작성해야 한다. 최소한 시작→개인 복귀→재시작→강제 중단의 씬 스택을 검증해야 한다.
• Docs/SceneArchitecture.md의 서버 RPC 복귀 설명과 실제 로컬 복귀 코드 불일치를 바로잡아야 한다.
• 레벨·HUD·입력 상태 전이 사양은 계속 비어 있다. 다음 기능 확장 전에 테스트 가능한 표로 작성해야 한다.

5. 문서화 상태

design 점수는 3점이다. 이번 커밋은 씬 아키텍처 중심이며, 게임 컨셉·코어 루프·플레이어 경험 목표를 보강한 흔적은 거의 없다. 게임의 재미를 판단할 문서가 아직 부족하다.

technical 점수는 6점이다. Docs/SceneArchitecture.md는 신규 유입자가 큰 구조를 파악할 수 있을 정도로 개선되었다. 다만 GameManager 위치를 Main으로 쓰는 부분, ReturnToLobbyBtn이 ServerRpc를 호출한다고 설명하는 부분 등 코드와 맞지 않는 서술이 있어 신뢰도를 깎는다.

spec 점수는 2점이다. 씬 전환 절차 문서는 생겼지만, 레벨별 입력, UI 상태, HUD 수치, 승패 조건, 밸런싱 값은 여전히 테스트 체크리스트로 쓰기 어렵다. 샘플 사양서 기준으로는 아직 placeholder에 가깝다.

6. Backlog

• 레벨/씬별 상세 사양서 입력 매핑·UI 상태 전이·HUD 수치 부재는 해결되지 않았다. 구현이 먼저 늘어나면 밸런스와 QA 기준이 계속 흔들린다.
• Game_01_BlackAndWhite 씬 생성물 리뷰 비용 문제는 이번 범위에서 직접 해소되지 않았다. 씬 빌더와 생성 결과의 책임 경계를 계속 관리해야 한다.
• 01_Lobby UI 하드코딩 문제도 이번 변경만으로는 해결 판정할 수 없다. Matching 구조 설명은 생겼지만 실제 씬·빌더 정리는 확인되지 않는다.
• URP 튜토리얼과 Mobile 렌더러 잔존 이슈는 그대로다. 제출 전 정리 대상이며, 지금은 우선순위가 낮다.