playcanvas-agent-bridge-cli 0.3.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -20,6 +20,10 @@ npm install -g github:Q-My99/playcanvas-agent-bridge-cli
20
20
  pcbridge install-skill --agent all
21
21
  ```
22
22
 
23
+ The commands documented below include repository version `0.4.2`. Until that version is published,
24
+ the npm `latest` release (`0.3.0` as of 2026-08-04) does not contain every command described here;
25
+ use the GitHub install when testing these unreleased changes.
26
+
23
27
  One-shot with npx:
24
28
 
25
29
  ```bash
@@ -70,6 +74,12 @@ The daemon serves the active build from `http://localhost:3487`. On a
70
74
  frontend**. Choose **Use official frontend** to remove `use_local_frontend` and reload the same
71
75
  Editor URL with the official frontend.
72
76
 
77
+ The extension remembers the last popup selection per PlayCanvas project ID. Later visits to either
78
+ the `/editor/project/<projectId>` scene picker or an `/editor/scene/<sceneId>` page automatically
79
+ add or remove `use_local_frontend` while preserving other query parameters and the URL hash. The
80
+ preference changes only when the user clicks **Use custom frontend** or **Use official frontend**
81
+ again, and the popup shows the remembered value under **Project preference**.
82
+
73
83
  Manage installed releases explicitly when needed:
74
84
 
75
85
  ```bash
@@ -84,26 +94,62 @@ until another installed release is selected.
84
94
 
85
95
  ## Start the bridge
86
96
 
97
+ Change into the directory that should become the local workspace root before starting the daemon:
98
+
87
99
  ```bash
100
+ cd /path/to/my-playcanvas-workspace
88
101
  pcbridge daemon start
89
102
  ```
90
103
 
104
+ When a ready Editor connects, pcbridge creates `<projectId>-<projectName>/` automatically:
105
+
106
+ ```text
107
+ 1552681-pcbridge-test/
108
+ ├── pcbridge.project.json
109
+ ├── assets/ # PlayCanvas folder mirror with bidirectional script sync
110
+ ├── tmp/ # task scripts, manifests, captures, and conflict copies
111
+ └── .pcbridge/ # internal asset index; do not edit
112
+ ```
113
+
114
+ Inspect or refresh the workspace with:
115
+
116
+ ```bash
117
+ pcbridge workspace status --target editor:<sceneId>
118
+ pcbridge workspace path --target editor:<sceneId>
119
+ pcbridge workspace sync --target editor:<sceneId>
120
+ pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
121
+ ```
122
+
123
+ Script contents synchronize in both directions. Create, move, rename, and delete assets through
124
+ structured pcbridge commands. Images, models, audio, and other file assets are indexed and downloaded
125
+ lazily with `workspace pull`. Concurrent local and remote script edits are preserved under
126
+ `tmp/conflicts/` instead of being overwritten.
127
+
128
+ Script, JSON, upload, and capture paths are restricted to the selected project workspace by default.
129
+ Use `--allow-external-path` only for an intentional external file.
130
+
91
131
  In another terminal:
92
132
 
93
133
  ```bash
94
134
  pcbridge doctor
95
135
  pcbridge targets
96
- pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor }"
97
- pcbridge eval --target launch:<sceneId> --code "return { href: location.href, hasPc: !!pc }"
136
+ pcbridge eval --target editor:<sceneId> --code "return { href: location.href, hasEditor: !!editor }"
137
+ pcbridge launch diagnose --target launch:<sceneId>
98
138
  ```
99
139
 
140
+ `doctor` distinguishes a missing listener (`DAEMON_NOT_LISTENING`) from a sandbox that blocks
141
+ localhost (`LOOPBACK_ACCESS_DENIED`); only the former means another daemon should be started.
142
+
100
143
  ## Progressive help
101
144
 
102
145
  The CLI exposes layered help so agents can load only the command surface they need:
103
146
 
104
147
  ```bash
105
148
  pcbridge help
149
+ pcbridge help core
150
+ pcbridge help workspace
106
151
  pcbridge help frontend
152
+ pcbridge help target
107
153
  pcbridge help entity
108
154
  pcbridge help asset
109
155
  pcbridge help material
@@ -124,54 +170,71 @@ large multi-step scene edits where one script is clearer and faster than many CL
124
170
  ## Common commands
125
171
 
126
172
  ```bash
127
- pcbridge entity list --target current --limit 50
128
- pcbridge entity list --target current --tag enemy --component render
129
- pcbridge entity create --target current --json ./entity.json
130
- pcbridge entity create-many --target current --json ./entities.json
131
- pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
132
- pcbridge entity patch-many --target current --json ./edits.json
133
- pcbridge entity duplicate --target current --id <resource_id>
134
- pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
135
- pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
136
- pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
137
- pcbridge entity delete --target current --id <resource_id>
138
-
139
- pcbridge asset list --target current --type script
140
- pcbridge asset list --target current --tag generated
141
- pcbridge asset get --target current --id <asset_id>
142
- pcbridge asset create --target current --json ./assets.json
143
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/Demo/Textures"
144
- pcbridge asset upload --target current --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
145
- pcbridge asset upload-many --target current --json ./upload-manifest.json
146
- pcbridge asset instantiate --target current --id <template_asset_id>
147
- pcbridge asset delete --target current --id <asset_id>
148
-
149
- pcbridge material create --target current --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
150
- pcbridge material patch --target current --asset-id <asset_id> --set diffuse='[1,0,0]'
151
-
152
- pcbridge template create --target current --entity-id <resource_id> --name DemoTemplate --folder "AI Agent Bridge/Demo/Templates"
153
- pcbridge template instantiate --target current --id <template_asset_id>
154
-
155
- pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
156
- pcbridge script upsert --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts" --parse
157
- pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js
158
- pcbridge script parse --target current --asset-id <asset_id>
159
-
160
- pcbridge scene settings get --target current
161
- pcbridge scene settings patch --target current --set physics.gravity='[0,-9.8,0]'
162
-
163
- pcbridge store search --target current --search vehicle --limit 20
164
- pcbridge store get --target current --id <store_asset_id>
165
- pcbridge store download --target current --id <store_asset_id> --name Vehicle --license-json ./license.json
166
-
167
- pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
168
- pcbridge viewport focus --target current --id <resource_id> --view perspective
169
-
170
- pcbridge logs get --target current --limit 100
173
+ pcbridge entity list --target editor:<sceneId> --limit 50
174
+ pcbridge entity list --target editor:<sceneId> --tag enemy --component render
175
+ pcbridge entity create --target editor:<sceneId> --json ./entity.json
176
+ pcbridge entity create-many --target editor:<sceneId> --json ./entities.json
177
+ pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set position='[0,1,0]'
178
+ pcbridge entity patch-many --target editor:<sceneId> --json ./edits.json
179
+ pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
180
+ pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
181
+ pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
182
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
183
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
184
+ pcbridge entity delete --target editor:<sceneId> --id <resource_id>
185
+
186
+ pcbridge asset list --target editor:<sceneId> --type script
187
+ pcbridge asset list --target editor:<sceneId> --tag generated
188
+ pcbridge asset get --target editor:<sceneId> --id <asset_id>
189
+ pcbridge asset create --target editor:<sceneId> --json ./assets.json
190
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Demo/Textures"
191
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
192
+ pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
193
+ pcbridge asset instantiate --target editor:<sceneId> --id <template_asset_id>
194
+ pcbridge asset delete --target editor:<sceneId> --id <asset_id>
195
+
196
+ pcbridge material create --target editor:<sceneId> --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
197
+ pcbridge material patch --target editor:<sceneId> --asset-id <asset_id> --set diffuse='[1,0,0]'
198
+
199
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name DemoTemplate --folder "AI Agent Bridge/Demo/Templates"
200
+ pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
201
+ pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
202
+ pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
203
+ pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
204
+
205
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
206
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts" --parse --wait
207
+ pcbridge script set-text --target editor:<sceneId> --asset-id <asset_id> --file ./controller.js --parse --wait
208
+ pcbridge script parse --target editor:<sceneId> --asset-id <asset_id>
209
+
210
+ pcbridge scene settings get --target editor:<sceneId>
211
+ pcbridge scene settings patch --target editor:<sceneId> --set physics.gravity='[0,-9.8,0]'
212
+
213
+ pcbridge store search --target editor:<sceneId> --search vehicle --limit 20
214
+ pcbridge store get --target editor:<sceneId> --id <store_asset_id>
215
+ pcbridge store download --target editor:<sceneId> --id <store_asset_id> --name Vehicle --license-json ./license.json
216
+
217
+ pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas-viewport.png
218
+ pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
219
+
220
+ pcbridge logs get --target editor:<sceneId> --limit 100
171
221
  pcbridge logs get --target launch:<sceneId> --level error
172
- pcbridge logs clear --target current
222
+ pcbridge logs clear --target editor:<sceneId>
173
223
  ```
174
224
 
225
+ Use `--script-name` for ScriptTypes registered by a bundle or runtime asset and therefore lacking a
226
+ standalone script asset id. Script update commands with `--parse --wait` verify the uploaded text,
227
+ stable file metadata, and parsed attributes before returning. This completion check covers the
228
+ remote asset and current Editor observer, not a later workspace mirror sync.
229
+
230
+ Template apply commands invoke the Editor's existing `templates:apply` action. When overrides exist,
231
+ completion requires its pipeline callback plus two zero-override observations. A returned `verified`
232
+ value only confirms the current Editor observer; it does not confirm persistence across an Editor
233
+ reload. Editor entity patches are durable: restore preview-only enabled/visibility changes before
234
+ applying a Template. `apply-many` accepts
235
+ `{"entityIds":["root-a","root-b"]}` (or an array of ids or `{ "entityId": "..." }` items), validates
236
+ its manifest first, and applies roots serially.
237
+
175
238
  For task-sized installs, keep upload manifests next to the generated files. Relative `file` paths are resolved from the manifest location:
176
239
 
177
240
  ```json
@@ -190,22 +253,22 @@ For task-sized installs, keep upload manifests next to the generated files. Rela
190
253
  Use `eval --args-json` when a large Editor script needs local configuration without embedding JSON into source:
191
254
 
192
255
  ```bash
193
- pcbridge eval --target current --file ./install-scene.js --args-json ./install-args.json
256
+ pcbridge eval --target editor:<sceneId> --file ./install-scene.js --args-json ./install-args.json
194
257
  ```
195
258
 
196
259
  ## Texture + material + script workflow
197
260
 
198
261
  ```bash
199
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/Texture Box/Textures"
200
- pcbridge asset upload --target current --file ./cat.png --name CatTexture --folder "AI Agent Bridge/Texture Box/Textures"
262
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Texture Box/Textures"
263
+ pcbridge asset upload --target editor:<sceneId> --file ./cat.png --name CatTexture --folder "AI Agent Bridge/Texture Box/Textures"
201
264
 
202
- pcbridge material create --target current --name CatMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
265
+ pcbridge material create --target editor:<sceneId> --name CatMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
203
266
 
204
- pcbridge script create --target current --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
267
+ pcbridge script create --target editor:<sceneId> --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
205
268
 
206
- pcbridge entity create --target current --json ./box.json
207
- pcbridge entity set-material --target current --id <box_resource_id> --material-id <material_asset_id>
208
- pcbridge entity add-script --target current --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
269
+ pcbridge entity create --target editor:<sceneId> --json ./box.json
270
+ pcbridge entity set-material --target editor:<sceneId> --id <box_resource_id> --material-id <material_asset_id>
271
+ pcbridge entity add-script --target editor:<sceneId> --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
209
272
  ```
210
273
 
211
274
  ## Target selection
@@ -216,7 +279,9 @@ pcbridge eval --target current --code "return location.href"
216
279
  pcbridge eval --target tab:123 --code "return location.href"
217
280
  pcbridge eval --target scene:987654 --code "return location.href"
218
281
  pcbridge eval --target project:123456 --code "return location.href"
219
- pcbridge eval --target launch:987654 --code "return { href: location.href, hasPc: !!pc }"
282
+ pcbridge launch diagnose --target launch:987654
283
+ pcbridge launch wait-ready --target launch:987654 --focus --timeout-ms 30000
284
+ pcbridge eval --target launch:987654 --code "return { runtimeCreated: !!runtimeApp, rootChildCount: runtimeApp?.root?.children?.length ?? 0 }"
220
285
  pcbridge viewport capture --target launch:987654 --out ./tmp/launch.png
221
286
  pcbridge logs get --target launch:987654 --limit 100
222
287
  ```
@@ -226,6 +291,17 @@ are open for the same scene, use `tab:<id>`, `editor:<sceneId>`, or `launch:<sce
226
291
  ambiguity. Editor-only structured commands require an Editor target; `eval`, `viewport capture`,
227
292
  and `logs` also work on Launch targets.
228
293
 
294
+ Launch readiness is a best-effort heuristic, not an Engine lifecycle event. `lifecycleReady`
295
+ requires a runtime app with its own graphics canvas/context, an attached scene root, and at least
296
+ one completed frame, with no recognized splash. Target `ready` additionally requires the tab to be
297
+ visible, so use `launch wait-ready --focus` for a hidden Launch tab. `scriptTypeCount` is diagnostic
298
+ only and does not prove every ScriptType has registered. Eval receives a compatibility-resolved
299
+ `runtimeApp` binding for Engine V1 and V2.
300
+
301
+ `viewport capture` records the current canvas; it does not resize Chrome or emulate a mobile DPR.
302
+ PNG can preserve transparency; the default `--max-width 1200` can downscale output. Eval output is bounded; use a
303
+ leaf projection first, then bounded `--max-depth`, `--max-items`, or `--max-keys` if needed.
304
+
229
305
  ## Agent skills
230
306
 
231
307
  Install rules/skills for common agents:
@@ -245,6 +321,10 @@ Installed locations:
245
321
  - Cursor: `~/.cursor/rules/playcanvas-agent-bridge-cli.mdc`
246
322
  - Windsurf: `~/.windsurf/rules/playcanvas-agent-bridge-cli.md`
247
323
 
324
+ The extension popup shows daemon and current-tab connectivity, project/scene/branch identity,
325
+ workspace path and sync counts, conflicts, and custom Editor frontend state. Red means disconnected
326
+ or conflicted, yellow means initializing/syncing/local attention, and green means ready/synced.
327
+
248
328
  ## Security model
249
329
 
250
330
  This is a local trusted developer tool. It executes JavaScript inside PlayCanvas Editor and Launch pages that you already have open.
@@ -280,8 +360,8 @@ repository does not need an `NPM_TOKEN` secret.
280
360
  3. Create and push the matching tag, for example:
281
361
 
282
362
  ```bash
283
- git tag v0.3.0
284
- git push origin v0.3.0
363
+ git tag v<version>
364
+ git push origin v<version>
285
365
  ```
286
366
 
287
367
  The workflow rejects tags that do not match the package version or whose commit is not on `main`.
package/README.zh-CN.md CHANGED
@@ -13,6 +13,9 @@ npm install -g playcanvas-agent-bridge-cli
13
13
  pcbridge install-skill --agent all
14
14
  ```
15
15
 
16
+ 下文命令包含仓库版 `0.4.2` 的尚未发布改动。在该版本发布前,npm 的 `latest`(截至
17
+ 2026-08-04 为 `0.3.0`)不包含这里列出的全部命令;测试本轮新能力时请使用 GitHub 安装。
18
+
16
19
  如果要测试尚未发布的改动,也可以直接从这个 GitHub 仓库安装:
17
20
 
18
21
  ```bash
@@ -70,6 +73,12 @@ daemon 会在 `http://localhost:3487` 提供当前激活的构建。打开
70
73
  点击 **Use official frontend** 会删除 `use_local_frontend` 参数,并用官方前端重新加载同一个
71
74
  Editor URL。
72
75
 
76
+ 插件会按 PlayCanvas project ID 记住最后一次在 popup 中选择的模式。之后进入
77
+ `/editor/project/<projectId>` 场景选择页或 `/editor/scene/<sceneId>` 场景编辑页时,会自动
78
+ 添加或删除 `use_local_frontend`,并保留 URL 中其他查询参数和 hash。该偏好只会在用户再次
79
+ 点击 **Use custom frontend** 或 **Use official frontend** 时改变;popup 的 **Project
80
+ preference** 会显示当前项目的记忆值。
81
+
73
82
  需要时可以显式管理本地版本:
74
83
 
75
84
  ```bash
@@ -84,26 +93,61 @@ pcbridge frontend remove playcanvas-editor-v2.28.1-r1
84
93
 
85
94
  ## 启动桥接
86
95
 
96
+ 请先进入希望作为本地工作区根目录的位置,再启动 daemon:
97
+
87
98
  ```bash
99
+ cd /path/to/my-playcanvas-workspace
88
100
  pcbridge daemon start
89
101
  ```
90
102
 
103
+ 连接 ready 的 Editor 后,pcbridge 会自动创建 `<projectId>-<projectName>/` 工程目录:
104
+
105
+ ```text
106
+ 1552681-pcbridge-test/
107
+ ├── pcbridge.project.json
108
+ ├── assets/ # 与 PlayCanvas 文件夹结构对应,脚本自动双向同步
109
+ ├── tmp/ # 临时脚本、清单、截图和冲突副本
110
+ └── .pcbridge/ # 内部资源索引,请勿手动修改
111
+ ```
112
+
113
+ 查看或手动刷新工作区:
114
+
115
+ ```bash
116
+ pcbridge workspace status --target editor:<sceneId>
117
+ pcbridge workspace path --target editor:<sceneId>
118
+ pcbridge workspace sync --target editor:<sceneId>
119
+ pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
120
+ ```
121
+
122
+ 脚本内容保持双向同步。资源的新建、移动、重命名和删除仍应使用 pcbridge 结构化命令;
123
+ 图片、模型和音频等文件只建立索引,需要时用 `workspace pull` 懒下载。检测到本地与远端
124
+ 同时修改时不会覆盖任一版本,冲突副本写入 `tmp/conflicts/`。
125
+
126
+ CLI 的脚本、JSON、上传文件和截图路径默认必须位于对应项目工作区内。只有明确需要使用
127
+ 外部文件时才使用 `--allow-external-path`。
128
+
91
129
  另开一个终端检查:
92
130
 
93
131
  ```bash
94
132
  pcbridge doctor
95
133
  pcbridge targets
96
- pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor }"
97
- pcbridge eval --target launch:<sceneId> --code "return { href: location.href, hasPc: !!pc }"
134
+ pcbridge eval --target editor:<sceneId> --code "return { href: location.href, hasEditor: !!editor }"
135
+ pcbridge launch diagnose --target launch:<sceneId>
98
136
  ```
99
137
 
138
+ `doctor` 会区分 daemon 未监听(`DAEMON_NOT_LISTENING`)和受限环境禁止 localhost
139
+ (`LOOPBACK_ACCESS_DENIED`);只有前一种情况才应该再启动 daemon。
140
+
100
141
  ## 渐进式 help
101
142
 
102
143
  CLI 提供分层 help,方便 agent 只加载当前需要的命令面:
103
144
 
104
145
  ```bash
105
146
  pcbridge help
147
+ pcbridge help core
148
+ pcbridge help workspace
106
149
  pcbridge help frontend
150
+ pcbridge help target
107
151
  pcbridge help entity
108
152
  pcbridge help asset
109
153
  pcbridge help material
@@ -123,54 +167,70 @@ Editor/Engine 工作流、Launch 调试、大量多步骤场景修改,则优
123
167
  ## 常用命令
124
168
 
125
169
  ```bash
126
- pcbridge entity list --target current --limit 50
127
- pcbridge entity list --target current --tag enemy --component render
128
- pcbridge entity create --target current --json ./entity.json
129
- pcbridge entity create-many --target current --json ./entities.json
130
- pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
131
- pcbridge entity patch-many --target current --json ./edits.json
132
- pcbridge entity duplicate --target current --id <resource_id>
133
- pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
134
- pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
135
- pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
136
- pcbridge entity delete --target current --id <resource_id>
137
-
138
- pcbridge asset list --target current --type script
139
- pcbridge asset list --target current --tag generated
140
- pcbridge asset get --target current --id <asset_id>
141
- pcbridge asset create --target current --json ./assets.json
142
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/Demo/Textures"
143
- pcbridge asset upload --target current --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
144
- pcbridge asset upload-many --target current --json ./upload-manifest.json
145
- pcbridge asset instantiate --target current --id <template_asset_id>
146
- pcbridge asset delete --target current --id <asset_id>
147
-
148
- pcbridge material create --target current --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
149
- pcbridge material patch --target current --asset-id <asset_id> --set diffuse='[1,0,0]'
150
-
151
- pcbridge template create --target current --entity-id <resource_id> --name DemoTemplate --folder "AI Agent Bridge/Demo/Templates"
152
- pcbridge template instantiate --target current --id <template_asset_id>
153
-
154
- pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
155
- pcbridge script upsert --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts" --parse
156
- pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js
157
- pcbridge script parse --target current --asset-id <asset_id>
158
-
159
- pcbridge scene settings get --target current
160
- pcbridge scene settings patch --target current --set physics.gravity='[0,-9.8,0]'
161
-
162
- pcbridge store search --target current --search vehicle --limit 20
163
- pcbridge store get --target current --id <store_asset_id>
164
- pcbridge store download --target current --id <store_asset_id> --name Vehicle --license-json ./license.json
165
-
166
- pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
167
- pcbridge viewport focus --target current --id <resource_id> --view perspective
168
-
169
- pcbridge logs get --target current --limit 100
170
+ pcbridge entity list --target editor:<sceneId> --limit 50
171
+ pcbridge entity list --target editor:<sceneId> --tag enemy --component render
172
+ pcbridge entity create --target editor:<sceneId> --json ./entity.json
173
+ pcbridge entity create-many --target editor:<sceneId> --json ./entities.json
174
+ pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set position='[0,1,0]'
175
+ pcbridge entity patch-many --target editor:<sceneId> --json ./edits.json
176
+ pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
177
+ pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
178
+ pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
179
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
180
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
181
+ pcbridge entity delete --target editor:<sceneId> --id <resource_id>
182
+
183
+ pcbridge asset list --target editor:<sceneId> --type script
184
+ pcbridge asset list --target editor:<sceneId> --tag generated
185
+ pcbridge asset get --target editor:<sceneId> --id <asset_id>
186
+ pcbridge asset create --target editor:<sceneId> --json ./assets.json
187
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Demo/Textures"
188
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
189
+ pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
190
+ pcbridge asset instantiate --target editor:<sceneId> --id <template_asset_id>
191
+ pcbridge asset delete --target editor:<sceneId> --id <asset_id>
192
+
193
+ pcbridge material create --target editor:<sceneId> --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
194
+ pcbridge material patch --target editor:<sceneId> --asset-id <asset_id> --set diffuse='[1,0,0]'
195
+
196
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name DemoTemplate --folder "AI Agent Bridge/Demo/Templates"
197
+ pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
198
+ pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
199
+ pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
200
+ pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
201
+
202
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
203
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts" --parse --wait
204
+ pcbridge script set-text --target editor:<sceneId> --asset-id <asset_id> --file ./controller.js --parse --wait
205
+ pcbridge script parse --target editor:<sceneId> --asset-id <asset_id>
206
+
207
+ pcbridge scene settings get --target editor:<sceneId>
208
+ pcbridge scene settings patch --target editor:<sceneId> --set physics.gravity='[0,-9.8,0]'
209
+
210
+ pcbridge store search --target editor:<sceneId> --search vehicle --limit 20
211
+ pcbridge store get --target editor:<sceneId> --id <store_asset_id>
212
+ pcbridge store download --target editor:<sceneId> --id <store_asset_id> --name Vehicle --license-json ./license.json
213
+
214
+ pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas-viewport.png
215
+ pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
216
+
217
+ pcbridge logs get --target editor:<sceneId> --limit 100
170
218
  pcbridge logs get --target launch:<sceneId> --level error
171
- pcbridge logs clear --target current
219
+ pcbridge logs clear --target editor:<sceneId>
172
220
  ```
173
221
 
222
+ 通过 bundle 或 runtime asset 注册、没有独立 script asset id 的 ScriptType,请使用
223
+ `--script-name`。脚本更新配合 `--parse --wait` 时,会在返回前校验远端文本、稳定的文件元数据
224
+ 以及最新的解析属性。这个完成检查覆盖远端 asset 和当前 Editor observer,不等待之后一次
225
+ workspace mirror sync。
226
+
227
+ Template apply 命令会调用 Editor 现有的 `templates:apply` action。存在 overrides 时,完成条件
228
+ 是 pipeline callback 已到达,且连续两次观察到 overrides 为 0。返回的 `verified` 只确认当前
229
+ Editor observer 状态,不代表刷新 Editor 后仍然持久。
230
+ Editor entity patch 是持久修改;apply 前必须先恢复只用于预览的 enabled/visibility 状态。
231
+ `apply-many` 会先校验清单,再串行处理每个 root。清单可以写成
232
+ `{"entityIds":["root-a","root-b"]}`,也可直接使用 entity id 或 `{ "entityId": "..." }` 条目数组。
233
+
174
234
  大型任务可以把上传清单放在生成文件旁边。`file` 的相对路径会按清单文件所在目录解析:
175
235
 
176
236
  ```json
@@ -189,22 +249,22 @@ pcbridge logs clear --target current
189
249
  当较大的 Editor 脚本需要本地配置时,用 `eval --args-json`,避免把 JSON 直接拼进代码里:
190
250
 
191
251
  ```bash
192
- pcbridge eval --target current --file ./install-scene.js --args-json ./install-args.json
252
+ pcbridge eval --target editor:<sceneId> --file ./install-scene.js --args-json ./install-args.json
193
253
  ```
194
254
 
195
255
  ## 贴图 + 材质 + 脚本工作流
196
256
 
197
257
  ```bash
198
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/Texture Box/Textures"
199
- pcbridge asset upload --target current --file ./cat.png --name CatTexture --folder "AI Agent Bridge/Texture Box/Textures"
258
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Texture Box/Textures"
259
+ pcbridge asset upload --target editor:<sceneId> --file ./cat.png --name CatTexture --folder "AI Agent Bridge/Texture Box/Textures"
200
260
 
201
- pcbridge material create --target current --name CatMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
261
+ pcbridge material create --target editor:<sceneId> --name CatMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
202
262
 
203
- pcbridge script create --target current --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
263
+ pcbridge script create --target editor:<sceneId> --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
204
264
 
205
- pcbridge entity create --target current --json ./box.json
206
- pcbridge entity set-material --target current --id <box_resource_id> --material-id <material_asset_id>
207
- pcbridge entity add-script --target current --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
265
+ pcbridge entity create --target editor:<sceneId> --json ./box.json
266
+ pcbridge entity set-material --target editor:<sceneId> --id <box_resource_id> --material-id <material_asset_id>
267
+ pcbridge entity add-script --target editor:<sceneId> --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
208
268
  ```
209
269
 
210
270
  ## 目标选择
@@ -215,7 +275,9 @@ pcbridge eval --target current --code "return location.href"
215
275
  pcbridge eval --target tab:123 --code "return location.href"
216
276
  pcbridge eval --target scene:987654 --code "return location.href"
217
277
  pcbridge eval --target project:123456 --code "return location.href"
218
- pcbridge eval --target launch:987654 --code "return { href: location.href, hasPc: !!pc }"
278
+ pcbridge launch diagnose --target launch:987654
279
+ pcbridge launch wait-ready --target launch:987654 --focus --timeout-ms 30000
280
+ pcbridge eval --target launch:987654 --code "return { runtimeCreated: !!runtimeApp, rootChildCount: runtimeApp?.root?.children?.length ?? 0 }"
219
281
  pcbridge viewport capture --target launch:987654 --out ./tmp/launch.png
220
282
  pcbridge logs get --target launch:987654 --limit 100
221
283
  ```
@@ -224,6 +286,16 @@ pcbridge logs get --target launch:987654 --limit 100
224
286
  页面,请使用 `tab:<id>`、`editor:<sceneId>` 或 `launch:<sceneId>` 避免歧义。结构化编辑命令需要
225
287
  Editor 目标;`eval`、`viewport capture` 和 `logs` 也可以用于 Launch 目标。
226
288
 
289
+ Launch ready 是尽力而为的启发式判断,不是 Engine 生命周期事件。`lifecycleReady` 要求找到
290
+ 拥有自身 graphics canvas/context 的 runtime app、scene root 已挂载、至少完成一帧,并且没有
291
+ 识别到启动遮罩;target `ready` 还要求 tab 可见。因此后台 Launch 应使用
292
+ `launch wait-ready --focus`。`scriptTypeCount` 只用于诊断,不能证明所有 ScriptType 已注册。
293
+ eval 提供通过兼容 resolver 选择的 Engine V1/V2 `runtimeApp`。
294
+
295
+ `viewport capture` 只截取当前 canvas,不会调整 Chrome 尺寸或模拟手机 DPR。PNG 可能保留
296
+ 透明通道;默认的 `--max-width 1200` 可能缩放输出。eval 输出有边界;优先返回叶子字段,必要时再使用有
297
+ 上限的 `--max-depth`、`--max-items` 或 `--max-keys`。
298
+
227
299
  ## Agent skill / rules
228
300
 
229
301
  安装各家 agent 的使用说明:
@@ -243,6 +315,10 @@ pcbridge install-skill --agent all
243
315
  - Cursor: `~/.cursor/rules/playcanvas-agent-bridge-cli.mdc`
244
316
  - Windsurf: `~/.windsurf/rules/playcanvas-agent-bridge-cli.md`
245
317
 
318
+ 插件 popup 会展示 daemon、当前 tab、项目、scene、branch、工作区路径、同步统计、冲突数
319
+ 以及自定义 Editor frontend 状态。红色表示断联或冲突,黄色表示初始化、同步中或本地待处理
320
+ 状态,绿色表示 ready / synced。
321
+
246
322
  ## 安全模型
247
323
 
248
324
  这是一个本地可信开发工具,会在你已经打开的 PlayCanvas Editor 和 Launch 页面内执行 JavaScript。
@@ -276,8 +352,8 @@ node dist/cli.js doctor
276
352
  3. 创建并推送匹配的 tag,例如:
277
353
 
278
354
  ```bash
279
- git tag v0.3.0
280
- git push origin v0.3.0
355
+ git tag v<version>
356
+ git push origin v<version>
281
357
  ```
282
358
 
283
359
  如果 tag 与包版本不一致,或者 tag 对应的提交不属于 `main`,workflow 会拒绝发布。