Thread-Safe한 Godot 4.7 backend 연동 설계: Godot 4.7 RC 3의 Network Bottlenecks 해결

Godot에서 Multiplayer 게임을 출시해 본 인디 개발자라면 HTTP client가 소리 없이 connection timeout을 발생시키거나 thread-safety exception을 던지는 당혹스러운 순간을 잘 알고 있을 것입니다. 이러한 문제는 로컬 에디터 플레이 도중에는 좀처럼 드러나지 않다가, 수백 명의 동시 접속 플레이어가 로그인 endpoint에 몰리는 production build 단계에서 갑작스러운 크래시를 유발하곤 합니다. 이 문제를 해결하려면 엔진의 비동기 네트워킹 레이어에 대한 깊은 이해가 필요합니다.

Godot 4.7 RC 3 출시: 안정성 강화 및 Core Regression 수정

Release Candidate의 크리티컬한 Regression 수정

Godot 4.7 RC 3 출시로 많은 기대를 모으고 있는 stable release가 한 걸음 더 가까워졌습니다. 현재 기능 동결(feature freeze) 상태인 개발 팀은 beta 단계에서 발견된 크리티컬한 regression을 해결하는 데 온전히 집중하고 있습니다. 외부 API를 다루는 개발자들에게 이번 수정 사항들은 복잡한 실행 라이프사이클 속에서도 핵심적인 안정성을 보장해 줍니다. 구체적으로 이번 RC 3에서는 애니메이션 시스템의 custom_timeline 내 stretch mode 버그가 수정되었습니다. 또한 AssetLib에서 "Other"로 표시된 라이센스가 잘못 필터링되던 asset 목록 조회 버그도 해결되었습니다. 마지막으로 XR 개발자들은 spatial entity marker tracker에 의해 발생하던 크래시 현상에 대한 수정을 환영할 것입니다.

Jolt Physics Area Event Queuing 버그 수정

Jolt는 뛰어난 속도와 안정성 덕분에 Godot 4.x의 필수 물리 플러그인이 되었습니다. 그러나 beta 빌드의 regression으로 인해 body exit 시 area event queuing이 강제되었고, 이는 rigid body가 area를 벗어날 때마다 엔진이 불필요한 큐 삽입 작업을 수행함을 의미했습니다. 64명의 플레이어와 수십 개의 트리거 영역이 있는 빠른 템포의 Multiplayer 로비에서 이러한 CPU 오버헤드는 서버 tick rate를 60Hz에서 20Hz 미만으로 급격히 저하시켰습니다. 이 regression을 해결함으로써 로컬 트리거 체크가 network thread를 방해하지 않도록 보장합니다.

AssetLib REST API 개편

Godot 4.7의 또 다른 하이라이트는 에셋 라이브러리(AssetLib) API 개편입니다. backend 연결이 현대적인 REST 구조로 이식되어 릴리스 순서 관련 문제와 로딩 실패 현상이 해결되었습니다. 이 upgrade는 게임 개발자가 자체적인 외부 API 연동을 구축할 때 훌륭한 모범 사례가 됩니다. 명확한 endpoint와 paginated request를 활용하면 콘텐츠 전달을 위한 로드 시간을 최적화할 수 있습니다. 아울러 일관된 스키마 구조의 JSON array를 사용하면 GDScript의 역직렬화(deserialization) 병목 현상을 방지할 수 있습니다.

Godot 4.7에서 Backend 연동 시 구조적 설계가 중요한 이유

HTTPRequest 노드의 한계

Godot 4.7에서 backend를 연동할 때는 게임의 메인 스레드(main thread)에 부하를 주지 않으면서 비동기 작업을 관리해야 합니다. Godot는 호출을 관리하기 위해 HTTPRequest와 같은 논블로킹(non-blocking) 노드에 의존하지만, 이 노드들에는 치명적인 한계가 있습니다. 바로 동시 요청(concurrent request)을 처리할 수 없다는 점입니다. 현재 응답을 대기 중인 노드에 대해 request()를 다시 호출하려고 시도하면 엔진에서 오류가 발생합니다. 적절히 처리하지 않을 경우 이 "Request already in progress" 오류는 중요한 게임 플레이 기능을 멈추게 할 수 있습니다.

스레드 안전성(Thread Safety) 및 SceneTree 수정

이러한 충돌을 방지하려면 여유 노드에 요청을 동적으로 할당하는 견고한 큐(queue)나 풀(pool)을 구축해야 합니다. 또한 네트워크 응답을 처리할 때 스레드 안전성(thread safety)은 지속적인 과제입니다. 만약 백그라운드 network thread가 SceneTree를 직접 수정하려고 하면 Godot가 크래시를 일으키거나 불안정한 상태가 될 수 있습니다. 안정성을 보장하려면 UI 변경 사항은 항상 메인 스레드(main thread)로 지연 실행(defer)되도록 처리해야 합니다.

SSL/TLS 및 CORS 제한 극복하기

플레이어 데이터를 보호하는 것은 매우 중요합니다. 침해 사고로부터 살아남는 게임 backend 아키텍처 설계에서 다룬 것처럼, 데이터 보호는 TLS와 강력한 서버 측 인증(server-side authentication)에서 시작됩니다. backend와의 핸드셰이크는 보안된 https:// 또는 wss:// 프로토콜을 통해 이루어져야 하며, 이를 위해서는 적절한 SSL/TLS 인증서 핸드셰이크가 필요합니다. 모바일 플랫폼에서는 아주 작은 네트워크 설정 오류만으로도 아무런 알림 없이 연결이 끊어질 수 있습니다. 게다가 웹 익스포트(HTML5)의 경우 브라우저가 엄격한 CORS(Cross-Origin Resource Sharing) 규칙을 적용하기 때문에 복잡성이 한층 더 가중됩니다.

코드: GDScript 2.0에서 Thread-Safe한 HTTP Request Pool 구현하기

Pool Manager GDScript 구현

다음 GDScript 싱글톤(singleton)은 요청이 중복되어 발생하는 오류를 예방하는 thread-safe한 pool 기반 HTTP 매니저를 제공합니다. 모든 노드가 사용 중일 때 들어오는 요청을 대기열에 추가하고, HTTPRequest 노드 풀을 동적으로 인스턴스화합니다. 또한 예상치 못한 서버 페이로드로 인한 런타임 크래시를 방지하기 위해 안전한 JSON 파싱을 수행합니다.

extends Node
class_name BackendHTTPManager

# Maximum concurrent HTTP requests allowed in the pool
const MAX_CONCURRENT_REQUESTS = 4

# Structure to hold queued request data
class PendingRequest:
	var url: String
	var method: HTTPClient.Method
	var headers: PackedStringArray
	var body: String
	var callback: Callable
	
	func _init(p_url: String, p_method: HTTPClient.Method, p_headers: PackedStringArray, p_body: String, p_callback: Callable):
		self.url = p_url
		self.method = p_method
		self.headers = p_headers
		self.body = p_body
		self.callback = p_callback

# Internal tracking
var _request_pool: Array[HTTPRequest] = []
var _active_requests: Dictionary = {}
var _request_queue: Array[PendingRequest] = []

func _ready() -> void:
	# Initialize the HTTPRequest pool
	for i in range(MAX_CONCURRENT_REQUESTS):
		var http_node = HTTPRequest.new()
		add_child(http_node)
		http_node.request_completed.connect(_on_request_completed.bind(http_node))
		_request_pool.append(http_node)

## Queue an asynchronous HTTP request
func send_request(url: String, method: HTTPClient.Method, headers: PackedStringArray, body: String, callback: Callable) -> void:
	var new_req = PendingRequest.new(url, method, headers, body, callback)
	_request_queue.append(new_req)
	_process_queue()

# Process next items in the queue if a pool node is free
func _process_queue() -> void:
	if _request_queue.is_empty():
		return
		
	# Find an idle HTTPRequest node
	var free_node: HTTPRequest = null
	for node in _request_pool:
		if not _active_requests.has(node):
			free_node = node
			break
			
	if free_node == null:
		# All nodes are busy; request remains in queue
		return
		
	var req = _request_queue.pop_front()
	_active_requests[free_node] = req
	
	var err = free_node.request(req.url, req.headers, req.method, req.body)
	if err != OK:
		# Immediately notify failure if the request failed to initiate
		_active_requests.erase(free_node)
		req.callback.call_deferred(false, -1, {}, "Failed to initiate request")
		_process_queue()

# Callback triggered when a request completes
func _on_request_completed(result: int, response_code: int, headers: PackedStringArray, body: PackedByteArray, http_node: HTTPRequest) -> void:
	if not _active_requests.has(http_node):
		return
		
	var req = _active_requests[http_node]
	_active_requests.erase(http_node)
	
	var response_string = body.get_string_from_utf8()
	var parsed_data = {}
	var success = (result == HTTPRequest.RESULT_SUCCESS) and (response_code >= 200 and response_code < 300)
	var error_message = ""
	
	if success:
		var json = JSON.new()
		var parse_err = json.parse(response_string)
		if parse_err == OK:
			if typeof(json.data) == TYPE_DICTIONARY:
				parsed_data = json.data
			else:
				success = false
				error_message = "Parsed JSON is not a dictionary"
						else:
				success = false
				error_message = "JSON parse error code: " + str(parse_err)
	else:
		error_message = "HTTP error code: " + str(response_code) + " or result failure: " + str(result)
				# Execute callback on the main thread safely
	req.callback.call_deferred(success, response_code, parsed_data, error_message)
	
	# Process next queued request
	_process_queue()

Pool 및 Queue 로직 분석

이 매니저는 _ready() 콜백 동안 HTTPRequest 자식 노드들의 정적 배열을 초기화합니다. 풀 크기를 MAX_CONCURRENT_REQUESTS와 같은 정의된 상수로 제한함으로써 클라이언트 측의 네트워크 혼잡을 제어할 수 있습니다. 각 노드는 중앙 응답 핸들러에 바인딩되며, 어떤 요청이 완료되었는지 추적하기 위해 자신의 참조(reference)를 전달합니다.

send_request() 함수는 URL, 페이로드, 호출 가능한 콜백을 포함하는 래퍼 클래스를 FIFO 큐에 추가합니다. 요청이 완료되면 풀 노드는 유휴 상태(idle)로 표시되고 매니저는 즉시 대기열의 다음 항목을 처리합니다. 이를 통해 요청 중복 오류를 원천적으로 예방합니다.

Godot 4.7에서 JSON Payload 안전하게 파싱하기

Godot 4.7에서의 데이터 파싱은 이전 주요 버전들과 달라졌습니다. 이제는 지원 중단된(deprecated) 전역 함수들을 사용하는 대신 새로운 JSON 객체를 인스턴스화하고 parse()를 호출합니다. json.data가 TYPE_DICTIONARY 유형인지 확인하여, backend가 잘못된 형식의 응답을 반환할 때 클라이언트가 크래시되는 것을 방지합니다.

마지막으로, call_deferred를 사용하여 메인 스레드(main thread)에서 콜백을 실행합니다. 이를 통해 네트워크 응답으로 인해 트리거되는 모든 UI 업데이트나 SceneTree 수정 작업이 안전하게 발생하도록 보장합니다. 이러한 콜백을 비동기식으로 실행하면 스레딩 충돌을 방지하고 프레임 레이트(frame rate)를 매끄럽게 유지할 수 있습니다.

플랫폼별 연동 장애물 해결: 웹 및 모바일

웹 익스포트 및 단일 스레드 WASM 제한 사항

WebAssembly 타겟은 데스크톱 빌드와 다르게 동작합니다. 브라우저 환경에서 Godot는 특정 SharedArrayBuffer 헤더가 설정되지 않는 한 단일 스레드 루프(single-threaded loop)에서 동작합니다. 동기식 블로킹 HTTP 작업을 사용하면 브라우저 창 전체가 멈추어 사용자 경험을 크게 저해할 수 있습니다.

이를 방지하려면 웹 플레이어를 위해 항상 시그널 기반의 논블로킹(non-blocking) 요청을 사용해야 합니다. 또한 backend endpoint가 적절한 CORS 헤더를 전송하도록 구성되었는지 확인해야 합니다. 구체적으로 Access-Control-Allow-Origin 및 Access-Control-Allow-Headers 헤더는 웹 게임이 호스팅되는 도메인을 명시적으로 허용해야 합니다.

안드로이드 익스포트 및 네트워크 권한

모바일 타겟은 고유의 당면 과제를 제시합니다. 안드로이드(Android) 익스포트 시 익스포트 프리셋에서 INTERNET 권한을 체크하는 것을 잊어버리는 흔한 실수로 인해 모든 네트워크 호출이 비활성화되곤 합니다. 아울러 Godot 4.7은 안드로이드 스플래시 화면 및 창 크기 조정에 대한 세련된 사용자 정의 기능을 도입하여 초기 부팅 시의 네트워크 확인 과정에서 발생할 수 있는 화면 글리치(glitch)를 방지해 줍니다.

모바일 플랫폼으로 익스포트하는 경우 규제 환경에 대한 이해가 필수적입니다. 제3자 모바일 결제 시스템 설계 가이드에서 다룬 바와 같이, 제3자 결제를 처리하기 위해서는 보안성이 보장된 API 핸드셰이크가 필수적입니다. 결제 콜백과 클라이언트 핸드셰이크가 안전하게 이루어지도록 설계해야 플레이어가 인앱 결제(microtransactions)를 우회하는 것을 방지할 수 있습니다.

Godot 4.7 Backend 연동 확장을 위한 Best Practices

1. Jitter를 포함한 Exponential Backoff 구현

재연결 폭풍(reconnection storm)이 발생했을 때 서버가 과부하되지 않도록 해야 합니다. 플레이어가 연결을 잃었을 때 고정된 간격으로 즉시 재시도하지 마십시오. 대신 매번 재시도 대기 시간을 1.5배 또는 2.0배로 늘리고, 모든 클라이언트가 동시에 재시도하는 것을 방지하기 위해 임의의 작은 오프셋(jitter)을 추가하십시오.

예를 들어 초기 재시도가 1.0초 뒤라면 다음 재시도는 2.0초, 4.0초, 8.0초 뒤에 발생해야 합니다. 연결이 끊긴 모든 클라이언트가 정확히 동일한 밀리초 단위에 동시에 재연결을 시도하지 않도록, 각 대기 시간마다 0.1초에서 0.5초 사이의 무작위 float 값을 더해 줍니다. 이렇게 하면 backend 서버의 부하를 분산시키고 장애 발생 시 연속적인 API 실패를 예방할 수 있습니다.

2. 양방향 Payload 검증

클라이언트 데이터는 절대 신뢰하지 마시고, 서버 데이터도 완벽한 형태를 갖추고 있다고 가정하지 마십시오. GDScript에서 데이터를 읽기 전에 모든 딕셔너리(dictionary)와 키(key)를 검증하십시오. 마찬가지로 backend 측에서도 수신되는 request body를 검증하여 SQL injection이나 원격 실행 취약점을 방지해야 합니다.

Multiplayer 게임에서 흔히 발생하는 취약점 중 하나는 클라이언트 측 데이터 신뢰입니다. 클라이언트 스크립트가 backend로부터 딕셔너리를 수신하는 경우, 액세스하기 전에 Dictionary.has()를 사용하여 필요한 모든 키가 존재하는지 검증하십시오. GDScript에서 누락된 키에 접근하면 런타임 에러가 발생하여 스크립트 실행이 중단됩니다. 이러한 검증을 통해 서버의 endpoint가 업데이트되더라도 UI가 망가지는 현상을 예방할 수 있습니다.

3. UI와 네트워크 서비스의 디커플링(Decoupling)

UI 스크립트 내부에 네트워킹 코드를 직접 작성하는 것을 피하십시오. 모든 HTTP 트래픽과 상태 관리를 처리하는 전용 autoload 싱글톤을 만드십시오. UI는 이 매니저가 방출(emit)하는 시그널에만 연결해야 하며, 이를 통해 프론트엔드 코드를 모듈화하고 테스트하기 쉽게 유지할 수 있습니다.

예를 들어 플레이어가 인벤토리 화면을 열 때, UI는 데이터를 요청하기 위한 사용자 정의 시그널을 방출해야 합니다. 네트워크 autoload는 이 시그널을 수신하고 HTTP 호출을 수행한 후, 딕셔너리가 채워지면 완료 시그널을 방출합니다. UI는 이 완료 시그널을 감지하여 인벤토리 그리드를 채웁니다. 이러한 디커플링은 UI의 응답성을 유지하고 네트워크 로직을 쉽게 디버깅할 수 있게 만들어 줍니다.

4. 조기에 CORS Pre-Flight 테스트 수행

itch.io와 같은 플랫폼에 게임을 게시하기 전에 항상 CORS가 활성화된 로컬 웹 서버에서 테스트를 진행하십시오. 많은 개발자들이 게임을 빌드한 후 웹 환경에서 오리진(origin) 정책으로 인해 HTTP 호출이 실패하는 현상을 뒤늦게 발견합니다. 조기 테스트는 출시 당일 구성 관련 응급 상황이 발생하는 것을 막아 줍니다.

브라우저는 POST 요청을 실행하기 전에 pre-flight 검사로 HTTP OPTIONS 요청을 먼저 전송합니다. backend가 OPTIONS 요청에 200 OK 상태로 응답하도록 설정되어 있지 않으면 브라우저는 후속 요청을 블록합니다. 이러한 오리진 문제를 진단하려면 브라우저의 콘솔 로그(F12)를 확인해야 합니다. 스테이징 과정에서 이러한 오류들을 파악하면 출시 당일 Multiplayer 로그인 문제가 발생하는 것을 방지할 수 있습니다.

Backend 인프라 표준화: 직접 코딩(Hand-Coding) vs 관리형 솔루션(Managed Solutions)

게임 서버를 처음부터 직접 구축할 때의 실제 비용

Godot 게임을 위한 커스텀 backend를 직접 구축하려면 상당한 노력이 필요합니다. 서버 코드를 작성하고, JWT Token 인증을 구현하며, 데이터베이스 인덱싱을 구성하고, load balancer를 관리해야 합니다. 이러한 인프라를 수동으로 설정하려면 전담 개발 시간이 4~6주 정도 소요될 수 있으며, 이는 게임 플레이 구현에 집중해야 할 에너지를 분산시킵니다. 안전한 production backend를 운영하려면 데이터베이스 클러스터링, 인증 토큰 만료 처리, 데이터베이스 스키마 마이그레이션이 필요합니다. 또한 서버 헬스 체크 및 네트워크 이슈 로깅을 위한 커스텀 스크립트도 직접 작성해야 합니다.

horizOn으로 개발 속도 향상시키기

horizOn SDK를 사용하면 이러한 번거로운 관리 작업을 제거할 수 있습니다. 플랫폼 내부에서 사용자 데이터 유지 관리, 텔레메트리(telemetry) 및 리더보드(leaderboard)를 백그라운드에서 알아서 처리하므로 여러분은 오롯이 게임 개발에만 집중할 수 있습니다. HTTP 연결 풀을 디버깅하는 대신 최적화된 인프라에서 작동하는 간단한 API 호출을 사용하기만 하면 됩니다. 덕분에 몇 주가 걸리던 기능을 단 몇 분 만에 플레이어들에게 배포할 수 있습니다. 이러한 인프라를 직접 구축하려면 4~6주의 고된 개발 일정이 걸릴 수 있지만, horizOn을 통해 이러한 backend 서비스를 사전 제공받음으로써 인프라 대신 게임을 빠르게 출시(ship)할 수 있게 됩니다.

Multiplayer backend의 규모를 안정적으로 확장할 준비가 되셨나요? 다음 프로젝트를 시작하려면 horizOn을 무료로 사용해 보거나 API documentation을 확인해 보십시오.

---

Source: Release candidate: Godot 4.7 RC 3