Godot 버전을 안전하게 업그레이드하는 방법

소개

프로젝트 진행 중에 게임 엔진을 업그레이드하는 것은 게임 개발의 일상적인 결정 중에서도 가장 무서운 것 중 하나입니다. 새 Godot 버전은 지금 여러분을 가로막고 있는 버그를 고쳐 줄 수도 있지만, 6개월치 작업을 쏟아부은 씬을 소리 없이 망가뜨릴 수도 있습니다. 그래서 Godot 커뮤니티의 숙련된 개발자들은 버전 업그레이드를 일상적인 잡무가 아니라 리스크 결정으로 취급합니다.

이 가이드는 "항상 업그레이드하라"는 주장이 아닙니다. Godot 4.x에서 4.x로의 마이그레이션을 위한 리스크 관리 체크리스트입니다. 애초에 업그레이드할지 말지를 결정하는 방법, 안전하게 되돌릴 수 있도록 준비하는 방법, 버전 간에 깨지는 것으로 알려진 지점들, 그리고 가장 중요한 — 아무것도 깨지지 않았음을 실제로 검증하는 방법을 다룹니다.

애초에 업그레이드해야 할까?

무언가를 건드리기 전에 이 질문에 솔직하게 답하세요. 업그레이드에는 실질적인 비용(마이그레이션 작업 + 재테스트)이 들기 때문에, 그에 상응하는 실질적인 이득이 있어야 합니다.

업그레이드해야 하는 경우

• 업스트림에서 수정된 버그가 발목을 잡고 있다. 겪고 있는 문제가 새 릴리스에서 이미 수정되었다면, 영원히 우회책을 안고 가는 것보다 업그레이드하는 편이 대개 더 저렴합니다.
• 새 기능이 게임에 실질적인 이득을 준다. "좋아 보인다" 수준이 아니라 — 실제 개발 시간을 절약해 주거나 필요한 디자인을 가능하게 해 주는 기능이어야 합니다.
• 개발 기간이 길다. 프로젝트가 수년에 걸쳐 진행된다면, 작고 잦은 점프(한 번에 마이너 버전 하나씩)가 마지막에 한 번의 거대한 점프보다 훨씬 안전합니다. 격차는 커지기만 합니다.

업그레이드하지 말아야 하는 경우

• 릴리스가 가깝다. 출시 전 몇 주는 엔진 수준의 변경을 도입하기에 최악의 시점입니다. 먼저 출시하고, 업그레이드는 그 후에 하세요.
• C# + 웹 내보내기가 필요하다. C# 프로젝트의 웹 내보내기는 Godot 4.x에서 여전히 사용할 수 없습니다(godot#70796에서 추적 중). 3.x에서 이 기능에 의존하고 있다면, 4.x로 옮기는 순간 사라집니다.
• 오래된 하드웨어가 타깃이다. Godot 3.x는 OpenGL 2급 GPU에서 돌아가지만, Godot 4의 Compatibility 렌더러는 OpenGL 3.3 / WebGL 2가 필요합니다. 플레이어층이 오래된 기기를 쓴다면, 3.x가 정말로 올바른 엔진일 수 있습니다.
• 핵심 애드온이 아직 업데이트되지 않았다. 프로젝트가 의존하는 플러그인이 새 버전을 지원하지 않으면, 자신의 마이그레이션 문제에 더해 그 애드온의 문제까지 떠안게 됩니다.

업그레이드 전 — 준비 체크리스트

여기의 각 단계는, 업그레이드가 잘못되더라도 잃는 것이 프로젝트가 아니라 반나절이 되도록 하기 위해 존재합니다.

1. 모든 것을 커밋하고 업그레이드 브랜치를 만드세요. 프로젝트의 유일한 사본을 업그레이드해서는 절대 안 됩니다. 전용 브랜치(git을 안 쓴다면 폴더 전체 복사본)가 있으면 되돌리기는 복구 작전이 아니라 명령 하나로 끝납니다.
2. 현재의 정확한 버전을 기록하세요(예: 어떤 4.x.y 빌드인지, 표준판인지 .NET판인지). 되돌아가야 하거나 버그 리포트를 제출할 때 필요합니다.
3. 기존 에디터 바이너리를 보관하세요. Godot은 여러 버전을 나란히 설치할 수 있습니다 — 에디터는 단일 실행 파일이므로 둘 다 보관하는 데 드는 비용은 없고, 언제든 기존 브랜치를 기존 에디터로 열 수 있습니다.
4. 애드온을 목록화하고 각각의 지원 버전을 확인하세요. addons/를 훑어보고 각 애드온의 출처를 기록한 뒤, 리포지토리나 Asset Library 페이지에서 대상 버전을 지원하는지 확인합니다.
5. 건너뛰는 모든 버전의 공식 업그레이드 노트를 읽으세요. 공식 마이그레이션 가이드는 버전별로 작성되어 있습니다 — 4.2에서 4.4로 간다면 4.3과 4.4 노트를 모두 읽으세요.
6. "정상 동작" 증거를 확보하세요. 주요 씬의 스크린샷을 찍고, 짧은 게임플레이 클립을 녹화하거나 — 가장 좋은 방법은 — 자동화된 테스트 시나리오를 작성하는 것입니다(아래 테스트 섹션에서 자세히 다룹니다). 업그레이드 후 "겉모습과 동작이 똑같은가?"에 답할 수 있는 것은, 사전에 "똑같다"의 기준을 기록해 둔 경우뿐입니다.

업그레이드 절차

1. 새 에디터로 브랜치 사본을 엽니다. main이 아니라 업그레이드 브랜치입니다. 새 에디터가 변환/재임포트를 제안할 것입니다 — 수락하세요.
2. 재임포트를 기다립니다. .godot 폴더는 처음부터 다시 생성됩니다. 큰 프로젝트에서는 첫 임포트에 시간이 걸릴 수 있고, 그 첫 번째 패스에서 출력되는 경고는 대개 무해합니다.
3. Output 패널과 Debugger에서 새로운 에러를 확인합니다. 업그레이드 전에 이미 있던 에러와 비교하세요(미리 기록해 두셨죠?). 새 에러가 곧 마이그레이션의 할 일 목록입니다.
4. 크리티컬 패스를 직접 플레이합니다. 새 게임 시작, 세이브 로드, 핵심 게임플레이 루프 실행, 주요 메뉴 열기. 에디터 단계의 에러는 쉬운 축에 속합니다 — 리그레션이 숨어 있는 곳은 런타임 동작입니다.
5. 테스트 시나리오를 실행합니다(업그레이드 전에 준비해 둔 것). 베이스라인과 결과를 비교하세요.
6. 커밋하기 전에 git으로 작업 트리의 diff를 확인합니다. 마이그레이션 중 에디터는 파일을 다시 씁니다. project.godot에 새 설정 값이 들어가고, .tscn 파일이 다시 저장되며, 새 .uid 파일이 나타날 수 있습니다. 무엇이 바뀌었는지 diff로 정확히 파악한 뒤 — 명확하게 라벨링된 단일 마이그레이션 커밋으로 커밋하세요.

4.x 버전 간의 알려진 파손 지점

Godot 4의 마이너 버전들은 대체로 호환되지만, 이 문장에서 "대체로"라는 단어가 꽤 큰 역할을 하고 있습니다. 공식 노트와 커뮤니티 보고에 근거해, 가장 걸리기 쉬운 변경 사항들을 소개합니다.

4.2 → 4.3: TileMap이 비추천되고 TileMapLayer로

Godot 4.3은 TileMap 노드를 비추천(deprecated)으로 지정하고 TileMapLayer로 대체했습니다 — 하나의 노드 안에 레이어를 두는 대신, 레이어당 노드 하나입니다. 기존 TileMap은 계속 동작하지만, 새 코드와 새 프로젝트는 TileMapLayer를 사용해야 합니다. 에디터에는 추출 도구가 포함되어 있습니다. TileMap을 선택하고, 하단의 TileMap 패널을 열고, 우측 상단의 툴박스 아이콘을 클릭한 뒤 "Extract TileMap layers as individual TileMapLayer nodes"를 선택하세요.

4.3 → 4.4: .uid 파일과 GDScript 추가 기능

• Godot 4.4는 .uid 동반 파일을 추가했습니다. 스크립트와 셰이더 옆에 생성됩니다. 버전 관리에 커밋하세요 — 삭제하면 uid:// 참조가 사용되는 곳마다 참조가 깨질 수 있습니다(공식 4.4 업그레이드 노트에 @export_file 경로가 uid://로 바뀌는 등의 관련 변경 사항이 나와 있습니다). 잡동사니처럼 보이지만, 잡동사니가 아닙니다.
• 타입 지정 Dictionary 등 GDScript 추가 기능은 하위 호환입니다 — 기존 코드는 그대로 동작합니다. 다만 새 기능을 채택한 애드온은 구버전에서 동작하지 않게 되므로, 버전을 넘나들면 애드온 동작이 달라질 수 있습니다.

일반: 모든 마이너 버전 사이의 미묘한 변화

마이너 버전 사이의 렌더링 조정은 게임의 겉모습을 미묘하게 바꿀 수 있습니다 — 라이팅, 안티에일리어싱, 2D 스내핑 등. 커뮤니티 논의에는 새 프로젝트에서는 재현되지 않는 씬 한정 리그레션 사례도 있습니다. 업그레이드 후 특정 씬만 이상해지는데, 같은 씬을 깨끗한 프로젝트에서 다시 만들면 정상 동작하는 경우입니다. 원인 불명의 문제가 생기면 이 격리 절차를 시도하세요. 에디터를 닫고 .godot 폴더를 삭제한 뒤 다시 열어 전체 재임포트를 시킵니다. 그래도 문제가 남으면, 깨끗한 프로젝트에서 같은 씬을 재현해서 범인이 프로젝트에 쌓인 상태인지 실제 엔진 변경인지 가려내세요.

3.x → 4.x는 완전히 다른 이야기

위의 모든 내용은 4.x에서 4.x로의 점프에 관한 것입니다. Godot 3에서 Godot 4로의 마이그레이션은 완전히 다른 범주입니다. GDScript 문법이 바뀌었고, 많은 노드가 이름이 바뀌었으며, TileMap, 물리, 렌더링이 밑바닥부터 재작업되었습니다 — 그리고 대부분의 애드온은 전용 4.x 버전이 필요합니다. 대규모 3.x 프로젝트라면 마이그레이션 비용이 재구축 비용에 근접할 수 있으며, 그럴 가치가 있는지는 진정으로 프로젝트별 결정입니다. 그 마이그레이션은 전용 문서가 필요하고(실제로 존재합니다), 이 글에서 다루는 척하지 않겠습니다.

업그레이드 후 테스트 — 진짜 병목

솔직한 부분은 여기입니다. 개발자들이 업그레이드를 피하는 첫 번째 이유는 마이그레이션 자체가 아니라, "아무것도 깨지지 않았음"을 손으로 검증하는 비용이 크기 때문입니다. 중간 규모 게임의 전체 수동 리그레션 테스트 한 바퀴에 주말이 통째로 사라질 수 있습니다. 그리고 릴리스 후 플레이어가 발견하는 런타임 버그는 어떤 에디터 에러보다 훨씬 나쁩니다. 이제 그것은 할 일 목록의 항목이 아니라 평판 문제이기 때문입니다.

최소한의 수동 스모크 테스트

• 타이틀 화면에서 새 게임 시작하기
• 기존 세이브 파일 로드하기
• 핵심 게임플레이 루프를 몇 분간 플레이하기
• 지원하는 각 해상도와 창 모드에서 UI 확인하기

전후 비교 자동화하기

수동 테스트는 확장되지 않고, 스프라이트가 2픽셀 밀렸다는 것도 알려주지 못합니다. 바로 이를 위해 만들어진 것이 Godot QA입니다 — 무료, MIT 라이선스의 오픈소스 Godot용 테스트 러너입니다. 이 워크플로는 버전 업그레이드와 완벽하게 맞아떨어집니다.

1. 업그레이드 전에 크리티컬 패스를 커버하는 시나리오 JSON 파일을 작성(또는 기록)하고, 구버전에서 베이스라인 스크린샷을 확보합니다.
2. 업그레이드 후에 새 버전에서 정확히 같은 시나리오를 실행하고, 베이스라인과의 픽셀 diff를 수행합니다.
3. 실패한 지점이 리그레션의 위치를 정확히 짚어 주므로, 주말 내내 수동 재플레이할 것을 몇 분 만에 끝낼 수 있습니다.

시나리오는 단계(입력, 대기, 어서션, 스크린샷)를 나열한 JSON일 뿐입니다:

{
  "name": "core_loop_smoke",
  "steps": [
    {"type": "wait", "seconds": 1.0},
    {"type": "input", "action": "ui_accept", "pressed": true},
    {"type": "wait", "seconds": 0.5},
    {"type": "assert", "node_path": "/root/Main/Player",
     "property": "health", "expected": 100, "operator": "eq"},
    {"type": "input", "action": "move_right", "pressed": true},
    {"type": "wait", "seconds": 2.0},
    {"type": "input", "action": "move_right", "pressed": false},
    {"type": "assert", "node_path": "/root/Main/Player",
     "property": "position:x", "expected": 100.0, "operator": "gt"},
    {"type": "screenshot", "name": "after_move"}
  ]
}

이 시나리오 형식은 Godot MCP Pro의 run_test_scenario 도구가 사용하는 것과 동일하므로, 에디터에 연결된 AI 어시스턴트가 이런 시나리오를 대신 작성해 줄 수 있습니다.

무언가 깨졌다면

1. 버전으로 이등분 탐색하세요. 여러 마이너 버전을 한 번에 건너뛰었다면, 마이너 버전 하나씩 다시 업그레이드해서 정확히 어디서 깨졌는지 찾으세요. 조사 범위가 "전부"에서 changelog 하나로 좁혀집니다.
2. .godot 폴더를 비우고 프로젝트를 재임포트시키세요. 업그레이드 후의 이상 현상 중 의외로 많은 비율이 오래된 임포트 캐시가 원인입니다.
3. 정확한 에러 메시지로 엔진의 GitHub 이슈를 검색하세요. 진짜 리그레션이라면 누군가 이미 보고했을 때가 많고 — 우회책이 함께 적혀 있기도 합니다.
4. 애드온이 범인인지 확인하세요. 프로젝트 설정에서 애드온을 비활성화하고 다시 테스트합니다. 문제가 사라지면 범인은 애드온입니다 — 엔진을 탓하기 전에 업데이트된 릴리스가 있는지 확인하세요.
5. 구버전에 머무는 것도 정당한 결말임을 받아들이세요. 수정 비용이 업그레이드의 이득을 넘어선다면, 브랜치를 되돌리고 현 상태를 유지하며, 다음 릴리스가 나오면 재시도하도록 리마인더를 설정하세요. 그것은 실패가 아니라 — 리스크 관리가 작동한 것입니다.

현상 유지가 정답일 때

단순히 업그레이드하지 말아야 할 프로젝트도 있으며, 이 점은 분명히 말해 둘 가치가 있습니다. 출시했거나 출시 직전인 게임, 웹 내보내기가 필요한 C# 프로젝트, 오래된 하드웨어를 타깃으로 하는 게임, 크게 수정한 커스텀 엔진 빌드 위의 프로젝트가 그렇습니다. 이 모든 경우에 지금 쓰고 있는 버전이 제 몫을 하고 있습니다. 업그레이드는 도구이지 미덕이 아닙니다 — 목표는 완성된 게임이지, 갓 나온 엔진이 아닙니다.

자주 묻는 질문

업그레이드 후에 다운그레이드할 수 있나요?

아니요, 신뢰할 수 있는 방법은 없습니다. 새 에디터가 씬과 리소스를 다시 저장한 순간, 그것들은 구버전 에디터와의 하위 호환성을 잃습니다. 안전하게 되돌아가는 유일한 방법은 버전 관리에서 복원하는 것입니다 — 업그레이드 브랜치가 존재하는 이유가 바로 이것입니다.

여러 버전을 한 번에 건너뛰어도 되나요?

작은 점프가 더 안전합니다. 공식 업그레이드 노트는 버전별로 작성되어 있어서, 한 번에 한 점프씩이라면 확인해야 할 항목이 명확합니다 — 여러 버전을 한 번에 건너뛰면 그것들이 전부 한꺼번에 쌓여서 어떤 변경이 무엇을 깨뜨렸는지 가려내기가 어려워집니다.

마이너 버전에서도 정말로 뭔가 깨지나요?

드물지만, 그렇습니다. 대부분의 프로젝트는 문제없이 마이너 버전을 넘어가지만, 커뮤니티에서 보고된 엣지 케이스는 존재합니다 — 충돌 비트 리셋, 씬 한정 렌더링 리그레션 같은 것들입니다. 그래서 업그레이드 전의 베이스라인 테스트가 중요합니다. "뭔가 깨졌나?"를 느낌에서 측정으로 바꿔 주기 때문입니다.

이 체크리스트는 3.x → 4.x에도 적용되나요?

체크리스트 자체는 네 — 브랜치 만들기, 기존 바이너리 보관, 베이스라인 확보, 사후 테스트. 파손 지점 목록은 아니요. 3에서 4로의 마이그레이션은 훨씬 규모가 크고(GDScript 문법, 노드 이름 변경, 시스템 재작업), 전용 공식 문서가 따로 있습니다.