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 연결을 통해 배포되어야만 사용이 가능합니다(로컬 호스트는 보통 예외입니다).
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!');")
private void MyFunc()
{
JavaScriptBridge.Eval("alert('Calling JavaScript per C#!');")
}
마지막 JavaScript 명령문의 값은 GDScript 값으로 변환되며 특정 경우에 eval()
에 의해 반환됩니다:
JavaScript
number
is returned as floatJavaScript
boolean
is returned as boolJavaScript
string
is returned as StringJavaScript
ArrayBuffer
,TypedArray
andDataView
are returned as PackedByteArray
func my_func2():
var js_return = JavaScriptBridge.eval("var myNumber = 1; myNumber + 2;")
print(js_return) # prints '3.0'
private void MyFunc2()
{
var jsReturn = JavaScriptBridge.Eval("var myNumber = 1; myNumber + 2;");
GD.Print(jsReturn); // 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")
private void MyFunc3()
{
if (OS.HasFeature("web"))
{
JavaScriptBridge.Eval("console.log('The JavaScriptBridge singleton is available')");
}
else
{
GD.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)
private void MyFunc4()
{
// 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.
Export option |
Environment variable |
---|---|
Encryption / Encryption Key |
|