PlayCanvas 引擎

PlayCanvas Engine 是面向 Web 的开源 3D 引擎，可通过 WebGPU 或 WebGL 2 在桌面和移动设备的现代浏览器中渲染，也是 Editor、PlayCanvas React 和 Web Components 的基础。

快速入门 →浏览示例 API 参考

你的第一个应用

下面是一个完整的引擎应用，它就运行在当前页面中，而且可以编辑：输入代码时，预览会重新运行。

实时示例

import * as pc from 'playcanvas';

// create a graphics device, preferring WebGPU over WebGL 2
const canvas = document.getElementById('application');
const device = await pc.createGraphicsDevice(canvas, {
    deviceTypes: [pc.DEVICETYPE_WEBGPU]
});
device.maxPixelRatio = Math.min(window.devicePixelRatio, 2);

// create an application with the component systems it uses
const options = new pc.AppOptions();
options.graphicsDevice = device;
options.componentSystems = [
    pc.RenderComponentSystem,
    pc.CameraComponentSystem,
    pc.LightComponentSystem
];

const app = new pc.AppBase(canvas);
app.init(options);
app.setCanvasFillMode(pc.FILLMODE_FILL_WINDOW);
app.setCanvasResolution(pc.RESOLUTION_AUTO);
window.addEventListener('resize', () => app.resizeCanvas());
app.start();

// light the scene softly from all around
app.scene.ambientLight = new pc.Color(0.3, 0.3, 0.35);

// create a camera looking down at the middle of the grid
const camera = new pc.Entity('camera');
camera.addComponent('camera', {
    clearColor: new pc.Color(0.12, 0.14, 0.17)
});
camera.setPosition(0, 7, 17);
camera.lookAt(0, 0, 0);
app.root.addChild(camera);

// create a sun that casts shadows
const light = new pc.Entity('light');
light.addComponent('light', {
    castShadows: true,
    shadowDistance: 40,
    shadowBias: 0.2,
    normalOffsetBias: 0.05
});
light.setEulerAngles(45, 30, 0);
app.root.addChild(light);

// create a grid of boxes, shading from orange in the middle to purple at the edges
const size = 10;
const orange = new pc.Color(1, 0.4, 0.1);
const purple = new pc.Color(0.4, 0.2, 1);
const boxes = [];
for (let x = -size; x <= size; x++) {
    for (let z = -size; z <= size; z++) {
        const material = new pc.StandardMaterial();
        material.diffuse.lerp(orange, purple, Math.hypot(x, z) / (size * 1.5));
        material.update();

        const box = new pc.Entity();
        box.addComponent('render', { type: 'box', material: material });
        box.setPosition(x, 0, z);
        app.root.addChild(box);
        boxes.push(box);
    }
}

// every frame, ripple the boxes' heights out from the middle
let time = 0;
app.on('update', (dt) => {
    time += dt;
    for (const box of boxes) {
        const { x, z } = box.getPosition();
        const height = 2.2 + 2 * Math.sin(time * 3 - Math.hypot(x, z) * 0.5);
        box.setLocalScale(0.9, height, 0.9);
    }
});

每个引擎应用的开头都类似。createGraphicsDevice 请求 WebGPU，并在浏览器不支持时回退到 WebGL 2。AppBase 代表应用，负责运行逐帧循环，但只运行已注册的组件系统，因此打包工具可以排除其余系统。场景中的一切都是 app.root 层级下的实体，由组件赋予能力：本例包含相机、投射阴影的太阳光，以及 441 个使用独立材质渲染的立方体。每帧，update 事件将距上一帧的时间传给代码，用于生成立方体的波浪运动。可以尝试：

增大 time * 3 中的 3，加快波浪速度；增大 0.5，让波纹更密集。
将 orange 和 purple 替换为任意两种颜色。
将 size 改为 20，把网格扩大到 1,681 个立方体。
使用 type: 'cylinder' 将立方体改为圆柱体。

要在自己的电脑上创建类似应用，运行 npm create playcanvas@latest 并选择 Engine，或按照独立使用引擎手动配置项目。

可以构建什么？

引擎应用运行在浏览器中，无论构建什么，用户都可以在各种设备上通过链接访问。下面是开发者常见的应用场景：

游戏

通过链接即可启动、无需安装的浏览器和移动游戏。这个攻城游戏完全使用引擎构建。

产品配置器

让顾客实时调整产品外观。这只鞋通过在 3D 中渲染的 HTML 面板，切换 glTF 材质变体。

高斯泼溅应用

基于照片级采集场景构建查看器、导览和游戏。这个滑板公园会随视点移动，按细节层级流式加载。

XR 应用

借助 WebXR，在头显和手机上通过链接直接打开 VR 和 AR 体验，支持控制器与手部追踪。

试玩广告

将投石机这样的游戏打包为交互式广告，通过编辑器导出到 Facebook 和 Snapchat。

教育

交互课程与讲解。这个由滚动驱动的太阳系导览，是通过 Web Components 构建的单个 HTML 页面。

示例浏览器包含超过 250 个实时示例，从体积雾、动态天空，到成千上万个动画角色组成的人群，每个示例都附带可编辑的源码。

模型： Tropical Island by Elin (in the demo at the top of the page), Catapult by AlexJJ, Low Poly Lumberjack by Daz and Materials Variants Shoe by Shopify, all CC BY 4.0. Skatepark splat by Christoph Schindelar.

为什么选择 PlayCanvas Engine？

**同一套代码支持 WebGPU 和 WebGL 2。**请求 WebGPU 后，引擎会在尚不支持的浏览器中回退到 WebGL 2，同时保持一致的 API 和视觉效果。各自的适用环境见支持的浏览器。
**功能齐备。**内置刚体物理、基于状态的动画、空间音频、2D 和 3D 用户界面、用于 AR 和 VR 的 WebXR、高斯泼溅，以及鼠标、键盘、触摸和手柄输入。包中还附带相机控制、角色控制器、XR、后期效果等现成脚本。
**精简的设计。**引擎以 ES 模块发布，AppBase 仅运行已注册的组件系统和资源处理器，打包工具可以排除应用未使用的部分。
**资源加载迅速。**模型通过 glTF 2.0 文件加载，支持 Draco 几何压缩和 Basis 纹理压缩；大型高斯泼溅场景则可随相机移动按细节层级流式加载。
**支持 TypeScript。**npm 包提供完整的 TypeScript 声明，无论编写 TypeScript 还是 JavaScript，编辑器都可以对每个类、方法和属性进行补全与检查。
**支持浏览器之外的 JavaScript 环境。**除了浏览器，引擎还可在 Node.js 中以无界面方式运行，用于多人游戏服务器、资源工具和单元测试。
**开源，并经过生产验证。**引擎在 GitHub 上公开开发，采用 MIT 许可证，个人和商业项目均可免费使用。它驱动 PlayCanvas Editor、SuperSplat，以及所有使用 Editor、PlayCanvas React 或 Web Components 构建的应用。

一个引擎，四种使用方式

所有 PlayCanvas 产品都基于同一个引擎，你可以选择适合自己的工作方式。实体、组件、材质和脚本等知识可以在它们之间通用。

通过 JavaScript 或 TypeScript 自行创建应用、实体和组件，完全控制逐帧循环和每个系统。

在浏览器编辑器中与团队搭建场景，并附加调用同一套引擎 API 的脚本。

使用 JSX 组件描述场景，并通过 Hook 处理资源、材质、物理和输入。

在普通网页中通过 <pc-*> 标签构建场景，无需构建步骤。

探索引擎

引擎功能按主题组织文档，无论采用哪种使用方式，各主题都适用。

主题	内容
实体组件系统	实体、组件和场景层级
脚本编程	脚本类、生命周期、属性和事件
资源	在运行时加载和管理模型、纹理及其他文件
图形渲染	相机、网格、光照、材质、着色器、后期效果和粒子
高斯泼溅	3D 高斯泼溅的渲染、流式加载和定制
动画	动画状态图、图层遮罩和动画事件
物理	刚体、碰撞、触发器、射线检测和关节
2D	精灵、九宫格切片、纹理图集和 Spine
用户界面	屏幕或 3D 世界中的屏幕组件、布局、文本、图像与输入
XR	使用 WebXR 构建沉浸式 AR 和 VR，包括输入与手部追踪
优化	加载时间、帧率和内存的性能分析与调优

本节内容

独立使用引擎：使用 npm 与 Vite，或导入映射与 CDN 配置项目。
在 Node.js 中运行引擎：运行用于服务器、工具和测试的无界面应用。
版本编号与发布：版本号、npm 标签，以及如何控制接受哪些更新。
引擎迁移：破坏性变更和代码升级方法。
支持的浏览器：WebGL 2 和 WebGPU 的最低浏览器版本。
借助 AI 开发：在引擎项目中配置编程智能体并验证其修改。
扩展库：与引擎配合使用的 Spine 动画、3D Tiles 流式加载、补间动画和 loaders.gl。
示例：超过 250 个附带可编辑源码的实时示例。
API 参考：所有类、方法和属性。

关注最新动态

在 GitHub 查看源码、问题和拉取请求，通过版本说明了解各版本变更。
通过 PlayCanvas 博客了解引擎新闻。
在 Discord 和论坛中提问、分享作品。
面向编程智能体的引擎 AI 可读文档索引。

PlayCanvas 引擎

你的第一个应用

可以构建什么？