Work in progress
The content of this page was not yet updated for Godot
4.4
and may be outdated. If you know how to improve this page or you can confirm
that it's up to date, feel free to open a pull request.
HTML5 Shell 類別參考
匯出到網頁平台的專案會將 Engine() 類別暴露給 JavaScript 環境，以便細緻地控制引擎的啟動流程。
此 API 採用非同步設計，使用時需要具備 Promises 的基本概念。
Engine
Engine 類別提供在網頁上載入與啟動匯出專案的方法。預設匯出設定下，這些功能已經包含在匯出的 HTML 頁面中。若要了解 Engine 類別的實際應用，請參考 自訂 Web 匯出的 HTML 頁面。
靜態方法
Promise |
|
void |
|
布林值 |
|
實例方法
Promise |
|
Promise |
|
Promise |
|
Promise |
|
void |
|
void |
|
- class Engine(initConfig)
以指定的組態建立新的 Engine 實例。
- 引數:
initConfig (
EngineConfig()) -- 此實例的初始組態。
靜態方法
- Engine.load(basePath)
從指定的基礎路徑載入引擎。
- 引數:
basePath (
string()) -- 要載入引擎的基礎路徑。
- 回傳:
引擎載入完成時會解決的 Promise。
- 回傳型別:
Promise
- Engine.unload()
解除載入引擎以釋放記憶體。
根據組態，此方法可能會自動呼叫。詳見
unloadAfterInit。
- Engine.isWebGLAvailable([majorVersion=1])
檢查 WebGL 是否可用。你也可以選擇檢查特定的 WebGL 主要版本。
- 引數:
majorVersion (
number()) -- 要檢查的 WebGL 主要版本。
- 回傳:
如果指定的 WebGL 主要版本可用則為 true。
- 回傳型別:
布林值
實例方法
- Engine.prototype.init([basePath])
初始化引擎實例。如尚未載入引擎，可選擇傳入基礎路徑以進行載入。詳見
Engine.load()。- 引數:
basePath (
string()) -- 要載入引擎的基礎路徑。
- 回傳:
引擎載入並初始化完成時會解決的
Promise。- 回傳型別:
Promise
- Engine.prototype.preloadFile(file[, path])
載入檔案，讓其在實例執行時於檔案系統中可用。必須在啟動實例 之前 呼叫。
若未提供
path，則會從檔案的 URL 取得其路徑。- 引數:
file (
string|ArrayBuffer()) -- 要預先載入的檔案。若為string，則會從該路徑載入檔案。若為ArrayBuffer或其視圖，該緩衝區內容即為檔案內容。path (
string()) -- 檔案可被存取時所使用的路徑。若file不是字串，則此項必須指定。
- 回傳:
檔案載入完成時會解決的 Promise。
- 回傳型別:
Promise
- Engine.prototype.start(override)
以給定的覆寫組態（如有）啟動引擎實例。一般情況下可直接使用
startGame。若實例尚未初始化，此步驟會自動初始化。若需手動初始化，請參考
init。引擎必須事先載入。若頁面上找不到 Canvas，或組態未指定 Canvas，則會啟動失敗。
- 引數:
override (
EngineConfig()) -- （可選）組態覆寫參數。
- 回傳:
引擎啟動完成時會解決的 Promise。
- 回傳型別:
Promise
- Engine.prototype.startGame(override)
以給定的組態覆寫（如有）啟動遊戲實例。
若實例尚未初始化，此步驟會自動初始化。若需手動初始化，請參考
init。若尚未載入引擎，則會自動載入，並預先載入主 pck。
此方法要求初始組態（或覆寫參數）必須同時設置
executable與mainPack屬性（通常由編輯器在匯出時自動設定）。- 引數:
override (
EngineConfig()) -- （可選）組態覆寫參數。
- 回傳:
遊戲啟動完成時會解決的 Promise。
- 回傳型別:
Promise
- Engine.prototype.copyToFS(path, buffer)
於實例的檔案系統中，在指定
path建立檔案，內容為傳入的buffer。- 引數:
path (
string()) -- 要建立檔案的位置。buffer (
ArrayBuffer()) -- 檔案內容。
- Engine.prototype.requestQuit()
請求目前的實例結束執行。
這就像使用者在視窗管理員中按下關閉按鈕一樣。若引擎已當機或陷入無窮迴圈，將不會有任何效果。
Engine 組態
一個物件，用於根據 Godot 匯出選項設定 Engine 實例，也可在自訂 HTML 模板中覆寫。
屬性
型別 |
名稱 |
布林值 |
|
HTMLCanvasElement |
|
字串 |
|
字串 |
|
字串 |
|
數值 |
|
字串陣列 |
|
函式 |
|
函式 |
|
函式 |
|
函式 |
|
函式 |
- EngineConfig
Engine 組態物件。這僅為型別定義，可像一般物件建立，例如：
const MyConfig = { executable: 'godot', unloadAfterInit: false }屬性說明
- unloadAfterInit
實例初始化後是否自動解除載入引擎。
- 型別:
布林值
- 值:
true
- canvas
要使用的 HTML DOM Canvas 物件。
預設會使用文件中的第一個 canvas 元素，除非明確指定。
- 型別:
HTMLCanvasElement
- 值:
null
- executable
WASM 檔案（不含副檔名）的名稱。（由 Godot 編輯器匯出時設定）。
- 型別:
字串
- 值:
""
- mainPack
要載入的遊戲 pck 檔案別名。若未指定則使用可執行檔名。
- 型別:
字串
- 值:
null
- canvasResizePolicy
Canvas 調整大小策略，決定 Godot 如何調整畫布尺寸。
0表示 Godot 不會自動調整畫布大小。若你要在模板中以 JavaScript 控制畫布尺寸，這很有用。1表示 Godot 在啟動及以引擎功能改變視窗大小時，會自動調整畫布尺寸。2表示 Godot 會自動將畫布尺寸調整為與整個瀏覽器視窗一致。- 型別:
數值
- 值:
2
- onExecute(path, args)
處理 Godot
OS.execute呼叫的回呼函式。例如在 Web 編輯器模板中，可利用此函式於專案管理員與編輯器間切換，或用於執行遊戲。
- 引數:
path (
string()) -- Godot 要執行的路徑。args (
Array.) -- 要執行之「命令」的參數。
- onExit(status_code)
當 Godot 實例結束時會被呼叫的回呼函式。
注意：若引擎當機或無回應，此函式不會被呼叫。
- 引數:
status_code (
number()) -- Godot 結束時回傳的狀態碼。
- onProgress(current, total)
顯示下載進度的回呼函式。
下載檔案時每幀都會呼叫此函式，因此不需要自行使用
requestAnimationFrame()。若回呼函式收到的總位元組數為 0，代表無法計算總量，可能原因包括：
伺服器端以分段壓縮傳送檔案
在 Chromium 上，伺服器端進行壓縮傳送
部分檔案尚未開始下載（通常發生於不支援多執行緒的伺服器）
- 引數:
current (
number()) -- 目前已下載的位元組數。total (
number()) -- 需下載的位元組總數。
- onPrint([...var_args])
處理標準輸出流的回呼函式。通常僅於除錯頁面上使用。
預設使用
console.log()。- 引數:
var_args (
*()) -- 欲輸出的多個參數。
- onPrintError([...var_args])
處理標準錯誤流的回呼函式。通常僅於除錯頁面上使用。
預設使用
console.error()。- 引數:
var_args (
*()) -- 欲作為錯誤輸出的多個參數。