playcanvas-agent-bridge-cli 0.6.1 → 0.6.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.
@@ -35,7 +35,7 @@ The CLI/daemon, copied agent skills, generated Chrome extension, and custom Edit
35
35
  independently. For an explicit update request:
36
36
 
37
37
  1. Record the workspace root reported by `pcbridge daemon status`.
38
- 2. Run `npm install -g playcanvas-agent-bridge-cli@latest`, check `pcbridge version`, and rerun
38
+ 2. Run `bun add --global playcanvas-agent-bridge-cli@latest`, check `pcbridge version`, and rerun
39
39
  `pcbridge install-skill --agent all`.
40
40
  For a custom or project-local parent directory, use
41
41
  `pcbridge install-skill --agent <one-agent> --path <parent-directory>`; `--path` appends the
@@ -61,6 +61,8 @@ pcbridge help script
61
61
  pcbridge help store
62
62
  pcbridge help target
63
63
  pcbridge help workspace
64
+ pcbridge help processing
65
+ pcbridge help import
64
66
  pcbridge help frontend
65
67
  pcbridge help entity
66
68
  pcbridge help asset
@@ -76,23 +78,53 @@ Workspace layout:
76
78
 
77
79
  ```text
78
80
  <workspace root>/<projectId>-<projectName>/
79
- pcbridge.project.json # project metadata and agent-readable asset catalog
80
- assets/ # collision-safe projection of the remote folder tree
81
- tmp/ # agent files, builds, cache, conflicts, captures, and deletion quarantine; never synchronized
82
- .pcbridge/ # internal state and object cache; do not edit
81
+ pcbridge.project.json # project metadata, scenes list, and agent-readable asset catalog (with meta summaries)
82
+ scenes/ # active writable .scene.json plus read-only (0o444) mirrors of inactive scenes
83
+ assets/ # collision-safe projection of the remote folder tree (text, *.<type>.json, pulled binaries)
84
+ tmp/ # agent files, builds, conflicts, captures, and local/remote deletion trash; never synchronized
85
+ .pcbridge/ # internal sync state, 3-way JSON baselines, and object cache; do not edit
83
86
  ```
84
87
 
85
- Prefer local operations for file-backed Assets. Edit scripts under `assets/`; create files and
86
- folders there to upload them through PlayCanvas processing; and rename or move local files to keep
87
- the same remote Asset ID. Deleting a local file only clears its local cache and does not delete the
88
- remote Asset. Use `asset delete --id <id>` only for intentional remote deletion. Scripts are eager,
89
- while binary contents are lazy; use `pcbridge workspace pull --target editor:<sceneId> --asset
90
- <assetId>` before modifying a missing remote binary. Generated GLB Model/Container/material Assets
91
- and font atlases are lazy, read-only projections. Edit the source Asset; derivative edits or moves
92
- are quarantined and restored from `.pcbridge/objects`, never uploaded.
93
-
94
- After local writes, wait for the watcher and poll `workspace status` until `synced`. A brief
95
- `local-change` is normal. If it does not converge, run one `workspace sync`, inspect status and
88
+ Inspect local files first (0 RPC) to understand the project: read `pcbridge.project.json` (which
89
+ includes `scenes[]`, full Asset IDs/paths, and lazy binary `meta` such as texture dimensions), read
90
+ `scenes/<name>.<sceneId>.scene.json` (DFS-ordered `entities` + `settings`), and search `scenes/` and
91
+ `assets/` with `rg` instead of issuing `entity list` / `asset list` / `eval` RPCs for static
92
+ inspection.
93
+
94
+ Synchronization is event-driven via WebSocket `workspace:delta` pushes and targeted local `fs.watch`
95
+ dirty paths (zero idle polling):
96
+ - **Tier 1 (Eager bidirectional)**: Text assets (`script`, `text`, `json`, `html`, `css`, `shader`)
97
+ and structured JSON data assets (`material`, `template`, `cubemap`, `sprite`, `animstategraph`,
98
+ `bundle`, projected as `<name>.<type>.json`) up to the direct-sync limit (default **2 MB**,
99
+ adjustable **1–10 MB** via the extension popup **Direct sync limit** slider or
100
+ `pcbridge workspace settings --eager-max-mb <1..10>`) sync automatically in both directions.
101
+ - **Scenes (`scenes/<name>.<sceneId>.scene.json`)**: The active Editor scene carries
102
+ `"$pcbridge": { "id": "...", "kind": "scene", "active": true }` (`0o644` writable, automatic
103
+ `parent <-> children` reconciliation). Inactive scenes carry
104
+ `"$pcbridge": { "id": "...", "kind": "scene", "active": false, "readonly": true }` (`0o444`
105
+ read-only); run `pcbridge scene open --target editor:<currentSceneId> --id <targetSceneId>` before
106
+ editing an inactive scene.
107
+ - **Property-path 3-way merge**: Structured JSON assets and the active `.scene.json` merge against
108
+ `.pcbridge/baselines/` at property/entity granularity so non-overlapping local and Editor edits
109
+ merge cleanly; same-path conflicts write `.local`, `.remote`, and `.conflict.json` under
110
+ `tmp/conflicts/`.
111
+ - **Create, rename, and delete semantics**: Creating files under `assets/` (including new
112
+ `*.<type>.json` structured assets) creates matching remote folders/Assets and writes back
113
+ `$pcbridge.id`. Renaming or moving local files preserves the Asset ID via `$pcbridge.id`, file
114
+ inode, or content hash. **Deleting a local Tier 1 eagerly synced file backs it up to
115
+ `tmp/trash/local/` AND deletes the remote PlayCanvas Asset**; delete Tier 1 files only when remote
116
+ deletion is intended. Deleting a pulled Tier 2 lazy binary (images, models, audio, fonts, or
117
+ over-limit files; pull missing ones with `pcbridge workspace pull --target editor:<sceneId>
118
+ --asset <assetId>`) only evicts the local cache (`pcbridge asset delete --id <id>` deletes remote
119
+ Tier 2 assets).
120
+ - **Derived assets**: Binary derivatives (`container`, `model`, generated font atlases) remain lazy
121
+ and read-only (`0o444`), whereas structured JSON assets linked to a source model (such as
122
+ FBX/GLB-imported `material` files) are writable (`0o644`) and sync bidirectionally while keeping
123
+ `$pcbridge.sourceAssetId` for provenance.
124
+
125
+ After local writes, allow ~0.5–1s for the watcher debounce and poll `workspace status` until
126
+ `synced` (do not mix local file saves and CLI write RPCs on the same asset/scene simultaneously). A
127
+ brief `local-change` is normal. If it does not converge, run one `workspace sync`, inspect status and
96
128
  `tmp/conflicts/`, and never overwrite a conflict automatically. Local file
97
129
  arguments must stay inside the selected project workspace. Do not use `--allow-external-path`
98
130
  unless the user explicitly asks to use a known external file.
@@ -112,10 +144,15 @@ values. CLI equivalents are
112
144
  `pcbridge builder start --target editor:<sceneId> --asset <id>` and
113
145
  `pcbridge builder status --job <jobId>`.
114
146
 
115
- Use structured commands for scene structure, Asset metadata, explicit transfers, and verification.
116
- For ordinary file-content edits, prefer the tracked file under `assets/`:
147
+ Prefer local file edits for scripts, shaders, text, `*.material.json` / `*.template.json` data, and
148
+ multi-property edits in the active `.scene.json`. Use structured commands for Editor pipelines
149
+ (`scene open`, `template instantiate/create/overrides/apply`, `script parse`, `import`), explicit
150
+ transfers, and live viewport/Launch verification:
117
151
 
118
152
  ```bash
153
+ pcbridge workspace settings --eager-max-mb 2
154
+ pcbridge scene list --target editor:<sceneId>
155
+ pcbridge scene open --target editor:<sceneId> --id <otherSceneId>
119
156
  pcbridge entity list --target editor:<sceneId> --limit 50
120
157
  pcbridge entity create --target editor:<sceneId> --json ./entity.json
121
158
  pcbridge entity create-many --target editor:<sceneId> --json ./entities.json
@@ -127,27 +164,35 @@ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-
127
164
  pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
128
165
  pcbridge asset list --target editor:<sceneId> --type script
129
166
  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"
167
+ pcbridge asset folder ensure --target editor:<sceneId> --path "My Task/Textures"
168
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "My Task/Textures"
132
169
  pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
133
- pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
134
- pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
170
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "My Task/Materials" --diffuse-map <texture_asset_id>
171
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "My Task/Templates"
135
172
  pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
136
173
  pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
137
174
  pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
138
175
  pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
139
176
  pcbridge scene settings get --target editor:<sceneId>
140
177
  pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
141
- pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
142
- pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
178
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "My Task/Scripts" --parse --wait
179
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "My Task/Scripts"
143
180
  pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
144
181
  pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
145
182
  pcbridge logs get --target launch:<sceneId> --limit 100
146
183
  pcbridge logs get --target launch:<sceneId> --level error
147
184
  ```
148
185
 
149
- Organize final file-backed assets under `assets/AI Agent Bridge/<task name>/...` and disposable
150
- generation files under `tmp/<task name>/`. Use `pcbridge eval` for exploratory API inspection,
186
+ Before creating asset folders, inspect the project's existing directory tree and comparable
187
+ resources. Prefer reusing suitable folders and follow the project's naming language, casing,
188
+ separators, hierarchy, and resource grouping when new folders are needed. Organize related assets
189
+ by task or feature within that structure; if the project groups by resource type first, preserve
190
+ that layout rather than imposing a task-first hierarchy. Do not create an `AI Agent Bridge` folder
191
+ by default. If no convention exists, use a descriptive task folder with resource subfolders as needed.
192
+
193
+ Keep final file-backed assets in the project `assets/` tree and intermediate or disposable files
194
+ under `tmp/<task name>/` so the watcher does not upload them. Paths in command examples are
195
+ illustrative; adapt them to the project's existing conventions before creating folders. Use `pcbridge eval` for exploratory API inspection,
151
196
  custom Editor/Engine workflows, and large multi-step scene edits:
152
197
 
153
198
  ```bash
@@ -187,3 +232,8 @@ scene edits or runtime verification. Use upload manifests only when explicit imp
187
232
  non-watched source path is required, then capture under `tmp/captures/` after smoke tests.
188
233
 
189
234
  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.
235
+
236
+
237
+ ## Self-hosted local processing
238
+
239
+ Use `pcbridge help processing` and `pcbridge help import` for self-hosted conversion. Diagnose with `processing status --target editor:<sceneId>`; tools require explicit installation and `processing enable`. Do not enable local conversion on official targets. Use `import submit --asset <id> --kind model|texture --json options.json`, then `import wait --job <id> --sync-workspace`. Server `complete` means published; workspace synchronization is separate and keeps binary lazy loading. On a wait timeout query the same job before repeating a write. Browser authentication, leases and signed URLs must never be copied into CLI arguments. Extension source upgrades require regenerating the unpacked extension, reloading it in Chrome and refreshing target pages. Custom host permissions are granted by the user through the popup.
@@ -45,7 +45,7 @@ Treat the CLI/daemon, installed agent skill, generated Chrome extension, and cus
45
45
  as separate components. When the user asks to update pcbridge:
46
46
 
47
47
  1. Record the current workspace root from `pcbridge daemon status`.
48
- 2. Run `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, and reinstall
48
+ 2. Run `bun add --global playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, and reinstall
49
49
  copied skills with `pcbridge install-skill --agent all`.
50
50
  For a custom or project-local parent directory, use
51
51
  `pcbridge install-skill --agent <one-agent> --path <parent-directory>`; `--path` appends the
@@ -69,21 +69,26 @@ steps have been acknowledged or verified.
69
69
  1. Run `pcbridge targets`. Use `editor:<sceneId>` for Editor writes and `launch:<sceneId>` for
70
70
  runtime verification; use `tab:<id>` when either selector is ambiguous.
71
71
  2. Run `pcbridge workspace status --target editor:<sceneId>`. Do not write while it reports a conflict or sync error.
72
- 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`.
73
- 4. Edit asset file contents locally under the selected project's `assets/` tree and let the daemon synchronize them. Keep temporary files, manifests, and captures under `tmp/`, which is not synchronized.
74
- 5. Use structured commands for scene structure and non-file Asset operations that map cleanly to one Editor action.
75
- 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.
76
- 7. Return compact JSON from snippets. Never return raw `editor`, `Entity`, `Asset`, `entities.root`, or app objects.
77
- 8. Use PlayCanvas history options for writes when available and verify writes with a read-only command.
72
+ 3. **Inspect local files first (0 RPC)** to understand the project before calling Editor RPCs:
73
+ - Read `pcbridge.project.json` for `scenes[]` (active/writable vs inactive/read-only), full asset IDs, paths, and lazy binary `meta` (texture dimensions/format, model/audio summaries).
74
+ - Read `scenes/<name>.<sceneId>.scene.json` (DFS-ordered `entities` + `settings`) and search `scenes/` + `assets/` with `rg` to trace entities, script attachments, `<name>.material.json`, `<name>.template.json`, scripts, and shaders across the entire project.
75
+ 4. Use layered help to load only the command group you need: `pcbridge help`, then `pcbridge help core|workspace|processing|import|frontend|target|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
76
+ 5. **Choose the right write path** (never mix local file edits and CLI write RPCs on the same target concurrently):
77
+ - **Edit local files** under `assets/` and `scenes/` for scripts, shaders, CSS/HTML/JSON/text, `<name>.material.json` / `<name>.template.json` / other `*.<type>.json` structured assets (including batch edits and creating new `*.<type>.json` files), file renames/moves, and ordinary property or entity edits in the **active** `.scene.json` (`"$pcbridge": { "active": true }`).
78
+ - **Use structured CLI commands** for Editor-specific pipelines: `scene open` (required before editing an inactive read-only scene), `template instantiate`, `template create --entity-id`, `template overrides`, `template apply` / `apply-many` (never hand-edit `template_ent_ids`), `script parse`, `import submit/wait`, `viewport focus/capture`, and `launch` diagnostics/logs.
79
+ 6. Keep temporary files, manifests, and captures under `tmp/`, which is never synchronized.
80
+ 7. Use `pcbridge eval` for exploratory Editor/Engine API inspection, Launch runtime debugging (`runtimeApp`), and custom Editor workflows not covered by local projections or structured commands.
81
+ 8. Return compact JSON from snippets. Never return raw `editor`, `Entity`, `Asset`, `entities.root`, or app objects.
78
82
 
79
83
  ## Workspace
80
84
 
81
85
  ```text
82
86
  <workspace root>/<projectId>-<projectName>/
83
- pcbridge.project.json # project metadata and agent-readable asset catalog
84
- assets/ # collision-safe projection of the PlayCanvas folder tree
85
- tmp/ # agent files, builds, cache, conflicts, captures, and deletion quarantine; never synchronized
86
- .pcbridge/ # internal sync state and object cache; do not edit
87
+ pcbridge.project.json # project metadata, scenes list, and agent-readable asset catalog (with meta summaries)
88
+ scenes/ # active writable .scene.json plus read-only (0o444) mirrors of inactive scenes
89
+ assets/ # collision-safe projection of the PlayCanvas folder tree (text, *.<type>.json, pulled binaries)
90
+ tmp/ # agent files, builds, conflicts, captures, and local/remote deletion trash; never synchronized
91
+ .pcbridge/ # internal sync state, 3-way JSON baselines, and object cache; do not edit
87
92
  ```
88
93
 
89
94
  Use:
@@ -91,20 +96,24 @@ Use:
91
96
  ```bash
92
97
  pcbridge workspace status --target editor:<sceneId>
93
98
  pcbridge workspace path --target editor:<sceneId>
99
+ pcbridge workspace settings [--eager-max-mb <1..10>]
94
100
  pcbridge workspace sync --target editor:<sceneId>
95
101
  pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
96
102
  ```
97
103
 
98
- Prefer local file operations for file-backed Assets:
104
+ Synchronization is event-driven via WebSocket `workspace:delta` pushes and targeted local `fs.watch` dirty paths (zero idle polling):
99
105
 
100
- - Edit existing scripts directly under `assets/`; the watcher uploads them to PlayCanvas.
101
- - Create files and folders under `assets/` to upload them into the matching remote folder. Let PlayCanvas infer and process the Asset type.
102
- - Rename or move a local file to rename or move the same remote Asset ID.
103
- - Deleting a local file only removes the local lazy cache. It does not delete the remote Asset; use `pcbridge asset delete --id <id>` only when remote deletion is explicitly intended.
104
- - Scripts are downloaded eagerly. Binary files are lazy; run `workspace pull --asset <id>` before modifying a remote binary that is not present locally.
105
- - PlayCanvas-generated derivatives such as GLB Model/Container/material outputs and font atlases are lazy, read-only projections. Edit the source Asset, not a derivative. A local derivative edit or move is quarantined under `tmp/conflicts/`, restored from `.pcbridge/objects`, and never uploaded.
106
+ - **Tier 1 (Eager bidirectional)**: Text assets (`script`, `text`, `json`, `html`, `css`, `shader`) and structured JSON data assets (`material`, `template`, `cubemap`, `sprite`, `animstategraph`, `bundle`, projected as `<name>.<type>.json`) up to the direct-sync limit (**default `2 MB`**, adjustable **`1–10 MB`** via the extension popup **Direct sync limit** slider or `pcbridge workspace settings --eager-max-mb <1..10>`) are downloaded automatically and synced bidirectionally.
107
+ - **Scenes (`scenes/<name>.<sceneId>.scene.json`)**: `entities` are ordered in hierarchy DFS pre-order. The open Editor scene has `"$pcbridge": { "id": "...", "kind": "scene", "active": true }` (`0o644` writable); adding/removing entities locally reconciles `parent <-> children` automatically. Inactive scenes have `"$pcbridge": { "id": "...", "kind": "scene", "active": false, "readonly": true }` (`0o444` read-only) — inspect them freely with `rg`, and run `pcbridge scene open --target editor:<currentSceneId> --id <targetSceneId>` before editing one.
108
+ - **Property-path 3-way merge**: Structured JSON assets and the active `.scene.json` merge against `.pcbridge/baselines/` at property/entity granularity, so non-overlapping local and Editor edits merge automatically without false whole-file conflicts. True same-path conflicts write `.local`, `.remote`, and `.conflict.json` under `tmp/conflicts/`.
109
+ - **Create, rename, and move locally**: Creating files under `assets/` (including new `<name>.material.json` or other `*.<type>.json` files without an ID) creates matching remote folders and Assets and writes back `$pcbridge.id`. Renaming or moving local files preserves the remote Asset ID via `$pcbridge.id`, file inode, or content hash (even when renamed and edited together).
110
+ - **Tier 2 (Lazy binary / over-limit files)**: Images, models, audio, fonts, binaries, and files above `eagerMaxMb` record metadata, dimensions, and MD5 in `pcbridge.project.json` without downloading bytes. Run `workspace pull --asset <id>` before modifying a missing binary locally.
111
+ - **Deletion semantics (important distinction)**:
112
+ - Deleting a local **Tier 1** eagerly synced file (in-limit text/script/shader or `*.<type>.json`) **backs it up under `tmp/trash/local/` AND deletes the remote PlayCanvas Asset** to keep both sides consistent. Delete Tier 1 files only when remote deletion is intended.
113
+ - Deleting a locally pulled **Tier 2** lazy binary (or over-limit file) only evicts the local cache without deleting the remote Asset; use `pcbridge asset delete --id <id>` to delete a remote Tier 2 Asset.
114
+ - **Derived assets**: Binary derivatives (`source_asset_id != null` with a file, such as GLB `container`/`model` outputs and generated font atlases) remain lazy and read-only (`0o444`); local edits are quarantined to `tmp/conflicts/` and restored. Structured JSON assets linked to a source model (such as FBX/GLB-imported `material` files) **are writable (`0o644`)** and sync bidirectionally while keeping `$pcbridge.sourceAssetId` for provenance.
106
115
 
107
- After a local edit, allow the watcher to react, then poll `workspace status` until it reports
116
+ After a local edit, allow ~0.5–1s for the watcher debounce to flush, then check `workspace status` until it reports
108
117
  `synced`. A brief yellow `local-change` is expected. Do not declare completion or alternate to
109
118
  remote editing while the same file is pending. If it does not converge, run one explicit
110
119
  `workspace sync`, inspect `lastError`, `lastWarning`, and `tmp/conflicts/`, and do not overwrite
@@ -130,9 +139,11 @@ Local file arguments are restricted to the selected project workspace. Never use
130
139
 
131
140
  ## Safe Commands
132
141
 
133
- Inspect a scene:
142
+ Prefer reading local `pcbridge.project.json`, `scenes/*.scene.json`, and `assets/` first for static inspection. Use CLI commands when you need live Editor/Launch state, pipeline actions, or single targeted RPC mutations:
134
143
 
135
144
  ```bash
145
+ pcbridge scene list --target editor:<sceneId>
146
+ pcbridge scene open --target editor:<sceneId> --id <otherSceneId>
136
147
  pcbridge eval --target editor:<sceneId> --code "return { href: location.href, hasEditor: !!editor, entityCount: editor.api.globals.entities.list().length }"
137
148
  ```
138
149
 
@@ -175,25 +186,24 @@ Use exactly one of `--asset-id` and `--script-name`. The name form is for a Scri
175
186
  by a bundle or runtime asset and therefore lacking a standalone script asset id. Verify such a
176
187
  script in Launch; explicit script reordering is not yet a dedicated command.
177
188
 
178
- Work with asset metadata, explicit transfers, and script verification. For ordinary file-content
179
- edits, prefer editing the tracked local file under `assets/` over `script set-text` or re-uploading it:
189
+ Work with asset pipelines, explicit transfers, and script verification. For ordinary script/shader/text or `*.material.json` / `*.template.json` content edits, prefer editing the tracked local file under `assets/` over CLI `patch` / `set-text` or re-uploading:
180
190
 
181
191
  ```bash
182
192
  pcbridge asset list --target editor:<sceneId> --type script --limit 50
183
193
  pcbridge asset create --target editor:<sceneId> --json ./assets.json
184
- pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
185
- pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
194
+ pcbridge asset folder ensure --target editor:<sceneId> --path "My Task/Textures"
195
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "My Task/Textures"
186
196
  pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
187
197
  pcbridge asset instantiate --target editor:<sceneId> --id <template_asset_id>
188
- pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
198
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "My Task/Materials" --diffuse-map <texture_asset_id>
189
199
  pcbridge material patch --target editor:<sceneId> --asset-id <material_asset_id> --set diffuse='[1,0,0]'
190
- pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
200
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "My Task/Templates"
191
201
  pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
192
202
  pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
193
203
  pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
194
204
  pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
195
- pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
196
- pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts"
205
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "My Task/Scripts" --parse --wait
206
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "My Task/Scripts"
197
207
  pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./controller.js --parse --wait
198
208
  pcbridge script parse --target editor:<sceneId> --asset-id <id>
199
209
  ```
@@ -247,16 +257,16 @@ authoritative.
247
257
 
248
258
  ## Asset Organization
249
259
 
250
- Create synchronized files directly under a task-scoped path in the project `assets/` tree. Keep
251
- intermediate or disposable generation files under `tmp/` so the watcher does not upload them:
260
+ Before creating asset folders, inspect the project's existing directory tree and comparable
261
+ resources. Prefer reusing suitable folders and follow the project's naming language, casing,
262
+ separators, hierarchy, and resource grouping when new folders are needed. Organize related assets
263
+ by task or feature within that structure; if the project groups by resource type first, preserve
264
+ that layout rather than imposing a task-first hierarchy. Do not create an `AI Agent Bridge` folder
265
+ by default. If no convention exists, use a descriptive task folder with resource subfolders as needed.
252
266
 
253
- ```text
254
- assets/AI Agent Bridge/<task name>/Textures
255
- assets/AI Agent Bridge/<task name>/Models
256
- assets/AI Agent Bridge/<task name>/Scripts
257
- ```
258
-
259
- Use stable names that describe the asset purpose. Avoid dumping generated files at the project root.
267
+ Keep final file-backed assets in the project `assets/` tree and intermediate or disposable files
268
+ under `tmp/<task name>/` so the watcher does not upload them. Paths in command examples are
269
+ illustrative; adapt them to the project's existing conventions before creating folders.
260
270
 
261
271
  ## Large Task Workflow
262
272
 
@@ -264,11 +274,11 @@ For multi-asset or game-sized tasks:
264
274
 
265
275
  1. Choose an explicit target from `pcbridge targets`, preferably `editor:<sceneId>` for writes or
266
276
  `launch:<sceneId>` for tests; use `tab:<id>` to resolve ambiguity.
267
- 2. Confirm `workspace status` is `synced`. Put disposable generation inputs under `<project>/tmp/<task name>/`.
268
- 3. Put final scripts, textures, models, audio, and other file-backed Assets under `<project>/assets/AI Agent Bridge/<task name>/...`; create or edit them locally and wait for synchronization.
277
+ 2. Confirm `workspace status` is `synced`. Inspect `pcbridge.project.json`, `scenes/*.scene.json`, and `assets/` locally with `rg` to understand existing hierarchy, conventions, and asset IDs without extra RPC traffic. Put disposable generation inputs under `<project>/tmp/<task name>/`.
278
+ 3. Follow existing folder naming and hierarchy. Group new resources within that convention, reuse suitable folders, and create or edit scripts, shaders, `*.material.json` files, and assets locally under `<project>/assets/`; wait for `workspace status` to reach `synced`.
269
279
  4. Use `asset upload-many` only when explicit upload settings or a non-watched source path is required. Do not upload a file again when it is already tracked under `assets/`.
270
280
  5. For an existing script, edit its local file. Use `script parse` after synchronization when parse verification is needed; reserve `script upsert --parse --wait` for recovery or workflows that intentionally bypass the mirror.
271
- 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.
281
+ 6. For active scene edits, either edit `scenes/<name>.<sceneId>.scene.json` directly (ideal for multi-entity/property tuning with 3-way merge) or use structured `entity` / `template` commands (or `pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./args.json --timeout-ms 120000` for procedural Editor setup). Do not edit `.scene.json` and run scene-mutating RPCs at the exact same instant.
272
282
  7. Wait for `workspace status` to become `synced`, then verify with read-only commands, a small smoke-test eval, and a capture under `<project>/tmp/captures/`.
273
283
 
274
284
  If repeated manual glue is needed across tasks, improve the CLI or this skill rather than continuing to hand-roll brittle shell/script sequences.
@@ -291,10 +301,10 @@ That verification is limited to the current Editor observer and does not prove r
291
301
  For a textured scripted box, compose structured commands instead of writing one large eval:
292
302
 
293
303
  ```bash
294
- pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Texture Box/Textures"
295
- pcbridge asset upload --target editor:<sceneId> --file ./image.png --name TextureBoxImage --folder "AI Agent Bridge/Texture Box/Textures"
296
- pcbridge material create --target editor:<sceneId> --name TextureBoxMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
297
- pcbridge script create --target editor:<sceneId> --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
304
+ pcbridge asset folder ensure --target editor:<sceneId> --path "Texture Box/Textures"
305
+ pcbridge asset upload --target editor:<sceneId> --file ./image.png --name TextureBoxImage --folder "Texture Box/Textures"
306
+ pcbridge material create --target editor:<sceneId> --name TextureBoxMaterial --folder "Texture Box/Materials" --diffuse-map <texture_asset_id>
307
+ pcbridge script create --target editor:<sceneId> --filename jumpingBox.js --file ./jumpingBox.js --folder "Texture Box/Scripts"
298
308
  pcbridge entity create --target editor:<sceneId> --json ./box.json
299
309
  pcbridge entity set-material --target editor:<sceneId> --id <box_resource_id> --material-id <material_asset_id>
300
310
  pcbridge entity add-script --target editor:<sceneId> --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
@@ -339,3 +349,8 @@ return entities.slice(0, 20).map((entity) => ({
339
349
  ```
340
350
 
341
351
  Avoid destructive operations unless the user clearly asked for them. When deleting or overwriting, require explicit stable IDs and report affected counts.
352
+
353
+
354
+ ## Self-hosted local processing
355
+
356
+ Use `pcbridge help processing` and `pcbridge help import` for self-hosted conversion. Diagnose with `processing status --target editor:<sceneId>`; tools require explicit installation and `processing enable`. Do not enable local conversion on official targets. Use `import submit --asset <id> --kind model|texture --json options.json`, then `import wait --job <id> --sync-workspace`. Server `complete` means published; workspace synchronization is separate and keeps binary lazy loading. On a wait timeout query the same job before repeating a write. Browser authentication, leases and signed URLs must never be copied into CLI arguments. Extension source upgrades require regenerating the unpacked extension, reloading it in Chrome and refreshing target pages. Custom host permissions are granted by the user through the popup.
@@ -19,7 +19,7 @@ with local-loopback permission. If no target appears, ask the user to install/re
19
19
 
20
20
  Updates are component-specific. For an explicit update request, record the workspace root from
21
21
  `pcbridge daemon status`. Run
22
- `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
22
+ `bun add --global playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
23
23
  `pcbridge install-skill --agent all`. For a custom or project-local parent directory, use
24
24
  `pcbridge install-skill --agent <one-agent> --path <parent-directory>`; it appends the standard
25
25
  artifact name and cannot be combined with `--agent all`. Regenerate the extension with
@@ -34,16 +34,34 @@ claim completion before these manual steps are confirmed.
34
34
  The current directory is the default workspace root; `daemon start/restart --workspace <directory>`
35
35
  selects it explicitly, and `daemon stop` stops the authenticated daemon. After selecting a target, run
36
36
  `pcbridge workspace status --target editor:<sceneId>` and do not write while it reports a conflict
37
- or sync error. Project files live under `<projectId>-<projectName>/{assets,tmp}`. Prefer local
38
- operations for file-backed Assets: edit scripts under `assets/`; create files/folders there to
39
- upload through PlayCanvas processing; rename or move locally to preserve the remote Asset ID.
40
- Deleting locally only clears the cache, never the remote Asset. Scripts are eager and binaries are
41
- lazy; use `pcbridge workspace pull --target editor:<sceneId> --asset <id>` before editing a missing
42
- binary. Generated GLB Model/Container/material Assets and font atlases are lazy, read-only
43
- projections: edit the source Asset. Derivative edits or moves are quarantined, restored from
44
- `.pcbridge/objects`, and never uploaded. `tmp/` is never synced.
45
- After a local write, poll `workspace status` until `synced`; a brief `local-change` is expected.
46
- If it does not converge, run one `workspace sync` and inspect status plus `tmp/conflicts/`.
37
+ or sync error. Project files live under `<projectId>-<projectName>/{pcbridge.project.json,scenes,assets,tmp}`.
38
+ Inspect local files first (0 RPC) to understand the project: read `pcbridge.project.json` (scenes list,
39
+ full asset catalog, and lazy binary `meta` such as texture dimensions), read `scenes/<name>.<sceneId>.scene.json`
40
+ (DFS-ordered `entities` + `settings`), and search `scenes/` + `assets/` with `rg` before calling RPCs.
41
+
42
+ Sync is event-driven via WebSocket `workspace:delta` and targeted `fs.watch` dirty paths (zero idle polling):
43
+ - Tier 1 eager bidirectional: text assets (`script`, `text`, `json`, `html`, `css`, `shader`) and structured
44
+ JSON data assets (`material`, `template`, `cubemap`, `sprite`, `animstategraph`, `bundle`, projected as
45
+ `<name>.<type>.json`) up to the direct-sync limit (default 2 MB, adjustable 1–10 MB via the extension popup
46
+ slider or `pcbridge workspace settings --eager-max-mb <1..10>`).
47
+ - Scenes: the active open scene has `"$pcbridge": { "active": true }` (`0o644` writable, auto-reconciling
48
+ `parent <-> children`); inactive scenes have `"$pcbridge": { "active": false, "readonly": true }` (`0o444`
49
+ read-only — run `pcbridge scene open --target editor:<currentSceneId> --id <targetSceneId>` before editing).
50
+ - Structured JSON assets and the active `.scene.json` use property-path 3-way merge against `.pcbridge/baselines/`
51
+ so non-overlapping local and Editor edits merge automatically; same-path conflicts write `.local`, `.remote`,
52
+ and `.conflict.json` under `tmp/conflicts/`.
53
+ - Create files under `assets/` (including new `*.<type>.json` assets) to create remote folders/Assets; rename or
54
+ move locally to preserve the Asset ID via `$pcbridge.id`, inode, or MD5. **Deleting a local Tier 1 eagerly
55
+ synced file backs it up to `tmp/trash/local/` AND deletes the remote Asset** (delete Tier 1 files only when
56
+ remote deletion is intended). Images, models, audio, fonts, and over-limit files are Tier 2 lazy (use
57
+ `pcbridge workspace pull --target editor:<sceneId> --asset <id>` before modifying missing bytes; deleting a
58
+ pulled Tier 2 file only evicts local cache).
59
+ - Binary derivatives (`container`, `model`, font atlases) remain lazy and read-only (`0o444`), whereas structured
60
+ JSON assets linked to a source model (such as FBX/GLB-imported `material` files) are writable (`0o644`) and
61
+ keep `$pcbridge.sourceAssetId` for provenance. `tmp/` is never synced.
62
+ After a local write, allow ~0.5–1s for debounce and poll `workspace status` until `synced` (do not mix local saves
63
+ and CLI write RPCs on the same asset/scene concurrently). If it does not converge, run one `workspace sync` and
64
+ inspect status plus `tmp/conflicts/`.
47
65
  Read schema-v3 `pcbridge.project.json.assets`: `folder` is the remote display path,
48
66
  `projectionPath` is the unique local path, and `origin`/`remoteFile`/`local` describe role,
49
67
  effective metadata, presence, writability, and hashes. Only collisions gain
@@ -61,12 +79,16 @@ For the optional published Editor build, use `pcbridge frontend install latest`,
61
79
  The popup remembers that choice per project and reapplies it on later project-picker and scene
62
80
  Editor navigations; change the remembered choice only through the popup.
63
81
 
64
- 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`.
82
+ Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help core|target|workspace|processing|import|frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
65
83
 
66
- Use structured commands for scene structure, Asset metadata, explicit transfers, and verification.
67
- For normal file-content changes, prefer editing the tracked local file under `assets/`:
84
+ Prefer local file edits for scripts, shaders, text, `*.material.json` / `*.template.json` data, and multi-property
85
+ edits in the active `.scene.json`. Use structured commands for Editor pipelines (`scene open`,
86
+ `template instantiate/create/overrides/apply`, `script parse`, `import`), explicit transfers, and live verification:
68
87
 
69
88
  ```bash
89
+ pcbridge workspace settings --eager-max-mb 2
90
+ pcbridge scene list --target editor:<sceneId>
91
+ pcbridge scene open --target editor:<sceneId> --id <otherSceneId>
70
92
  pcbridge entity list --target editor:<sceneId> --limit 50
71
93
  pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set name=Player
72
94
  pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
@@ -76,27 +98,35 @@ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-
76
98
  pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
77
99
  pcbridge asset list --target editor:<sceneId> --type script
78
100
  pcbridge asset create --target editor:<sceneId> --json ./assets.json
79
- pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
80
- pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
101
+ pcbridge asset folder ensure --target editor:<sceneId> --path "My Task/Textures"
102
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "My Task/Textures"
81
103
  pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
82
- pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
83
- pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
104
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "My Task/Materials" --diffuse-map <texture_asset_id>
105
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "My Task/Templates"
84
106
  pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
85
107
  pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
86
108
  pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
87
109
  pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
88
110
  pcbridge scene settings get --target editor:<sceneId>
89
111
  pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
90
- pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
91
- pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
112
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "My Task/Scripts" --parse --wait
113
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "My Task/Scripts"
92
114
  pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
93
115
  pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
94
116
  pcbridge logs get --target launch:<sceneId> --limit 100
95
117
  pcbridge logs get --target launch:<sceneId> --level error
96
118
  ```
97
119
 
98
- Put final file-backed assets under `assets/AI Agent Bridge/<task name>/...`; keep disposable
99
- generation files under `tmp/<task name>/`.
120
+ Before creating asset folders, inspect the project's existing directory tree and comparable
121
+ resources. Prefer reusing suitable folders and follow the project's naming language, casing,
122
+ separators, hierarchy, and resource grouping when new folders are needed. Organize related assets
123
+ by task or feature within that structure; if the project groups by resource type first, preserve
124
+ that layout rather than imposing a task-first hierarchy. Do not create an `AI Agent Bridge` folder
125
+ by default. If no convention exists, use a descriptive task folder with resource subfolders as needed.
126
+
127
+ Keep final file-backed assets in the project `assets/` tree and intermediate or disposable files
128
+ under `tmp/<task name>/` so the watcher does not upload them. Paths in command examples are
129
+ illustrative; adapt them to the project's existing conventions before creating folders.
100
130
 
101
131
  Use `pcbridge launch diagnose` and `pcbridge launch wait-ready --focus` before runtime assertions.
102
132
  Launch `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context,
@@ -123,3 +153,8 @@ explicit import settings or a non-watched path is required. File arguments must
123
153
  workspace; never use `--allow-external-path` without explicit user approval.
124
154
 
125
155
  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.
156
+
157
+
158
+ ## Self-hosted local processing
159
+
160
+ Use `pcbridge help processing` and `pcbridge help import` for self-hosted conversion. Diagnose with `processing status --target editor:<sceneId>`; tools require explicit installation and `processing enable`. Do not enable local conversion on official targets. Use `import submit --asset <id> --kind model|texture --json options.json`, then `import wait --job <id> --sync-workspace`. Server `complete` means published; workspace synchronization is separate and keeps binary lazy loading. On a wait timeout query the same job before repeating a write. Browser authentication, leases and signed URLs must never be copied into CLI arguments. Extension source upgrades require regenerating the unpacked extension, reloading it in Chrome and refreshing target pages. Custom host permissions are granted by the user through the popup.