Godot 4.8 Beta 3 출시? 씬이 깨지기 전에 마이그레이션 테스트를 실행하세요
핵심 요약
Godot 4.8 베타 3 빌드에서 마이그레이션 테스트를 실행하고 씬 파손, 물리 drift 및 잠재적 회귀 버그를 사전에 방지하세요.
Godot 4.8 beta 3 스냅샷이 방금 출시되었으며, 개발팀은 release candidate 단계에 접어들고 있다고 밝혔습니다. 즉, regression을 찾아 리포트할 수 있는 시간 창이 빠르게 줄어들고 있다는 뜻입니다. 다음 달에 출시하든 1년 뒤에 출시하든 상관없이, 지금이 바로 Godot 프로젝트의 codebase를 이 빌드로 열어보고 어떤 부분이 깨지는지 확인해야 할 때입니다.
대부분의 개발자는 체계적으로 테스트를 진행하지 않습니다. 빌드를 클론하고, 프로젝트를 열어 몇 개의 씬을 대충 훑어본 뒤 문제없다고 넘겨버립니다. 그러고 나서 stable 버전이 출시되면 물리 연산이 다르게 느껴지고, 세이브 파일이 올바르게 deserialize되지 않으며, 개발 중에는 한 번도 발생하지 않았던 모호한 GDScript 파싱 에러를 플레이어가 겪게 됩니다. 해결책은 출시 후 영웅적인 디버깅이 아니라, 지금 이러한 문제를 잡아내는 반복 가능한 테스트 프로토콜입니다.
이 가이드에서는 구체적인 워크플로우를 제공합니다. 오늘 바로 실행할 수 있는 마이그레이션 테스트 스크립트, 스캔해야 할 세 가지 특정 함정, 그리고 Godot 팀의 이목을 실제로 끌 수 있는 regression 리포팅 구조를 다룹니다.
Beta 3가 테스팅 마감일인 이유
Beta 3는 Godot 팀이 release candidate로 넘어가기 전의 마지막 beta입니다. Release candidate 단계는 45도보다 가파른 경사에서 move_and_slide()가 다르게 동작하는지 뒤늦게 발견하는 시기가 아니라, 폴리싱을 위한 단계입니다. RC1이 출시될 시점에는, 새로운 regression은 출시를 지연시킬 만큼 심각한 경우에만 blocker로 분류됩니다.
Beta 기간 동안 여러분의 임무는 명확합니다.
- stable 빌드에서는 눈에 띄지 않게 숨어버리기 전에 regression을 찾아내세요
- 프로젝트 codebase에 특화된 breaking change를 문서화하세요
- 메인테이너가 수정할 수 있도록 최소한의 재현 단계와 함께 버그를 리포트하세요
Godot 팀은 지난주 GodotFest에 참석했음에도 남은 release blocker에 대한 수정 사항을 계속 푸시했습니다. 그만큼 개발 속도가 빠릅니다. 4.8 정식 버전의 모습을 직접 만들고 싶다면 지금 테스트하세요.
마이그레이션 테스팅 브랜치 설정하기
Beta 3에서 어떤 파일이든 열기 전에, 깨끗한 테스팅 환경부터 만드세요.
# Create a dedicated testing branch from your stable codebase
git checkout -b beta/4.8-testing
git push -u origin beta/4.8-testing
별도의 브랜치가 중요한 이유: Godot의 씬 파일(.tscn)은 텍스트 기반이며 엔진 고유의 메타데이터를 포함합니다. 4.8 beta 3에서 씬을 열고 저장하면 파일 해시가 변경됩니다. 서로 다른 Godot 버전을 사용하는 팀원들과 머지할 때 해결하기 까다로운 merge conflict가 발생할 수 있습니다. Beta 테스팅은 철저히 격리해 두세요.
마이그레이션 테스트 스크립트 구축하기
개발자들이 겪는 가장 큰 테스팅 공백은 베이스라인이 없다는 점입니다. 프로젝트를 열었을 때 "괜찮아 보인다"고 넘어가지만, 문제는 괜찮아 보이는 것으로는 물리 drift, 셰이더 컴파일 차이, 특정 조건에서만 드러나는 GDScript 동작 변경 등을 놓치게 된다는 점입니다.
모든 Godot 4.x 프로젝트에 바로 적용할 수 있는 마이그레이션 테스트 스크립트입니다. 이 스크립트는 핵심 엔진 동작이 기대값과 일치하는지 검증합니다.
@tool
extends SceneTree
## Godot 4.8 Beta 3 Migration Test Suite
## Run with: godot --headless -s migration_test.gd
##
## This script validates that core engine behaviors match
## expectations from Godot 4.7.x stable. Run it in both
## the stable build and beta 3, then compare output.
var results: Array[Dictionary] = []
func _init() -> void:
print("\n╔══════════════════════════════════════════════╗")
print("║ Godot 4.8 Beta 3 — Migration Test Suite ║")
print("╚══════════════════════════════════════════════╝\n")
test_vector_math()
test_json_parsing()
test_scene_serialization()
test_input_map_registration()
test_color_conversion()
test_file_access_permissions()
print_summary()
quit(get_exit_code())
func record(test_name: String, passed: bool, detail: String) -> void:
results.append({
"name": test_name,
"passed": passed,
"detail": detail
})
func test_vector_math() -> void:
# Vector2 operations — regression-prone area in minor releases
var a := Vector2(3.0, 4.0)
var b := Vector2(1.0, 0.0)
# Length should be exactly 5.0
record(
"Vector2.length()",
abs(a.length() - 5.0) < 0.001,
"Expected 5.0, got %.6f" % a.length()
)
# Normalized vector should have length 1.0
var normalized := a.normalized()
record(
"Vector2.normalized()",
abs(normalized.length() - 1.0) < 0.001,
"Expected length 1.0, got %.6f" % normalized.length()
)
# Dot product: (3,4)·(1,0) = 3.0
record(
"Vector2.dot()",
abs(a.dot(b) - 3.0) < 0.001,
"Expected 3.0, got %.6f" % a.dot(b)
)
func test_json_parsing() -> void:
var test_cases := [
'{"score": 1500, "level": 12, "name": "TestPlayer"}',
'{"nested": {"value": true}, "array": [1, 2, 3]}',
'{"special": "chars: \\\"quotes\\\" and \\\\backslash"}',
]
for i in test_cases.size():
var json := JSON.new()
var error := json.parse(test_cases[i])
record(
"JSON.parse() case %d" % i,
error == OK and json.data is Dictionary,
"Parse error: %s" % error_string(error) if error != OK else "Parsed successfully with %d keys" % json.data.size()
)
func test_scene_serialization() -> void:
# Create a minimal scene and verify round-trip serialization
var root := Node.new()
root.name = "TestRoot"
var child := Node2D.new()
child.name = "TestChild"
child.position = Vector2(100.5, 200.75)
child.rotation = 1.5708 # ~90 degrees
child.scale = Vector2(2.0, 2.0)
root.add_child(child)
# Test that properties are preserved
record(
"Node2D.position precision",
abs(child.position.x - 100.5) < 0.01 and abs(child.position.y - 200.75) < 0.01,
"Expected (100.5, 200.75), got (%.2f, %.2f)" % [child.position.x, child.position.y]
)
record(
"Node2D.rotation",
abs(child.rotation - 1.5708) < 0.001,
"Expected ~1.5708, got %.6f" % child.rotation
)
root.free()
func test_input_map_registration() -> void:
var action_name := "__migration_test_action_7f3a"
var event := InputEventKey.new()
event.keycode = KEY_SPACE
InputMap.add_action(action_name)
InputMap.action_add_event(action_name, event)
record(
"InputMap.add_action()",
InputMap.has_action(action_name),
"Action registered: %s" % InputMap.has_action(action_name)
)
var events := InputMap.action_get_events(action_name)
record(
"InputMap.action_get_events()",
events.size() == 1 and events[0] is InputEventKey,
"Expected 1 InputEventKey, got %d event(s)" % events.size()
)
InputMap.erase_action(action_name)
record(
"InputMap.erase_action()",
not InputMap.has_action(action_name),
"Action erased: %s" % (not InputMap.has_action(action_name))
)
func test_color_conversion() -> void:
# Colors can serialize differently across versions
var red := Color(1.0, 0.0, 0.0, 1.0)
var hex := red.to_html()
record(
"Color.to_html()",
hex == "ff0000ff",
"Expected 'ff0000ff', got '%s'" % hex
)
var from_html := Color.html("00ff00ff")
record(
"Color.html()",
abs(from_html.g - 1.0) < 0.001 and abs(from_html.a - 1.0) < 0.001,
"Expected green (0,1,0,1), got (%.2f, %.2f, %.2f, %.2f)" % [from_html.r, from_html.g, from_html.b, from_html.a]
)
func test_file_access_permissions() -> void:
# Verify user:// directory is writable
var test_path := "user://_migration_test.tmp"
var file := FileAccess.open(test_path, FileAccess.WRITE)
record(
"FileAccess user:// write",
file != null if true else FileAccess.get_open_error() == OK,
"File opened for writing: %s" % ("OK" if file != null else error_string(FileAccess.get_open_error()))
)
if file:
file.store_string("migration_test_4.8_beta3")
file.close()
# Read it back
var reader := FileAccess.open(test_path, FileAccess.READ)
if reader:
var content := reader.get_as_text()
reader.close()
record(
"FileAccess user:// read",
content == "migration_test_4.8_beta3",
"Read back: '%s'" % content
)
DirAccess.remove_absolute(test_path)
func print_summary() -> void:
var passed_count := 0
for result in results:
var icon := "✅" if result["passed"] else "❌"
print("%s %s: %s" % [icon, result["name"], result["detail"]])
if result["passed"]:
passed_count += 1
print("\n────────────────────────────────────────────")
print("Results: %d / %d tests passed" % [passed_count, results.size()])
if passed_count < results.size():
var failed := results.size() - passed_count
print("⚠️ %d test(s) failed." % failed)
print(" Compare output against Godot 4.7.1 stable.")
print(" File regressions: https://github.com/godotengine/godot/issues")
else:
print("✅ All core behaviors match expected values.")
print(" This does NOT guarantee full compatibility,")
print(" but it confirms fundamental APIs are stable.")
func get_exit_code() -> int:
for result in results:
if not result["passed"]:
return 1
return 0
양쪽 빌드에서 모두 실행하고 출력 결과를 diff로 비교하세요:
# In Godot 4.7.1 stable:
godot --headless -s migration_test.gd > results_stable.txt
# In Godot 4.8 beta 3:
godot --headless -s migration_test.gd > results_beta3.txt
# Compare:
diff results_stable.txt results_beta3.txt
Diff 결과 성공/실패 여부가 동일하다면 핵심 동작들은 업그레이드를 무사히 통과한 것입니다. 차이가 발생한다면 변경된 API를 직접적으로 가리키는 신호입니다.
스캔해야 할 세 가지 마이그레이션 함정
함정 1: GDScript 파싱 및 타입 추론
GDScript 파서는 마이너 버전마다 업데이트가 이루어집니다. 4.8 버전에서는 다음 영역들을 특히 주의 깊게 살펴보세요.
- 타입화된 배열 강제 변환(coercion) — 최근 버전에서는
Array[int]와PackedByteArray간의 변환 동작이 더 엄격해졌습니다. 코드에서 타입화된 배열과 패키지 배열 간의 암시적 변환에 의존하고 있다면 해당 코드 경로를 명시적으로 테스트하세요. - @tool 스크립트 평가 순서 — 특정 초기화 순서에 의존하는 EditorScripts는 평가기 타이밍이 변경된 경우 다르게 동작할 수 있습니다.
- 시그널 연결 문법 —
signal.connect(callable)패턴은 안정적이지만, 문자열 기반 연결("signal_name")은 deprecated되었으며 경고나 에러를 발생시킬 수 있습니다.
# Check your project for these patterns:
# AVOID — string-based signal connections (deprecated):
# node.connect("body_entered", self, "_on_body_entered")
# USE — callable-based connections:
node.body_entered.connect(_on_body_entered)
# AVOID — implicit typed array coercion:
var bytes: PackedByteArray = [72, 101, 108] # May warn in 4.8
# USE — explicit construction:
var bytes: PackedByteArray = PackedByteArray([72, 101, 108])
탐지 접근법: 프로젝트에서 다음 패턴을 grep으로 검색하세요:
# Find deprecated signal connections
grep -rn '\.connect("' --include="*.gd" .
# Find string-based export hints
grep -rn 'export(' --include="*.gd" .
# Find untyped variables that may trigger new warnings
grep -rn 'var [a-z_]* =' --include="*.gd" . | grep -v ':'
함정 2: 씬 파일 메타데이터
4.8 beta 3 에디터에서 .tscn 파일을 열면 업데이트된 메타데이터와 함께 씬이 다시 저장됩니다. load_steps 카운트, uid 값, [resource] 섹션 순서가 변경될 수 있습니다. 대개는 무해하지만, git blame이 깨지며 merge conflict를 더 복잡하게 만듭니다.
Beta 3에서 씬을 열기 전:
- 현재 씬 해시 내보내기:
git ls-files '*.tscn' | xargs md5sum > scene_hashes_stable.txt - Beta 3에서 프로젝트를 열고 몇몇 씬을 둘러본 뒤 저장
- 다시 내보내기:
git ls-files '*.tscn' | xargs md5sum > scene_hashes_beta.txt - 비교:
diff scene_hashes_stable.txt scene_hashes_beta.txt
메타데이터만 변경되었다면 (씬의 콘텐츠는 동일하지만 파일 자체만 다름) stable 버전으로 마이그레이션할 때 어떤 결과가 나올지 미리 파악할 수 있습니다.
함정 3: 물리 시뮬레이션 베이스라인 drift
물리 연산 변경은 가장 알아채기 힘든 regression 카테고리입니다. 크래시도 나지 않고 에러도 발생하지 않습니다. 다만 캐릭터가 미세하게 2% 느리게 느껴지거나, 투사체의 포물선이 이전보다 5픽셀 낮게 떨어질 뿐입니다. 플레이어는 알아채지 못할 수도 있으며, QA 팀도 세심하게 신경 쓰지 않으면 감각 테스트에서나 잡아낼 수 있습니다.
해결책 — 물리 regression 테스트 씬:
extends Node2D
## Physics Regression Test — Godot 4.8 Beta 3
## Attach this to a Node2D in an empty scene.
## Run the scene and compare the printed positions
## against values from your stable build.
func _ready() -> void:
await get_tree().create_timer(0.1).timeout
run_gravity_test()
run_velocity_test()
func run_gravity_test() -> void:
var body := CharacterBody2D.new()
var collision := CollisionShape2D.new()
var shape := RectangleShape2D.new()
shape.size = Vector2(16, 32)
collision.shape = shape
body.add_child(collision)
add_child(body)
body.position = Vector2(200, 100)
body.velocity = Vector2.ZERO
# Simulate 1 second of free fall (60 physics frames)
for i in range(60):
body.velocity.y += body.get_gravity().y * (1.0 / 60.0)
body.move_and_slide()
await get_tree().physics_frame
var fall_distance := body.position.y - 100.0
print("[Gravity Test] Fell %.2f pixels in 60 frames" % fall_distance)
print(" Compare against stable build — deviation > 1.0 px = investigate")
print(" Expected range: 489.0 - 491.0 (default gravity 980 px/s²)")
body.queue_free()
func run_velocity_test() -> void:
var body := CharacterBody2D.new()
var collision := CollisionShape2D.new()
var shape := RectangleShape2D.new()
shape.size = Vector2(16, 32)
collision.shape = shape
body.add_child(collision)
add_child(body)
body.position = Vector2(50, 300)
body.velocity = Vector2(300, 0)
# Move horizontally for 2 seconds
for i in range(120):
body.velocity = Vector2(300, 0)
body.move_and_slide()
await get_tree().physics_frame
var horizontal_distance := body.position.x - 50.0
print("[Velocity Test] Moved %.2f pixels horizontally in 120 frames" % horizontal_distance)
print(" Expected: ~600.0 px (300 px/s × 2 seconds)")
print(" Deviation > 2.0 px = physics engine behavior changed")
body.queue_free()
Stable 4.7.x 버전에서의 출력을 기록하고, 4.8 beta 3에서의 출력과 비교하세요. 수치가 1~2픽셀 이상 차이 난다면 리포트할 가치가 있는 물리 regression이 발생한 것입니다.
내보낸 빌드 테스트하기 — 대부분의 개발자가 건너뛰는 영역
에디터 테스트는 스크립팅과 씬 문제를 잡아냅니다. 하지만 **내보낸 빌드(exported build)**에는 고유한 문제 영역이 따로 존재합니다.
| 플랫폼 | 중점 영역 | 일반적인 4.x 함정 |
|---|---|---|
| Windows | 셰이더 컴파일, DLL 로딩 | Godot 버전 간 셰이더 캐시 무효화 |
| Linux | Vulkan 드라이버 호환성 | Vulkan 1.3 기능을 다루는 Mesa 드라이버 차이 |
| Android | 터치 입력 지연, 앱 라이프사이클 | 최신 안드로이드 버전에서의 Activity 일시중지/재개 상태 손실 |
| Web | 메모리 제한, GDScript 성능 | Emscripten으로 컴파일된 빌드의 엄격한 메모리 상한선 |
| WebXR | 몰입형 모드 전환 | 세션 종료 시 정리(cleanup) 과정이 데스크톱 XR과 다를 수 있음 |
내보내기 호환성 테스트:
# Export your project for each target platform
# Save the export output with the Godot version in the filename
# Windows
godot --headless --export-release "Windows Desktop" build/godot471_win.exe
# Then repeat with beta 3:
godot --headless --export-release "Windows Desktop" build/godot48b3_win.exe
# Android APK
godot --headless --export-release "Android" build/godot471_android.apk
godot --headless --export-release "Android" build/godot48b3_android.apk
각 빌드를 실행하고 표준 10분 게임플레이 루프를 진행하세요. 로딩 시간, 프레임 레이트, 그리고 stable 버전에는 없던 시각적 아티팩트가 나타나는지 주의 깊게 살펴보세요.
수정되는 Regression 리포트 작성법
Godot 이슈 트래커에는 릴리스당 수백 건의 리포트가 접수됩니다. 개발자가 빠르게 배정되는 리포트들은 다음과 같은 공통된 구조를 가지고 있습니다.
## Summary
CharacterBody2D.move_and_slide() produces 3.2% less vertical displacement
on slopes steeper than 45° compared to Godot 4.7.1 stable.
## Environment
- OS: Windows 11, NVIDIA RTX 3070, driver 551.86
- Godot build: 4.8-beta3 (build hash from Help → Copy Build Info)
- Rendering method: Forward+
## Minimal Reproduction
1. Open attached project
2. Run scene `test_slope_regression.tscn`
3. Observe printed displacement: 456.2 px (expected: 471.3 px)
## Regression Marker
Verified behavior in Godot 4.7.1 stable: displacement is 471.3 px.
Likely introduced between commit [first known good] and [first known bad].
리포트를 실효성 있게 만드는 핵심 요소:
- "느려진 것 같다"가 아닌 구체적인 수치
- 단순히 "beta 3"가 아니라 도움말 메뉴에서 가져온 빌드 해시
- 전체 프로젝트 없이도 문제를 재현할 수 있는 단일 씬 파일
- 정확한 기대값 대 실제값을 보여주는 stable 버전과의 비교
- 렌더링 문제는 하드웨어에 종속적이므로 GPU 및 드라이버 정보
정확한 커밋을 bisect하고 싶다면 Godot 소스를 클론하고 git bisect를 사용하세요. regression이 도입된 시점을 정확히 찾아내는 가장 효율적인 방법이며 수정 속도를 극적으로 단축해 줍니다.
성공적인 Godot 4.8 마이그레이션을 위한 모범 사례
저장소에
MIGRATION-4.8.md유지하기 — 마주치는 모든 API 변경 사항과 동작 차이를 GDScript 라인 및 임시 방편(workaround)과 함께 문서화하세요. 정식 버전이 출시될 때쯤이면, 문제를 재발견하는 대신 프로젝트에 딱 맞는 완벽한 마이그레이션 가이드를 갖추게 됩니다.세이브/로드 왕복 테스트하기 — 게임이
JSON.stringify()나ResourceSaver.save()로 플레이어 데이터를 직렬화한다면, 4.7.x로 작성된 데이터가 4.8 beta 3에서 올바르게 로드되는지 (그리고 그 반대도) 검증하세요. 직렬화 포맷의 변경은 플레이어 진행 상황을 조용히 손상시킬 수 있습니다.애드온 호환성 확인하기 — Asset Library의 GDExtension 플러그인이나 GDScript 애드온을 사용하고 있다면, 4.8 호환성 노트가 있는지 GitHub 저장소를 확인하세요. 많은 애드온 메인테이너들은 개발자가 요청하지 않는 한 beta 버전 상대로 테스트를 진행하지 않습니다. 여러분이 바로 그 개발자가 되세요.
CI 파이프라인 테스트하기 — 프로젝트에 자동화된 빌드가 있다면, CI 러너의 Godot 버전을 4.8 beta 3로 업데이트하고 전체 파이프라인을 실행해 보세요. 에디터 경로이나 CLI 플래그를 참조하는 빌드 스크립트는 해당 API가 변경된 경우 깨질 수 있습니다.
렌더링 검증 분리하기 — 가능하다면 게임을
--rendering-driver vulkan,--rendering-driver opengl3,--rendering-driver d3d12(Windows) 옵션으로 각각 실행해 보세요. 렌더링 드라이버 동작은 다른 어떤 서브시스템보다 버전 간 차이가 큽니다.
백엔드 스택이 업그레이드를 견뎌내야 할 때
엔진 마이그레이션은 게임플레이 코드 그 이상에 영향을 미칩니다. 게임이 원격으로 플레이어 데이터(인증 토큰, 저장된 진행 상황, 리더보드 제출 등)를 저장하는 경우, 클라이언트와 백엔드 간의 직렬화 포맷은 일관성을 유지해야 합니다.
다음 시나리오를 생각해 보세요. Godot 4.8이 Dictionary 값의 부동소수점 정밀도를 처리하는 JSON.stringify() 방식을 변경합니다. 클라우드 세이브 페이로드가 {"x": 100.5}에서 {"x": 100.499999}로 바뀝니다. 백엔드는 이를 신경 쓰지 않지만, 만약 클라이언트 사이드 충돌 해결(로컬 세이브 버전과 원격 세이브 버전 비교)을 수행하고 있다면 이 미세한 오차(epsilon) 차이가 불필요한 merge conflict를 유발하게 됩니다.
이것이 바로 엔진 마이그레이션 중에 리비전 인식 세이브 시스템(revision-aware save system)이 중요한 이유입니다. horizOn은 클라이언트가 충돌 해결을 담당하는, 리비전 인식 읽기 및 쓰기 기능을 갖춘 계정 연동 Cloud Save를 제공합니다. 엔진의 직렬화 동작이 버전 간에 변경되더라도, 리비전 인식 시스템을 사용하면 동등성 기반 비교(equality-based comparison)로 인해 발생하는 유령 충돌(phantom conflict)을 방지할 수 있습니다.
다음 단계
- 공식 스냅샷에서 Godot 4.8 beta 3를 다운로드하거나 빠른 스모크 테스트를 위해 웹 에디터를 사용해 보세요.
- 테스팅 브랜치를 생성하고 위에서 언급한 마이그레이션 테스트 스크립트를 실행하세요.
- 가장 복잡한 씬들을 열어 여전히 올바르게 보이고 동작하는지 확인하세요.
- 에디터만이 아니라 타겟 플랫폼에 내보내고 테스트하세요.
- 최소한의 재현 단계와 함께 Godot GitHub 이슈 트래커에 regression을 리포트하세요.
Stable 버전은 테스트 여부와 상관없이 다가오고 있습니다. Beta 버전 상대로 검증을 마친 개발자는 첫날에 게임을 출시할 수 있습니다. 나머지는 출시 윈도우 기간 동안 프로덕션 이슈를 디버깅하느라 바쁠 것입니다.
Source: Dev snapshot: Godot 4.8 beta 3