game/godot

Godot3 API - Exporting for the Web

C/H 2018. 11. 13. 08:30

Exporting for the Web

HTML5 export allows publishing games made in Godot Engine to the browser. This requires support for the recent technologies WebAssembly and WebGL 2.0 in the user’s browser. Firefox and Chromium (Chrome, Opera) are the most popular supported browsers, Safari and Edge do not work yet. On iOS, all browsers must be based on WebKit (i.e. Safari), so they will also not work.
HTML5 내보내기는 Godot Engine에서 만든 게임을 브라우저에 게시 할 수있게합니다. 이를 위해서는 사용자의 브라우저에 최신 기술인 WebAssembly 및 WebGL 2.0에 대한 지원이 필요합니다. Firefox 및 Chromium (Chrome, Opera)은 가장 인기있는 지원되는 브라우저이며 Safari 및 Edge는 아직 작동하지 않습니다. iOS에서는 모든 브라우저가 WebKit (예 : Safari)을 기반으로해야하므로 작동하지 않습니다.

Limitations

For security and privacy reasons, many features that work effortlessly on native platforms are more complicated on the web platform. Following is a list of limitations you should be aware of when porting a Godot game to the web.
보안 및 개인 정보 보호 측면에서 네이티브 플랫폼에서 쉽게 작동하는 많은 기능은 웹 플랫폼에서 더 복잡합니다. 다음은 Godot 게임을 웹으로 이식 할 때 알아야 할 제한 사항 목록입니다.

Exported .html file must not be reused

On export, several text placeholders are replaced in the generated HTML file specifically for the given export options. It must not be reused in further exports.
내보내기시 생성 된 HTML 파일에서 지정된 내보내기 옵션에 맞게 여러 텍스트 자리 표시자가 대체됩니다. 더 이상의 내보내기에 재사용해서는 안됩니다.

Using cookies for data persistence

Users must allow cookies (specifically IndexedDB) if persistence of the user:// file system is desired. When playing a game presented in an iframe, third-party cookies must also be enabled. Incognito/private browsing mode also prevents persistence.
user:// 파일 시스템의 지속성이 필요한 경우 사용자는 쿠키 (특히 IndexedDB)를 허용해야합니다. iframe에 표시된 게임을 할 때 제3자 쿠키도 활성화해야합니다. 또한 보안/개인 정보 보호 브라우징 모드는 지속성을 방해합니다.

The method OS.is_userfs_persistent() can be used to check if the user:// file system is persistent, but can give false positives in some cases.
OS.is_userfs persistent()메서드는 user:// 파일 시스템이 영구적인지 여부를 확인하는 데 사용할 수 있지만 경우에 따라 오 탐지 될 수 있습니다.

Full screen and mouse capture

Browsers do not allow arbitrarily entering full screen at any time. The same goes for capturing the cursor. Instead, these actions have to occur as a response to a JavaScript input event. In Godot, this is most easily done by entering full screen from within an input callback such as _input or _unhandled_input.
브라우저는 언제든지 전 화면을 임의로 입력 할 수 없습니다. 커서 캡처에 대해서도 마찬가지입니다. 대신 이러한 작업은 JavaScript 입력 이벤트에 대한 응답으로 발생해야합니다. Godot에서는 _input 또는 _unhandled_input과 같은 입력 콜백에서 전체 화면으로 들어가서 가장 쉽게 수행 할 수 있습니다.

For the same reason, the full screen project setting is ignored.
동일한 이유로 전체 화면 프로젝트 설정이 무시됩니다.

HTTPClient

The HTTPClient implementation for the HTML5 platform has several restrictions:
HTML5 플랫폼 용 HTTPClient 구현에는 몇 가지 제한 사항이 있습니다.

  • Accessing or changing the StreamPeer is not possible
    StreamPeer에 액세스하거나 변경할 수 없습니다.
  • Blocking mode is not available
    차단 모드를 사용할 수 없습니다.
  • Cannot progress more than once per frame, so polling in a loop will freeze
    프레임 당 한 번 이상 진행할 수 없으므로 루프에서 폴링이 멈 춥니 다.
  • No chunked responses
    청크 응답 없음
  • Host verification cannot be disabled
    호스트 확인을 비활성화 할 수 없습니다.
  • Subject to same-origin policy
    동일출처 정책 적용을 받음

Unimplemented functionality

The following functionality is currently unavailable on the HTML5 platform:
다음 기능은 현재 HTML5 플랫폼에서 사용할 수 없습니다.

  • Threads
  • GDNative
  • Clipboard synchronisation between engine and operating system
    엔진과 운영 체제 간의 클립 보드 동기화
  • Networking other than HTTPClient
    HTTPClient 이외의 네트워킹

Check the list of open HTML5 issues on Github to see if functionality you’re interested in has an issue yet. If not, open one to communicate your interest.
관심있는 기능에 아직 문제가 있는지 확인하려면 Github에서 열린 HTML5 문제 목록을 확인하세요. 그렇지 않다면 관심있는 내용을 전달하십시오.

Starting exported games from the local file system

Many browsers, Chromium-based browsers specifically, will not load exported projects when opened locally per file:// protocol. To get around this, use a local server.
많은 브라우저, Chromium 기반 브라우저는 특별히 로컬로 "file://" 프로토콜을 열 때 내보낸(Export) 프로젝트를 로드하지 않습니다.

Python offers an easy method for this, using python -m SimpleHTTPServer with Python 2 or python -m http.server with Python 3 will serve the current working directory on http://localhost:8000.
파이썬은 파이썬2에서 python -m SimpleHTTPServer를 사용하거나 파이썬3에서 python -m http.server를 사용하여 http:// localhost:8000의 현재 작업 디렉토리를 제공한다.

Serving the files

Exporting for the web generates several files to be served from a web server, including a default HTML page for presentation. A custom HTML file can be used, see Customizing the Web export HTML page.
웹용으로 내보내는 것은 프레젠테이션을위한 기본 HTML 페이지를 포함하여 웹 서버에서 제공 할 여러 파일을 생성합니다. 사용자 정의 HTML 파일을 사용할 수 있습니다. 웹 내보내기 HTML 페이지 사용자 정의를 참조하십시오.

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.
생성된 .html 파일은 Apache 서버에서 DirectoryIndex로 사용될 수 있으며 예를 들어 이름을 변경할 수 있습니다. index.html은 언제든지 이 이름을 기본으로 사용하지 않을 수 있습니다.

The HTML page is designed to fit the game perfectly without cutting off parts of the canvas when the browser window is scaled to the game’s dimensions. This way it can be inserted into an <iframe> with the game’s size, as is common on most web game hosting sites.
HTML 페이지는 브라우저 창의 크기가 게임의 크기에 맞게 조정될 때 캔버스의 일부를 잘라 내지 않고 게임에 완벽하게 맞도록 설계되었습니다. 이렇게하면 대부분의 웹 게임 호스팅 사이트에서 일반적인 것처럼 게임의 크기와 함께 <iframe>에 삽입 할 수 있습니다.

The other exported files are served as they are, next to the .html file, names unchanged. The .wasm file is a binary WebAssembly module implementing the engine. The .pck file is the Godot main pack containing your game. The .js file contains start-up code and is used by the .html file to access the engine. The .png file contains the boot splash image. It is not used in the default HTML page, but is included for custom HTML pages.
다른 내보낸 파일은 .html 파일 옆에 이름이 변경되지 않은 상태로 제공됩니다. .wasm 파일은 엔진을 구현하는 바이너리 WebAssembly 모듈입니다. .pck 파일은 게임이 포함 된 Godot 기본 팩입니다. .js 파일에는 시작 코드가 들어 있으며 .html 파일에서 엔진에 액세스하는데 사용됩니다. .png 파일에는 부팅 스플래시 이미지가 들어 있습니다. 기본 HTML 페이지에서는 사용되지 않지만 사용자 정의 HTML 페이지에는 포함됩니다.

The .pck file is binary, usually delivered with the MIME-type application/octet-stream. The .wasm file is delivered as application/wasm.
.pck 파일은 바이너리이며, 일반적으로 MIME 유형 application/octet-stream과 함께 제공됩니다. .wasm 파일은 application/wasm으로 제공됩니다.

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.
특히 크기가 큰 .pck 및 .wasm 파일의 경우 서버측 압축을 사용하여 파일을 제공하는 것이 좋습니다. WebAssembly 모듈은 gzip 압축을 사용하여 원래 크기의 약 4 분의 1로 특히 잘 압축됩니다.

Export options

If a runnable web export template is available, a button appears between the Stop scene and Play edited Scene buttons in the editor to quickly open the game in the default browser for testing.
실행 가능한 웹 내보내기 템플릿을 사용할 수있는 경우 편집기의 장면 중지 및 재생 된 장면 단추 사이에 단추가 나타나 테스팅을 위해 기본 브라우저에서 게임을 빠르게 엽니 다.

If a path to a Custom HTML shell file is given, it will be used instead of the default HTML page. See Customizing the Web export HTML page.
사용자 정의 HTML 셸파일의 경로가 지정되면 기본 HTML 페이지 대신 사용됩니다. 웹 내보내기 HTML 페이지 사용자 정의를 참조하십시오.

Head Include is appended into the <head> element of the generated HTML page. This allows to, for example, load webfonts and third-party JavaScript APIs, include CSS, or run JavaScript code.
생성 된 HTML 페이지의 <head> 요소에 head가 추가됩니다. 예를 들어, 웹 폰트 및 제3자 JavaScript API를로드하고 CSS를 포함 시키거나 JavaScript 코드를 실행할 수 있습니다.

Turning on Export with Debug when exporting will, in addition to enabling various debug features of the engine, display a debug output below the canvas when using the default HTML page, displaying JavaScript and engine errors. You can also use the browser-integrated developer console, usually opened with the F12 key, which often shows more information, including WebGL errors.
내보내기 할 때 디버그로 내보내기를 켜면 엔진의 다양한 디버그 기능을 사용할 수있을뿐만 아니라 기본 HTML 페이지를 사용할 때 JavaScript 및 엔진 오류를 표시 할 때 캔버스 아래에 디버그 출력을 표시합니다. 일반적으로 F12키로 열리는 브라우저 통합 개발자 콘솔을 사용할 수도 있습니다. 이 콘솔은 WebGL 오류를 포함하여 더 많은 정보를 자주 표시합니다.

Calling JavaScript from script

In web builds, the JavaScript singleton is implemented. If 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.
웹 빌드에서는 JavaScript 싱글톤이 구현됩니다. 동일한 이름의 JavaScript 함수와 유사하게 작동하는 eval이라는 단일 메서드를 제공합니다. 문자열을 인수로 취하여 JavaScript 코드로 실행합니다. 이것은 Godot에 통합된 스크립트 언어로는 불가능한 방식으로 브라우저와 상호 작용할 수있게합니다.

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

The value of the last JavaScript statement is converted to a GDScript value and returned by eval() under certain circumstances:
마지막 JavaScript 문은 GDScript 값으로 변환되어 특정 상황에서 eval()에 의해 반환됩니다.

  • JavaScript number is returned as GDScript float
  • JavaScript boolean is returned as GDScript bool
  • JavaScript string is returned as GDScript String
  • JavaScript ArrayBuffer, TypedArray and DataView are returned as GDScript PoolByteArray
func my_func2():
    var js_return = JavaScript.eval("var myNumber = 1; myNumber + 2;")
    print(js_return) # prints '3.0'

Any other JavaScript value is returned as null.
다른 JavaScript 값은 null로 반환됩니다.

HTML5 export templates may be built without support for the singleton. With such templates, and on platforms other than HTML5, calling JavaScript.eval will also return null. The availability of the singleton can be checked with the JavaScript feature tag
HTML5 내보내기 템플릿은 싱글 톤에 대한 지원없이 빌드 될 수 있습니다. 이러한 템플릿 및 HTML5 이외의 플랫폼에서 JavaScript.eval을 호출하면 null이 반환됩니다. 싱글 톤의 가용성은 JavaScript 기능 태그를 사용하여 확인할 수 있습니다.

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

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:
eval 메서드는 전역 실행 컨텍스트에서 코드를 실행할 것인지 여부를 지정하는 두 번째 선택적 Boolean 인수도 허용하며 기본값은 전역 네임 스페이스 오염을 방지하기 위해 false로 설정됩니다.

func my_func4():
    # execute in global execution context,
    # 전역 실행 컨텍스트에서 실행,
    # thus adding a new JavaScript global variable `MyGlobal`
    # 따라서 새 JavaScript 전역 변수 인 MyGlobal을 추가합니다.
    JavaScript.eval("var SomeGlobal = {};", true)


반응형