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
|
@@ -13,29 +13,50 @@ pcbridge targets
|
|
|
13
13
|
Run `pcbridge daemon start` only for `DAEMON_NOT_LISTENING`; for `LOOPBACK_ACCESS_DENIED`, retry
|
|
14
14
|
with local-loopback permission. If no target is connected, install/reload the unpacked extension.
|
|
15
15
|
|
|
16
|
-
Updates are component-specific. For an explicit update request,
|
|
17
|
-
|
|
18
|
-
`
|
|
19
|
-
`pcbridge install-skill --agent all`.
|
|
16
|
+
Updates are component-specific. For an explicit update request, record the workspace root from
|
|
17
|
+
`pcbridge daemon status`. Run
|
|
18
|
+
`bun add --global playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
|
|
19
|
+
`pcbridge install-skill --agent all`. For a custom or project-local parent directory, use
|
|
20
|
+
`pcbridge install-skill --agent <one-agent> --path <parent-directory>`; it appends the standard
|
|
21
|
+
artifact name and cannot be combined with `--agent all`. Regenerate the extension with
|
|
20
22
|
`pcbridge install-extension --no-open`; the user must manually click **Reload** in
|
|
21
|
-
`chrome://extensions` and refresh Editor/Launch tabs.
|
|
22
|
-
root and verify `pcbridge doctor`.
|
|
23
|
+
`chrome://extensions` and refresh Editor/Launch tabs. Run `pcbridge daemon restart --workspace
|
|
24
|
+
<original-root>` and verify `pcbridge doctor`. A daemon version without authenticated shutdown must
|
|
25
|
+
be stopped once with Ctrl+C before starting the updated daemon. Update the independently published Editor build with
|
|
23
26
|
`pcbridge frontend update` and `frontend status`; a frontend-only update needs no daemon restart,
|
|
24
27
|
but the Editor tab must be refreshed and custom mode selected in the popup when necessary. Do not
|
|
25
28
|
claim completion before these manual steps are confirmed.
|
|
26
29
|
|
|
27
|
-
The
|
|
30
|
+
The current directory is the default workspace root; `daemon start/restart --workspace <directory>`
|
|
31
|
+
selects it explicitly, and `daemon stop` stops the authenticated daemon. After selecting a target, run
|
|
28
32
|
`pcbridge workspace status --target editor:<sceneId>` and stop if it reports a conflict or sync
|
|
29
|
-
error. Each project is mirrored under `<projectId>-<projectName>/{assets,tmp}`.
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
`
|
|
38
|
-
|
|
33
|
+
error. Each project is mirrored under `<projectId>-<projectName>/{pcbridge.project.json,scenes,assets,tmp}`.
|
|
34
|
+
Inspect local files first (0 RPC) to understand the project: read `pcbridge.project.json` (scenes list,
|
|
35
|
+
full asset catalog, and lazy binary `meta` such as texture dimensions), read `scenes/<name>.<sceneId>.scene.json`
|
|
36
|
+
(DFS-ordered `entities` + `settings`), and search `scenes/` + `assets/` with `rg` before calling RPCs.
|
|
37
|
+
|
|
38
|
+
Sync is event-driven via WebSocket `workspace:delta` and targeted `fs.watch` dirty paths (zero idle polling):
|
|
39
|
+
- Tier 1 eager bidirectional: text assets (`script`, `text`, `json`, `html`, `css`, `shader`) and structured
|
|
40
|
+
JSON data assets (`material`, `template`, `cubemap`, `sprite`, `animstategraph`, `bundle`, projected as
|
|
41
|
+
`<name>.<type>.json`) up to the direct-sync limit (default 2 MB, adjustable 1–10 MB via the extension popup
|
|
42
|
+
slider or `pcbridge workspace settings --eager-max-mb <1..10>`).
|
|
43
|
+
- Scenes: the active open scene has `"$pcbridge": { "active": true }` (`0o644` writable, auto-reconciling
|
|
44
|
+
`parent <-> children`); inactive scenes have `"$pcbridge": { "active": false, "readonly": true }` (`0o444`
|
|
45
|
+
read-only — run `pcbridge scene open --target editor:<currentSceneId> --id <targetSceneId>` before editing).
|
|
46
|
+
- Structured JSON assets and the active `.scene.json` use property-path 3-way merge against `.pcbridge/baselines/`
|
|
47
|
+
so non-overlapping local and Editor edits merge automatically; same-path conflicts write `.local`, `.remote`,
|
|
48
|
+
and `.conflict.json` under `tmp/conflicts/`.
|
|
49
|
+
- Create files under `assets/` (including new `*.<type>.json` assets) to create remote folders/Assets; rename or
|
|
50
|
+
move locally to preserve the Asset ID via `$pcbridge.id`, inode, or MD5. **Deleting a local Tier 1 eagerly
|
|
51
|
+
synced file backs it up to `tmp/trash/local/` AND deletes the remote Asset** (delete Tier 1 files only when
|
|
52
|
+
remote deletion is intended). Images, models, audio, fonts, and over-limit files are Tier 2 lazy (use
|
|
53
|
+
`workspace pull --asset <id>` before modifying missing bytes; deleting a pulled Tier 2 file only evicts local cache).
|
|
54
|
+
- Binary derivatives (`container`, `model`, font atlases) remain lazy and read-only (`0o444`), whereas structured
|
|
55
|
+
JSON assets linked to a source model (such as FBX/GLB-imported `material` files) are writable (`0o644`) and
|
|
56
|
+
keep `$pcbridge.sourceAssetId` for provenance. `tmp/` is never synchronized.
|
|
57
|
+
After local writes, allow ~0.5–1s for debounce and poll `workspace status` until `synced` (do not mix local saves
|
|
58
|
+
and CLI write RPCs on the same asset/scene concurrently). If it does not converge, run one `workspace sync` and
|
|
59
|
+
inspect status plus `tmp/conflicts/`.
|
|
39
60
|
Read schema-v3 `pcbridge.project.json.assets`: `folder` is the remote display path,
|
|
40
61
|
`projectionPath` is the unique local path, and `origin`/`remoteFile`/`local` describe role,
|
|
41
62
|
effective metadata, presence, writability, and hashes. Only collisions gain
|
|
@@ -53,12 +74,16 @@ For the optional published Editor build, use `pcbridge frontend install latest`,
|
|
|
53
74
|
The popup remembers that choice per project and reapplies it on later project-picker and scene
|
|
54
75
|
Editor navigations; change the remembered choice only through the popup.
|
|
55
76
|
|
|
56
|
-
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`.
|
|
77
|
+
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`.
|
|
57
78
|
|
|
58
|
-
|
|
59
|
-
|
|
79
|
+
Prefer local file edits for scripts, shaders, text, `*.material.json` / `*.template.json` data, and multi-property
|
|
80
|
+
edits in the active `.scene.json`. Use structured commands for Editor pipelines (`scene open`,
|
|
81
|
+
`template instantiate/create/overrides/apply`, `script parse`, `import`), explicit transfers, and live verification:
|
|
60
82
|
|
|
61
83
|
```bash
|
|
84
|
+
pcbridge workspace settings --eager-max-mb 2
|
|
85
|
+
pcbridge scene list --target editor:<sceneId>
|
|
86
|
+
pcbridge scene open --target editor:<sceneId> --id <otherSceneId>
|
|
62
87
|
pcbridge entity list --target editor:<sceneId> --limit 50
|
|
63
88
|
pcbridge entity create --target editor:<sceneId> --json ./entity.json
|
|
64
89
|
pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set position='[0,1,0]'
|
|
@@ -69,27 +94,35 @@ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-
|
|
|
69
94
|
pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
|
|
70
95
|
pcbridge asset list --target editor:<sceneId> --type script
|
|
71
96
|
pcbridge asset create --target editor:<sceneId> --json ./assets.json
|
|
72
|
-
pcbridge asset folder ensure --target editor:<sceneId> --path "
|
|
73
|
-
pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "
|
|
97
|
+
pcbridge asset folder ensure --target editor:<sceneId> --path "My Task/Textures"
|
|
98
|
+
pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "My Task/Textures"
|
|
74
99
|
pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
|
|
75
|
-
pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "
|
|
76
|
-
pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "
|
|
100
|
+
pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "My Task/Materials" --diffuse-map <texture_asset_id>
|
|
101
|
+
pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "My Task/Templates"
|
|
77
102
|
pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
|
|
78
103
|
pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
|
|
79
104
|
pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
|
|
80
105
|
pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
|
|
81
106
|
pcbridge scene settings get --target editor:<sceneId>
|
|
82
107
|
pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
|
|
83
|
-
pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "
|
|
84
|
-
pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "
|
|
108
|
+
pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "My Task/Scripts" --parse --wait
|
|
109
|
+
pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "My Task/Scripts"
|
|
85
110
|
pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
|
|
86
111
|
pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
|
|
87
112
|
pcbridge logs get --target launch:<sceneId> --limit 100
|
|
88
113
|
pcbridge logs get --target launch:<sceneId> --level error
|
|
89
114
|
```
|
|
90
115
|
|
|
91
|
-
|
|
92
|
-
|
|
116
|
+
Before creating asset folders, inspect the project's existing directory tree and comparable
|
|
117
|
+
resources. Prefer reusing suitable folders and follow the project's naming language, casing,
|
|
118
|
+
separators, hierarchy, and resource grouping when new folders are needed. Organize related assets
|
|
119
|
+
by task or feature within that structure; if the project groups by resource type first, preserve
|
|
120
|
+
that layout rather than imposing a task-first hierarchy. Do not create an `AI Agent Bridge` folder
|
|
121
|
+
by default. If no convention exists, use a descriptive task folder with resource subfolders as needed.
|
|
122
|
+
|
|
123
|
+
Keep final file-backed assets in the project `assets/` tree and intermediate or disposable files
|
|
124
|
+
under `tmp/<task name>/` so the watcher does not upload them. Paths in command examples are
|
|
125
|
+
illustrative; adapt them to the project's existing conventions before creating folders.
|
|
93
126
|
|
|
94
127
|
Use `pcbridge launch diagnose` and `pcbridge launch wait-ready --focus` before runtime assertions.
|
|
95
128
|
Launch `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context,
|
|
@@ -115,3 +148,8 @@ explicit import settings or a non-watched path is required. Local file arguments
|
|
|
115
148
|
the workspace; never use `--allow-external-path` without explicit user approval.
|
|
116
149
|
|
|
117
150
|
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.
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
## Self-hosted local processing
|
|
154
|
+
|
|
155
|
+
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.
|