為 Web 匯出

匯出 HTML5 可以將 Godot Engine 做的遊戲發佈在瀏覽器上。該功能需要使用者瀏覽器有支援 WebAssemblyWebGL

重要

使用整合在瀏覽器內的開發者主控台 (通常可以按 F12 打開),即可檢視如 JavaScript、引擎與 WebGL 錯誤之類的 除錯資訊

注意

There are significant bugs when running HTML5 projects on iOS (regardless of the browser). We recommend using iOS' native export functionality instead, as it will also result in better performance.

WebGL 2

直到 Godot 將 OpenGL ES 3 算繪引擎刪除並改用 Vulkan 之前,HTML5 匯出都在選擇 GLES3 時使用 WebGL 2

警告

由於未來 Godot 會將 WebGL 2 移除,且不會有替換方案,所以不建議使用。

並非所有瀏覽器都支援 WebGL 2。 FirefoxChromium (Chrome, Opera) 為支援的瀏覽器中最受歡迎的,而 SafariEdge 則不支援。 iOS 上所有的瀏覽器都是基於 WebKit 的 (即 Safari),所以全部都不支援。

Godot 的 WebGL 2 算繪引擎有一些 3D 問題,而且已停止維護。

匯出選項

若有可執行的網頁匯出樣板,則在編輯器上 [停止場景][執行編輯的場景] 按鈕中間會多一個按鈕,可以用來在預設瀏覽器中快速開啟遊戲來測試。

You can choose the Export Type to select which features will be available:

  • Regular: is the most compatible across browsers, will not support threads, nor GDNative.

  • Threads: will require the browser to support SharedArrayBuffer

  • GDNative: enables GDNative support but makes the binary bigger and slower to load.

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 Shell 檔案,則會用這個檔案而非預設 HTML 頁面。請參考 :ref:doc_customizing_html5_shell` 。

Head Include 會被加到產生的 HTML 頁面中 <head> 元素的尾端。這樣便可以達成如載入 Webfont 或第三方 JavaScript API、加上 CSS 或執行 JavaScript 等功能。

重要

Each project must generate their own HTML file. On export, several text placeholders are replaced in the generated HTML file specifically for the given export options. Any direct modifications to that HTML file will be lost in future exports. To customize the generated file, use the Custom HTML shell option.

警告

Export types other then Regular are not yet supported by the C# version.

限制

由於安全性與隱私權問題,要將許多在原生平台上能輕鬆運作的功能放到 Web 平台上會很複雜。以下列出了一些在將 Godot 遊戲移植到網頁時應注意的限制。

重要

Browser vendors are making more and more functionalities only available in secure contexts, this means that such features are only be available if the web page is served via a secure HTTPS connection (localhost is usually exempt from such requirement).

小訣竅

請瀏覽 GitHub 上的 HTML5 問題列表 以瞭解您有興趣的功能目前是否有問題。若列表上沒有,可以開啟 Issue 來與大家交流。

使用 Cookie 來保留資料

若要保留 user:// 檔案系統中的資料,則使用者必須要 允許 Cookie (尤其是 IndexedDB)。若在 iframe 內玩遊戲的話,則必須同時啟用 第三方 Cookie。隱私模式也會防止保留資料。

OS.is_userfs_persistent() 方法可以用來檢查 user:// 檔案系統是否會被保留,但有時候檢查結果不會是正確的。

執行緒

As mentioned above multi-threading is only available if the appropriate Export Type is set and support for it across browsers is still limited.

警告

Requires a secure context. Browsers are also starting to require that the web page is served with specific cross-origin isolation headers.

GDNative

As mentioned above GDNative is only available if the appropriate Export Type is set.

The export will also copy the required GDNative .wasm files to the output folder (and must be uploaded to your server along with your game).

全螢幕與滑鼠截取

瀏覽器不允許任意 進入全螢幕 模式。同樣地,也不允許隨時 截取滑鼠遊標 。這些操作必須要改為用 JavaScript 輸入事件來處理。這代表,在 Godot 中必須要在按鍵輸入事件回呼 (如 _input_unhandled_input) 中才能進入全螢幕。用 :ref:``class_Input``單例來查詢還不夠,必須要啟用相關的輸入事件。

出於相同原因,除非引擎是從有效的輸入事件處理常式中開始的,否則無法使用全螢幕專案設定。要設定則需要 自定 HTML 頁面

音訊

Chrome 會顯示網站能否播放音訊。可能有需要玩家點擊、輕觸或按按鍵來啟用音訊。

也參考

Google 有提供關於 網頁音訊自動播放政策 (英文) 的額外資訊。

警告

Access to microphone requires a secure context.

網路

Low level networking is not implemented due to lacking support in browsers.

Currently, only HTTP client, HTTP requests, WebSocket (client) and WebRTC are supported.

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

  • 無法存取或更改 StreamPeer

  • 無法使用 Threaded/Blocking 模式

  • 每幀無法處理多次,因此在迴圈內輪詢會導致程式凍結

  • 無法區塊回覆

  • 無法禁用主機驗證

  • 必須遵守 同源政策 (Same-origin policy)

Clipboard

Clipboard synchronization between engine and the operating system requires a browser supporting the Clipboard API, additionally, due to the API asynchronous nature might not be reliable when accessed from GDScript.

警告

Requires a secure context.

Gamepads

Gamepads will not be detected until one of their button is pressed. Gamepads might have the wrong mapping depending on the browser/OS/gamepad combination, sadly the Gamepad API does not provide a reliable way to detect the gamepad information necessary to remap them based on model/vendor/OS due to privacy considerations.

警告

Requires a secure context.

不會顯示啟動畫面

預設 HTML 頁面不會在載入時顯示啟動畫面。但,圖片是匯出為 PNG 檔案,所以 自定 HTML 頁面 可以顯示圖片。

著色器語言限制

當匯出 GLES2 專案為 HTML5 時會使用 WebGL 1.0。WebGL 1.0 不支援動態循環,因此使用動態循環的著色器將不會運作。

提供檔案

匯出網頁會產生多個用來在網頁伺服器上提供的檔案,其中包含一個用來顯示的預設 HTML 頁面。可以使用自定 HTML 檔案,請參考 Custom HTML page for Web export

產生的 .html 可以用來在 Apache 伺服器中的 DirectoryIndex 功能中使用,並且可以隨時重命名為如 index.html 之類的名稱。預設情況下不會依賴其檔名。

HTML 頁面會以瀏覽器視窗的最大尺寸來繪製遊戲。這樣便可將其插入在遊戲大小的 <iframe> 中,大多數遊戲在託管網頁中都是這麼做。

除了 .html 外其他的檔案都是以原本的樣子來提供,名稱不變。 .wasm 檔案為實作引擎的二進位 WebAssembly 模組。 .pck 檔案則是包含遊戲的 Godot 主要套件。 .js 檔案包含了由 .html 檔案用來存取引擎的啟動程式碼。 .png 檔案包含了啟動畫面,預設的 HTML 頁面不會使用到,但可以用 自定 HTML 頁面 來顯示。

.pck 檔案為二進位形式,通常會以 MIME 類型 application/octet-strem 來傳送。 .wasm 則是 application/wasm

警示

使用 application/wasm 之外的 MIME 類型來傳遞 WebAssembly 模組 (``.wasm`) 可以防止一些啟動最佳化。

建議以伺服器端壓縮來傳送這些檔案,特別是 .pck.wasm ,這兩種檔案大小通常很大。WebAssembly 模組特別適合壓縮,使用 gzip 通常能壓縮到小於原本的四分之一。

Hosts that provide on-the-fly compression: GitHub Pages (gzip)

Hosts that don't provide on-the-fly compression: itch.io, GitLab Pages (supports manual gzip precompression)

從腳本中呼叫 JavaScript

在網頁建置中有實作 JavaScript 單例。該單例只提供了一個名為 eval 的方法,類似 JavaScript 中相同名稱的函式。該方法接受單一字串引數,會將該字串作為 JavaScript 程式碼來執行。這樣便可用 Godot 整合腳本中無法實現的方法來與瀏覽器互動。

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

特定情況下,最後一個 JavaScript 陳述式的回傳值會轉換為 GDScript 值,並由 eval() 回傳:

  • JavaScript number 型會以 GDScript float 回傳

  • JavaScript bool 型會以 GDScript bool 回傳

  • JavaScript string 型會以 GDScript String 回傳

  • JavaScript ArrayBuffer, TypedArrayDataView 型會以 GDScript PoolByteArray 回傳

func my_func2():
    var js_return = JavaScript.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 JavaScript.eval will also return null. The availability of the singleton can be checked with the JavaScript feature tag:

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")

小訣竅

GDScript 的多行字串是由三個引號 """ 來包圍,如同上方 my_func3() 中的範例,適用於讓 JavaScript 更容易閱讀。

eval 方法也接受第二個可選的布林引數,可以用來指定是否要在全域執行上下文中執行程式碼。預設值為 false ,以防止汙染全域命名空間:

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