Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
웹으로 내보내기
더 보기
이 페이지는 Godot 프로젝트를 HTML5로 내보내는 방법을 설명합니다. 소스로부터 편집기나 내보내기 템플릿 바이너리를 컴파일하고자 한다면, 대신 웹용으로 컴파일하기를 읽으세요.
HTML5 내보내기로 Godot 엔진에서 만든 게임을 브라우저에 출시할 수 있습니다. 이를 위해 사용자의 브라우저에서 WebAssembly와 WebGL 2.0을 지원해야 합니다.
주의
Godot 4를 사용하여 C#으로 작성된 프로젝트는 현재 웹으로 내보낼 수 없습니다. 자세한 내용은 `이 블로그 게시물 <https://godotengine.org/article/platform-state-in-csharp-for-godot-4-2/#web>`__을 참조하세요.
웹 플랫폼에서 C#을 사용하려면 대신 Godot 3를 사용하세요.
팁
JavaScript, 엔진, WebGL 오류와 같은 디버그 정보를 보려면 브라우저 통합 개발자 콘솔을 사용하세요. 이 콘솔은 일반적으로 F12 또는 Ctrl + Shift + I(macOS에서는 Cmd + Option + I)로 열립니다.
단축키가 작동하지 않는다면 Godot가 실제로 입력을 캡처하기 때문입니다. 브라우저 메뉴에 액세스하여 개발자 콘솔을 열 수 있습니다.
참고
다양한 악용으로 인한 ``SharedArrayBuffer``의 보안 문제로 인해 웹 플랫폼에 다중 스레드를 사용하면 특정 서버 측 헤더 및 완전한 원본 간 격리가 필요한 등 여러 가지 단점이 있습니다(게임을 호스팅하는 웹 사이트에 광고가 없고 타사 통합이 없음을 의미함).
Godot 4.3부터 Godot는 단일 스레드에서 게임 내보내기를 지원하여 이 문제를 해결합니다. 자체적으로 몇 가지 단점이 있지만(스레드를 사용할 수 없고 멀티스레드 내보내기만큼 성능이 좋지 않음) 설치하는 데 많은 오버헤드가 필요하지 않습니다. 또한 itch.io <https://itch.io/>`__과 같은 상점이나 `Poki 또는 `CrazyGames <https://crazygames.com/>`__과 같은 웹 게시자와 전반적으로 더 잘 호환됩니다. 단일 스레드 내보내기는 항상 다중 스레드 내보내기와 호환성 문제가 있었던 macOS 및 iOS에서도 매우 잘 작동합니다.
이러한 이유로 웹에서 게임을 내보내는 것이 선호되는 기본 방법입니다.
자세한 내용은 `단일 스레드 웹 내보내기에 대한 이 블로그 게시물 <https://godotengine.org/article/progress-report-web-export-in-4-3/#single-threaded-web-export>`__을 참조하세요.
더 보기
알려진 버그의 목록에 대해서는 웹 내보내기와 관련된 GitHub의 열린 이슈 목록을 참조하세요.
내보내기 파일 이름
사용자는 파일 이름으로 ``index.html``를 사용하여 웹 프로젝트를 내보내는 것이 좋습니다. ``index.html``는 일반적으로 상위 디렉토리에 액세스할 때 웹 서버가 로드하는 기본 파일이며 일반적으로 해당 파일의 이름을 숨깁니다.
주의
Godot 4 웹 내보내기에서는 일부 파일의 이름이 초기 내보내기에서 설정된 것과 동일한 이름으로 지정될 것으로 예상합니다. 기본 HTML 파일을 포함하여 일부 내보낸 파일의 이름을 바꾸면 일부 문제가 발생할 수 있습니다.
WebGL 버전
Godot 4는 WebGL 2.0만을 대상으로 할 수 있습니다(호환성 렌더링 방법 사용). Forward+/Mobile은 웹 플랫폼에서 지원되지 않습니다. 이러한 렌더링 방법은 최신 저수준 그래픽 API를 중심으로 설계되었기 때문입니다. Godot는 현재 웹 플랫폼에서 Forward+/Mobile을 실행하기 위한 전제 조건인 WebGPU를 지원하지 않습니다.
WebGL 2.0을 지원하는 브라우저 버전 목록은 `WebGL 2.0 <https://caniuse.com/webgl2>`__을 사용할 수 있습니까?를 참조하세요. Safari에는 WebGL 2.0 지원과 관련하여 다른 브라우저에는 없는 몇 가지 문제가 있으므로 가능하면 Chromium 기반 브라우저나 Firefox를 사용하는 것이 좋습니다.
내보내기 고려 사항
웹 내보내기는 몇 가지 주의 사항이 있지만 모바일 플랫폼에서 실행할 수 있습니다. 기본 Android 및 iOS 내보내기는 항상 상당한 차이로 더 나은 성능을 발휘하지만 웹 내보내기를 사용하면 사람들이 앱 스토어를 거치지 않고도 프로젝트를 실행할 수 있습니다.
모바일 장치에서 실행할 때 CPU 및 GPU 성능이 가장 중요하다는 점을 기억하십시오. 이는 웹으로 내보낸 프로젝트를 실행할 때 더욱 그렇습니다(네이티브 코드 대신 WebAssembly이기 때문입니다). 프로젝트 최적화에 대한 조언은 문서의 성능 섹션을 참조하세요. 프로젝트가 웹이 아닌 플랫폼에서 실행되는 경우 웹으로 내보낸 프로젝트를 실행할 때 :ref:`doc_feature_tags`를 사용하여 저사양 지향 설정을 적용할 수 있습니다.
모바일 장치에서 로딩 시간을 단축하려면 사용하지 않는 기능을 비활성화한 상태에서 :ref:`최적화된 내보내기 템플릿 <doc_optimizing_for_size>`을 컴파일해야 합니다. 프로젝트에서 사용하는 기능에 따라 WebAssembly 페이로드의 크기가 크게 줄어들어 다운로드 및 초기화가 더 빨라집니다(캐시된 경우에도).
오토로드
Godot 4.3부터 오디오 재생은 웹 플랫폼에서 Web Audio API를 사용하여 수행됩니다. 이 샘플 재생 모드는 스레드 지원 없이 프로젝트를 내보내는 경우에도 낮은 대기 시간을 허용하지만 몇 가지 제한 사항이 있습니다.
모드 지원 제공
잔향 및 도플러 효과는 지원되지 않습니다.
절차적 오디오 생성은 지원되지 않습니다.
노드의 속성에 따라 위치 오디오가 올바르게 작동하지 않을 수도 있습니다.
웹 플랫폼에서 Godot의 자체 오디오 재생 시스템을 사용하려면 Audio > 일반 > Default Playback Type.web 프로젝트 설정을 사용하여 기본 재생 모드를 변경하거나 AudioStreamPlayer, AudioStreamPlayer2D 또는 AudioStreamPlayer3D 노드에서 재생 유형 속성을 **스트림**으로 변경할 수 있습니다. 이로 인해 지연 시간이 늘어나지만(특히 스레드 지원이 비활성화된 경우) Godot의 전체 오디오 기능이 작동할 수 있습니다.
내보내기 옵션
실행 가능한 웹 내보내기 템플릿을 사용할 수 있다면, 편집기에서 씬 정지 버튼과 편집된 씬 재생 버튼 사이에 버튼이 나타나 테스트를 위해 빠르게 기본 브라우저에서 게임을 열 수 있습니다.
프로젝트에서 GDExtension을 사용하는 경우 **확장 지원**을 활성화해야 합니다.
VRAM 압축을 사용할 생각이라면 목표 플랫폼의 Vram 텍스처 압축이 활성화되어 있는지 확인해야합니다(데스크톱용과 모바일용을 둘 다 활성화 하면 용량은 커지지만 호환성이 증가합니다).
커스텀 HTML 셸 파일에 대한 경로가 주어진다면, 그것이 기본 HTML 페이지 대신 사용됩니다. 웹 내보내기를 위한 사용자 정의 HTML 페이지을 참고하세요.
Head Include는 생성된 HTML 페이지의 <head>에 나타납니다. 이걸로 웹 글꼴이나 CSS가 포함된 서드 파티 JavaScript API를 불러오거나, JavaScript 코드를 실행할 수 있습니다.
창 크기는 기본적으로 브라우저 창 크기와 자동으로 일치합니다. 브라우저 창 크기에 관계없이 고정된 크기를 사용하려면 **캔버스 크기 조정 정책**을 **없음**으로 변경하세요. 이를 통해 HTML 셸에서 사용자 정의 JavaScript 코드로 창 크기를 제어할 수 있습니다. :ref:`프로젝트 설정 <doc_multiple_solutions>`에 따라 기본 내보내기에 더 가깝게 작동하도록 **프로젝트**로 설정할 수도 있습니다.
중요
프로젝트는 항상 각자의 HTML를 생성해야 합니다. 내보내기 과정에서, 내보내기 옵션에 따라 생성된 HTML의 text placeholders들이 대체됩니다. HTML을 직접 수정한 부분은 이후 내보내기 과정에서 사라지게 됩니다. 생성된 파일을 수정하려면 Custom HTML shell 옵션을 사용하세요.
GDNative 미지원.
스레드 지원**이 활성화된 경우 내보낸 프로젝트는 :ref:`멀티스레딩 <doc_using_multiple_threads>`을 사용하여 성능을 향상시킬 수 있습니다. 또한 재생 유형이 **스트림**(웹 내보내기에 사용되는 기본 **샘플 대신)으로 설정된 경우 지연 시간이 짧은 오디오 재생이 가능합니다. 이 기능을 활성화하려면 아래 파일 전달하기 섹션에 설명된 교차 출처 격리 헤더를 사용해야 합니다.
**확장 지원**이 활성화된 경우 :ref:`GDExtensions <doc_what_is_gdextension>`을 로드할 수 있습니다. 웹 플랫폼이 작동하려면 GDExtensions를 특별히 컴파일해야 합니다. 스레드 지원과 마찬가지로 이 기능을 활성화하려면 원본 간 격리 헤더를 사용해야 합니다.
PWA(프로그레시브 웹 앱)로 내보내기
**프로그레시브 웹 앱 > 활성화**가 활성화되면 다음과 같은 여러 가지 효과가 있습니다.
고해상도 아이콘, 디스플레이 모드 및 화면 방향을 구성합니다. 이는 내보내기 옵션의 Progressive Web App 섹션 끝에서 구성됩니다. 이 옵션은 사용자가 장치의 홈 화면에 프로젝트를 추가하는 경우 사용되며, 이는 모바일 플랫폼에서 일반적입니다. 이는 비록 용량이 더 제한되어 있지만 데스크탑 플랫폼에서도 지원됩니다.
프로젝트가 사전에 한 번 이상 로드된 경우 인터넷 연결 없이 프로젝트를 로드할 수 있도록 허용합니다. 이는 프로젝트가 사용자 브라우저에 처음 로드될 때 설치되는 서비스 워커 덕분에 작동합니다. 이 서비스 워커는 인터넷 연결을 사용할 수 없을 때 로컬 대체를 제공합니다.
사용자의 디스크 공간이 부족하거나 사용자가 한동안 프로젝트를 열지 않은 경우 웹 브라우저는 캐시된 데이터를 제거하도록 선택할 수 있습니다. 데이터가 더 오랫동안 캐시되도록 하려면 사용자가 페이지를 북마크에 추가하거나 이상적으로는 해당 페이지를 장치의 홈 화면에 추가할 수 있습니다.
캐시에서 제거되어 오프라인 데이터를 사용할 수 없는 경우 이 경우 표시될 **오프라인 페이지**를 구성할 수 있습니다. 페이지는 HTML 형식이어야 하며 프로젝트가 처음 로드될 때 클라이언트 컴퓨터에 저장됩니다.
웹 서버가 헤더를 보내도록 구성되지 않은 경우에도 원본 간 격리 헤더가 항상 존재하는지 확인하세요. 이를 통해 전송되는 헤더를 제어할 수 있는 방법이 없는 경우에도 모든 웹 사이트에서 호스팅될 때 스레드가 활성화된 내보내기가 작동할 수 있습니다.
프로그레시브 웹 앱 섹션에서 **원본 간 격리 헤더 활성화**를 선택 취소하면 이 동작을 비활성화할 수 있습니다.
제한 사항
보안 및 개인 정보의 이유로, 네이티브 플랫폼에서 여유롭게 작동하는 많은 기능이 웹 플랫폼에서는 더 복잡합니다. 다음은 Godot 게임을 웹으로 이식할 때 알아야 할 제한 사항의 목록입니다.
중요
브라우저 공급업체는 보안 컨텍스트에서만 사용 가능한 기능을 점점 더 많이 만들고 있는데 즉, 이러한 기능은 웹 페이지가 보안 HTTPS 연결을 통해 제공되는 경우에만 사용 가능합니다 (localhost는 보통 이러한 요구 사항에서 예외입니다).
백그라운드 처리
탭이 더 이상 사용자 브라우저의 활성 탭이 아닌 경우 브라우저에 의해 프로젝트가 일시 중지됩니다. 이는 사용자가 탭을 다시 활성화할 때까지(탭으로 다시 전환하여) _process() 및 ``_physics_process()``와 같은 기능이 더 이상 실행되지 않음을 의미합니다. 이로 인해 사용자가 오랫동안 탭을 전환하면 네트워크로 연결된 게임의 연결이 끊어질 수 있습니다.
이 제한은 초점이 맞지 않는 브라우저 *창*에는 적용되지 않습니다. 따라서 사용자 측에서는 별도의 탭이 아닌 별도의 *창*에서 프로젝트를 실행하여 이 문제를 해결할 수 있습니다.
전체화면과 마우스 캡쳐
브라우저는 임의로 전체화면으로 가기를 하용하지 않습니다. 마우스 캡쳐하기도 마찬가지입니다. 대신 이러한 동작은 JavaScript 입력 이벤트의 결과로 일어나야합니다. Godot에서는, _input이나 _unhandled_input과 같은 입력된 이벤트 콜백 내에서 전체화면으로 들어가는 것입니다. Input 싱글톤을 쿼리하는 것으로는 충분하지 않고, 관련된 입력 이벤트가 현재 활성화되어야 합니다.
같은 이유에서, 전체화면 프로젝트 설정은 올바른 입력 이벤트 핸들러 내에서 엔진이 시작해야 작동합니다. 여기에는 HTML 페이지의 커스터마이징이 필요합니다.
오디오
일부 브라우저는 웹사이트의 오디오 자동 재생을 제한합니다. 이 제한을 해결하는 가장 쉬운 방법은 예를 들어 게임 시작 시 스플래시 화면을 표시할 때 플레이어에게 키/버튼을 클릭하거나 탭하거나 눌러 오디오를 활성화하도록 요청하는 것입니다.
더 보기
Google은 웹 오디오 자동재생 정책에 대한 추가 정보를 제공합니다.
Apple의 Safari 팀은 `macOS에 대한 자동 재생 정책 변경 사항 <https://webkit.org/blog/7734/auto-play-policy-changes-for-macos/>`__에 대한 추가 정보도 게시했습니다.
경고
마이크에 접근하려면 보안 컨텍스트가 필요합니다.
경고
Godot 4.3부터 기본적으로 웹 내보내기는 스트림 대신 샘플을 사용하여 오디오를 재생합니다.
이는 브라우저가 오디오 재생을 선호하는 방식과 스레드 사용 내보내기 옵션을 끈 상태에서 웹 게임을 내보낼 때 사용할 수 있는 처리 능력이 부족하기 때문입니다.
샘플에는 아직 오디오 효과가 구현되지 않았습니다.
네트워킹
저수준 네트워킹은 브라우저의 지원이 미미하여 구현되지 않았습니다.
현재는 HTTP client, HTTP requests, WebSocket (client) 와 :ref:`WebRTC <doc_webrtc>`가 지원됩니다.
HTTP 클래스는 HTML5 플랫폼에 여러 제한을 갖고 있습니다:
StreamPeer로 접근하거나 바꾸는 것이 불가능합니다Threaded/Blocking 모드를 사용할 수 없습니다
한 프레임에 여러 번 처리할 수 없습니다, 그래서 루프에서 폴링은 멈춥니다
청크 응답 없음
호스트 확인을 비활성화할 수 없습니다
동일 출처 정책 <https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy>이 적용됨
클립보드
엔진과 운영 체제간 클립보드 동기화는 브라우저가 Clipboard API를 지원해야 합니다. 또한 비동기적 API의 특성으로 인해 GDScript에서의 접근시 안정성을 보장하지 못할 수 있습니다.
경고
secure context가 필요합니다.
게임패드
게임패드의 버튼이 눌리기 전까지는 감지되지 않습니다. 또한 브라우저/OS/게임패드의 조합에 따라 게임패드의 매핑이 잘못되었을 가능성이 존재합니다. 안타깝게도 Gamepad API 는 개인정보 보호 차원에서 모델/공급자/OS에 따라 게임패드를 다시 매핑할 수 있는 안정적인 방법을 지원하지 않습니다.
경고
secure context가 필요합니다.
파일 전달하기
웹으로 내보내면 웹 서버로 보낼 여러 파일들을 생성합니다, 표시하기 위한 기본 HTML 페이지도 이에 속합니다. 커스텀 HTML 파일을 사용할 수 있습니다, 웹 내보내기를 위한 사용자 정의 HTML 페이지을 보세요.
경고
**스레드 사용**으로 내보낼 때만 낮은 오디오 대기 시간과 웹 내보내기에서 Thread 사용 기능을 보장하기 위해 Godot 4 웹 내보내기는 `SharedArrayBuffer <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer>`__을 사용합니다. 이를 위해서는 :ref:`secure context <doc_javascript_secure_contexts>`가 필요하며 파일을 제공할 때 다음 CORS 헤더를 설정해야 합니다.
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
웹 서버를 제어하지 않거나 응답 헤더를 추가할 수 없는 경우 내보내기 옵션에서 **Progressive Web App > 활성화**를 선택하세요. 이는 이러한 응답 헤더의 존재를 시뮬레이션하여 프로젝트를 실행할 수 있는 서비스 작업자 기반 해결 방법을 적용합니다. 이 경우에도 보안 컨텍스트가 필요합니다.
클라이언트가 필요한 응답 헤더를 수신하지 못하거나 서비스 작업자 기반 해결 방법이 적용되지 않으면 프로젝트가 실행되지 않습니다.
생성된 .html 파일을 Apache 서버에서 DirectoryIndex로 사용할 수 있고 언제든지 index.html과 같은 이름으로 바꿀 수 있습니다, 이름은 기본적으로 파일에 의지하지 않습니다.
HTML 페이지는 브라우저 창에 최대 크기로 게임을 표시합니다. 이렇게 하면 게임을 게임의 크기가 있는 <iframe>에 넣을 수 있습니다, 흔한 웹 게임 호스팅 사이트에서 쓰는 방식이죠.
.html 파일 옆에 다른 내보낸 파일은 그대로 전달되지만, 이름은 바뀌지 않습니다. .wasm 파일은 엔진을 구현하는 이진 WebAssembly 모듈입니다. .pck 파일은 Godot 메인 팩으로 게임을 갖고 있습니다. .js 파일은 시작 코드가 있으며 .html 파일이 엔진에 접근하는 데 사용됩니다. .png 파일은 부팅 스플래시 이미지입니다. 기본 HTML 페이지에서는 쓰이지 않지만, 맞춤 HTML 페이지를 위해 포함됩니다.
.pck 파일은 이진 파일로, 보통 MIME 타입 application/octet-stream으로 전달됩니다. .wasm 파일은 application/wasm 으로 전달됩니다.
경고
WebAssembly 모듈(.wasm)을 application/wasm이외의 MIME 유형으로 전달하면 일부 시작 최적화를 방지할 수 있습니다.
서버 측에서 압축한 파일을 전달하는 것이 .pck 와 .wasm 파일 같은 큰 사이즈의 파일에 적합합니다. WebAssembly 모듈은 압축을 특히 잘하는데, gzip 압축을 사용하여 원번 크기의 약 4분의 1까지 줄일 수 있습니다.
On-the-fly 압축을 지원하는 호스트: GitHub Pages (gzip)
On-the-fly 압축을 지원하지 않는 호스트: itch.io, GitLab Pages (supports manual gzip precompression)
팁
Godot 저장소에는 `로컬 웹 서버를 호스팅하는 Python 스크립트 <https://raw.githubusercontent.com/godotengine/godot/master/platform/web/serve.py>`__가 포함되어 있습니다. 이 스크립트는 웹 편집기를 테스트하기 위한 것이지만 내보낸 프로젝트를 테스트하는 데에도 사용할 수 있습니다.
연결된 스크립트를 ``serve.py``라는 파일에 저장하고 이 파일을 내보낸 프로젝트의 ``index.html``가 포함된 폴더로 이동한 후 동일한 폴더 내의 명령 프롬프트에서 다음 명령을 실행합니다.
# You may need to replace `python` with `python3` on some platforms.
python serve.py --root .
Windows에서는 :kbd:`Shift`을 누른 상태에서 Windows 탐색기의 빈 공간을 마우스 오른쪽 버튼으로 클릭한 다음 **여기에서 PowerShell 창 열기**를 선택하여 현재 폴더에서 명령 프롬프트를 열 수 있습니다.
그러면 현재 폴더의 내용이 제공되고 기본 웹 브라우저가 자동으로 열립니다.
프로덕션 사용 사례의 경우 이 Python 기반 웹 서버를 사용하면 안 됩니다. 대신 Apache 또는 nginx와 같은 확립된 웹 서버를 사용해야 합니다.
쿼터니언(quaternions) 으로 보간하기
JavaScript와 상호 작용하고 일부 고유한 웹 브라우저 기능에 액세스하는 방법은 :ref:`전용 페이지 <doc_web_javascript_bridge>`를 참조하세요.
환경변수
다음 환경 변수를 사용하여 편집기 외부에서 내보내기 옵션을 설정할 수 있습니다. 내보내기 프로세스 중에 이는 내보내기 메뉴에서 설정한 값보다 우선 적용됩니다.
내보내기 옵션 |
환경 변수 |
|---|---|
암호화 / 암호화 키 |
|
문제 해결
로컬로 내보내기를 실행하면 대신 다른 프로젝트가 표시됩니다.
여러 프로젝트에서 원클릭 배포를 사용하는 경우 현재 작업 중인 프로젝트 대신 이전에 배포한 프로젝트 중 하나가 표시되는 것을 확인할 수 있습니다. 이는 현재 자동화된 캐시 무효화 메커니즘이 부족한 서비스 작업자 캐싱 때문입니다.
해결 방법으로 현재 서비스 워커를 수동으로 등록 취소하여 캐시가 재설정되도록 할 수 있습니다. 이를 통해 새로운 서비스 워커를 등록할 수도 있습니다. Chromium 기반 브라우저에서는 F12 또는 Ctrl + Shift + I`(macOS의 경우 :kbd:`Cmd + Option + I)를 눌러 개발자 도구를 연 다음 DevTools의 Application 탭을 클릭합니다(devtools 창이 좁은 경우 갈매기형 아이콘 뒤에 숨겨져 있을 수 있음). reload@@에서 :button:`Update를 선택하고 페이지를 새로 로드하거나, 현재 등록된 서비스 워커 옆에 있는 `RSTROLE§button§Unregister@@을 클릭한 다음 페이지를 다시 로드할 수 있습니다.
Chromium 기반 브라우저의 DevTools에서 서비스 워커 등록 취소
절차는 Firefox에서도 비슷합니다. F12 또는 Ctrl + Shift + I`(macOS의 경우 :kbd:`Cmd + Option + I)를 눌러 개발자 도구를 열고 DevTools의 Application 탭을 클릭합니다(devtools 창이 좁은 경우 갈매기형 아이콘 뒤에 숨겨져 있을 수 있음). 현재 등록된 서비스 워커 옆에 있는 :button:`Unregister`을 클릭한 후 페이지를 다시 로드하세요.
Firefox의 DevTools에서 서비스 워커 등록 취소
내보내기 옵션
EditorExportPlatformWeb 클래스 참조에서 사용 가능한 내보내기 옵션의 전체 목록을 찾을 수 있습니다.