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.
@@ -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, have the user stop the foreground
17
- daemon with Ctrl+C and remember its workspace-root directory; there is no `daemon stop`. Run
18
- `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
19
- `pcbridge install-skill --agent all`. Regenerate the extension with
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. Restart the daemon from the original workspace
22
- root and verify `pcbridge doctor`. Update the independently published Editor build with
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 daemon start directory is the workspace root. After selecting an explicit target, run
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}`. Prefer local
30
- operations for file-backed Assets: edit scripts under `assets/`; create files/folders there to
31
- upload through PlayCanvas processing; rename or move locally to preserve the remote Asset ID.
32
- Deleting locally only clears the cache, never the remote Asset. Scripts are eager and binaries are
33
- lazy; use `workspace pull` before editing a missing binary. Generated GLB Model/Container/material
34
- Assets and font atlases are lazy, read-only projections: edit the source Asset. Derivative edits or
35
- moves are quarantined, restored from `.pcbridge/objects`, and never uploaded. `tmp/` is never
36
- synchronized. After local writes, poll
37
- `workspace status` until `synced`; a brief `local-change` is expected. If it does not converge,
38
- run one `workspace sync` and inspect status plus `tmp/conflicts/`.
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
- Use structured commands for scene structure, Asset metadata, explicit transfers, and verification.
59
- For normal file-content changes, prefer editing the tracked local file under `assets/`:
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 "AI Agent Bridge/My Task/Textures"
73
- pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
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 "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
76
- pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
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 "AI Agent Bridge/My Task/Scripts" --parse --wait
84
- pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
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
- Put final file-backed assets under `assets/AI Agent Bridge/<task name>/...`; keep disposable
92
- generation files under `tmp/<task name>/`.
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.