Phaser 4 완전 정리 — Phaser 3와 뭐가 달라졌나?
Phaser 4의 핵심 변경사항을 Phaser 3와 비교하여 인디게임 개발자 관점에서 정리합니다. 성능, 구조, 렌더링 변화까지 한 번에 이해할 수 있습니다.
Phaser 4 마이그레이션 체크리스트 (Phaser 3 -> 4)
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개(스테이지/모드)만 제한 공개
- 성능/안정성 확인 후 범위 확장
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로 변환하는 예시를 이어서 정리해보겠다.
관련 태그 글
