VS Code 扩展
扩展将 PlayCanvas 项目的文本资源映射为本地工作区。可使用 VS Code 或 Cursor 编辑脚本和着色器，由扩展处理登录、分支、类型信息和同步。
扩展在 GitHub 开源，采用 MIT 许可证。
安装与打开项目
- 安装 VS Code 或 Cursor。
- 从对应市场安装 PlayCanvas 扩展：
- VS Code：Visual Studio Marketplace
- Cursor：Open VSX
- 点击登录通知，使用 PlayCanvas 账户验证。
- 按
Ctrl/Cmd+Shift+P。 - 运行 PlayCanvas: Open Project，选择项目和分支。
Explorer 显示文本资源。打开脚本后，可使用 PlayCanvas 类型检查、自动补全和行内 API 文档。Collaborators 显示其他成员。
选择同步模式
设置 PlayCanvas: Sync Mode（playcanvas.syncMode），修改后重新加载窗口。
| Realtime | Pull/Push（预览） | |
|---|---|---|
| 适合 | 实时协作 | 外部工具与经过审查的批量修改 |
| 同步 | 输入时同步 | 显式 Pull 和 Push |
| 冲突 | 自动合并 | 三方合并解决 |
| 可用平台 | 桌面和 Web | 仅桌面 |
实时模式
Realtime 为默认模式。
- 打开文件的输入实时同步。
- 协作者修改自动出现。
Ctrl/Cmd+S保存到编辑器。- Explorer 中创建、删除、重命名、移动会更新项目。
Ctrl/Cmd+Z和Ctrl/Cmd+Shift+Z只撤销或重做自己的修改。
打开文件时从服务器刷新。外部程序修改关闭文件时，实时模式保留本地修改，但不会提交，扩展会提示切换 Pull/Push。
Pull/Push 模式
文件系统修改保持本地，直到显式同步。适合格式化工具、编译器、脚本和可能编辑关闭文件的 AI 助手。
- 设置为 Pull/Push 并重新加载窗口。
- 打开 Source Control，选择 PlayCanvas 仓库。
- Pull 获取最新服务器状态。
- 照常编辑保存，本地修改出现在 Changes。
- 审查差异后 Push。
状态栏显示传入、传出和冲突文件数。命令面板也可运行 PlayCanvas: Pull 和 PlayCanvas: Push。
- Pull：
Ctrl/Cmd+Alt+Down。 - Push：
Ctrl/Cmd+Alt+Up。
Push 仅允许快进。上次 Pull 后服务器已变化时，Push 停止而不覆盖。先 Pull、解决冲突，再 Push。
解决 Pull/Push 冲突
冲突文件位于 Merge Changes。
- 打开冲突文件。
- 使用合并编辑器，或直接编辑
<<<<<<<、=======、>>>>>>>区域。 - 保留正确结果，移除全部冲突标记并保存。
- 确认回到 Changes，再 Push。
放弃本地修改可在 Source Control 选择丢弃，会先确认，再恢复最后同步版本。
配合 AI 编程助手
AI 编辑文件时使用 Pull/Push，从映射目录启动助手，说明范围、预期结果和检查要求。
不要为外部助手使用实时模式。它忽略其他程序对关闭文件的修改，避免陈旧本地文件覆盖协作结果。
例如：
检查玩家移动脚本，使键盘移动不受帧率影响。
保留当前控制方式和公开脚本属性。
修改后检查 Problems 面板或运行可用的类型检查，再说明修改了哪些文件。
不要修改无关资源。
Push 前修改始终在本地。审查所有文件和诊断，Pull 最新状态，解决冲突后 Push，再从编辑器启动项目，在真实场景验证。
切换分支
先同步或丢弃当前工作，再运行 PlayCanvas: Switch Branch 选择目标，工作区随之切换。
忽略文件
项目根目录创建 .pcignore，语法与 .gitignore 一致，支持 *.ts、generated/** 等模式。
扩展会重新读取修改后的规则。变更后重新加载项目，使磁盘文件刷新。
故障排查
外部修改不同步
Pull/Push 仅桌面扩展可用。确认 playcanvas.syncMode 为 pullpush，重载窗口，外部工具编辑前先 Pull。
Push 被阻止
远程已变化。先 Pull，解决 Merge Changes，再 Push。
文件路径冲突
运行 PlayCanvas: Show Path Collisions，在编辑器重命名列出的资源，确保路径唯一，再重载项目。
工作区内容陈旧
运行 PlayCanvas: Reload Project。仍有问题时，运行 PlayCanvas: Report Issue 并附复现步骤。