使用 create-playcanvas 开始开发
create-playcanvas 是面向代码开发的 PlayCanvas 项目官方脚手架工具。它可以为 PlayCanvas Engine、React 或 Web Components 创建 Vite 和 TypeScript 项目，并提供可直接运行的初始场景。
创建项目
使用你喜欢的包管理器运行创建工具：
# npm
npm create playcanvas@latest
# pnpm
pnpm create playcanvas@latest
# Yarn
yarn create playcanvas
# Bun
bun x create-playcanvas@latest
按照提示为项目命名，选择开发方式和初始模板。使用 npm、pnpm 或 Yarn 时，创建工具要求 Node.js 22.23.2 或更高版本。
文件创建完成后，安装依赖并启动 Vite 开发服务器：
cd my-playcanvas-project
npm install
npm run dev
准备部署时，运行 npm run build 创建生产构建。构建中的 URL 使用相对路径，因此可以部署在服务器的任意目录下，不局限于域名根目录。
选择开发方式
所有开发方式均使用 TypeScript，并包含 Vite、ESLint、Prettier 和生产构建配置。
| 开发方式 | 适用场景 |
|---|---|
| Engine | 希望直接使用 playcanvas API。 |
| React | 使用 @playcanvas/react 构建 React 应用。 |
| Web Components | 希望使用 @playcanvas/web-components 提供的声明式自定义元素。 |
选择初始模板
每种开发方式都提供相同的一组可运行模板：
| 类别 | 模板 |
|---|---|
| 基础 | Spinning Cube（旋转立方体）、Interactive Sphere（交互球体） |
| 查看器 | Model Viewer（模型查看器）、Splat Viewer（高斯泼溅查看器）、Product Configurator（产品配置器） |
| 游戏 | Physics Playground（物理实验场）、First-Person Controller（第一人称控制器）、Third-Person Controller（第三人称控制器）、Sprite Game（精灵游戏）、Snapchat Web Lens |
| 工具 | Scene Editor（场景编辑器） |
| XR | VR Starter（VR 入门）、AR Placement（AR 放置） |
选择最接近目标应用的模板，先运行未经修改的版本，再逐步替换资源和行为。
Snapchat Web Lens 模板
Snapchat Web Lens 模板是一个竖屏游戏，已配置为通过 Web Lens 在 Snapchat 内运行：
npm create playcanvas@latest my-lens -- --starter web-lens
模板符合 Snap 的平台要求：采用竖屏布局，使 HUD 避开 Snapchat 的控件；构建使用相对 URL；不向其他主机发送请求。通过 Web Lens API，它会将每局成绩提交到排行榜，将玩家最高分保存在 Snapchat 存储中，并显示玩家的 Bitmoji。在 Snapchat 之外，API 由内置模拟实现响应，因此游戏也能在普通浏览器中运行。
要改造成自己的游戏，只需替换 src/dodge-game.ts 中的游戏实现，其余部分保持不变。项目 README 列出了需要替换和应当保留的文件。
游戏准备好后，执行打包：
npm run package
此命令会构建游戏，根据 Snap 的上传规则检查构建，并将 zip 文件写入 dist/。如果检查失败，会指出需要修复的文件，并且不会生成 zip。请参照 Snap 的发布指南，通过 My Lenses 上传 zip。
如果希望将编辑器项目发布为 Web Lens，请参阅 Snapchat Web Lenses。
使用 Inspector 调试
开发服务器会为正在运行的应用加载 Inspector。按反引号键（`）显示或隐藏面板，按 F9 暂停，按 F10 前进一帧。生产构建不包含 Inspector。
跳过交互提示
传入项目名称、开发方式和模板，即可非交互式地创建项目：
npm create playcanvas@latest my-viewer -- -f react -s model-viewer
当没有可回答提示的终端时，例如 AI 编程智能体或自动构建运行命令时，创建工具会对未指定的选项使用默认值，与 --yes 的行为一致。如果某项选择没有安全的默认值，仍会报错并停止，例如目标目录非空，却没有传入 --keep 或 --overwrite。
| 选项 | 简写 | 用途 |
|---|---|---|
--format <name> | -f | 选择 engine、react 或 web-components。 |
--starter <name> | -s | 选择上述初始模板之一。 |
--yes | -y | 接受默认的 Engine 和 Spinning Cube 选项。 |
--no-skills | 不包含默认附带的 PlayCanvas Skills。 | |
--keep | 向非空目标目录添加项目，不替换现有文件。 | |
--overwrite | 替换非空目标目录中的文件。 | |
--help | -h | 显示当前命令选项。 |
--overwrite 会删除目标目录中的现有文件。除非确实希望替换其内容，否则请使用新目录。
--keep 可以向已存有需求说明或资源等文件的目录中添加项目，不替换任何现有文件。如果项目模板包含同名文件，创建工具会保留原文件并列出该文件。如果目录中已经存在 package.json，则会报错并停止。
内置 PlayCanvas Skills
新项目会在 .claude/skills/ 和 .agents/skills/ 中包含 PlayCanvas Skills。兼容的 AI 编程智能体可以借此遵循 PlayCanvas 专用流程，完成应用配置、资源、场景、动画、光照、效果、渲染验证、性能优化和运行时检查。
仅当项目不使用 AI 编程智能体，或通过其他方式管理技能时，才需要传入 --no-skills。