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...

自訂 HTML 頁面用於網頁匯出

雖然 Web 匯出範本已經提供了可直接啟動專案的預設 HTML 頁面，無需額外自訂，但建立自訂 HTML 頁面仍可能帶來益處。即使遊戲本身目前尚無法輕易被外部直接控制，自訂頁面依然可以用來調整引擎的初始化流程。

以下情境適合自訂預設頁面：

  • 從與頁面不同的目錄載入檔案;

  • 載入 .zip 檔案（而非 .pck）作為主資源包;

  • 從與主資源包不同的目錄載入引擎檔案;

  • 加入點擊開始按鈕，讓遊戲能以全螢幕模式啟動;

  • 在引擎啟動前先載入額外檔案，以便讓這些檔案盡快於專案檔案系統中可用;

  • 傳遞自訂命令列參數，例如 -s 來啟動 MainLoop 腳本。

Godot Engine 預設的 HTML 頁面可於 /misc/dist/html/full-size.html 取得，下方範本則為更簡易的用法範例：

<!DOCTYPE html>
<html>
    <head>
        <title>My Template</title>
        <meta charset="UTF-8">
    </head>
    <body>
        <canvas id="canvas"></canvas>
        <script src="$GODOT_URL"></script>
        <script>
            var engine = new Engine($GODOT_CONFIG);
            engine.startGame();
        </script>
    </body>
</html>

設定

如上例所示，這基本上是一個普通的 HTML 文件，包含數個於匯出時會被取代的預留字串、一個 html <canvas> 元素，以及一些呼叫 Engine() 類別的簡易 JavaScript 程式碼。

唯一必要的預留字串如下：

  • $GODOT_URL：主 JavaScript 檔案的名稱，該檔案提供啟動引擎所需的 Engine() 類別，必須以 <script> 標籤納入 HTML。此名稱於匯出過程根據 Export Path 產生。

  • $GODOT_CONFIG：一個 JavaScript 物件，內含匯出選項，日後可被覆寫。完整可覆寫項請參見 EngineConfig。

下列可選預留字串可於自訂 HTML 範本中啟用額外功能。

  • $GODOT_PROJECT_NAME：專案名稱，來自 Name （專案設定 > 應用程式 > 設定）。建議於範本中作為 <title> 使用。

  • $GODOT_HEAD_INCLUDE：匯出選項 Html / Head Include 中設定的自訂字串，將插入 HTML 文件的 <head> 標籤結尾前。雖然你可完全自訂 HTML 頁面內容，此變數仍可協助從 Godot 編輯器動態設定不同 Web 匯出預設值時，調整 HTML head 元素內容。

  • $GODOT_SPLASH：啟動畫面圖片的路徑，來源為 Image （專案設定 > 應用程式 > 啟動畫面）。

  • $GODOT_SPLASH_COLOR：啟動畫面背景顏色，來源為 BG Color （專案設定 > 應用程式 > 啟動畫面），會自動轉換為十六進位色碼。

  • $GODOT_SPLASH_CLASSES：此預留字串會產生一組影響啟動畫面的設定名稱與值，作為 CSS 類名可應用於啟動畫面的樣式，讓你依據專案設定自訂畫面外觀。下列 專案設定 > 應用程式 > 啟動畫面 選項，會對應成 CSS 類名：

    • Show Image：show-image--true、show-image--false

    • Stretch Mode: fullsize--true (if not Disabled), fullsize--false

    • Use Filter：use-filter--true、use-filter--false

自訂頁面準備好後，可於匯出選項 Html / Custom Html Shell 指定使用。

../../../_images/html5_export_options.png

啟動專案

要啟動遊戲，你需撰寫一段初始化引擎的腳本（控制邏輯）。此流程共分三步，實際上視自訂需求大多可略過，採用預設行為即可。

完整方法與選項請參考 HTML5 shell 類別參考文件。

首先需載入引擎，再進行初始化，最後方能啟動專案。你可以完全手動控制每一步。但最簡單的情境下，只需以匯出的設定建立 Engine() 實例，然後呼叫 engine.startGame 方法，有需要時可覆寫任一 EngineConfig 參數。

const engine = new Engine($GODOT_CONFIG);
engine.startGame({
    /* optional override configuration, eg. */
    // unloadAfterInit: false,
    // canvasResizePolicy: 0,
    // ...
});

這段範例程式會在啟動遊戲前自動載入並初始化引擎，並以指定的設定檔載入。engine.startGame 方法為非同步，會回傳一個 Promise，讓你的控制邏輯能追蹤遊戲載入狀況，而不會阻塞執行或需要輪詢。

若你的專案需精確控制啟動參數及相依檔案，可改用 engine.start 方法。注意：此方法不會自動預載入 pck 檔案，你必須自行呼叫 engine.preloadFile 以預載入主資源包和其他檔案。

你也可以選擇在模組初始化後、引擎啟動前，手動呼叫 engine.init 執行特定動作。

這種做法雖較複雜，但會讓你完全掌控引擎啟動流程。

const myWasm = 'mygame.wasm';
const myPck = 'mygame.pck';
const engine = new Engine();
Promise.all([
    // Load and init the engine
    engine.init(myWasm),
    // And the pck concurrently
    engine.preloadFile(myPck),
]).then(() => {
    // Now start the engine.
    return engine.start({ args: ['--main-pack', myPck] });
}).then(() => {
    console.log('Engine has started!');
});

若要手動載入引擎，需呼叫 Engine.load() 靜態方法。此方法為靜態函式，只要共用同一份 wasm，即可建立多個引擎實例。

備註

預設下無法同時建立多個實例，因為引擎初始化完成後會立即卸載。如需避免此行為，請參考 unloadAfterInit 覆寫選項。你仍可隨時手動呼叫 Engine.unload() 靜態方法移除引擎，以釋放初始化後不再需要的檔案與瀏覽器記憶體。

自訂行為

在 Web 環境下，可採用多種方法確保遊戲能如預期運作。

若需指定 WebGL 目標版本，或僅需檢查 WebGL 是否可用，可呼叫 Engine.isWebGLAvailable() 方法。此方法可帶參數測試特定 WebGL 主版本。

由於 Web 環境無法存在實體可執行檔，引擎僅會儲存由載入檔案基底名稱組成的虛擬檔名。這個值會影響 OS.get_executable_path() 方法的回傳結果，同時也決定自動啟動的主資源包名稱。可使用 executable 覆寫選項調整此設定。

自訂呈現方式

可透過多項設定選項進一步自訂遊戲在頁面上的外觀與行為。

預設會使用頁面上的第一個 canvas 元素進行繪製。如需指定其他 canvas，請使用 canvas 覆寫選項，並傳入目標 DOM 元素參照。

const canvasElement = document.querySelector("#my-canvas-element");
engine.startGame({ canvas: canvasElement });

引擎調整畫布（canvas）尺寸的方式可透過 canvasResizePolicy 覆寫選項設定。

若遊戲載入時間較長，建議提供自訂載入 UI 顯示進度。可利用 onProgress 回呼選項，設定一個函式於載入新資料時被定期呼叫，以顯示即時進度。

function printProgress(current, total) {
    console.log("Loaded " + current + " of " + total + " bytes");
}
engine.startGame({ onProgress: printProgress });

請注意，有些情況下 total 可能為 0，代表無法計算總進度。

若遊戲支援多語言，可用 locale 覆寫選項強制指定語系（需提供有效語言代碼字串）。建議於伺服器端判斷用戶偏好語言，如從 HTTP 標頭 Accept-Language 取得，或利用 GeoIP 服務判別。

除錯

若需除錯匯出專案，可讀取引擎產生的標準輸出與錯誤訊息流，這類似於編輯器主控台的訊息。預設分別使用 console.log 與 console.warn 處理輸出與錯誤訊息。你亦可自訂函式來接收處理這些訊息。

使用 onPrint 覆寫選項指定輸出流回呼函式，用 onPrintError 覆寫選項指定錯誤流回呼函式。

function print(text) {
    console.log(text);
}
function printError(text) {
    console.warn(text);
}
engine.startGame({ onPrint: print, onPrintError: printError });

處理引擎輸出時，請注意正式發佈時通常不建議直接顯示這些訊息。