入门

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 版本中减小播放器的大小。