入門

Cavalry Web Player 和 API 目前處於 beta 階段，可能會有所變更。

簡介

Cavalry Web Player 是一個基於 WebAssembly 的執行時期，用於在網頁瀏覽器中渲染和播放 Cavalry 動畫（.cv 檔案）。

建立在現代瀏覽器中可檢視和匯出的自訂、完全可自訂的動畫。憑藉對 Cavalry 豐富功能的原生支援，設計師和動畫師現在可以擺脫 Lottie 等格式的限制，這意味著非技術團隊也可以以輕量、易用的格式向客戶建立和交付設計系統。

Web Player API 可用於從嵌入 Web Player 的場景中更新圖層屬性。

來看看 Algo 的優秀團隊與 scenery.io 上的多位藝術家合作完成的精彩專案，該專案使用了 Web Player，讓您一窺其無限可能。

以下範例是一個自訂整合，它使用 Web Player 和 API 載入 .cv 檔案，並提供一個自訂 UI，該 UI 可用於根據新增到控制中心的屬性來更新場景。

正在載入 Cavalry Player…

使用控制項來更新動畫。

快速開始

下載 Cavalry Web Player↓ Download

1. 下載 Cavalry Web Player 套件。

2. 解壓縮。

3. 啟動內建伺服器：

   # macOScd /path/to/cavalry-web-player# Windowscd \path\to\cavalry-web-playerpython3 serve.py

這將開啟瀏覽器視窗並載入 localhost:8000。嘗試 ‘Minimal Player’ 範例，載入 .cv 場景檔案並使用播放控制項。

整合

整合範例

// Import the Cavalry moduleconst wasm = await import("/CavalryWasm.js");// Initialise the moduleconst Module = await wasm.default({    locateFile: (path) => `/wasm-lib/${path}`});// Load a scene fileModule.FS.writeFile("scene.cv", sceneData);const player = Module.Cavalry.MakeWithPath("scene.cv");// Set up rendering surfaceconst canvas = document.getElementById("canvas");const surface = Module.makeWebGLSurfaceFromElement(canvas, 800, 600);// Render current frameplayer.render(surface);// Start playbackplayer.play();// Animation loop using requestAnimationFrame (for display sync and power efficient playback)let animationFrameId = null;function runPlaybackLoop() {    const tick = (timestamp) => {        if (!player.isPlaying()) {          return;        }        // tick() advances the frame based on elapsed time and renders        const status = player.tick(surface, timestamp);        // Optionally update UI when a frame changes        if (status.frameChanged) {            console.log(`Frame: ${status.currentFrame}`);        }        animationFrameId = requestAnimationFrame(tick);    };    animationFrameId = requestAnimationFrame(tick);}runPlaybackLoop();// To stop playback:// player.stop();// cancelAnimationFrame(animationFrameId);

伺服器要求

對於生產部署，請確保伺服器：

1. 設定正確的 MIME 類型：
   • .wasm 檔案使用 Content-Type: application/wasm
   • .js 檔案使用 Content-Type: application/javascript
2. 透過 HTTPS 提供服務。

檔案大小最佳化

由於全面的功能集，Cavalry Web Player 檔案相對較大。我們計劃在未來減小檔案大小，但目前如果檔案大小是個問題，請嘗試：

• 預先壓縮 .wasm 檔案為 gzip。
• 設定 Content-Encoding: gzip 標頭。
• 使用 CDN 以獲得更好的分發效果。
• 大多數伺服器會自動壓縮這些檔案。

瀏覽器相容性

要求：

• WebAssembly 支援
• WebGL 2.0
• 現代 JavaScript（ES6 modules）

---

多個播放器

同一頁面上可以使用多個 Cavalry Web Player，只需向頁面新增多個播放器執行個體即可。示範中包含大量建立播放器模組的範例。

Shadow Dom

Web Player 支援在 Shadow DOM 內使用，其中 canvas 元素隱藏於公共 DOM 之外。可以透過 HTML 中的 shadowHost 和 Shadow DOM 設定進行設定。請參見示範。

影片素材

Web Player 支援影片素材，但它並不被視為影片播放器。建議使用 video 元素來進行純粹的影片播放。

包含一個影片範例，示範了如何使用 Web Player 播放影片。如果需要更多功能，請檢視 webcodec-helper.js 檔案作為起點。請參見示範。

注意事項

場景檔案（.cv）應儲存為至少檔案版本 1.0.55，Cavalry 2.5.0 起支援該版本。

不支援的功能：

• 音訊（音訊支援正在開發中）

不支援的圖層：

• Image Smart Folder
• Audio Smart Folder
• JavaScript Layers
• Jsmath

常見問題

Cavalry 的所有功能都支援嗎？

99% 的功能已支援。仍在開發中的功能可在注意事項部分檢視。

動畫可以實現互動嗎？

可以部分實現。屬性可以透過 UI 或游標位置即時調整。請檢視示範頁面中的範例。請注意，Web Player 不包含任何狀態機。

Web Player 執行時期的檔案大小是多少？

目前有效承載壓縮後約為 3MB（參見檔案大小最佳化）。這個大檔案是由於對全面功能支援的關注所致，但請記住，該檔案會被瀏覽器快取，因此在後續訪問網頁時會預先載入。我們計劃在未來 beta 版本中減小播放器的大小。