Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

웹으로 내보내기

더 보기

This page describes how to export a Godot project to HTML5. If you're looking to compile editor or export template binaries from source instead, read Compiling for the Web.

HTML5 export allows publishing games made in Godot Engine to the browser. This requires support for WebAssembly, WebGL and SharedArrayBuffer in the user's browser.

주의

Projects written in C# using Godot 4 currently cannot be exported to the web. To use C# on web platforms, use Godot 3 instead.

Use the browser-integrated developer console, usually opened with F12 (Cmd + Option + I on macOS), to view debug information like JavaScript, engine, and WebGL errors.

주의

Godot 4's HTML5 exports currently cannot run on macOS and iOS due to upstream bugs with SharedArrayBuffer and WebGL 2.0. We recommend using macOS and iOS native export functionality instead, as it will also result in better performance.

Godot 3's HTML5 exports are more compatible with various browsers in general, especially when using the GLES2 rendering backend (which only requires WebGL 1.0).

WebGL 버전

Godot 4.0 and later can only target WebGL 2.0 (using the Compatibility rendering method). There is no stable way to run Vulkan applications on the web yet.

See Can I use WebGL 2.0 for a list of browser versions supporting WebGL 2.0. Note that Safari has several issues with WebGL 2.0 support that other browsers don't have, so we recommend using a Chromium-based browser or Firefox if possible.

내보내기 설정

실행 가능한 웹 내보내기 템플릿을 이용할 수 있다면, 편집기에서 씬 멈추기 버튼과 편집 중인 씬 실행 버튼 사이에 버튼이 나타나 테스트를 위해 빠르게 기본 브라우저에서 게임을 열 수 있습니다.

If you plan to use VRAM compression make sure that Vram Texture Compression is enabled for the targeted platforms (enabling both For Desktop and For Mobile will result in a bigger, but more compatible export).

맞춤 HTML 셸 파일에 대한 경로가 주어진다면, 그것이 기본 HTML 페이지 대신 사용됩니다. Custom HTML page for Web export을 참고하세요.

Head Include는 생성된 HTML 페이지의 <head>에 나타납니다. 이걸로 웹 폰트나CSS가 포함된 타사 JavaScript API를 불러오거나, JavaScript 코드를 실행할 수 있습니다.

중요

프로젝트는 항상 각자의 HTML를 생성해야 합니다. 내보내기 과정에서, 내보내기 옵션에 따라 생성된 HTML의 text placeholders들이 대체됩니다. HTML을 직접 수정한 부분은 이후 내보내기 과정에서 사라지게 됩니다. 생성된 파일을 수정하려면 Custom HTML shell 옵션을 사용하십시오.

제한사항

보안 및 개인 정보의 이유로, 네이티브 플랫폼에서 여유롭게 작동하는 많은 기능이 웹 플랫폼에서는 더 복잡합니다. 다음은 Godot 게임을 웹으로 이식할 때 알아야 할 제한사항 목록입니다.

중요

브라우저 공급자들은 만흔 기능들을 secure contexts 에서만 사용이 가능하도록 만들고 있는데, 때문에 그 기능들은 웹 페이지가 안전한 HTTPS 연결을 통해 배포되어야만 사용이 가능합니다(로컬 호스트는 보통 예외입니다).

데이터 지속성을 위한 쿠키 사용

user://의 파일 시스템이 지속성을 갖길 원한다면 (특히 IndexedDB에서) 사용자는 반드시 쿠키를 허용해야합니다. iframe에 게임을 하는 것을 보여준다면, 서드 파티 쿠키도 허용해야합니다. 시크릿/비밀 브라우징 모드도 이 지속성을 방해합니다.

메서드 OS.is_userfs_persistent()user:// 파일 시스템이 존재하는 지를 확인할 수 있습니다, 하지만 어떤 경우에는 잘못된 반응을 가져올 수 있습니다.

Background processing

The project will be paused by the browser when the tab is no longer the active tab in the user's browser. This means functions such as _process() and _physics_process() will no longer run until the tab is made active again by the user (by switching back to the tab). This can cause networked games to disconnect if the user switches tabs for a long duration.

This limitation does not apply to unfocused browser windows. Therefore, on the user's side, this can be worked around by running the project in a separate window instead of a separate tab.

전체화면과 마우스 캡쳐

브라우저는 임의로 전체화면으로 가기를 하용하지 않습니다. 마우스 캡쳐하기도 마찬가지입니다. 대신 이러한 동작은 JavaScript 입력 이벤트의 결과로 일어나야합니다. Godot에서는, _input이나 _unhandled_input과 같은 입력된 이벤트 콜백 내에서 전체화면으로 들어가는 것입니다. Input 싱글톤을 쿼리하는 것으로는 충분하지 않고, 관련된 입력 이벤트가 현재 활성화되어야 합니다.

같은 이유에서, 전체화면 프로젝트 설정은 유효한 입력 이벤트 핸들러 내에서 엔진이 시작해야 작동합니다. 여기에는 HTML 페이지의 커스터마이징이 필요합니다.

오디오

Some browsers restrict autoplay for audio on websites. The easiest way around this limitation is to request the player to click, tap or press a key/button to enable audio, for instance when displaying a splash screen at the start of your game.

더 보기

구글은 웹 오디오 자동재생 규칙에 대한 정보를 제공합니다.

Apple's Safari team also posted additional information about their Auto-Play Policy Changes for macOS.

경고

마이크에 액세스 하기 위해서는 secure context <doc_javascript_secure_contexts> 가 필요합니다.

네트워킹(Networking)

저수준 네트워킹은 브라우저의 지원이 미미하여 구현되지 않았습니다.

현재는 HTTP client, HTTP requests, WebSocket (client) 와 :ref:`WebRTC <doc_webrtc>`가 지원됩니다.

The HTTP classes also have several restrictions on the HTML5 platform:

  • StreamPeer로 접근하거나 바꾸는 것이 불가능합니다

  • Threaded/Blocking 모드를 사용할 수 없습니다

  • 한 프레임에 여러 번 처리할 수 없습니다, 그래서 루프에서 폴링은 멈춥니다

  • 청크 응답 없음

  • 호스트 확인을 비활성화할 수 없습니다

  • 동일 출처 정책 <https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy>이 적용됨

클립보드

엔진과 운영체제간 클립보드 동기화는 브라우저가 Clipboard API 를 지원해야만 가능합니다. 또한 비동기적 API 의 특성으로 인해 GDScript에서의 접근시 안정성을 보장하지 못할 수 있습니다.

경고

:ref:`Secure context <doc_javascript_secure_contexts>`가 필요합니다.

게임패드

게임패드의 버튼이 눌리기 전까지는 감지되지 않습니다. 또한 브라우저/OS/게임패드의 조합에 따라 게임패드의 매핑이 잘못되었을 가능성이 존재합니다. 안타깝게도 Gamepad API 는 개인정보 보호 차원에서 모델/공급자/OS에 따라 게임패드를 다시 매핑할 수 있는 안정적인 방법을 지원하지 않습니다.

경고

:ref:`Secure context <doc_javascript_secure_contexts>`가 필요합니다.

부팅 스플래시가 표시되지 않습니다

기본 HTML 페이지는 로딩 중에 부팅 스플래시를 보여주지 않습니다. 하지만 이미지를 PNG 파일로 내보낼 수 있기 때문에, 맞춤 HTML 페이지 가 부팅 스플래시를 보여줄 수 있습니다.

파일 전달하기

웹으로 내보내면 웹 서버로 보낼 여러 파일들을 생성합니다, 표시하기 위한 기본 HTML 페이지도 이에 속합니다. 맞춤 HTML 파일을 사용할 수 있습니다, Custom HTML page for Web export을 보세요.

경고

To ensure low audio latency and the ability to use Thread in web exports, Godot 4 web exports always use SharedArrayBuffer. This requires a secure context, while also requiring the following CORS headers to be set when serving the files:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

If you don't control the web server or are unable to add response headers, use coi-serviceworker as a workaround.

If the client doesn't receive the required response headers, the project will not run.

The generated .html file can be used as DirectoryIndex in Apache servers and can be renamed to e.g. index.html at any time. Its name is never depended on by default.

The HTML page draws the game at maximum size within the browser window. This way, it can be inserted into an <iframe> with the game's size, as is common on most web game hosting sites.

.html 파일 옆의 다른 내보낸 파일은 그대로 전달되지만, 이름은 바뀌지 않습니다. .wasm 파일은 엔진을 구현하는 이진 WebAssembly 모듈입니다. .pck 파일은 Godot 메인 팩으로 게임을 갖고 있습니다. .js 파일은 시작 코드가 있으며 .html 파일이 엔진에 접근하는 데 사용됩니다. .png 파일은 부팅 스플래시 이미지입니다. 기본 HTML 페이지에서는 쓰이지 않지만, 맞춤 HTML 페이지를 위해 포함됩니다.

.pck 파일은 이진 파일로, 보통 MIME 타입 application/octet-stream으로 전달됩니다. .wasm 파일은 application/wasm으로 전달됩니다.

경고

WebAssembly 모듈 (.wasm)을 application/wasm이외의 MIME 타입으로 전달하면 일부 시작 최적화를 방지할 수 있습니다.

Delivering the files with server-side compression is recommended especially for the .pck and .wasm files, which are usually large in size. The WebAssembly module compresses particularly well, down to around a quarter of its original size with gzip compression. Consider using Brotli precompression if supported on your web server for further file size savings.

On-the-fly 압축을 지원하는 호스트: GitHub Pages (gzip)

On-the-fly 압축을 지원하지 않는 호스트: itch.io, GitLab Pages (supports manual gzip precompression)

The Godot repository includes a Python script to host a local web server. This script is intended for testing the web editor, but it can also be used to test exported projects.

Save the linked script to a file called serve.py, move this file to the folder containing the exported project's index.html, then run the following command in a command prompt within the same folder:

# You may need to replace `python` with `python3` on some platforms.
python serve.py --root .

On Windows, you can open a command prompt in the current folder by holding Shift and right-clicking on empty space in Windows Explorer, then choosing Open PowerShell window here.

This will serve the contents of the current folder and open the default web browser automatically.

Note that for production use cases, this Python-based web server should not be used. Instead, you should use an established web server such as Apache or nginx.

스크립트에서 JavaScript 호출하기

In web builds, the JavaScriptBridge singleton is implemented. It offers a single method called eval that works similarly to the JavaScript function of the same name. It takes a string as an argument and executes it as JavaScript code. This allows interacting with the browser in ways not possible with script languages integrated into Godot.

func my_func():
    JavaScriptBridge.eval("alert('Calling JavaScript per GDScript!');")

마지막 JavaScript 명령문의 값은 GDScript 값으로 변환되며 특정 경우에 eval()에 의해 반환됩니다:

  • JavaScript number is returned as float

  • JavaScript boolean is returned as bool

  • JavaScript string is returned as String

  • JavaScript ArrayBuffer, TypedArray and DataView are returned as PackedByteArray

func my_func2():
    var js_return = JavaScriptBridge.eval("var myNumber = 1; myNumber + 2;")
    print(js_return) # prints '3.0'

다른 JavaScript 값은 null로 반환됩니다.

HTML5 export templates may be built without support for the singleton to improve security. With such templates, and on platforms other than HTML5, calling JavaScriptBridge.eval will also return null. The availability of the singleton can be checked with the web feature tag:

func my_func3():
    if OS.has_feature('web'):
        JavaScriptBridge.eval("""
            console.log('The JavaScriptBridge singleton is available')
        """)
    else:
        print("The JavaScriptBridge singleton is NOT available")

my_func3() 처럼 3개의 큰따옴표 """ 로 둘러싸인 GDScript의 멀티라인 문자열은 JavaScript 코드의 가독성을 높이는데 유용합니다.

The eval method also accepts a second, optional Boolean argument, which specifies whether to execute the code in the global execution context, defaulting to false to prevent polluting the global namespace:

func my_func4():
    # execute in global execution context,
    # thus adding a new JavaScript global variable `SomeGlobal`
    JavaScriptBridge.eval("var SomeGlobal = {};", true)

Environment variables

You can use the following environment variables to set export options outside of the editor. During the export process, these override the values that you set in the export menu.

HTML5 export environment variables

Export option

Environment variable

Encryption / Encryption Key

GODOT_SCRIPT_ENCRYPTION_KEY