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.
- package/README.md +79 -23
- package/README.zh-CN.md +71 -25
- package/dist/cli.js +132 -8
- package/dist/config.js +1 -1
- package/dist/daemon/server.js +79 -1
- package/dist/daemon/target-registry.js +3 -0
- package/dist/processing/manager.js +265 -0
- package/dist/processing/tools.js +97 -0
- package/dist/snippets.js +27 -0
- package/dist/workspace/json-sync.js +821 -0
- package/dist/workspace/manager.js +1973 -326
- package/extension/icons/icon-128.png +0 -0
- package/extension/icons/icon-16.png +0 -0
- package/extension/icons/icon-256.png +0 -0
- package/extension/icons/icon-32.png +0 -0
- package/extension/icons/icon-48.png +0 -0
- package/extension/isolated.js +48 -0
- package/extension/main.js +708 -39
- package/extension/manifest.json +60 -10
- package/extension/popup.html +33 -2
- package/extension/popup.js +142 -11
- package/extension/service-worker.js +124 -1
- package/package.json +19 -18
- package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +76 -26
- package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +59 -44
- package/skills/cursor/playcanvas-agent-bridge-cli.mdc +57 -22
- package/skills/windsurf/playcanvas-agent-bridge-cli.md +56 -22
|
@@ -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 `
|
|
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
|
-
|
|
81
|
-
|
|
82
|
-
|
|
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
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
`
|
|
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
|
-
|
|
116
|
-
|
|
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 "
|
|
131
|
-
pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "
|
|
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 "
|
|
134
|
-
pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "
|
|
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 "
|
|
142
|
-
pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "
|
|
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
|
-
|
|
150
|
-
|
|
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 `
|
|
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.
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
-
|
|
85
|
-
|
|
86
|
-
|
|
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
|
-
|
|
104
|
+
Synchronization is event-driven via WebSocket `workspace:delta` pushes and targeted local `fs.watch` dirty paths (zero idle polling):
|
|
99
105
|
|
|
100
|
-
-
|
|
101
|
-
-
|
|
102
|
-
-
|
|
103
|
-
-
|
|
104
|
-
-
|
|
105
|
-
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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 "
|
|
185
|
-
pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "
|
|
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 "
|
|
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 "
|
|
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 "
|
|
196
|
-
pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "
|
|
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
|
-
|
|
251
|
-
|
|
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
|
-
|
|
254
|
-
|
|
255
|
-
|
|
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.
|
|
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.
|
|
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 "
|
|
295
|
-
pcbridge asset upload --target editor:<sceneId> --file ./image.png --name TextureBoxImage --folder "
|
|
296
|
-
pcbridge material create --target editor:<sceneId> --name TextureBoxMaterial --folder "
|
|
297
|
-
pcbridge script create --target editor:<sceneId> --filename jumpingBox.js --file ./jumpingBox.js --folder "
|
|
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
|
-
`
|
|
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}`.
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
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
|
-
|
|
67
|
-
|
|
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 "
|
|
80
|
-
pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "
|
|
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 "
|
|
83
|
-
pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "
|
|
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 "
|
|
91
|
-
pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "
|
|
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
|
-
|
|
99
|
-
|
|
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.
|