playcanvas-agent-bridge-cli 0.3.0 → 0.5.0

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.5.0`. 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,106 @@ 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 # project metadata plus the agent-readable asset catalog
109
+ ├── assets/ # PlayCanvas folder mirror with bidirectional file-content sync
110
+ ├── tmp/ # builds, cache, conflicts, captures, and quarantined remote deletions
111
+ └── .pcbridge/ # internal sync state; 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
+ Scripts, images, models, audio, and other asset files synchronize in both directions. The initial
124
+ mirror downloads project files. Later refreshes read the complete Asset metadata snapshot but reuse
125
+ cached local size/mtime/MD5 values and transfer file content only when it is missing or changed.
126
+ A local-only edit uploads, a remote-only edit downloads, and concurrent edits preserve both text or
127
+ binary copies under `tmp/conflicts/`. Create, move, rename, and delete assets through structured
128
+ pcbridge commands; `workspace pull` remains available for an explicit single-file refresh.
129
+
130
+ `pcbridge.project.json` schema v2 stores every asset id, type, PlayCanvas folder, project-relative
131
+ `assets/...` file path, download presence, and the remote/local/base MD5 values. Agents may read
132
+ this catalog directly; the `assets` object is managed by pcbridge. An existing schema-v1 hidden
133
+ asset index is migrated automatically and retained as `.pcbridge/asset-index.v1.json` for rollback.
134
+ An empty snapshot received while indexed assets exist is ignored, and a non-empty shrinking
135
+ snapshot must repeat before files are moved to `tmp/trash/remote/`.
136
+
137
+ ## Template builds and S3 uploads
138
+
139
+ Selecting a PlayCanvas Template Asset adds a **pcbridge Tiny Builder** section to the Attributes
140
+ panel. **Build and upload to S3** collects recursive Asset references, attached scripts, and child
141
+ Templates in the page. The daemon validates the workspace MD5 cache, downloads only missing or
142
+ remote-updated files, and uploads objects concurrently without creating a ZIP. Generated
143
+ `tinyapp.json` and `gamescript.js` files live under `tmp/builds/`; variants and additional font maps
144
+ are cached under `tmp/cache/assets/`.
145
+
146
+ Create `.env` in the directory where the daemon starts for workspace defaults, or in a project
147
+ directory for per-project values. Project values override workspace values field by field. Do not
148
+ commit credential-bearing `.env` files:
149
+
150
+ ```dotenv
151
+ PCBRIDGE_S3_ENDPOINT=https://s3.example.com
152
+ PCBRIDGE_S3_REGION=us-east-1
153
+ PCBRIDGE_S3_BUCKET=my-bucket
154
+ PCBRIDGE_S3_ACCESS_KEY_ID=your-access-key
155
+ PCBRIDGE_S3_SECRET_ACCESS_KEY=your-secret-key
156
+ # PCBRIDGE_S3_SESSION_TOKEN=
157
+ PCBRIDGE_S3_PUBLIC_BASE_URL=https://cdn.example.com
158
+ PCBRIDGE_S3_PREFIX=assets
159
+ PCBRIDGE_S3_FORCE_PATH_STYLE=false
160
+ ```
161
+
162
+ The implementation uses the standard AWS S3 client and supports Amazon S3, Alibaba OSS, Tencent
163
+ COS, Cloudflare R2, and other compatible providers. Set `PCBRIDGE_S3_FORCE_PATH_STYLE` when the
164
+ provider requires path-style addressing. Builds can also be started and inspected from the CLI:
165
+
166
+ ```bash
167
+ pcbridge builder start --target editor:<sceneId> --asset <templateAssetId> --suffix '-${time}'
168
+ pcbridge builder status --job <jobId>
169
+ ```
170
+
171
+ Script, JSON, upload, and capture paths are restricted to the selected project workspace by default.
172
+ Use `--allow-external-path` only for an intentional external file.
173
+
91
174
  In another terminal:
92
175
 
93
176
  ```bash
94
177
  pcbridge doctor
95
178
  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 }"
179
+ pcbridge eval --target editor:<sceneId> --code "return { href: location.href, hasEditor: !!editor }"
180
+ pcbridge launch diagnose --target launch:<sceneId>
98
181
  ```
99
182
 
183
+ `doctor` distinguishes a missing listener (`DAEMON_NOT_LISTENING`) from a sandbox that blocks
184
+ localhost (`LOOPBACK_ACCESS_DENIED`); only the former means another daemon should be started.
185
+
100
186
  ## Progressive help
101
187
 
102
188
  The CLI exposes layered help so agents can load only the command surface they need:
103
189
 
104
190
  ```bash
105
191
  pcbridge help
192
+ pcbridge help core
193
+ pcbridge help workspace
194
+ pcbridge help builder
106
195
  pcbridge help frontend
196
+ pcbridge help target
107
197
  pcbridge help entity
108
198
  pcbridge help asset
109
199
  pcbridge help material
@@ -124,54 +214,71 @@ large multi-step scene edits where one script is clearer and faster than many CL
124
214
  ## Common commands
125
215
 
126
216
  ```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
217
+ pcbridge entity list --target editor:<sceneId> --limit 50
218
+ pcbridge entity list --target editor:<sceneId> --tag enemy --component render
219
+ pcbridge entity create --target editor:<sceneId> --json ./entity.json
220
+ pcbridge entity create-many --target editor:<sceneId> --json ./entities.json
221
+ pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set position='[0,1,0]'
222
+ pcbridge entity patch-many --target editor:<sceneId> --json ./edits.json
223
+ pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
224
+ pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
225
+ pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
226
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
227
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
228
+ pcbridge entity delete --target editor:<sceneId> --id <resource_id>
229
+
230
+ pcbridge asset list --target editor:<sceneId> --type script
231
+ pcbridge asset list --target editor:<sceneId> --tag generated
232
+ pcbridge asset get --target editor:<sceneId> --id <asset_id>
233
+ pcbridge asset create --target editor:<sceneId> --json ./assets.json
234
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Demo/Textures"
235
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
236
+ pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
237
+ pcbridge asset instantiate --target editor:<sceneId> --id <template_asset_id>
238
+ pcbridge asset delete --target editor:<sceneId> --id <asset_id>
239
+
240
+ pcbridge material create --target editor:<sceneId> --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
241
+ pcbridge material patch --target editor:<sceneId> --asset-id <asset_id> --set diffuse='[1,0,0]'
242
+
243
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name DemoTemplate --folder "AI Agent Bridge/Demo/Templates"
244
+ pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
245
+ pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
246
+ pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
247
+ pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
248
+
249
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
250
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts" --parse --wait
251
+ pcbridge script set-text --target editor:<sceneId> --asset-id <asset_id> --file ./controller.js --parse --wait
252
+ pcbridge script parse --target editor:<sceneId> --asset-id <asset_id>
253
+
254
+ pcbridge scene settings get --target editor:<sceneId>
255
+ pcbridge scene settings patch --target editor:<sceneId> --set physics.gravity='[0,-9.8,0]'
256
+
257
+ pcbridge store search --target editor:<sceneId> --search vehicle --limit 20
258
+ pcbridge store get --target editor:<sceneId> --id <store_asset_id>
259
+ pcbridge store download --target editor:<sceneId> --id <store_asset_id> --name Vehicle --license-json ./license.json
260
+
261
+ pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas-viewport.png
262
+ pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
263
+
264
+ pcbridge logs get --target editor:<sceneId> --limit 100
171
265
  pcbridge logs get --target launch:<sceneId> --level error
172
- pcbridge logs clear --target current
266
+ pcbridge logs clear --target editor:<sceneId>
173
267
  ```
174
268
 
269
+ Use `--script-name` for ScriptTypes registered by a bundle or runtime asset and therefore lacking a
270
+ standalone script asset id. Script update commands with `--parse --wait` verify the uploaded text,
271
+ stable file metadata, and parsed attributes before returning. This completion check covers the
272
+ remote asset and current Editor observer, not a later workspace mirror sync.
273
+
274
+ Template apply commands invoke the Editor's existing `templates:apply` action. When overrides exist,
275
+ completion requires its pipeline callback plus two zero-override observations. A returned `verified`
276
+ value only confirms the current Editor observer; it does not confirm persistence across an Editor
277
+ reload. Editor entity patches are durable: restore preview-only enabled/visibility changes before
278
+ applying a Template. `apply-many` accepts
279
+ `{"entityIds":["root-a","root-b"]}` (or an array of ids or `{ "entityId": "..." }` items), validates
280
+ its manifest first, and applies roots serially.
281
+
175
282
  For task-sized installs, keep upload manifests next to the generated files. Relative `file` paths are resolved from the manifest location:
176
283
 
177
284
  ```json
@@ -190,22 +297,22 @@ For task-sized installs, keep upload manifests next to the generated files. Rela
190
297
  Use `eval --args-json` when a large Editor script needs local configuration without embedding JSON into source:
191
298
 
192
299
  ```bash
193
- pcbridge eval --target current --file ./install-scene.js --args-json ./install-args.json
300
+ pcbridge eval --target editor:<sceneId> --file ./install-scene.js --args-json ./install-args.json
194
301
  ```
195
302
 
196
303
  ## Texture + material + script workflow
197
304
 
198
305
  ```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"
306
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Texture Box/Textures"
307
+ pcbridge asset upload --target editor:<sceneId> --file ./cat.png --name CatTexture --folder "AI Agent Bridge/Texture Box/Textures"
201
308
 
202
- pcbridge material create --target current --name CatMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
309
+ pcbridge material create --target editor:<sceneId> --name CatMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
203
310
 
204
- pcbridge script create --target current --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
311
+ pcbridge script create --target editor:<sceneId> --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
205
312
 
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}'
313
+ pcbridge entity create --target editor:<sceneId> --json ./box.json
314
+ pcbridge entity set-material --target editor:<sceneId> --id <box_resource_id> --material-id <material_asset_id>
315
+ pcbridge entity add-script --target editor:<sceneId> --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
209
316
  ```
210
317
 
211
318
  ## Target selection
@@ -216,7 +323,9 @@ pcbridge eval --target current --code "return location.href"
216
323
  pcbridge eval --target tab:123 --code "return location.href"
217
324
  pcbridge eval --target scene:987654 --code "return location.href"
218
325
  pcbridge eval --target project:123456 --code "return location.href"
219
- pcbridge eval --target launch:987654 --code "return { href: location.href, hasPc: !!pc }"
326
+ pcbridge launch diagnose --target launch:987654
327
+ pcbridge launch wait-ready --target launch:987654 --focus --timeout-ms 30000
328
+ pcbridge eval --target launch:987654 --code "return { runtimeCreated: !!runtimeApp, rootChildCount: runtimeApp?.root?.children?.length ?? 0 }"
220
329
  pcbridge viewport capture --target launch:987654 --out ./tmp/launch.png
221
330
  pcbridge logs get --target launch:987654 --limit 100
222
331
  ```
@@ -226,6 +335,17 @@ are open for the same scene, use `tab:<id>`, `editor:<sceneId>`, or `launch:<sce
226
335
  ambiguity. Editor-only structured commands require an Editor target; `eval`, `viewport capture`,
227
336
  and `logs` also work on Launch targets.
228
337
 
338
+ Launch readiness is a best-effort heuristic, not an Engine lifecycle event. `lifecycleReady`
339
+ requires a runtime app with its own graphics canvas/context, an attached scene root, and at least
340
+ one completed frame, with no recognized splash. Target `ready` additionally requires the tab to be
341
+ visible, so use `launch wait-ready --focus` for a hidden Launch tab. `scriptTypeCount` is diagnostic
342
+ only and does not prove every ScriptType has registered. Eval receives a compatibility-resolved
343
+ `runtimeApp` binding for Engine V1 and V2.
344
+
345
+ `viewport capture` records the current canvas; it does not resize Chrome or emulate a mobile DPR.
346
+ PNG can preserve transparency; the default `--max-width 1200` can downscale output. Eval output is bounded; use a
347
+ leaf projection first, then bounded `--max-depth`, `--max-items`, or `--max-keys` if needed.
348
+
229
349
  ## Agent skills
230
350
 
231
351
  Install rules/skills for common agents:
@@ -245,6 +365,10 @@ Installed locations:
245
365
  - Cursor: `~/.cursor/rules/playcanvas-agent-bridge-cli.mdc`
246
366
  - Windsurf: `~/.windsurf/rules/playcanvas-agent-bridge-cli.md`
247
367
 
368
+ The extension popup shows daemon and current-tab connectivity, project/scene/branch identity,
369
+ workspace path and sync counts, conflicts, and custom Editor frontend state. Red means disconnected
370
+ or conflicted, yellow means initializing/syncing/local attention, and green means ready/synced.
371
+
248
372
  ## Security model
249
373
 
250
374
  This is a local trusted developer tool. It executes JavaScript inside PlayCanvas Editor and Launch pages that you already have open.
@@ -280,8 +404,8 @@ repository does not need an `NPM_TOKEN` secret.
280
404
  3. Create and push the matching tag, for example:
281
405
 
282
406
  ```bash
283
- git tag v0.3.0
284
- git push origin v0.3.0
407
+ git tag v<version>
408
+ git push origin v<version>
285
409
  ```
286
410
 
287
411
  The workflow rejects tags that do not match the package version or whose commit is not on `main`.