PlayCanvas Web Components

PlayCanvas Web Components 让你仅用 HTML 就能将实时三维内容放到网页。每个 <pc-*> 标签封装引擎的一部分，例如应用、场景、摄像机或灯光，使三维场景也能像普通页面一样通过标记组合。

拖动上方草甸可以环顾四周。摄像机、太阳、薄雾和声音都是 HTML 元素，绘制天空、生成地形、树木与草的脚本也同样通过标签声明。这是附带完整源码的 40 多个实时示例之一。

第一个场景

这是一个完整场景，直接在页面中运行。修改代码时，预览会立即重新运行。

实时示例

<pc-app>
    <pc-scene>
        <pc-entity name="camera" position="0 0 3">
            <pc-camera></pc-camera>
        </pc-entity>
        <pc-entity name="light" rotation="45 45 0">
            <pc-light></pc-light>
        </pc-entity>
        <pc-entity name="ball">
            <pc-render type="sphere"></pc-render>
        </pc-entity>
    </pc-scene>
</pc-app>

<pc-app> 是画布，<pc-scene> 是其中的世界。每个 <pc-entity> 表示有空间位置的对象，其内部标签赋予能力：摄像机、灯光或球体渲染。可以尝试：

将球的 type="sphere" 改为 cone、capsule 或 cylinder。
使用 <pc-light color="orange"> 为灯光染色。
使用 <pc-camera clear-color="midnightblue"> 修改背景。
复制球体实体，通过 position="1.2 0 0" 将副本移到旁边。

要放到自己的页面，只需添加加载库的两个 script 标签，完整文件见入门。

可以构建什么

同一组标签既可描述单个球体，也能构建完整体验。以下作品都是独立 HTML 页面，可在线体验、查看源码，并在 StackBlitz 上修改。

汽车配置器

选择车漆，观察跑车变色。

产品查看器

悬停高亮无人机部件，点击可将其从装配体中拉出。

太阳系

滚动页面，从太阳出发游览八大行星。

高斯泼溅

使用 <pc-gsplat> 标签渲染照片级三维捕获。

第三人称控制器

结合物理和混合动画，在庭院中行走、奔跑和跳跃。

钟楼

显示本地时间的时钟机械，配有尘埃光照和钟声。

示例浏览器还包含摄像头 AR、车辆、布娃娃、粒子、空间声音，以及二维和三维界面。

为什么使用 PlayCanvas Web Components？

通过 HTML 配置完整场景。 无需构建步骤或引擎初始化样板，只有需要自定义行为时才编写 JavaScript。
属性实时生效。 从 JavaScript、框架或开发者工具修改属性，场景立即更新，通用规则见属性。
基于完整引擎。 使用支撑大量 Web 应用的同一 PlayCanvas 引擎，优先 WebGPU，自动回退 WebGL 2。标签能力不足时，可访问底层引擎对象。
遵循 Web 标准。 基于 Custom Elements，支持普通 HTML 和任何输出 DOM 的框架。只需 WebGL 2 或 WebGPU、ES 模块和自定义元素，现代 Chrome、Edge、Firefox、Safari 均支持。
编辑器理解标签。 包内提供 Custom Elements Manifest，支持 VS Code 和 JetBrains IDE 的标签、属性补全及悬停文档。
MIT 开源。 在 GitHub 公开开发，个人和商业项目均可免费使用，欢迎贡献。

从哪里开始？

从 CDN 加载库，或通过 npm create playcanvas, 创建项目，几分钟内渲染第一个页面。

加载 glTF 或 GLB，查看内部结构，并通过标记调整部件。

逐步创建查看器：加载捕获、添加环绕摄像机，并调整渲染设置。

为实体添加运动和玩法脚本，通过标记配置，并复用引擎现成脚本。

使用 React

Web Components 可用于任何支持 HTML 的环境，包括 React。如果更希望通过 hooks 和 JSX 组织场景，请参阅 PlayCanvas React。

本章内容

入门：从 CDN 或 npm 加载并渲染第一个页面。
构建场景：逐步加入摄像机、网格、灯光和材质。
加载模型：加载 glTF／GLB，查看结构并声明式修改。
属性：所有标签共用的值规则。
通过脚本添加行为：为实体添加运动和交互。
代码访问：通过 whenReady 从 JavaScript 驱动应用。
通过模板复用场景：声明一次子树，克隆为多个实例。
XR 支持：将场景带入 VR 和 AR。
标签参考：全部元素及属性。
示例：附带源码的实时演示。

PlayCanvas Web Components

第一个场景