跳到主要内容

独立使用引擎

不使用编辑器，也可以基于 PlayCanvas Engine 构建应用。以下应用直接使用引擎开发：

本页将介绍如何开始。

备注

开始之前，请确保已经安装 Node.js。

快速入门

要创建 Vite 和 TypeScript 项目，可以使用官方 create-playcanvas 工具，并选择 Engine 开发方式：

npm create playcanvas@latest my-app -- -f engine

生成的项目包含可运行的初始模板，以及供兼容 AI 编程智能体使用的 PlayCanvas Skills。

手动配置项目时，主要有以下两种方式。

方式一：构建工具与 npm​

这是推荐的配置方式，适合大多数开发者。

构建工具可以将应用打包为经过优化的代码，使其在多种浏览器中运行。webpack、Rollup 和 esbuild 等构建工具都支持 PlayCanvas。这里使用流行的 Vite，它致力于为现代 Web 项目提供更快、更精简的开发体验。

首先选择使用 JavaScript 还是 TypeScript 开发：

  1. 打开终端或命令提示符，为应用创建目录，并通过 cd 进入该目录。

  2. 安装 playcanvas 和 vite：

    npm install playcanvas
    npm install vite --save-dev

    要控制 npm 将来可以更新到哪些引擎版本，请参阅版本编号与发布。

  3. 创建 index.html，粘贴以下内容：

    index.html
    <!DOCTYPE html>
    <html lang="en">
        <head>
            <meta charset="utf-8">
            <style>
                body { margin: 0; overflow: hidden; }
            </style>
        </head>
        <body>
            <script type="module" src="main.js"></script>
            <canvas id='application'></canvas>
        </body>
    </html>

  4. 创建 main.js，粘贴以下内容：

    main.js
    import * as pc from 'playcanvas';

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

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

    const app = new pc.AppBase(canvas);
    app.init(options);
    app.setCanvasResolution(pc.RESOLUTION_AUTO);
    app.setCanvasFillMode(pc.FILLMODE_FILL_WINDOW);
    app.start();

    // resize the canvas when the window is resized
    window.addEventListener('resize', () => app.resizeCanvas());

    // create a camera
    const camera = new pc.Entity();
    camera.addComponent('camera', {
        clearColor: new pc.Color(0.3, 0.3, 0.7)
    });
    camera.setPosition(0, 0, 3);
    app.root.addChild(camera);

    // create a light
    const light = new pc.Entity();
    light.addComponent('light');
    light.setEulerAngles(45, 45, 0);
    app.root.addChild(light);

    // create a box
    const box = new pc.Entity();
    box.addComponent('render', {
        type: 'box'
    });
    app.root.addChild(box);

    // rotate the box
    app.on('update', (dt) => box.rotate(10 * dt, 20 * dt, 30 * dt));

  5. 启动 Vite 开发服务器：

    npx vite

    这会在 http://localhost:5173 启动服务器。在浏览器中访问此地址，可以看到：

    旋转的立方体

    提示

    每次保存源文件时，页面都会自动重新加载。

方式二：导入映射与 CDN​

导入映射可以解析 JavaScript 模块中的模块说明符。例如，下面的导入语句：

import * as pc from 'playcanvas';

导入映射可以将 playcanvas 解析为托管在 CDN 上的引擎构建，由浏览器动态加载。因此可以省略方式一中的构建步骤。

首先选择使用 JavaScript 还是 TypeScript 开发：

  1. 打开终端或命令提示符，为应用创建目录，并通过 cd 进入该目录。

  2. 创建 index.html，粘贴以下内容：

    index.html
    <!DOCTYPE html>
    <html lang="en">
        <head>
            <meta charset="utf-8">
            <style>
                body { margin: 0; overflow: hidden; }
            </style>
            <script type="importmap">
            {
                "imports": {
                    "playcanvas": "https://cdn.jsdelivr.net/npm/playcanvas/+esm"
                }
            }
            </script>
        </head>
        <body>
            <script type="module" src="main.js"></script>
            <canvas id='application'></canvas>
        </body>
    </html>

  3. 创建 main.js，粘贴以下内容：

    main.js
    import * as pc from 'playcanvas';

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

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

    const app = new pc.AppBase(canvas);
    app.init(options);
    app.setCanvasResolution(pc.RESOLUTION_AUTO);
    app.setCanvasFillMode(pc.FILLMODE_FILL_WINDOW);
    app.start();

    // resize the canvas when the window is resized
    window.addEventListener('resize', () => app.resizeCanvas());

    // create a camera
    const camera = new pc.Entity();
    camera.addComponent('camera', {
        clearColor: new pc.Color(0.3, 0.3, 0.7)
    });
    camera.setPosition(0, 0, 3);
    app.root.addChild(camera);

    // create a light
    const light = new pc.Entity();
    light.addComponent('light');
    light.setEulerAngles(45, 45, 0);
    app.root.addChild(light);

    // create a box
    const box = new pc.Entity();
    box.addComponent('render', {
        type: 'box'
    });
    app.root.addChild(box);

    // rotate the box
    app.on('update', (dt) => box.rotate(10 * dt, 20 * dt, 30 * dt));

  4. 运行 serve：

    npx serve

    这会在 http://localhost:3000 启动服务器。在浏览器中访问此地址，可以看到：

    旋转的立方体

配置应用​

示例分两步创建应用：

  1. createGraphicsDevice 创建图形设备。在 deviceTypes 中指定 DEVICETYPE_WEBGPU 即可请求 WebGPU；WebGPU 不可用时，引擎会回退到 WebGL 2.0。
  2. 使用 AppOptions 对象初始化 AppBase，列出应用所需的组件系统和资源处理器。由于未注册其他功能，构建工具可以将其余部分排除在打包结果之外。

随着应用功能增加，需要注册相应内容：

  • 组件：每种组件类型都需要对应的组件系统。例如，要使用 script 组件，需要添加 pc.ScriptComponentSystem。包体积与 Tree Shaking列出了所有组件及对应系统。缺少系统时，addComponent 会返回 null，调试版引擎还会记录错误。
  • 资源：每种资源类型都需要对应的资源处理器。示例为纹理注册 pc.TextureHandler，为 GLB 模型注册 pc.ContainerHandler。包体积与 Tree Shaking列出了所有资源类型及对应处理器。
  • 其他功能：声音、批处理、光照贴图和 XR 通过额外的 AppOptions 属性启用。例如，sound 组件还需要 options.soundManager = new pc.SoundManager()。
备注

Application 类会代你完成全部配置。不过，它的构造函数无法创建 WebGPU 设备，会将所有组件系统和资源处理器加入包中，并且预计会在未来版本中被弃用。