Playground Devlog #34 - main.js 대수술: 4,474줄 → 3,370줄, 사이드이펙트 제거

"하나 고치면 다른 게 깨진다" — 이 문제의 근본 원인을 잡았습니다.

문제

main.js가 4,474줄짜리 IIFE 모놀리스. 50+개 let 클로저 변수를 100+ 함수가 자유롭게 읽고 쓴다. 특히:

• conversationFocusNpcId — 8개 함수에서 쓰기, 15곳
• player.moveTarget — 6곳에서 쓰기
• 비동기 LLM 콜백이 2~5초 뒤 상태 변경 → 레이스 컨디션

Phase 0: ConversationManager

가장 위험한 변수 conversationFocusNpcId를 상태 머신으로 캡슐화.

Before: conversationFocusNpcId = npc.id; (15곳에서 자유롭게)
After:  convoMgr.startConversation(npcId, holdMs, "reason");

비동기 잠금으로 레이스 컨디션 방지:

convoMgr.lockForAsync("proactive_greet");
// LLM 호출...
convoMgr.unlockAsync("proactive_greet");

유저가 NPC 클릭 → proactive 잠금 걸려있으면 거부. 기존에는 마지막 쓰기가 승리하는 구조.

Phase 1: ChatManager + GameState

채팅 관련 상태 5개(npcChatHistories, globalChats, speechBubbles, logs, systemToasts)와 함수 10개를 chat-manager.js로 이관.

game-state.js는 world/player/npcs/quest를 하나의 컨테이너로 묶어 서브시스템에 전달.

Phase 2: 7개 서브시스템 추출

에이전트 4명이 isolated worktree에서 병렬 작업 → 모듈 파일 생성 → 리드가 main.js 통합.

Phase 3: PlayerController

updatePlayer(dt)와 autoWalk 로직을 player-controller.js로 이관. player.moveTarget 쓰기를 playerCtrl.setMoveTarget()으로 통일.

Phase 4: AsyncGuard + 프레임 루프 문서화

비동기 연산 동시성 가드:

asyncGuard.guarded('ambient', async () => {
  const line = await llmReplyOrEmpty(npc, prompt);
  if (line) chatMgr.upsertSpeechBubble(npc.id, line, 4000);
});
// 이미 ambient 슬롯이 사용 중이면 자동 스킵

frame() 함수에 실행 순서 문서화:

Phase A: 시간
Phase B: 플레이어 이동 (NPC보다 먼저)
Phase C: NPC 이동 (가이드 → 일반)
Phase D: NPC 소셜
Phase E: 환경 (날씨, 발견)
Phase F: 카메라
Phase G: 네트워크

결과

이번 커밋들