playcanvas-agent-bridge-cli 0.6.0 → 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 +117 -33
- package/README.zh-CN.md +102 -31
- package/dist/builder/manager.js +25 -2
- package/dist/cli.js +326 -46
- package/dist/config.js +1 -1
- package/dist/daemon/server.js +150 -9
- 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 +85 -30
- package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +70 -49
- package/skills/cursor/playcanvas-agent-bridge-cli.mdc +67 -28
- package/skills/windsurf/playcanvas-agent-bridge-cli.md +66 -28
|
@@ -18,7 +18,8 @@ terminal. For `LOOPBACK_ACCESS_DENIED`, retry with local-loopback permission ins
|
|
|
18
18
|
second daemon. If no PlayCanvas target appears, ask the user to run `pcbridge install-extension`,
|
|
19
19
|
load the printed directory in `chrome://extensions`, and refresh the Editor or Launch tab.
|
|
20
20
|
|
|
21
|
-
The directory
|
|
21
|
+
The current directory is the default workspace root; `daemon start/restart --workspace <directory>`
|
|
22
|
+
selects it explicitly, and `daemon stop` stops the authenticated daemon. Each ready Editor project
|
|
22
23
|
is mirrored into `<projectId>-<projectName>/` below it. After choosing an explicit target, run
|
|
23
24
|
`pcbridge workspace status --target editor:<sceneId>` and do not write while it reports a conflict
|
|
24
25
|
or sync error.
|
|
@@ -33,13 +34,17 @@ project-picker and scene Editor navigations; change the remembered mode only thr
|
|
|
33
34
|
The CLI/daemon, copied agent skills, generated Chrome extension, and custom Editor frontend update
|
|
34
35
|
independently. For an explicit update request:
|
|
35
36
|
|
|
36
|
-
1.
|
|
37
|
-
|
|
38
|
-
2. Run `npm install -g playcanvas-agent-bridge-cli@latest`, check `pcbridge version`, and rerun
|
|
37
|
+
1. Record the workspace root reported by `pcbridge daemon status`.
|
|
38
|
+
2. Run `bun add --global playcanvas-agent-bridge-cli@latest`, check `pcbridge version`, and rerun
|
|
39
39
|
`pcbridge install-skill --agent all`.
|
|
40
|
+
For a custom or project-local parent directory, use
|
|
41
|
+
`pcbridge install-skill --agent <one-agent> --path <parent-directory>`; `--path` appends the
|
|
42
|
+
standard artifact name and cannot be combined with `--agent all`.
|
|
40
43
|
3. Run `pcbridge install-extension --no-open`; the user must click **Reload** in
|
|
41
44
|
`chrome://extensions` and refresh every open Editor/Launch tab.
|
|
42
|
-
4.
|
|
45
|
+
4. Run `pcbridge daemon restart --workspace <original-root>` and verify `pcbridge doctor`. For a
|
|
46
|
+
one-time migration from a daemon without authenticated shutdown, have the user stop the old
|
|
47
|
+
daemon with Ctrl+C, then start the updated daemon with the same `--workspace` value.
|
|
43
48
|
5. Use `pcbridge frontend update` plus `frontend status` for the separately published Editor build.
|
|
44
49
|
That update is read dynamically by a running daemon, but the user must refresh the Editor page
|
|
45
50
|
and choose **Use custom frontend** in the popup if official mode is selected.
|
|
@@ -56,6 +61,8 @@ pcbridge help script
|
|
|
56
61
|
pcbridge help store
|
|
57
62
|
pcbridge help target
|
|
58
63
|
pcbridge help workspace
|
|
64
|
+
pcbridge help processing
|
|
65
|
+
pcbridge help import
|
|
59
66
|
pcbridge help frontend
|
|
60
67
|
pcbridge help entity
|
|
61
68
|
pcbridge help asset
|
|
@@ -71,23 +78,53 @@ Workspace layout:
|
|
|
71
78
|
|
|
72
79
|
```text
|
|
73
80
|
<workspace root>/<projectId>-<projectName>/
|
|
74
|
-
pcbridge.project.json # project metadata and agent-readable asset catalog
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
|
78
86
|
```
|
|
79
87
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
`
|
|
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
|
|
91
128
|
`tmp/conflicts/`, and never overwrite a conflict automatically. Local file
|
|
92
129
|
arguments must stay inside the selected project workspace. Do not use `--allow-external-path`
|
|
93
130
|
unless the user explicitly asks to use a known external file.
|
|
@@ -107,10 +144,15 @@ values. CLI equivalents are
|
|
|
107
144
|
`pcbridge builder start --target editor:<sceneId> --asset <id>` and
|
|
108
145
|
`pcbridge builder status --job <jobId>`.
|
|
109
146
|
|
|
110
|
-
|
|
111
|
-
|
|
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:
|
|
112
151
|
|
|
113
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>
|
|
114
156
|
pcbridge entity list --target editor:<sceneId> --limit 50
|
|
115
157
|
pcbridge entity create --target editor:<sceneId> --json ./entity.json
|
|
116
158
|
pcbridge entity create-many --target editor:<sceneId> --json ./entities.json
|
|
@@ -122,27 +164,35 @@ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-
|
|
|
122
164
|
pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
|
|
123
165
|
pcbridge asset list --target editor:<sceneId> --type script
|
|
124
166
|
pcbridge asset create --target editor:<sceneId> --json ./assets.json
|
|
125
|
-
pcbridge asset folder ensure --target editor:<sceneId> --path "
|
|
126
|
-
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"
|
|
127
169
|
pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
|
|
128
|
-
pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "
|
|
129
|
-
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"
|
|
130
172
|
pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
|
|
131
173
|
pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
|
|
132
174
|
pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
|
|
133
175
|
pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
|
|
134
176
|
pcbridge scene settings get --target editor:<sceneId>
|
|
135
177
|
pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
|
|
136
|
-
pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "
|
|
137
|
-
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"
|
|
138
180
|
pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
|
|
139
181
|
pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
|
|
140
182
|
pcbridge logs get --target launch:<sceneId> --limit 100
|
|
141
183
|
pcbridge logs get --target launch:<sceneId> --level error
|
|
142
184
|
```
|
|
143
185
|
|
|
144
|
-
|
|
145
|
-
|
|
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,
|
|
146
196
|
custom Editor/Engine workflows, and large multi-step scene edits:
|
|
147
197
|
|
|
148
198
|
```bash
|
|
@@ -182,3 +232,8 @@ scene edits or runtime verification. Use upload manifests only when explicit imp
|
|
|
182
232
|
non-watched source path is required, then capture under `tmp/captures/` after smoke tests.
|
|
183
233
|
|
|
184
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.
|
|
@@ -26,8 +26,10 @@ pcbridge daemon start
|
|
|
26
26
|
Do not start a second daemon for `LOOPBACK_ACCESS_DENIED`. That means the current execution
|
|
27
27
|
environment cannot access `127.0.0.1`; retry with local-loopback permission instead.
|
|
28
28
|
|
|
29
|
-
The directory where `pcbridge daemon start` runs is the workspace root
|
|
30
|
-
|
|
29
|
+
The directory where `pcbridge daemon start` runs is the default workspace root; use
|
|
30
|
+
`--workspace <directory>` to select it explicitly. Use `pcbridge daemon restart --workspace
|
|
31
|
+
<directory>` to switch roots safely, and `pcbridge daemon stop` to stop the authenticated daemon.
|
|
32
|
+
Each connected Editor project is mirrored into `<projectId>-<projectName>/` below that directory.
|
|
31
33
|
|
|
32
34
|
If no target appears, tell the user to run `pcbridge install-extension`, load the printed directory in `chrome://extensions`, then refresh the PlayCanvas Editor or Launch tab.
|
|
33
35
|
|
|
@@ -42,14 +44,18 @@ project-picker and scene Editor navigations; change the remembered mode only thr
|
|
|
42
44
|
Treat the CLI/daemon, installed agent skill, generated Chrome extension, and custom Editor frontend
|
|
43
45
|
as separate components. When the user asks to update pcbridge:
|
|
44
46
|
|
|
45
|
-
1.
|
|
46
|
-
|
|
47
|
-
2. Run `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, and reinstall
|
|
47
|
+
1. Record the current workspace root from `pcbridge daemon status`.
|
|
48
|
+
2. Run `bun add --global playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, and reinstall
|
|
48
49
|
copied skills with `pcbridge install-skill --agent all`.
|
|
50
|
+
For a custom or project-local parent directory, use
|
|
51
|
+
`pcbridge install-skill --agent <one-agent> --path <parent-directory>`; `--path` appends the
|
|
52
|
+
standard artifact name and cannot be combined with `--agent all`.
|
|
49
53
|
3. Run `pcbridge install-extension --no-open`. The user must click **Reload** for PlayCanvas Agent
|
|
50
54
|
Bridge in `chrome://extensions` and refresh open Editor/Launch tabs; rewriting the unpacked
|
|
51
55
|
directory is not enough.
|
|
52
|
-
4.
|
|
56
|
+
4. Run `pcbridge daemon restart --workspace <original-root>` and verify with `pcbridge doctor`.
|
|
57
|
+
When migrating from a daemon version without authenticated shutdown, ask the user to stop that
|
|
58
|
+
old daemon once with Ctrl+C, then start the updated daemon with the same `--workspace` value.
|
|
53
59
|
5. Update the independently published Editor build with `pcbridge frontend update`, then verify
|
|
54
60
|
`frontend status`. A frontend-only update does not require daemon restart, but the user must
|
|
55
61
|
refresh the Editor tab and select **Use custom frontend** in the popup when currently in official
|
|
@@ -63,21 +69,26 @@ steps have been acknowledged or verified.
|
|
|
63
69
|
1. Run `pcbridge targets`. Use `editor:<sceneId>` for Editor writes and `launch:<sceneId>` for
|
|
64
70
|
runtime verification; use `tab:<id>` when either selector is ambiguous.
|
|
65
71
|
2. Run `pcbridge workspace status --target editor:<sceneId>`. Do not write while it reports a conflict or sync error.
|
|
66
|
-
3.
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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.
|
|
72
82
|
|
|
73
83
|
## Workspace
|
|
74
84
|
|
|
75
85
|
```text
|
|
76
86
|
<workspace root>/<projectId>-<projectName>/
|
|
77
|
-
pcbridge.project.json # project metadata and agent-readable asset catalog
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
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
|
|
81
92
|
```
|
|
82
93
|
|
|
83
94
|
Use:
|
|
@@ -85,20 +96,24 @@ Use:
|
|
|
85
96
|
```bash
|
|
86
97
|
pcbridge workspace status --target editor:<sceneId>
|
|
87
98
|
pcbridge workspace path --target editor:<sceneId>
|
|
99
|
+
pcbridge workspace settings [--eager-max-mb <1..10>]
|
|
88
100
|
pcbridge workspace sync --target editor:<sceneId>
|
|
89
101
|
pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
|
|
90
102
|
```
|
|
91
103
|
|
|
92
|
-
|
|
104
|
+
Synchronization is event-driven via WebSocket `workspace:delta` pushes and targeted local `fs.watch` dirty paths (zero idle polling):
|
|
93
105
|
|
|
94
|
-
-
|
|
95
|
-
-
|
|
96
|
-
-
|
|
97
|
-
-
|
|
98
|
-
-
|
|
99
|
-
-
|
|
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.
|
|
100
115
|
|
|
101
|
-
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
|
|
102
117
|
`synced`. A brief yellow `local-change` is expected. Do not declare completion or alternate to
|
|
103
118
|
remote editing while the same file is pending. If it does not converge, run one explicit
|
|
104
119
|
`workspace sync`, inspect `lastError`, `lastWarning`, and `tmp/conflicts/`, and do not overwrite
|
|
@@ -124,9 +139,11 @@ Local file arguments are restricted to the selected project workspace. Never use
|
|
|
124
139
|
|
|
125
140
|
## Safe Commands
|
|
126
141
|
|
|
127
|
-
|
|
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:
|
|
128
143
|
|
|
129
144
|
```bash
|
|
145
|
+
pcbridge scene list --target editor:<sceneId>
|
|
146
|
+
pcbridge scene open --target editor:<sceneId> --id <otherSceneId>
|
|
130
147
|
pcbridge eval --target editor:<sceneId> --code "return { href: location.href, hasEditor: !!editor, entityCount: editor.api.globals.entities.list().length }"
|
|
131
148
|
```
|
|
132
149
|
|
|
@@ -169,25 +186,24 @@ Use exactly one of `--asset-id` and `--script-name`. The name form is for a Scri
|
|
|
169
186
|
by a bundle or runtime asset and therefore lacking a standalone script asset id. Verify such a
|
|
170
187
|
script in Launch; explicit script reordering is not yet a dedicated command.
|
|
171
188
|
|
|
172
|
-
Work with asset
|
|
173
|
-
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:
|
|
174
190
|
|
|
175
191
|
```bash
|
|
176
192
|
pcbridge asset list --target editor:<sceneId> --type script --limit 50
|
|
177
193
|
pcbridge asset create --target editor:<sceneId> --json ./assets.json
|
|
178
|
-
pcbridge asset folder ensure --target editor:<sceneId> --path "
|
|
179
|
-
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"
|
|
180
196
|
pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
|
|
181
197
|
pcbridge asset instantiate --target editor:<sceneId> --id <template_asset_id>
|
|
182
|
-
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>
|
|
183
199
|
pcbridge material patch --target editor:<sceneId> --asset-id <material_asset_id> --set diffuse='[1,0,0]'
|
|
184
|
-
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"
|
|
185
201
|
pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
|
|
186
202
|
pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
|
|
187
203
|
pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
|
|
188
204
|
pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
|
|
189
|
-
pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "
|
|
190
|
-
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"
|
|
191
207
|
pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./controller.js --parse --wait
|
|
192
208
|
pcbridge script parse --target editor:<sceneId> --asset-id <id>
|
|
193
209
|
```
|
|
@@ -241,16 +257,16 @@ authoritative.
|
|
|
241
257
|
|
|
242
258
|
## Asset Organization
|
|
243
259
|
|
|
244
|
-
|
|
245
|
-
|
|
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.
|
|
246
266
|
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
assets/AI Agent Bridge/<task name>/Scripts
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
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.
|
|
254
270
|
|
|
255
271
|
## Large Task Workflow
|
|
256
272
|
|
|
@@ -258,11 +274,11 @@ For multi-asset or game-sized tasks:
|
|
|
258
274
|
|
|
259
275
|
1. Choose an explicit target from `pcbridge targets`, preferably `editor:<sceneId>` for writes or
|
|
260
276
|
`launch:<sceneId>` for tests; use `tab:<id>` to resolve ambiguity.
|
|
261
|
-
2. Confirm `workspace status` is `synced`. Put disposable generation inputs under `<project>/tmp/<task name>/`.
|
|
262
|
-
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`.
|
|
263
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/`.
|
|
264
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.
|
|
265
|
-
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.
|
|
266
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/`.
|
|
267
283
|
|
|
268
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.
|
|
@@ -285,10 +301,10 @@ That verification is limited to the current Editor observer and does not prove r
|
|
|
285
301
|
For a textured scripted box, compose structured commands instead of writing one large eval:
|
|
286
302
|
|
|
287
303
|
```bash
|
|
288
|
-
pcbridge asset folder ensure --target editor:<sceneId> --path "
|
|
289
|
-
pcbridge asset upload --target editor:<sceneId> --file ./image.png --name TextureBoxImage --folder "
|
|
290
|
-
pcbridge material create --target editor:<sceneId> --name TextureBoxMaterial --folder "
|
|
291
|
-
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"
|
|
292
308
|
pcbridge entity create --target editor:<sceneId> --json ./box.json
|
|
293
309
|
pcbridge entity set-material --target editor:<sceneId> --id <box_resource_id> --material-id <material_asset_id>
|
|
294
310
|
pcbridge entity add-script --target editor:<sceneId> --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
|
|
@@ -333,3 +349,8 @@ return entities.slice(0, 20).map((entity) => ({
|
|
|
333
349
|
```
|
|
334
350
|
|
|
335
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.
|
|
@@ -17,29 +17,51 @@ pcbridge targets
|
|
|
17
17
|
Run `pcbridge daemon start` only for `DAEMON_NOT_LISTENING`; for `LOOPBACK_ACCESS_DENIED`, retry
|
|
18
18
|
with local-loopback permission. If no target appears, ask the user to install/reload the extension.
|
|
19
19
|
|
|
20
|
-
Updates are component-specific. For an explicit update request,
|
|
21
|
-
|
|
22
|
-
`
|
|
23
|
-
`pcbridge install-skill --agent all`.
|
|
20
|
+
Updates are component-specific. For an explicit update request, record the workspace root from
|
|
21
|
+
`pcbridge daemon status`. Run
|
|
22
|
+
`bun add --global playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
|
|
23
|
+
`pcbridge install-skill --agent all`. For a custom or project-local parent directory, use
|
|
24
|
+
`pcbridge install-skill --agent <one-agent> --path <parent-directory>`; it appends the standard
|
|
25
|
+
artifact name and cannot be combined with `--agent all`. Regenerate the extension with
|
|
24
26
|
`pcbridge install-extension --no-open`; the user must manually click **Reload** in
|
|
25
|
-
`chrome://extensions` and refresh Editor/Launch tabs.
|
|
26
|
-
root and verify `pcbridge doctor`.
|
|
27
|
+
`chrome://extensions` and refresh Editor/Launch tabs. Run `pcbridge daemon restart --workspace
|
|
28
|
+
<original-root>` and verify `pcbridge doctor`. A daemon version without authenticated shutdown must
|
|
29
|
+
be stopped once with Ctrl+C before starting the updated daemon. Update the independently published Editor build with
|
|
27
30
|
`pcbridge frontend update` and `frontend status`; a frontend-only update needs no daemon restart,
|
|
28
31
|
but the Editor tab must be refreshed and custom mode selected in the popup when necessary. Do not
|
|
29
32
|
claim completion before these manual steps are confirmed.
|
|
30
33
|
|
|
31
|
-
The
|
|
34
|
+
The current directory is the default workspace root; `daemon start/restart --workspace <directory>`
|
|
35
|
+
selects it explicitly, and `daemon stop` stops the authenticated daemon. After selecting a target, run
|
|
32
36
|
`pcbridge workspace status --target editor:<sceneId>` and do not write while it reports a conflict
|
|
33
|
-
or sync error. Project files live under `<projectId>-<projectName>/{assets,tmp}`.
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
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/`.
|
|
43
65
|
Read schema-v3 `pcbridge.project.json.assets`: `folder` is the remote display path,
|
|
44
66
|
`projectionPath` is the unique local path, and `origin`/`remoteFile`/`local` describe role,
|
|
45
67
|
effective metadata, presence, writability, and hashes. Only collisions gain
|
|
@@ -57,12 +79,16 @@ For the optional published Editor build, use `pcbridge frontend install latest`,
|
|
|
57
79
|
The popup remembers that choice per project and reapplies it on later project-picker and scene
|
|
58
80
|
Editor navigations; change the remembered choice only through the popup.
|
|
59
81
|
|
|
60
|
-
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`.
|
|
61
83
|
|
|
62
|
-
|
|
63
|
-
|
|
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:
|
|
64
87
|
|
|
65
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>
|
|
66
92
|
pcbridge entity list --target editor:<sceneId> --limit 50
|
|
67
93
|
pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set name=Player
|
|
68
94
|
pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
|
|
@@ -72,27 +98,35 @@ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-
|
|
|
72
98
|
pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
|
|
73
99
|
pcbridge asset list --target editor:<sceneId> --type script
|
|
74
100
|
pcbridge asset create --target editor:<sceneId> --json ./assets.json
|
|
75
|
-
pcbridge asset folder ensure --target editor:<sceneId> --path "
|
|
76
|
-
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"
|
|
77
103
|
pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
|
|
78
|
-
pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "
|
|
79
|
-
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"
|
|
80
106
|
pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
|
|
81
107
|
pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
|
|
82
108
|
pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
|
|
83
109
|
pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
|
|
84
110
|
pcbridge scene settings get --target editor:<sceneId>
|
|
85
111
|
pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
|
|
86
|
-
pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "
|
|
87
|
-
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"
|
|
88
114
|
pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
|
|
89
115
|
pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
|
|
90
116
|
pcbridge logs get --target launch:<sceneId> --limit 100
|
|
91
117
|
pcbridge logs get --target launch:<sceneId> --level error
|
|
92
118
|
```
|
|
93
119
|
|
|
94
|
-
|
|
95
|
-
|
|
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.
|
|
96
130
|
|
|
97
131
|
Use `pcbridge launch diagnose` and `pcbridge launch wait-ready --focus` before runtime assertions.
|
|
98
132
|
Launch `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context,
|
|
@@ -119,3 +153,8 @@ explicit import settings or a non-watched path is required. File arguments must
|
|
|
119
153
|
workspace; never use `--allow-external-path` without explicit user approval.
|
|
120
154
|
|
|
121
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.
|