playcanvas-agent-bridge-cli 0.2.2 → 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.
Files changed (34) hide show
  1. package/README.md +218 -52
  2. package/README.zh-CN.md +210 -51
  3. package/dist/cli.js +723 -92
  4. package/dist/config.js +6 -2
  5. package/dist/daemon/server.js +181 -19
  6. package/dist/daemon/target-registry.js +61 -3
  7. package/dist/frontend/server.js +191 -0
  8. package/dist/frontend/store.js +369 -0
  9. package/dist/shared/protocol.js +3 -1
  10. package/dist/snippets.js +764 -30
  11. package/dist/workspace/manager.js +536 -0
  12. package/extension/icons/concepts/pcbridge-bridge.png +0 -0
  13. package/extension/icons/concepts/pcbridge-cube.png +0 -0
  14. package/extension/icons/concepts/pcbridge-p-active.png +0 -0
  15. package/extension/icons/concepts/pcbridge-p-arch.png +0 -0
  16. package/extension/icons/concepts/pcbridge-p-bridge.png +0 -0
  17. package/extension/icons/concepts/pcbridge-p-emblem.png +0 -0
  18. package/extension/icons/concepts/pcbridge-signal.png +0 -0
  19. package/extension/icons/icon-128.png +0 -0
  20. package/extension/icons/icon-16.png +0 -0
  21. package/extension/icons/icon-32.png +0 -0
  22. package/extension/icons/icon-48.png +0 -0
  23. package/extension/isolated.js +214 -43
  24. package/extension/main.js +619 -32
  25. package/extension/manifest.json +29 -7
  26. package/extension/popup.html +188 -24
  27. package/extension/popup.js +199 -10
  28. package/extension/service-worker.js +268 -17
  29. package/package.json +4 -1
  30. package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +97 -24
  31. package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +167 -52
  32. package/skills/codex/playcanvas-agent-bridge-cli/agents/openai.yaml +2 -2
  33. package/skills/cursor/playcanvas-agent-bridge-cli.mdc +63 -23
  34. package/skills/windsurf/playcanvas-agent-bridge-cli.md +61 -23
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # playcanvas-agent-bridge-cli
2
2
 
3
- CLI-first local automation for controlling an already-open PlayCanvas Editor scene from AI coding agents such as Codex, Claude Code, Cursor, and Windsurf.
3
+ CLI-first local automation for controlling already-open PlayCanvas Editor scenes and PlayCanvas Launch pages from AI coding agents such as Codex, Claude Code, Cursor, and Windsurf.
4
4
 
5
5
  The core interface is the `pcbridge` command plus a local daemon and a Chrome Manifest V3 extension. MCP is intentionally not required.
6
6
 
@@ -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
@@ -50,30 +54,102 @@ Then in Chrome:
50
54
  2. Enable Developer Mode.
51
55
  3. Click Load unpacked.
52
56
  4. Select the exact directory printed by `pcbridge install-extension`.
53
- 5. Open or refresh a PlayCanvas Editor page.
57
+ 5. Open or refresh a PlayCanvas Editor page or a PlayCanvas Launch page.
54
58
 
55
59
  The generated extension directory contains a local session token in `config.json`, so load that generated directory rather than the raw `extension/` folder from the repo.
56
60
 
61
+ ## Use the custom Editor frontend
62
+
63
+ The Editor build is not bundled in the npm package. Download the latest published build from
64
+ `Q-My99/playcanvas-editor`, verify its release metadata and SHA-256, then activate it locally:
65
+
66
+ ```bash
67
+ pcbridge frontend install latest
68
+ pcbridge frontend status
69
+ pcbridge daemon start
70
+ ```
71
+
72
+ The daemon serves the active build from `http://localhost:3487`. On a
73
+ `https://playcanvas.com/editor/...` tab, open the extension popup and choose **Use custom
74
+ frontend**. Choose **Use official frontend** to remove `use_local_frontend` and reload the same
75
+ Editor URL with the official frontend.
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
+
83
+ Manage installed releases explicitly when needed:
84
+
85
+ ```bash
86
+ pcbridge frontend list
87
+ pcbridge frontend update
88
+ pcbridge frontend use playcanvas-editor-v2.28.1-r1
89
+ pcbridge frontend remove playcanvas-editor-v2.28.1-r1
90
+ ```
91
+
92
+ Downloaded builds live under `~/.pcbridge/frontends/`. Removing the active release is refused
93
+ until another installed release is selected.
94
+
57
95
  ## Start the bridge
58
96
 
97
+ Change into the directory that should become the local workspace root before starting the daemon:
98
+
59
99
  ```bash
100
+ cd /path/to/my-playcanvas-workspace
60
101
  pcbridge daemon start
61
102
  ```
62
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
+
63
131
  In another terminal:
64
132
 
65
133
  ```bash
66
134
  pcbridge doctor
67
135
  pcbridge targets
68
- pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor }"
136
+ pcbridge eval --target editor:<sceneId> --code "return { href: location.href, hasEditor: !!editor }"
137
+ pcbridge launch diagnose --target launch:<sceneId>
69
138
  ```
70
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
+
71
143
  ## Progressive help
72
144
 
73
145
  The CLI exposes layered help so agents can load only the command surface they need:
74
146
 
75
147
  ```bash
76
148
  pcbridge help
149
+ pcbridge help core
150
+ pcbridge help workspace
151
+ pcbridge help frontend
152
+ pcbridge help target
77
153
  pcbridge help entity
78
154
  pcbridge help asset
79
155
  pcbridge help material
@@ -82,71 +158,117 @@ pcbridge help script
82
158
  pcbridge help scene
83
159
  pcbridge help store
84
160
  pcbridge help viewport
161
+ pcbridge help launch
162
+ pcbridge help logs
85
163
  pcbridge help eval
86
164
  ```
87
165
 
88
166
  Use structured commands for small, known operations that map cleanly to one Editor action. Use
89
- `pcbridge eval` for exploratory work, custom Editor/Engine API workflows, and large multi-step
90
- scene edits where one script is clearer and faster than many CLI calls.
167
+ `pcbridge eval` for exploratory work, custom Editor/Engine API workflows, Launch debugging, and
168
+ large multi-step scene edits where one script is clearer and faster than many CLI calls.
91
169
 
92
170
  ## Common commands
93
171
 
94
172
  ```bash
95
- pcbridge entity list --target current --limit 50
96
- pcbridge entity list --target current --tag enemy --component render
97
- pcbridge entity create --target current --json ./entity.json
98
- pcbridge entity create-many --target current --json ./entities.json
99
- pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
100
- pcbridge entity patch-many --target current --json ./edits.json
101
- pcbridge entity duplicate --target current --id <resource_id>
102
- pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
103
- pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
104
- pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
105
- pcbridge entity delete --target current --id <resource_id>
106
-
107
- pcbridge asset list --target current --type script
108
- pcbridge asset list --target current --tag generated
109
- pcbridge asset get --target current --id <asset_id>
110
- pcbridge asset create --target current --json ./assets.json
111
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/Demo/Textures"
112
- pcbridge asset upload --target current --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
113
- pcbridge asset instantiate --target current --id <template_asset_id>
114
- pcbridge asset delete --target current --id <asset_id>
115
-
116
- pcbridge material create --target current --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
117
- pcbridge material patch --target current --asset-id <asset_id> --set diffuse='[1,0,0]'
118
-
119
- pcbridge template create --target current --entity-id <resource_id> --name DemoTemplate --folder "AI Agent Bridge/Demo/Templates"
120
- pcbridge template instantiate --target current --id <template_asset_id>
121
-
122
- pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
123
- pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js
124
- pcbridge script parse --target current --asset-id <asset_id>
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
221
+ pcbridge logs get --target launch:<sceneId> --level error
222
+ pcbridge logs clear --target editor:<sceneId>
223
+ ```
125
224
 
126
- pcbridge scene settings get --target current
127
- pcbridge scene settings patch --target current --set physics.gravity='[0,-9.8,0]'
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
+
238
+ For task-sized installs, keep upload manifests next to the generated files. Relative `file` paths are resolved from the manifest location:
239
+
240
+ ```json
241
+ {
242
+ "assets": [
243
+ {
244
+ "key": "player",
245
+ "file": "final/player.png",
246
+ "name": "DemoPlayer",
247
+ "folder": "AI Agent Bridge/Demo/Textures"
248
+ }
249
+ ]
250
+ }
251
+ ```
128
252
 
129
- pcbridge store search --target current --search vehicle --limit 20
130
- pcbridge store get --target current --id <store_asset_id>
131
- pcbridge store download --target current --id <store_asset_id> --name Vehicle --license-json ./license.json
253
+ Use `eval --args-json` when a large Editor script needs local configuration without embedding JSON into source:
132
254
 
133
- pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
134
- pcbridge viewport focus --target current --id <resource_id> --view perspective
255
+ ```bash
256
+ pcbridge eval --target editor:<sceneId> --file ./install-scene.js --args-json ./install-args.json
135
257
  ```
136
258
 
137
259
  ## Texture + material + script workflow
138
260
 
139
261
  ```bash
140
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/Texture Box/Textures"
141
- 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"
142
264
 
143
- 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>
144
266
 
145
- 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"
146
268
 
147
- pcbridge entity create --target current --json ./box.json
148
- pcbridge entity set-material --target current --id <box_resource_id> --material-id <material_asset_id>
149
- 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}'
150
272
  ```
151
273
 
152
274
  ## Target selection
@@ -157,9 +279,28 @@ pcbridge eval --target current --code "return location.href"
157
279
  pcbridge eval --target tab:123 --code "return location.href"
158
280
  pcbridge eval --target scene:987654 --code "return location.href"
159
281
  pcbridge eval --target project:123456 --code "return location.href"
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 }"
285
+ pcbridge viewport capture --target launch:987654 --out ./tmp/launch.png
286
+ pcbridge logs get --target launch:987654 --limit 100
160
287
  ```
161
288
 
162
- `current` means the most recently seen ready PlayCanvas Editor target.
289
+ `current` means the most recently seen ready PlayCanvas target. If both the Editor and Launch page
290
+ are open for the same scene, use `tab:<id>`, `editor:<sceneId>`, or `launch:<sceneId>` to avoid
291
+ ambiguity. Editor-only structured commands require an Editor target; `eval`, `viewport capture`,
292
+ and `logs` also work on Launch targets.
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.
163
304
 
164
305
  ## Agent skills
165
306
 
@@ -180,15 +321,21 @@ Installed locations:
180
321
  - Cursor: `~/.cursor/rules/playcanvas-agent-bridge-cli.mdc`
181
322
  - Windsurf: `~/.windsurf/rules/playcanvas-agent-bridge-cli.md`
182
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
+
183
328
  ## Security model
184
329
 
185
- This is a local trusted developer tool. It executes JavaScript inside PlayCanvas Editor pages that you already have open.
330
+ This is a local trusted developer tool. It executes JavaScript inside PlayCanvas Editor and Launch pages that you already have open.
186
331
 
187
332
  Safeguards:
188
333
 
189
334
  - daemon binds only to `127.0.0.1`;
335
+ - the frontend server binds only to `127.0.0.1`, validates the Host header, and serves only files
336
+ under the active verified release;
190
337
  - CLI, daemon, and extension share a local session token;
191
- - extension matches only PlayCanvas Editor URLs;
338
+ - extension matches only PlayCanvas Editor and Launch URLs;
192
339
  - CLI output uses compact JSON envelopes;
193
340
  - structured write commands require explicit IDs or JSON files.
194
341
 
@@ -201,3 +348,22 @@ node dist/cli.js doctor
201
348
  ```
202
349
 
203
350
  Use `bun` for one-off TypeScript scripts if you add them.
351
+
352
+ ## Publishing to npm (maintainers)
353
+
354
+ Publishing uses npm Trusted Publishing through `.github/workflows/npm-publish.yml`; the GitHub
355
+ repository does not need an `NPM_TOKEN` secret.
356
+
357
+ 1. Update the same stable version in `package.json`, `src/config.ts`, and
358
+ `extension/manifest.json`.
359
+ 2. Run `pnpm test`, commit the release to `main`, and push `main`.
360
+ 3. Create and push the matching tag, for example:
361
+
362
+ ```bash
363
+ git tag v<version>
364
+ git push origin v<version>
365
+ ```
366
+
367
+ The workflow rejects tags that do not match the package version or whose commit is not on `main`.
368
+ Configure the npm package's Trusted Publisher with GitHub user `Q-My99`, repository
369
+ `playcanvas-agent-bridge-cli`, and workflow filename `npm-publish.yml` before pushing the tag.