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.
@@ -17,117 +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
+ 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
+
26
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.
27
33
 
28
34
  For the optional custom Editor frontend, use `pcbridge frontend install latest`, confirm
29
35
  `pcbridge frontend status`, then use the extension popup to switch between custom and official
30
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.
31
39
 
32
40
  ## Workflow
33
41
 
34
- 1. Run `pcbridge targets` and choose an explicit target when possible.
35
- 2. Use layered help to load only the command group you need: `pcbridge help`, then `pcbridge help frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
36
- 3. Use structured commands for small, known operations that map cleanly to one Editor action.
37
- 4. 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.
38
- 5. Return compact JSON from snippets. Never return raw `editor`, `Entity`, `Asset`, `entities.root`, or app objects.
39
- 6. Use PlayCanvas history options for writes when available.
40
- 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.
41
77
 
42
78
  ## Safe Commands
43
79
 
44
80
  Inspect a scene:
45
81
 
46
82
  ```bash
47
- 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 }"
48
84
  ```
49
85
 
50
86
  List entities:
51
87
 
52
88
  ```bash
53
- pcbridge entity list --target current --limit 50
54
- pcbridge entity list --target scene:<sceneId> --name Player --component render
55
- 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
56
92
  ```
57
93
 
58
94
  Create an entity from JSON:
59
95
 
60
96
  ```bash
61
- pcbridge entity create --target current --json ./entity.json
62
- 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
63
99
  ```
64
100
 
65
101
  Patch an entity:
66
102
 
67
103
  ```bash
68
- pcbridge entity patch --target current --id <resource_id> --set name=Player --set position='[0,1,0]'
69
- pcbridge entity patch-many --target current --json ./edits.json
70
- pcbridge entity duplicate --target current --id <resource_id>
71
- 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>
72
108
  ```
73
109
 
74
110
  Modify components and materials:
75
111
 
76
112
  ```bash
77
- pcbridge entity add-component --target current --id <resource_id> --component render --data '{"type":"box"}'
78
- pcbridge entity add-components --target current --id <resource_id> --json ./components.json
79
- pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
80
- pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
81
- 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>
82
119
  ```
83
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
+
84
125
  Work with assets and scripts:
85
126
 
86
127
  ```bash
87
- pcbridge asset list --target current --type script --limit 50
88
- pcbridge asset create --target current --json ./assets.json
89
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/My Task/Textures"
90
- pcbridge asset upload --target current --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
91
- pcbridge asset upload-many --target current --json ./upload-manifest.json
92
- pcbridge asset instantiate --target current --id <template_asset_id>
93
- pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
94
- pcbridge material patch --target current --asset-id <material_asset_id> --set diffuse='[1,0,0]'
95
- pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
96
- pcbridge template instantiate --target current --id <template_asset_id>
97
- pcbridge script upsert --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts" --parse
98
- pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts"
99
- pcbridge script set-text --target current --asset-id <id> --file ./controller.js
100
- 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>
101
145
  ```
102
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
+
103
156
  Scene, store, and viewport:
104
157
 
105
158
  ```bash
106
- pcbridge scene settings get --target current
107
- pcbridge scene settings patch --target current --json ./scene-settings.json
108
- pcbridge store search --target current --search vehicle --limit 20
109
- pcbridge store get --target current --id <store_asset_id>
110
- 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
111
164
  ```
112
165
 
113
166
  Capture the viewport:
114
167
 
115
168
  ```bash
116
- pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
169
+ pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas-viewport.png
117
170
  ```
118
171
 
119
172
  Launch runtime debugging:
120
173
 
121
174
  ```bash
122
- pcbridge eval --target launch:<sceneId> --code "return { href: location.href, hasPc: !!pc, canvasCount: document.querySelectorAll('canvas').length }"
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 }"
123
178
  pcbridge viewport capture --target launch:<sceneId> --out ./tmp/launch.png
124
179
  pcbridge logs get --target launch:<sceneId> --limit 100
125
180
  pcbridge logs get --target launch:<sceneId> --level error
126
181
  ```
127
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
+
128
194
  ## Asset Organization
129
195
 
130
- 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:
131
198
 
132
199
  ```text
133
200
  AI Agent Bridge/<task name>/Textures
@@ -141,13 +208,14 @@ Use stable names that describe the asset purpose. Avoid dumping generated files
141
208
 
142
209
  For multi-asset or game-sized tasks:
143
210
 
144
- 1. Choose an explicit target from `pcbridge targets`, preferably `scene:<sceneId>` or `tab:<id>`.
145
- 2. Create a project-local task folder for generated scripts, manifests, captures, and temporary assets.
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>/`.
146
214
  3. Put PlayCanvas assets under `AI Agent Bridge/<task name>/{Textures,Materials,Scripts,Templates}`.
147
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.
148
- 5. Use `pcbridge script upsert --filename <name>.js --file ./script.js --folder "AI Agent Bridge/<task name>/Scripts" --parse` for repeatable script creation or update.
149
- 6. Use `pcbridge eval --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.
150
- 7. Verify with read-only commands, a small smoke-test eval, and `pcbridge viewport capture --out ./task/captures/preview.png`.
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/`.
151
219
 
152
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.
153
221
 
@@ -157,18 +225,25 @@ Do not pre-place runtime-generated content just to prove a game exists. For rogu
157
225
 
158
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.
159
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
+
160
235
  ## Texture Box Pattern
161
236
 
162
237
  For a textured scripted box, compose structured commands instead of writing one large eval:
163
238
 
164
239
  ```bash
165
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/Texture Box/Textures"
166
- pcbridge asset upload --target current --file ./image.png --name TextureBoxImage --folder "AI Agent Bridge/Texture Box/Textures"
167
- pcbridge material create --target current --name TextureBoxMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
168
- pcbridge script create --target current --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
169
- pcbridge entity create --target current --json ./box.json
170
- pcbridge entity set-material --target current --id <box_resource_id> --material-id <material_asset_id>
171
- 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}'
172
247
  ```
173
248
 
174
249
  ## Eval Snippet Rules
@@ -179,12 +254,17 @@ The snippet runs inside an async function with these bindings:
179
254
  editor;
180
255
  pc;
181
256
  pcui;
257
+ runtimeApp;
182
258
  window;
183
259
  document;
184
260
  command;
185
261
  serialize;
186
262
  ```
187
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
+
188
268
  Prefer:
189
269
 
190
270
  ```js
@@ -14,46 +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 or Launch.
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.
19
+
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>`.
18
25
 
19
26
  For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
20
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.
21
30
 
22
- Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
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`.
23
32
 
24
33
  Use structured commands for small, known Editor operations:
25
34
 
26
35
  ```bash
27
- pcbridge entity list --target current --limit 50
28
- pcbridge entity patch --target current --id <resource_id> --set name=Player
29
- pcbridge entity duplicate --target current --id <resource_id>
30
- pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
31
- pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
32
- pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
33
- pcbridge asset list --target current --type script
34
- pcbridge asset create --target current --json ./assets.json
35
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/My Task/Textures"
36
- pcbridge asset upload --target current --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
37
- pcbridge asset upload-many --target current --json ./upload-manifest.json
38
- pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
39
- pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
40
- pcbridge template instantiate --target current --id <template_asset_id>
41
- pcbridge scene settings get --target current
42
- pcbridge viewport focus --target current --id <resource_id> --view perspective
43
- pcbridge script upsert --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse
44
- pcbridge script create --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
45
- pcbridge script set-text --target current --asset-id <id> --file ./script.js
46
- 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
47
60
  pcbridge logs get --target launch:<sceneId> --limit 100
48
61
  pcbridge logs get --target launch:<sceneId> --level error
49
62
  ```
50
63
 
51
64
  Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
52
65
 
53
- Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, Launch runtime debugging, and large multi-step scene edits. Use `pcbridge eval --file ./install.js --args-json ./args.json --timeout-ms 120000` when local configuration is too large to embed in code or the install can exceed the default 15s timeout. 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.
54
73
 
55
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.
56
75
 
57
- For large tasks, choose an explicit target from `pcbridge targets`, keep generated files and captures in a local task folder, upload batches with `asset upload-many`, update scripts with `script upsert`, and capture the viewport after smoke tests. If repeated manual glue appears, improve the CLI or this rule.
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.
58
85
 
59
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.
@@ -10,47 +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 or Launch 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.
15
+
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.
14
20
 
15
21
  For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
16
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.
17
25
 
18
- Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
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`.
19
27
 
20
28
  Use structured commands for small, known Editor operations:
21
29
 
22
30
  ```bash
23
- pcbridge entity list --target current --limit 50
24
- pcbridge entity create --target current --json ./entity.json
25
- pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
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 asset upload-many --target current --json ./upload-manifest.json
35
- pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
36
- pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
37
- pcbridge template instantiate --target current --id <template_asset_id>
38
- pcbridge scene settings get --target current
39
- pcbridge viewport focus --target current --id <resource_id> --view perspective
40
- pcbridge script upsert --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse
41
- pcbridge script create --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
42
- pcbridge script set-text --target current --asset-id <id> --file ./script.js
43
- 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
44
56
  pcbridge logs get --target launch:<sceneId> --limit 100
45
57
  pcbridge logs get --target launch:<sceneId> --level error
46
58
  ```
47
59
 
48
60
  Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
49
61
 
50
- Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, Launch runtime debugging, and large multi-step scene edits. Use `pcbridge eval --file ./install.js --args-json ./args.json --timeout-ms 120000` when local configuration is too large to embed in code or the install can exceed the default 15s timeout. 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.
51
68
 
52
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.
53
70
 
54
- For large tasks, choose an explicit target from `pcbridge targets`, keep generated files and captures in a local task folder, upload batches with `asset upload-many`, update scripts with `script upsert`, and capture the viewport after smoke tests. If repeated manual glue appears, improve the CLI or this rule.
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.
55
80
 
56
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.