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.
@@ -17,117 +17,195 @@ 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 # project metadata and agent-readable asset catalog
57
+ assets/ # PlayCanvas folder tree; all asset file contents synchronize automatically
58
+ tmp/ # task files, builds, cache, conflicts, captures, and deletion quarantine
59
+ .pcbridge/ # internal 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 and binary asset contents synchronize in both directions. Create, move, rename,
72
+ and delete assets through structured pcbridge commands; do not perform structural changes by moving
73
+ or deleting mirrored local files. `workspace pull` explicitly refreshes one file but is not needed
74
+ for normal synchronization.
75
+ Read `pcbridge.project.json.assets` to resolve asset ids to project-relative `assets/...` paths and
76
+ compare remote, local, and base MD5 values. The catalog is managed by pcbridge; do not edit it to
77
+ request remote asset operations. Confirmed remote deletions are quarantined under
78
+ `tmp/trash/remote/`; `tmp/conflicts/` is reserved for divergent local and remote contents.
79
+
80
+ Selecting a Template Asset exposes **pcbridge Tiny Builder** in the Attributes panel. It collects
81
+ dependencies, fills the workspace cache, and uploads individual S3 objects without a ZIP. Project
82
+ `.env` overrides workspace-root `.env`; never read or return credential values. CLI equivalents are
83
+ `pcbridge builder start --target editor:<sceneId> --asset <id>` and
84
+ `pcbridge builder status --job <jobId>`.
85
+
86
+ Local file arguments are restricted to the selected project workspace. Never use
87
+ `--allow-external-path` unless the user explicitly asks to use a known external file.
41
88
 
42
89
  ## Safe Commands
43
90
 
44
91
  Inspect a scene:
45
92
 
46
93
  ```bash
47
- pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor, entityCount: editor.api.globals.entities.list().length }"
94
+ pcbridge eval --target editor:<sceneId> --code "return { href: location.href, hasEditor: !!editor, entityCount: editor.api.globals.entities.list().length }"
48
95
  ```
49
96
 
50
97
  List entities:
51
98
 
52
99
  ```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
100
+ pcbridge entity list --target editor:<sceneId> --limit 50
101
+ pcbridge entity list --target editor:<sceneId> --name Player --component render
102
+ pcbridge entity list --target editor:<sceneId> --tag enemy
56
103
  ```
57
104
 
58
105
  Create an entity from JSON:
59
106
 
60
107
  ```bash
61
- pcbridge entity create --target current --json ./entity.json
62
- pcbridge entity create-many --target current --json ./entities.json
108
+ pcbridge entity create --target editor:<sceneId> --json ./entity.json
109
+ pcbridge entity create-many --target editor:<sceneId> --json ./entities.json
63
110
  ```
64
111
 
65
112
  Patch an entity:
66
113
 
67
114
  ```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>
115
+ pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set name=Player --set position='[0,1,0]'
116
+ pcbridge entity patch-many --target editor:<sceneId> --json ./edits.json
117
+ pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
118
+ pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
72
119
  ```
73
120
 
74
121
  Modify components and materials:
75
122
 
76
123
  ```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>
124
+ pcbridge entity add-component --target editor:<sceneId> --id <resource_id> --component render --data '{"type":"box"}'
125
+ pcbridge entity add-components --target editor:<sceneId> --id <resource_id> --json ./components.json
126
+ pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
127
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
128
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
129
+ pcbridge entity delete --target editor:<sceneId> --id <resource_id>
82
130
  ```
83
131
 
132
+ Use exactly one of `--asset-id` and `--script-name`. The name form is for a ScriptType registered
133
+ by a bundle or runtime asset and therefore lacking a standalone script asset id. Verify such a
134
+ script in Launch; explicit script reordering is not yet a dedicated command.
135
+
84
136
  Work with assets and scripts:
85
137
 
86
138
  ```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>
139
+ pcbridge asset list --target editor:<sceneId> --type script --limit 50
140
+ pcbridge asset create --target editor:<sceneId> --json ./assets.json
141
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
142
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
143
+ pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
144
+ pcbridge asset instantiate --target editor:<sceneId> --id <template_asset_id>
145
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
146
+ pcbridge material patch --target editor:<sceneId> --asset-id <material_asset_id> --set diffuse='[1,0,0]'
147
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
148
+ pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
149
+ pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
150
+ pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
151
+ pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
152
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
153
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts"
154
+ pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./controller.js --parse --wait
155
+ pcbridge script parse --target editor:<sceneId> --asset-id <id>
101
156
  ```
102
157
 
158
+ `template-roots.json` may be `{"entityIds":["root-a","root-b"]}` or an array of entity ids/items.
159
+ `apply-many` validates every root before writing and processes them serially. When an apply is
160
+ needed, completion requires the pipeline callback plus two zero-override observations. `verified`
161
+ only covers the current Editor observer; it does not confirm persistence across an Editor reload.
162
+
163
+ Prefer the completion-checked `--parse --wait` forms after edits. They wait for non-empty stable
164
+ file metadata, verify the remote text, parse it, and read back stable script attributes before
165
+ returning. They do not wait for the workspace mirror to finish a later sync.
166
+
103
167
  Scene, store, and viewport:
104
168
 
105
169
  ```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
170
+ pcbridge scene settings get --target editor:<sceneId>
171
+ pcbridge scene settings patch --target editor:<sceneId> --json ./scene-settings.json
172
+ pcbridge store search --target editor:<sceneId> --search vehicle --limit 20
173
+ pcbridge store get --target editor:<sceneId> --id <store_asset_id>
174
+ pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
111
175
  ```
112
176
 
113
177
  Capture the viewport:
114
178
 
115
179
  ```bash
116
- pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
180
+ pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas-viewport.png
117
181
  ```
118
182
 
119
183
  Launch runtime debugging:
120
184
 
121
185
  ```bash
122
- pcbridge eval --target launch:<sceneId> --code "return { href: location.href, hasPc: !!pc, canvasCount: document.querySelectorAll('canvas').length }"
186
+ pcbridge launch diagnose --target launch:<sceneId>
187
+ pcbridge launch wait-ready --target launch:<sceneId> --focus --timeout-ms 30000
188
+ pcbridge eval --target launch:<sceneId> --code "return { href: location.href, runtimeCreated: !!runtimeApp, rootChildCount: runtimeApp?.root?.children?.length ?? 0 }"
123
189
  pcbridge viewport capture --target launch:<sceneId> --out ./tmp/launch.png
124
190
  pcbridge logs get --target launch:<sceneId> --limit 100
125
191
  pcbridge logs get --target launch:<sceneId> --level error
126
192
  ```
127
193
 
194
+ For Launch, `lifecycleReady` is a best-effort heuristic requiring a runtime app with its own
195
+ graphics canvas/context, an attached scene root, at least one completed frame, and no recognized
196
+ startup splash. Target `ready` additionally requires a visible tab, so use `target focus` or
197
+ `launch wait-ready --focus` for a hidden Launch. These are diagnostic signals, not Engine lifecycle
198
+ events; custom splash screens may be missed. `scriptTypeCount` is diagnostic only. Use the resolved
199
+ `runtimeApp` eval binding instead of calling `Application.getApplication()` yourself.
200
+
201
+ `viewport capture` records the current canvas. It does not emulate a phone viewport or DPR. PNG
202
+ may preserve transparency, and the default `--max-width 1200` may downscale the output; use returned dimensions as
203
+ authoritative.
204
+
128
205
  ## Asset Organization
129
206
 
130
- Create task-scoped folders before uploading generated assets:
207
+ Create task-scoped remote folders before uploading generated assets. Keep local generated files
208
+ under the project `tmp/` directory until they are uploaded:
131
209
 
132
210
  ```text
133
211
  AI Agent Bridge/<task name>/Textures
@@ -141,13 +219,14 @@ Use stable names that describe the asset purpose. Avoid dumping generated files
141
219
 
142
220
  For multi-asset or game-sized tasks:
143
221
 
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.
222
+ 1. Choose an explicit target from `pcbridge targets`, preferably `editor:<sceneId>` for writes or
223
+ `launch:<sceneId>` for tests; use `tab:<id>` to resolve ambiguity.
224
+ 2. Confirm `workspace status`, then create task files under `<project>/tmp/<task name>/`.
146
225
  3. Put PlayCanvas assets under `AI Agent Bridge/<task name>/{Textures,Materials,Scripts,Templates}`.
147
226
  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`.
227
+ 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.
228
+ 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.
229
+ 7. Verify with read-only commands, a small smoke-test eval, and a capture under `<project>/tmp/captures/`.
151
230
 
152
231
  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
232
 
@@ -157,18 +236,25 @@ Do not pre-place runtime-generated content just to prove a game exists. For rogu
157
236
 
158
237
  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
238
 
239
+ Editor entity patches are durable scene edits, not runtime-only preview state. Never apply a
240
+ Template while preview-only `enabled` or visibility changes remain on its source root. Restore and
241
+ read back the original preview values first, then run `template overrides` and `template apply`.
242
+ Prefer Launch eval for temporary runtime test state. `template apply` warns when the override set
243
+ contains an `enabled` change and waits until overrides are stably zero.
244
+ That verification is limited to the current Editor observer and does not prove reload persistence.
245
+
160
246
  ## Texture Box Pattern
161
247
 
162
248
  For a textured scripted box, compose structured commands instead of writing one large eval:
163
249
 
164
250
  ```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}'
251
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Texture Box/Textures"
252
+ pcbridge asset upload --target editor:<sceneId> --file ./image.png --name TextureBoxImage --folder "AI Agent Bridge/Texture Box/Textures"
253
+ pcbridge material create --target editor:<sceneId> --name TextureBoxMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
254
+ pcbridge script create --target editor:<sceneId> --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
255
+ pcbridge entity create --target editor:<sceneId> --json ./box.json
256
+ pcbridge entity set-material --target editor:<sceneId> --id <box_resource_id> --material-id <material_asset_id>
257
+ pcbridge entity add-script --target editor:<sceneId> --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
172
258
  ```
173
259
 
174
260
  ## Eval Snippet Rules
@@ -179,12 +265,17 @@ The snippet runs inside an async function with these bindings:
179
265
  editor;
180
266
  pc;
181
267
  pcui;
268
+ runtimeApp;
182
269
  window;
183
270
  document;
184
271
  command;
185
272
  serialize;
186
273
  ```
187
274
 
275
+ The final bridge serialization is bounded even when `--full` is used. Return only required leaf
276
+ fields. If a compact projection still contains `[MaxDepth ...]`, use bounded eval options such as
277
+ `--max-depth 8 --max-items 500`; do not return raw Editor or runtime objects.
278
+
188
279
  Prefer:
189
280
 
190
281
  ```js
@@ -14,46 +14,78 @@ 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}`. Script and binary
23
+ asset contents synchronize automatically; `pcbridge workspace pull --target editor:<sceneId>
24
+ --asset <id>` explicitly refreshes one file.
25
+ Read `pcbridge.project.json.assets` for asset ids, types, project-relative file paths, presence, and
26
+ remote/local/base MD5 values. Treat that asset catalog as pcbridge-managed. Confirmed remote
27
+ deletions are quarantined under `tmp/trash/remote/`; `tmp/conflicts/` contains content divergence.
28
+ Template selection exposes pcbridge Tiny Builder for direct S3 object uploads; project `.env`
29
+ overrides workspace-root `.env`.
18
30
 
19
31
  For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
20
32
  `pcbridge frontend status`, and switch custom/official mode from the extension popup.
33
+ The popup remembers that choice per project and reapplies it on later project-picker and scene
34
+ Editor navigations; change the remembered choice only through the popup.
21
35
 
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`.
36
+ 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
37
 
24
38
  Use structured commands for small, known Editor operations:
25
39
 
26
40
  ```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
41
+ pcbridge entity list --target editor:<sceneId> --limit 50
42
+ pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set name=Player
43
+ pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
44
+ pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
45
+ pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
46
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
47
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
48
+ pcbridge asset list --target editor:<sceneId> --type script
49
+ pcbridge asset create --target editor:<sceneId> --json ./assets.json
50
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
51
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
52
+ pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
53
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
54
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
55
+ pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
56
+ pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
57
+ pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
58
+ pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
59
+ pcbridge scene settings get --target editor:<sceneId>
60
+ pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
61
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
62
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
63
+ pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
64
+ pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
47
65
  pcbridge logs get --target launch:<sceneId> --limit 100
48
66
  pcbridge logs get --target launch:<sceneId> --level error
49
67
  ```
50
68
 
51
69
  Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
52
70
 
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.
71
+ Use `pcbridge launch diagnose` and `pcbridge launch wait-ready --focus` before runtime assertions.
72
+ Launch `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context,
73
+ attached scene root, a completed frame, and known splash selectors; target `ready` also requires a
74
+ visible tab. These are not Engine lifecycle events, and script type count is diagnostic only. Eval
75
+ snippets include compatibility-resolved `runtimeApp` plus `editor`, `pc`, `pcui`, `window`, `document`,
76
+ `command`, and `serialize`; never return raw app objects. Use bounded `--max-depth`/`--max-items`
77
+ only after projecting required fields.
54
78
 
55
79
  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
80
 
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.
81
+ Use `editor:<sceneId>` for writes. Use `--script-name` for bundle-registered ScriptTypes. Editor
82
+ patches are durable, so restore preview-only enabled/visibility changes before Template apply.
83
+ Template `verified` covers current Editor overrides, not persistence across a reload. Script
84
+ `--parse --wait` completion checks do not wait for the workspace mirror's later sync.
85
+ Capture does not focus/resize/emulate a mobile viewport and defaults to `--max-width 1200`; use returned dimensions as authoritative.
86
+
87
+ For large eval installs, use `pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./install-args.json --timeout-ms 120000`.
88
+
89
+ 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
90
 
59
91
  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,77 @@ 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 and binary
19
+ asset contents synchronize both ways; `workspace pull` explicitly refreshes one file.
20
+ Read `pcbridge.project.json.assets` for asset ids, types, project-relative file paths, presence, and
21
+ remote/local/base MD5 values. Treat that asset catalog as pcbridge-managed. Confirmed remote
22
+ deletions are quarantined under `tmp/trash/remote/`; `tmp/conflicts/` contains content divergence.
23
+ Template selection exposes pcbridge Tiny Builder for direct S3 object uploads; project `.env`
24
+ overrides workspace-root `.env`.
14
25
 
15
26
  For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
16
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.
17
30
 
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`.
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`.
19
32
 
20
33
  Use structured commands for small, known Editor operations:
21
34
 
22
35
  ```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
36
+ pcbridge entity list --target editor:<sceneId> --limit 50
37
+ pcbridge entity create --target editor:<sceneId> --json ./entity.json
38
+ pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set position='[0,1,0]'
39
+ pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
40
+ pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
41
+ pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
42
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
43
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
44
+ pcbridge asset list --target editor:<sceneId> --type script
45
+ pcbridge asset create --target editor:<sceneId> --json ./assets.json
46
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
47
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
48
+ pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
49
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
50
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
51
+ pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
52
+ pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
53
+ pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
54
+ pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
55
+ pcbridge scene settings get --target editor:<sceneId>
56
+ pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
57
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
58
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
59
+ pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
60
+ pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
44
61
  pcbridge logs get --target launch:<sceneId> --limit 100
45
62
  pcbridge logs get --target launch:<sceneId> --level error
46
63
  ```
47
64
 
48
65
  Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
49
66
 
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.
67
+ Use `pcbridge launch diagnose` and `pcbridge launch wait-ready --focus` before runtime assertions.
68
+ Launch `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context,
69
+ attached scene root, a completed frame, and known splash selectors; target `ready` also requires a
70
+ visible tab. These are not Engine lifecycle events, and script type count is diagnostic only. Eval
71
+ includes compatibility-resolved `runtimeApp` for Engine V1/V2 plus the existing Editor bindings. Return compact
72
+ JSON; use bounded `--max-depth`/`--max-items` only when a leaf projection is insufficient.
51
73
 
52
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.
53
75
 
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.
76
+ Use `editor:<sceneId>` for writes and `--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 records the current canvas, defaults to `--max-width 1200`, and does not emulate a mobile viewport or DPR.
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. 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
85
 
56
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.