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
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  name: playcanvas-agent-bridge-cli
3
- description: Control an already-open PlayCanvas Editor scene through the pcbridge CLI and Chrome extension. Use when Codex needs to inspect or modify PlayCanvas Editor targets, entities, assets, scripts, scene data, or viewport captures without DevTools, mouse/keyboard automation, MCP, or browser console scripting.
3
+ description: Control an already-open PlayCanvas Editor scene or Launch page and manage the optional custom Editor frontend through the pcbridge CLI and Chrome extension. Use when Codex needs to inspect or modify PlayCanvas Editor targets, debug Launch runtime pages, read logs, run eval snippets, capture viewports, or install and select a published Editor frontend without DevTools, mouse/keyboard automation, MCP, or browser console scripting.
4
4
  ---
5
5
 
6
6
  # PlayCanvas Agent Bridge CLI
7
7
 
8
- Use `pcbridge` to automate PlayCanvas Editor through a local daemon and Chrome extension. The CLI is the interface; this skill only tells the agent how to use it safely.
8
+ Use `pcbridge` to automate PlayCanvas Editor and PlayCanvas Launch pages through a local daemon and Chrome extension. The CLI is the interface; this skill only tells the agent how to use it safely.
9
9
 
10
10
  ## Quick Start
11
11
 
@@ -17,102 +17,184 @@ pcbridge daemon status
17
17
  pcbridge targets
18
18
  ```
19
19
 
20
- If the daemon is offline, tell the user to run this in a separate terminal:
20
+ If `doctor` reports `DAEMON_NOT_LISTENING`, tell the user to run this in a separate terminal:
21
21
 
22
22
  ```bash
23
23
  pcbridge daemon start
24
24
  ```
25
25
 
26
- If no target appears, tell the user to run `pcbridge install-extension`, load the printed directory in `chrome://extensions`, then refresh the PlayCanvas Editor tab.
26
+ Do not start a second daemon for `LOOPBACK_ACCESS_DENIED`. That means the current execution
27
+ environment cannot access `127.0.0.1`; retry with local-loopback permission instead.
28
+
29
+ The directory where `pcbridge daemon start` runs is the workspace root. Choose it intentionally;
30
+ each connected Editor project is mirrored into `<projectId>-<projectName>/` below that directory.
31
+
32
+ If no target appears, tell the user to run `pcbridge install-extension`, load the printed directory in `chrome://extensions`, then refresh the PlayCanvas Editor or Launch tab.
33
+
34
+ For the optional custom Editor frontend, use `pcbridge frontend install latest`, confirm
35
+ `pcbridge frontend status`, then use the extension popup to switch between custom and official
36
+ frontend modes. Load focused help with `pcbridge help frontend`.
37
+ The popup remembers that choice per PlayCanvas project and applies it automatically on later
38
+ project-picker and scene Editor navigations; change the remembered mode only through the popup.
27
39
 
28
40
  ## Workflow
29
41
 
30
- 1. Run `pcbridge targets` and choose an explicit target when possible.
31
- 2. Use layered help to load only the command group you need: `pcbridge help`, then `pcbridge help entity|asset|material|template|script|scene|store|viewport|eval`.
32
- 3. Use structured commands for small, known operations that map cleanly to one Editor action.
33
- 4. Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, and large multi-step scene edits where one script is clearer than many CLI calls.
34
- 5. Return compact JSON from snippets. Never return raw `editor`, `Entity`, `Asset`, `entities.root`, or app objects.
35
- 6. Use PlayCanvas history options for writes when available.
36
- 7. Verify writes with a read-only command after mutation.
42
+ 1. Run `pcbridge targets`. Use `editor:<sceneId>` for Editor writes and `launch:<sceneId>` for
43
+ runtime verification; use `tab:<id>` when either selector is ambiguous.
44
+ 2. Run `pcbridge workspace status --target editor:<sceneId>`. Do not write while it reports a conflict or sync error.
45
+ 3. Use layered help to load only the command group you need: `pcbridge help`, then `pcbridge help core|workspace|frontend|target|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
46
+ 4. Keep temporary scripts, JSON manifests, uploads, and captures inside the selected project workspace.
47
+ 5. Use structured commands for small, known operations that map cleanly to one Editor action.
48
+ 6. Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, Launch runtime debugging, and large multi-step scene edits where one script is clearer than many CLI calls.
49
+ 7. Return compact JSON from snippets. Never return raw `editor`, `Entity`, `Asset`, `entities.root`, or app objects.
50
+ 8. Use PlayCanvas history options for writes when available and verify writes with a read-only command.
51
+
52
+ ## Workspace
53
+
54
+ ```text
55
+ <workspace root>/<projectId>-<projectName>/
56
+ pcbridge.project.json
57
+ assets/ # PlayCanvas folder tree; scripts synchronize automatically
58
+ tmp/ # task scripts, manifests, captures, and conflict copies
59
+ .pcbridge/ # internal index and sync state; do not edit
60
+ ```
61
+
62
+ Use:
63
+
64
+ ```bash
65
+ pcbridge workspace status --target editor:<sceneId>
66
+ pcbridge workspace path --target editor:<sceneId>
67
+ pcbridge workspace sync --target editor:<sceneId>
68
+ pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
69
+ ```
70
+
71
+ Existing script contents synchronize in both directions. Create, move, rename, and delete assets
72
+ through structured pcbridge commands; do not perform structural changes by moving or deleting
73
+ mirrored local files. Non-script files are indexed but downloaded only with `workspace pull`.
74
+
75
+ Local file arguments are restricted to the selected project workspace. Never use
76
+ `--allow-external-path` unless the user explicitly asks to use a known external file.
37
77
 
38
78
  ## Safe Commands
39
79
 
40
80
  Inspect a scene:
41
81
 
42
82
  ```bash
43
- pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor, entityCount: editor.api.globals.entities.list().length }"
83
+ pcbridge eval --target editor:<sceneId> --code "return { href: location.href, hasEditor: !!editor, entityCount: editor.api.globals.entities.list().length }"
44
84
  ```
45
85
 
46
86
  List entities:
47
87
 
48
88
  ```bash
49
- pcbridge entity list --target current --limit 50
50
- pcbridge entity list --target scene:<sceneId> --name Player --component render
51
- pcbridge entity list --target current --tag enemy
89
+ pcbridge entity list --target editor:<sceneId> --limit 50
90
+ pcbridge entity list --target editor:<sceneId> --name Player --component render
91
+ pcbridge entity list --target editor:<sceneId> --tag enemy
52
92
  ```
53
93
 
54
94
  Create an entity from JSON:
55
95
 
56
96
  ```bash
57
- pcbridge entity create --target current --json ./entity.json
58
- pcbridge entity create-many --target current --json ./entities.json
97
+ pcbridge entity create --target editor:<sceneId> --json ./entity.json
98
+ pcbridge entity create-many --target editor:<sceneId> --json ./entities.json
59
99
  ```
60
100
 
61
101
  Patch an entity:
62
102
 
63
103
  ```bash
64
- pcbridge entity patch --target current --id <resource_id> --set name=Player --set position='[0,1,0]'
65
- pcbridge entity patch-many --target current --json ./edits.json
66
- pcbridge entity duplicate --target current --id <resource_id>
67
- pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
104
+ pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set name=Player --set position='[0,1,0]'
105
+ pcbridge entity patch-many --target editor:<sceneId> --json ./edits.json
106
+ pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
107
+ pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
68
108
  ```
69
109
 
70
110
  Modify components and materials:
71
111
 
72
112
  ```bash
73
- pcbridge entity add-component --target current --id <resource_id> --component render --data '{"type":"box"}'
74
- pcbridge entity add-components --target current --id <resource_id> --json ./components.json
75
- pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
76
- pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
77
- pcbridge entity delete --target current --id <resource_id>
113
+ pcbridge entity add-component --target editor:<sceneId> --id <resource_id> --component render --data '{"type":"box"}'
114
+ pcbridge entity add-components --target editor:<sceneId> --id <resource_id> --json ./components.json
115
+ pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
116
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
117
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
118
+ pcbridge entity delete --target editor:<sceneId> --id <resource_id>
78
119
  ```
79
120
 
121
+ Use exactly one of `--asset-id` and `--script-name`. The name form is for a ScriptType registered
122
+ by a bundle or runtime asset and therefore lacking a standalone script asset id. Verify such a
123
+ script in Launch; explicit script reordering is not yet a dedicated command.
124
+
80
125
  Work with assets and scripts:
81
126
 
82
127
  ```bash
83
- pcbridge asset list --target current --type script --limit 50
84
- pcbridge asset create --target current --json ./assets.json
85
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/My Task/Textures"
86
- pcbridge asset upload --target current --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
87
- pcbridge asset instantiate --target current --id <template_asset_id>
88
- pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
89
- pcbridge material patch --target current --asset-id <material_asset_id> --set diffuse='[1,0,0]'
90
- pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
91
- pcbridge template instantiate --target current --id <template_asset_id>
92
- pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts"
93
- pcbridge script set-text --target current --asset-id <id> --file ./controller.js
94
- pcbridge script parse --target current --asset-id <id>
128
+ pcbridge asset list --target editor:<sceneId> --type script --limit 50
129
+ pcbridge asset create --target editor:<sceneId> --json ./assets.json
130
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
131
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
132
+ pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
133
+ pcbridge asset instantiate --target editor:<sceneId> --id <template_asset_id>
134
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
135
+ pcbridge material patch --target editor:<sceneId> --asset-id <material_asset_id> --set diffuse='[1,0,0]'
136
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
137
+ pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
138
+ pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
139
+ pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
140
+ pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
141
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
142
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts"
143
+ pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./controller.js --parse --wait
144
+ pcbridge script parse --target editor:<sceneId> --asset-id <id>
95
145
  ```
96
146
 
147
+ `template-roots.json` may be `{"entityIds":["root-a","root-b"]}` or an array of entity ids/items.
148
+ `apply-many` validates every root before writing and processes them serially. When an apply is
149
+ needed, completion requires the pipeline callback plus two zero-override observations. `verified`
150
+ only covers the current Editor observer; it does not confirm persistence across an Editor reload.
151
+
152
+ Prefer the completion-checked `--parse --wait` forms after edits. They wait for non-empty stable
153
+ file metadata, verify the remote text, parse it, and read back stable script attributes before
154
+ returning. They do not wait for the workspace mirror to finish a later sync.
155
+
97
156
  Scene, store, and viewport:
98
157
 
99
158
  ```bash
100
- pcbridge scene settings get --target current
101
- pcbridge scene settings patch --target current --json ./scene-settings.json
102
- pcbridge store search --target current --search vehicle --limit 20
103
- pcbridge store get --target current --id <store_asset_id>
104
- pcbridge viewport focus --target current --id <resource_id> --view perspective
159
+ pcbridge scene settings get --target editor:<sceneId>
160
+ pcbridge scene settings patch --target editor:<sceneId> --json ./scene-settings.json
161
+ pcbridge store search --target editor:<sceneId> --search vehicle --limit 20
162
+ pcbridge store get --target editor:<sceneId> --id <store_asset_id>
163
+ pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
105
164
  ```
106
165
 
107
166
  Capture the viewport:
108
167
 
109
168
  ```bash
110
- pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
169
+ pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas-viewport.png
111
170
  ```
112
171
 
172
+ Launch runtime debugging:
173
+
174
+ ```bash
175
+ pcbridge launch diagnose --target launch:<sceneId>
176
+ pcbridge launch wait-ready --target launch:<sceneId> --focus --timeout-ms 30000
177
+ pcbridge eval --target launch:<sceneId> --code "return { href: location.href, runtimeCreated: !!runtimeApp, rootChildCount: runtimeApp?.root?.children?.length ?? 0 }"
178
+ pcbridge viewport capture --target launch:<sceneId> --out ./tmp/launch.png
179
+ pcbridge logs get --target launch:<sceneId> --limit 100
180
+ pcbridge logs get --target launch:<sceneId> --level error
181
+ ```
182
+
183
+ For Launch, `lifecycleReady` is a best-effort heuristic requiring a runtime app with its own
184
+ graphics canvas/context, an attached scene root, at least one completed frame, and no recognized
185
+ startup splash. Target `ready` additionally requires a visible tab, so use `target focus` or
186
+ `launch wait-ready --focus` for a hidden Launch. These are diagnostic signals, not Engine lifecycle
187
+ events; custom splash screens may be missed. `scriptTypeCount` is diagnostic only. Use the resolved
188
+ `runtimeApp` eval binding instead of calling `Application.getApplication()` yourself.
189
+
190
+ `viewport capture` records the current canvas. It does not emulate a phone viewport or DPR. PNG
191
+ may preserve transparency, and the default `--max-width 1200` may downscale the output; use returned dimensions as
192
+ authoritative.
193
+
113
194
  ## Asset Organization
114
195
 
115
- Create task-scoped folders before uploading generated assets:
196
+ Create task-scoped remote folders before uploading generated assets. Keep local generated files
197
+ under the project `tmp/` directory until they are uploaded:
116
198
 
117
199
  ```text
118
200
  AI Agent Bridge/<task name>/Textures
@@ -122,18 +204,46 @@ AI Agent Bridge/<task name>/Scripts
122
204
 
123
205
  Use stable names that describe the asset purpose. Avoid dumping generated files at the project root.
124
206
 
207
+ ## Large Task Workflow
208
+
209
+ For multi-asset or game-sized tasks:
210
+
211
+ 1. Choose an explicit target from `pcbridge targets`, preferably `editor:<sceneId>` for writes or
212
+ `launch:<sceneId>` for tests; use `tab:<id>` to resolve ambiguity.
213
+ 2. Confirm `workspace status`, then create task files under `<project>/tmp/<task name>/`.
214
+ 3. Put PlayCanvas assets under `AI Agent Bridge/<task name>/{Textures,Materials,Scripts,Templates}`.
215
+ 4. Use `pcbridge asset upload-many --json ./upload-manifest.json` for batches. In the manifest, each item needs `file` and may include `key`, `name`, `filename`, `type`, `mime`, `folder`, `folderId`, and `preload`. Relative `file` paths resolve from the manifest file; `key` is returned for later argument mapping but is not sent to PlayCanvas.
216
+ 5. Use `pcbridge script upsert --target editor:<sceneId> --filename <name>.js --file ./script.js --folder "AI Agent Bridge/<task name>/Scripts" --parse --wait` for repeatable script creation or update.
217
+ 6. Use `pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./args.json --timeout-ms 120000` for large scene installation scripts. The JSON object is available as `command.args`; increase `--timeout-ms` instead of splitting a coherent install script just to avoid the default 15s timeout.
218
+ 7. Verify with read-only commands, a small smoke-test eval, and a capture under `<project>/tmp/captures/`.
219
+
220
+ If repeated manual glue is needed across tasks, improve the CLI or this skill rather than continuing to hand-roll brittle shell/script sequences.
221
+
222
+ ## Editor Entity Persistence Notes
223
+
224
+ Do not pre-place runtime-generated content just to prove a game exists. For roguelike maps, procedural levels, particles, pickups, and enemies that are generated at launch, keep the durable Editor surface small: a root entity, script component, camera/light helpers when useful, and persistent assets/scripts.
225
+
226
+ When Editor entities do need to be created or replaced, prefer structured commands such as `entity create`, `entity create-many`, `entity add-script`, `entity set-material`, and `entity patch-many`. In current PlayCanvas Editor builds, a large `eval` script that creates many entities in a tight loop can briefly show objects in the viewport and then lose them from the Editor data model. For large static previews, create in small batches, pause between batches when needed, then immediately verify with `entity list` by name/tag before capturing the viewport.
227
+
228
+ Editor entity patches are durable scene edits, not runtime-only preview state. Never apply a
229
+ Template while preview-only `enabled` or visibility changes remain on its source root. Restore and
230
+ read back the original preview values first, then run `template overrides` and `template apply`.
231
+ Prefer Launch eval for temporary runtime test state. `template apply` warns when the override set
232
+ contains an `enabled` change and waits until overrides are stably zero.
233
+ That verification is limited to the current Editor observer and does not prove reload persistence.
234
+
125
235
  ## Texture Box Pattern
126
236
 
127
237
  For a textured scripted box, compose structured commands instead of writing one large eval:
128
238
 
129
239
  ```bash
130
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/Texture Box/Textures"
131
- pcbridge asset upload --target current --file ./image.png --name TextureBoxImage --folder "AI Agent Bridge/Texture Box/Textures"
132
- pcbridge material create --target current --name TextureBoxMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
133
- pcbridge script create --target current --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
134
- pcbridge entity create --target current --json ./box.json
135
- pcbridge entity set-material --target current --id <box_resource_id> --material-id <material_asset_id>
136
- pcbridge entity add-script --target current --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
240
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Texture Box/Textures"
241
+ pcbridge asset upload --target editor:<sceneId> --file ./image.png --name TextureBoxImage --folder "AI Agent Bridge/Texture Box/Textures"
242
+ pcbridge material create --target editor:<sceneId> --name TextureBoxMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
243
+ pcbridge script create --target editor:<sceneId> --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
244
+ pcbridge entity create --target editor:<sceneId> --json ./box.json
245
+ pcbridge entity set-material --target editor:<sceneId> --id <box_resource_id> --material-id <material_asset_id>
246
+ pcbridge entity add-script --target editor:<sceneId> --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
137
247
  ```
138
248
 
139
249
  ## Eval Snippet Rules
@@ -144,12 +254,17 @@ The snippet runs inside an async function with these bindings:
144
254
  editor;
145
255
  pc;
146
256
  pcui;
257
+ runtimeApp;
147
258
  window;
148
259
  document;
149
260
  command;
150
261
  serialize;
151
262
  ```
152
263
 
264
+ The final bridge serialization is bounded even when `--full` is used. Return only required leaf
265
+ fields. If a compact projection still contains `[MaxDepth ...]`, use bounded eval options such as
266
+ `--max-depth 8 --max-items 500`; do not return raw Editor or runtime objects.
267
+
153
268
  Prefer:
154
269
 
155
270
  ```js
@@ -1,4 +1,4 @@
1
1
  interface:
2
2
  display_name: "PlayCanvas Agent Bridge"
3
- short_description: "Control open PlayCanvas Editor scenes through pcbridge."
4
- default_prompt: "Use pcbridge to inspect or edit the open PlayCanvas Editor scene."
3
+ short_description: "Control open PlayCanvas Editor and Launch pages through pcbridge."
4
+ default_prompt: "Use pcbridge to inspect or edit the open PlayCanvas Editor scene, or debug the matching Launch page."
@@ -1,10 +1,10 @@
1
1
  ---
2
- description: Use pcbridge to control open PlayCanvas Editor tabs from Cursor.
2
+ description: Use pcbridge to control open PlayCanvas Editor and Launch tabs from Cursor.
3
3
  globs:
4
4
  alwaysApply: false
5
5
  ---
6
6
 
7
- Use `pcbridge` for PlayCanvas Editor automation. Do not use DevTools, mouse/keyboard browser automation, or raw console typing.
7
+ Use `pcbridge` for PlayCanvas Editor automation and PlayCanvas Launch runtime debugging. Do not use DevTools, mouse/keyboard browser automation, or raw console typing.
8
8
 
9
9
  Setup checks:
10
10
 
@@ -14,33 +14,73 @@ pcbridge daemon status
14
14
  pcbridge targets
15
15
  ```
16
16
 
17
- If needed, ask the user to run `pcbridge daemon start`. If no target appears, ask them to run `pcbridge install-extension`, load the printed extension directory in `chrome://extensions`, and refresh PlayCanvas Editor.
17
+ Run `pcbridge daemon start` only for `DAEMON_NOT_LISTENING`; for `LOOPBACK_ACCESS_DENIED`, retry
18
+ with local-loopback permission. If no target appears, ask the user to install/reload the extension.
18
19
 
19
- Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help entity|asset|material|template|script|scene|store|viewport|eval`.
20
+ The daemon start directory is the workspace root. After selecting an explicit target, run
21
+ `pcbridge workspace status --target editor:<sceneId>` and do not write while it reports a conflict
22
+ or sync error. Project files live under `<projectId>-<projectName>/{assets,tmp}`. Existing scripts
23
+ sync automatically; other files are lazy until
24
+ `pcbridge workspace pull --target editor:<sceneId> --asset <id>`.
25
+
26
+ For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
27
+ `pcbridge frontend status`, and switch custom/official mode from the extension popup.
28
+ The popup remembers that choice per project and reapplies it on later project-picker and scene
29
+ Editor navigations; change the remembered choice only through the popup.
30
+
31
+ Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help target|workspace|frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
20
32
 
21
33
  Use structured commands for small, known Editor operations:
22
34
 
23
35
  ```bash
24
- pcbridge entity list --target current --limit 50
25
- pcbridge entity patch --target current --id <resource_id> --set name=Player
26
- pcbridge entity duplicate --target current --id <resource_id>
27
- pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
28
- pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
29
- pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
30
- pcbridge asset list --target current --type script
31
- pcbridge asset create --target current --json ./assets.json
32
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/My Task/Textures"
33
- pcbridge asset upload --target current --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
34
- pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
35
- pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
36
- pcbridge template instantiate --target current --id <template_asset_id>
37
- pcbridge scene settings get --target current
38
- pcbridge viewport focus --target current --id <resource_id> --view perspective
39
- pcbridge script create --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
40
- pcbridge script set-text --target current --asset-id <id> --file ./script.js
41
- pcbridge viewport capture --target current --out ./tmp/playcanvas.png
36
+ pcbridge entity list --target editor:<sceneId> --limit 50
37
+ pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set name=Player
38
+ pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
39
+ pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
40
+ pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
41
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
42
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
43
+ pcbridge asset list --target editor:<sceneId> --type script
44
+ pcbridge asset create --target editor:<sceneId> --json ./assets.json
45
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
46
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
47
+ pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
48
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
49
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
50
+ pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
51
+ pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
52
+ pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
53
+ pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
54
+ pcbridge scene settings get --target editor:<sceneId>
55
+ pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
56
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
57
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
58
+ pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
59
+ pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
60
+ pcbridge logs get --target launch:<sceneId> --limit 100
61
+ pcbridge logs get --target launch:<sceneId> --level error
42
62
  ```
43
63
 
44
64
  Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
45
65
 
46
- Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, and large multi-step scene edits. Snippets run with `editor`, `pc`, `pcui`, `window`, `document`, `command`, and `serialize`. Return compact JSON; never return raw `editor`, `Entity`, `Asset`, or app objects.
66
+ Use `pcbridge launch diagnose` and `pcbridge launch wait-ready --focus` before runtime assertions.
67
+ Launch `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context,
68
+ attached scene root, a completed frame, and known splash selectors; target `ready` also requires a
69
+ visible tab. These are not Engine lifecycle events, and script type count is diagnostic only. Eval
70
+ snippets include compatibility-resolved `runtimeApp` plus `editor`, `pc`, `pcui`, `window`, `document`,
71
+ `command`, and `serialize`; never return raw app objects. Use bounded `--max-depth`/`--max-items`
72
+ only after projecting required fields.
73
+
74
+ For Launch runtime debugging, target `launch:<sceneId>` or `tab:<id>` and use `pcbridge eval`, `pcbridge viewport capture`, and `pcbridge logs get`. Editor-only structured entity/asset/script commands require an Editor target.
75
+
76
+ Use `editor:<sceneId>` for writes. Use `--script-name` for bundle-registered ScriptTypes. Editor
77
+ patches are durable, so restore preview-only enabled/visibility changes before Template apply.
78
+ Template `verified` covers current Editor overrides, not persistence across a reload. Script
79
+ `--parse --wait` completion checks do not wait for the workspace mirror's later sync.
80
+ Capture does not focus/resize/emulate a mobile viewport and defaults to `--max-width 1200`; use returned dimensions as authoritative.
81
+
82
+ For large eval installs, use `pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./install-args.json --timeout-ms 120000`.
83
+
84
+ For large tasks, choose an explicit target from `pcbridge targets`, keep generated files and captures under the project `tmp/` directory, upload batches with `asset upload-many`, edit tracked scripts under `assets/`, and capture the viewport after smoke tests. File arguments must remain inside the workspace; never use `--allow-external-path` without explicit user approval. If repeated manual glue appears, improve the CLI or this rule.
85
+
86
+ Do not pre-place runtime-generated content just to prove a game exists. Keep procedural maps, pickups, enemies, and VFX in the runtime script, with only a small durable Editor root and helper entities when needed. If Editor entities must be created, use structured commands and small `entity create-many` batches with read-back verification; large eval scripts that create many entities in a tight loop can briefly show objects and then lose them from the Editor data model.
@@ -1,6 +1,6 @@
1
1
  # PlayCanvas Agent Bridge CLI
2
2
 
3
- Use `pcbridge` to automate an already-open PlayCanvas Editor tab through the local daemon and Chrome extension.
3
+ Use `pcbridge` to automate an already-open PlayCanvas Editor tab or debug a PlayCanvas Launch tab through the local daemon and Chrome extension.
4
4
 
5
5
  Start with:
6
6
 
@@ -10,34 +10,72 @@ pcbridge daemon status
10
10
  pcbridge targets
11
11
  ```
12
12
 
13
- If the daemon is offline, ask the user to run `pcbridge daemon start`. If no target is connected, ask the user to run `pcbridge install-extension`, load the printed unpacked extension path in `chrome://extensions`, and refresh the Editor tab.
13
+ Run `pcbridge daemon start` only for `DAEMON_NOT_LISTENING`; for `LOOPBACK_ACCESS_DENIED`, retry
14
+ with local-loopback permission. If no target is connected, install/reload the unpacked extension.
14
15
 
15
- Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help entity|asset|material|template|script|scene|store|viewport|eval`.
16
+ The daemon start directory is the workspace root. After selecting an explicit target, run
17
+ `pcbridge workspace status --target editor:<sceneId>` and stop if it reports a conflict or sync
18
+ error. Each project is mirrored under `<projectId>-<projectName>/{assets,tmp}`. Script content syncs
19
+ both ways; other asset files are lazy until explicitly pulled.
20
+
21
+ For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
22
+ `pcbridge frontend status`, and switch custom/official mode from the extension popup.
23
+ The popup remembers that choice per project and reapplies it on later project-picker and scene
24
+ Editor navigations; change the remembered choice only through the popup.
25
+
26
+ Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help target|workspace|frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
16
27
 
17
28
  Use structured commands for small, known Editor operations:
18
29
 
19
30
  ```bash
20
- pcbridge entity list --target current --limit 50
21
- pcbridge entity create --target current --json ./entity.json
22
- pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
23
- pcbridge entity duplicate --target current --id <resource_id>
24
- pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
25
- pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
26
- pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
27
- pcbridge asset list --target current --type script
28
- pcbridge asset create --target current --json ./assets.json
29
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/My Task/Textures"
30
- pcbridge asset upload --target current --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
31
- pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
32
- pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
33
- pcbridge template instantiate --target current --id <template_asset_id>
34
- pcbridge scene settings get --target current
35
- pcbridge viewport focus --target current --id <resource_id> --view perspective
36
- pcbridge script create --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
37
- pcbridge script set-text --target current --asset-id <id> --file ./script.js
38
- pcbridge viewport capture --target current --out ./tmp/playcanvas.png
31
+ pcbridge entity list --target editor:<sceneId> --limit 50
32
+ pcbridge entity create --target editor:<sceneId> --json ./entity.json
33
+ pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set position='[0,1,0]'
34
+ pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
35
+ pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
36
+ pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
37
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
38
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
39
+ pcbridge asset list --target editor:<sceneId> --type script
40
+ pcbridge asset create --target editor:<sceneId> --json ./assets.json
41
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
42
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
43
+ pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
44
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
45
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
46
+ pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
47
+ pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
48
+ pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
49
+ pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
50
+ pcbridge scene settings get --target editor:<sceneId>
51
+ pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
52
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
53
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
54
+ pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
55
+ pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
56
+ pcbridge logs get --target launch:<sceneId> --limit 100
57
+ pcbridge logs get --target launch:<sceneId> --level error
39
58
  ```
40
59
 
41
60
  Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
42
61
 
43
- Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, and large multi-step scene edits. Return compact JSON and never return raw PlayCanvas Editor objects. Use history-enabled mutations when available and verify writes with a read-only command.
62
+ Use `pcbridge launch diagnose` and `pcbridge launch wait-ready --focus` before runtime assertions.
63
+ Launch `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context,
64
+ attached scene root, a completed frame, and known splash selectors; target `ready` also requires a
65
+ visible tab. These are not Engine lifecycle events, and script type count is diagnostic only. Eval
66
+ includes compatibility-resolved `runtimeApp` for Engine V1/V2 plus the existing Editor bindings. Return compact
67
+ JSON; use bounded `--max-depth`/`--max-items` only when a leaf projection is insufficient.
68
+
69
+ For Launch runtime debugging, target `launch:<sceneId>` or `tab:<id>` and use `pcbridge eval`, `pcbridge viewport capture`, and `pcbridge logs get`. Editor-only structured entity/asset/script commands require an Editor target.
70
+
71
+ Use `editor:<sceneId>` for writes and `--script-name` for bundle-registered ScriptTypes. Editor
72
+ patches are durable, so restore preview-only enabled/visibility changes before Template apply.
73
+ Template `verified` covers current Editor overrides, not persistence across a reload. Script
74
+ `--parse --wait` completion checks do not wait for the workspace mirror's later sync.
75
+ Capture records the current canvas, defaults to `--max-width 1200`, and does not emulate a mobile viewport or DPR.
76
+
77
+ For large eval installs, use `pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./install-args.json --timeout-ms 120000`.
78
+
79
+ For large tasks, choose an explicit target from `pcbridge targets`, keep generated files and captures under the project `tmp/` directory, upload batches with `asset upload-many`, edit tracked scripts under `assets/`, and capture the viewport after smoke tests. Local file arguments must remain inside the workspace; never use `--allow-external-path` without explicit user approval. If repeated manual glue appears, improve the CLI or this rule.
80
+
81
+ Do not pre-place runtime-generated content just to prove a game exists. Keep procedural maps, pickups, enemies, and VFX in the runtime script, with only a small durable Editor root and helper entities when needed. If Editor entities must be created, use structured commands and small `entity create-many` batches with read-back verification; large eval scripts that create many entities in a tight loop can briefly show objects and then lose them from the Editor data model.