Godot 프로젝트를 웹으로 내보내기: 제약과 확인할 점

Godot 엔진으로 게임을 만들었다면 브라우저에서 바로 실행되는 웹 빌드로 배포하고 싶을 때가 많습니다. 하지만 웹 플랫폼은 네이티브 환경과 다른 제약이 많아서, 내보내기 전에 미리 확인해두지 않으면 배포 후 예상치 못한 문제를 만나게 됩니다. 이 글은 Godot 공식 문서를 바탕으로 웹 내보내기 시 꼭 알아야 할 제약과 점검 포인트를 정리합니다.

어떤 제작자에게 필요한가

Godot으로 만든 게임을 itch.io 같은 플랫폼이나 Poki, CrazyGames 같은 웹 퍼블리셔를 통해 배포하려는 제작자, 또는 앱스토어 심사 없이 브라우저에서 바로 플레이할 수 있는 버전을 제공하려는 제작자에게 필요한 내용입니다. 다만 Godot 4에서 C#으로 작성한 프로젝트는 현재 웹으로 내보낼 수 없으므로, C#을 웹에서 쓰고 싶다면 Godot 3을 사용해야 한다는 점을 먼저 알아두어야 합니다.

실제로 무엇을 할 수 있나

Godot은 프로젝트를 HTML5로 내보내 WebAssembly와 WebGL 2.0을 지원하는 브라우저에서 실행할 수 있게 해줍니다. Godot 4는 Compatibility 렌더링 방식을 사용하는 WebGL 2.0만 지원하며, Forward+나 Mobile 렌더링 방식은 웹에서 지원되지 않습니다. 이는 이 방식들이 WebGPU 같은 최신 저수준 그래픽 API를 전제로 설계되었고, Godot이 아직 WebGPU를 지원하지 않기 때문입니다.

Godot 4.3부터는 단일 스레드 내보내기가 기본값이 되었습니다. 기존 멀티스레드 내보내기는 SharedArrayBuffer 관련 보안 문제 때문에 서버 측에서 특정 헤더와 완전한 교차 출처 격리를 요구했고, 이 경우 광고나 서드파티 연동을 쓸 수 없었습니다. 단일 스레드 방식은 스레드를 쓸 수 없고 성능도 다소 떨어지지만, 설치 오버헤드가 적고 itch.io나 Poki, CrazyGames 같은 플랫폼과 호환성이 더 좋습니다. macOS와 iOS에서도 기존 멀티스레드 방식보다 안정적으로 동작합니다.

오디오 역시 Godot 4.3부터 Web Audio API 기반의 Sample 재생 방식을 기본으로 사용합니다. 스레드 지원 없이도 낮은 지연시간을 유지할 수 있지만, AudioEffects, 리버브, 도플러 효과, 프로시저럴 오디오 생성은 지원되지 않고 위치 기반 오디오도 노드 속성에 따라 정상 동작하지 않을 수 있습니다. Godot의 전체 오디오 기능을 쓰려면 Audio > General > Default Playback Type.web 프로젝트 설정이나 AudioStreamPlayer 계열 노드의 Playback Type을 Stream으로 바꿔야 하지만, 이 경우 지연시간이 늘어납니다.

사용 방법

내보내기 옵션에서는 다음을 확인해야 합니다.

• 파일 이름은 index.html로 지정하는 것이 권장됩니다. 웹 서버가 디렉터리 접근 시 기본으로 불러오는 파일명이기 때문입니다. 내보낸 파일 이름을 바꾸면 문제가 생길 수 있습니다.
• GDExtension을 사용한다면 Extension Support를 활성화해야 하며, GDExtension도 웹 플랫폼용으로 따로 컴파일되어 있어야 합니다.
• VRAM 압축을 쓸 계획이라면 대상 플랫폼에 맞게 VRAM Texture Compression을 켜야 합니다. Desktop과 Mobile 둘 다 켜면 호환성은 높아지지만 용량이 커집니다.
• Custom HTML shell 파일 경로를 지정하면 기본 HTML 페이지 대신 사용할 수 있고, Head Include를 통해 웹폰트나 서드파티 JS, CSS를 추가할 수 있습니다.
• Canvas Resize Policy를 None으로 바꾸면 브라우저 창 크기와 무관하게 고정 크기를 쓸 수 있고, Project로 설정하면 네이티브 내보내기와 비슷하게 동작합니다.
• Thread Support를 켜면 멀티스레드를 활용해 성능을 높이고 Stream 재생 시 낮은 지연시간도 얻을 수 있지만, 교차 출처 격리 헤더 설정이 필요합니다.
• Progressive Web App(PWA) 기능을 켜면 고해상도 아이콘, 화면 방향 설정, 인터넷 연결 없이도 실행 가능한 오프라인 지원 등을 구성할 수 있습니다. 오프라인 캐시가 지워졌을 때 보여줄 Offline Page도 설정할 수 있습니다.

모바일 환경을 고려한다면, 네이티브 Android/iOS 빌드보다 성능은 떨어지지만 앱스토어를 거치지 않고 실행할 수 있다는 장점이 있습니다. 기능 태그를 활용해 웹 전용으로 저사양 설정을 적용하거나, 사용하지 않는 기능을 뺀 최적화된 내보내기 템플릿을 컴파일하면 WebAssembly 페이로드 크기를 줄여 로딩을 빠르게 할 수 있습니다.

한계와 주의할 점

웹 플랫폼은 보안과 개인정보 보호 때문에 네이티브에서는 쉬웠던 기능들이 복잡해집니다.

• 일부 브라우저 기능은 HTTPS 같은 보안 컨텍스트에서만 동작하며, localhost는 보통 예외입니다.
• user:// 파일 시스템의 영속성을 위해서는 사용자가 쿠키(IndexedDB)를 허용해야 하고, iframe 안에서 실행한다면 서드파티 쿠키도 허용되어야 합니다. 시크릿 모드에서는 영속성이 보장되지 않습니다.
• 브라우저 탭이 비활성 상태가 되면 _process()나 _physics_process() 같은 함수 실행이 멈춰, 네트워크 게임이 연결 끊김을 겪을 수 있습니다. 이 제약은 별도 창으로 실행하면 피할 수 있습니다.
• 전체 화면 전환이나 마우스 커서 캡처는 임의로 실행할 수 없고, 반드시 클릭 등 유효한 입력 이벤트 콜백 안에서 호출해야 합니다.
• 일부 브라우저는 오디오 자동 재생을 제한하므로, 시작 화면에서 클릭이나 키 입력을 유도해 오디오를 활성화하는 방식이 권장됩니다. 마이크 접근 역시 보안 컨텍스트가 필요합니다.
• 저수준 네트워킹은 브라우저 자체의 한계로 구현되어 있지 않습니다.

또한 Safari는 WebGL 2.0 지원에서 다른 브라우저와 다른 여러 문제가 있어, 가능하면 Chromium 기반 브라우저나 Firefox 사용이 권장됩니다. 내보낸 HTML 파일을 직접 수정하면 다음 내보내기 때 사라지므로, 커스터마이징이 필요하면 Custom HTML shell 옵션을 사용해야 합니다.

다음에 볼 것

웹 내보내기 설정을 더 깊이 다루려면 Custom HTML 페이지 구성 방법이나 서버 헤더 설정(Serving the files) 부분을 추가로 확인하는 것이 좋고, 성능 최적화가 필요하다면 Performance 관련 문서를 참고하는 것이 도움이 됩니다.

이 글은 공식 문서를 한국어로 정리한 것이며 세부 내용은 원문을 기준으로 해 주세요.