Phaser 4 마이그레이션 체크리스트 (Phaser 3 -> 4)

Phaser 4는 Phaser 3의 “마이너 업그레이드”가 아니다.
구조(ECS), 렌더링 파이프라인, 개발 방식이 함께 바뀌기 때문에, 무작정 버전만 올리면 거의 100% 삽질한다.

이 글은 실제 이전 작업에서 바로 쓸 수 있게, 준비 -> 이전 -> 검증 순서로 체크리스트를 정리했다.

---

먼저 결론: 어떤 프로젝트가 옮길 만한가?

아래에 2개 이상 해당하면 마이그레이션을 고려할 만하다.

• 스프라이트/이펙트 수가 많아 프레임 드랍이 자주 난다.
• 시스템 단위(전투, AI, 상태, 이펙트)로 구조를 다시 정리할 계획이 있다.
• 신규 기능 개발보다 기술 부채 청산 우선순위가 높다.
• 팀 내에서 ECS 학습/도입 의지가 있다.

아래에 해당하면 Phaser 3 유지가 더 낫다.

• 이미 라이브 운영 중이고 안정성이 최우선이다.
• 현재 성능 이슈가 거의 없다.
• 짧은 기간 내 콘텐츠 업데이트가 더 중요하다.

---

0. 사전 점검 체크리스트

마이그레이션 전에 이 단계가 끝나지 않으면 시작하지 않는 게 좋다.

• 현재 Phaser 3 버전과 주요 플러그인 목록을 문서화했다.
• 핵심 게임 루프(이동, 전투, 충돌, UI, 저장)를 다이어그램으로 정리했다.
• 성능 기준선(FPS, 메모리, 로딩 시간)을 측정했다.
• “반드시 동일하게 동작해야 하는 기능”과 “바꿔도 되는 기능”을 구분했다.
• 릴리스 전까지 병행 운영할 브랜치 전략을 정했다.

팁:

• 기능 기준선이 없으면, 이전 후에 빨라졌는지 느려졌는지 판단이 안 된다.
• 최소한 3개 스테이지(가벼움/보통/무거움)에서 FPS를 기록해두자.

---

1. 코드베이스 분리 체크리스트

한 번에 전체 이전하지 말고, “새 코어 + 점진 이전”으로 간다.

• legacy(phaser3)와 next(phaser4) 실행 엔트리를 분리했다.
• 공용 도메인 로직(데이터 모델, 레벨 정의, 밸런스 값)을 엔진 의존 코드와 분리했다.
• 입력/사운드/저장소 인터페이스를 추상화했다.
• 기존 Scene 의존 유틸을 독립 모듈로 분리했다.

예시 디렉터리:

src/
  game-core/            # 엔진 독립 도메인
  phaser3-runtime/      # 기존 런타임
  phaser4-runtime/      # 신규 런타임
  shared/               # 입력/저장/사운드 어댑터

---

2. Scene -> ECS 전환 체크리스트

Phaser 3의 GameObject 중심 로직을 ECS로 옮길 때는 매핑표를 먼저 만든다.

• Entity 설계: 플레이어/적/투사체/아이템 엔티티 구분
• Component 설계: Position, Velocity, Health, SpriteRef, Collider 등
• System 설계: MovementSystem, CombatSystem, CollisionSystem, RenderSyncSystem
• 기존 update 루프의 책임을 각 System으로 나눴다.

간단한 매핑 예시:

Phaser 3 패턴	Phaser 4/ECS 전환 방향
scene.update()에 모든 로직	System별 처리 순서 정의
sprite.setVelocity() 직접 호출	Velocity 컴포넌트 수정 -> MovementSystem 반영
오브젝트 내부 상태 혼합	상태를 Component로 분리

---

3. 입력/카메라/물리 체크리스트

체감 버그가 가장 많이 나오는 영역이다.

• 키보드/패드 입력 매핑이 프레임 독립적으로 동작한다.
• 카메라 추적, 줌, 흔들림 효과가 기존과 동일하거나 의도대로 변경됐다.
• 충돌 레이어/마스크 규칙을 다시 검증했다.
• 히트박스 동기화(애니메이션 프레임 변화 포함)를 확인했다.

권장 테스트 시나리오:

• 연속 점프 + 대시 + 공격 동시 입력
• 좁은 지형 모서리 충돌
• 저사양 기기에서 프레임 저하 상태 입력 지연

---

4. 렌더링/에셋 파이프라인 체크리스트

Phaser 4에서 렌더링 구조가 바뀌면 “보이긴 보이는데 다르게 보이는” 문제가 잦다.

• 텍스처 아틀라스 로딩 순서와 키 충돌을 정리했다.
• 블렌드/필터/파티클 표현이 의도대로 재현된다.
• 배치 순서(z-order) 기준을 명시했다.
• 폰트 렌더링과 UI 스케일이 해상도별로 안정적이다.

검증 포인트:

• 같은 장면 스크린샷을 Phaser 3/4에서 비교
• 알파/글로우/블러 효과 차이 확인
• UI 오버레이와 월드 오브젝트 레이어 충돌 확인

---

5. 성능 회귀 테스트 체크리스트

“돌아간다”와 “쓸 만하다”는 다르다.

• 장면별 평균 FPS를 Phaser 3 기준선과 비교했다.
• 프레임 타임 스파이크 구간을 기록했다.
• 메모리 사용량(초기/5분/15분)을 측정했다.
• 오브젝트 수 증가 시 선형/비선형 저하를 확인했다.

예시 목표:

• 무거운 전투 장면에서 95퍼센타일 프레임 타임 20ms 이하
• 15분 플레이 후 메모리 증가폭 10% 이하

---

6. 릴리스 전략 체크리스트

마이그레이션의 실패는 보통 코드보다 롤아웃에서 나온다.

• 기능 플래그로 Phaser 3/4 런타임 전환 가능
• 내부 QA -> 소규모 사용자 -> 전체 공개 순서 계획
• 치명 버그 발생 시 즉시 Phaser 3로 롤백 가능
• 오류 로그/성능 로그 대시보드 알림 설정

권장 순서:

1. 개발 빌드에서 핵심 루프만 이전
2. 콘텐츠 1개(스테이지/모드)만 제한 공개
3. 성능/안정성 확인 후 범위 확장

---

7. “여기서 멈춰야 하는” 신호

아래 상황이면 일정 기준으로 Phaser 3 유지가 더 현명할 수 있다.

• ECS 전환으로 개발 속도가 기존 대비 절반 이하로 떨어진다.
• 플러그인/툴체인 대체 비용이 예상보다 크다.
• 마이그레이션 때문에 콘텐츠 업데이트가 장기간 중단된다.

기술 선택의 목적은 “새로운 것 사용”이 아니라 팀 생산성과 게임 품질 개선이다.

---

실전용 2주 플랜 예시

• 1~2일: 사전 점검 + 성능 기준선 기록
• 3~5일: 코어 루프(ECS 최소 단위) 프로토타입
• 6~8일: 입력/충돌/카메라 이전
• 9~10일: 렌더링 표현 정합성 보정
• 11~12일: 성능 회귀 테스트
• 13~14일: 제한 공개 + 로그 모니터링

---

마무리

Phaser 3 -> 4 이전의 핵심은 버전 업이 아니라 구조적 리팩토링이다.

체크리스트 기반으로 진행하면,

• 어떤 기능을 먼저 옮길지
• 어디서 품질이 깨지는지
• 언제 롤백해야 하는지

를 팀이 같은 언어로 판단할 수 있다.

차후에는 실제 코드 기준으로 Player 이동/공격 로직을 Phaser 3 스타일에서 ECS로 변환하는 예시를 이어서 정리해보겠다.