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.
@@ -15,7 +15,7 @@ with local-loopback permission. If no target is connected, install/reload the un
15
15
 
16
16
  Updates are component-specific. For an explicit update request, record the workspace root from
17
17
  `pcbridge daemon status`. Run
18
- `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
18
+ `bun add --global playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
19
19
  `pcbridge install-skill --agent all`. For a custom or project-local parent directory, use
20
20
  `pcbridge install-skill --agent <one-agent> --path <parent-directory>`; it appends the standard
21
21
  artifact name and cannot be combined with `--agent all`. Regenerate the extension with
@@ -30,16 +30,33 @@ claim completion before these manual steps are confirmed.
30
30
  The current directory is the default workspace root; `daemon start/restart --workspace <directory>`
31
31
  selects it explicitly, and `daemon stop` stops the authenticated daemon. After selecting a target, run
32
32
  `pcbridge workspace status --target editor:<sceneId>` and stop if it reports a conflict or sync
33
- error. Each project is mirrored under `<projectId>-<projectName>/{assets,tmp}`. Prefer local
34
- operations for file-backed Assets: edit scripts under `assets/`; create files/folders there to
35
- upload through PlayCanvas processing; rename or move locally to preserve the remote Asset ID.
36
- Deleting locally only clears the cache, never the remote Asset. Scripts are eager and binaries are
37
- lazy; use `workspace pull` before editing a missing binary. Generated GLB Model/Container/material
38
- Assets and font atlases are lazy, read-only projections: edit the source Asset. Derivative edits or
39
- moves are quarantined, restored from `.pcbridge/objects`, and never uploaded. `tmp/` is never
40
- synchronized. After local writes, poll
41
- `workspace status` until `synced`; a brief `local-change` is expected. If it does not converge,
42
- 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/`.
43
60
  Read schema-v3 `pcbridge.project.json.assets`: `folder` is the remote display path,
44
61
  `projectionPath` is the unique local path, and `origin`/`remoteFile`/`local` describe role,
45
62
  effective metadata, presence, writability, and hashes. Only collisions gain
@@ -57,12 +74,16 @@ For the optional published Editor build, use `pcbridge frontend install latest`,
57
74
  The popup remembers that choice per project and reapplies it on later project-picker and scene
58
75
  Editor navigations; change the remembered choice only through the popup.
59
76
 
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`.
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`.
61
78
 
62
- Use structured commands for scene structure, Asset metadata, explicit transfers, and verification.
63
- 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:
64
82
 
65
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>
66
87
  pcbridge entity list --target editor:<sceneId> --limit 50
67
88
  pcbridge entity create --target editor:<sceneId> --json ./entity.json
68
89
  pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set position='[0,1,0]'
@@ -73,27 +94,35 @@ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-
73
94
  pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
74
95
  pcbridge asset list --target editor:<sceneId> --type script
75
96
  pcbridge asset create --target editor:<sceneId> --json ./assets.json
76
- pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
77
- 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"
78
99
  pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
79
- pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
80
- 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"
81
102
  pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
82
103
  pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
83
104
  pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
84
105
  pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
85
106
  pcbridge scene settings get --target editor:<sceneId>
86
107
  pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
87
- pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
88
- 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"
89
110
  pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
90
111
  pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
91
112
  pcbridge logs get --target launch:<sceneId> --limit 100
92
113
  pcbridge logs get --target launch:<sceneId> --level error
93
114
  ```
94
115
 
95
- Put final file-backed assets under `assets/AI Agent Bridge/<task name>/...`; keep disposable
96
- 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.
97
126
 
98
127
  Use `pcbridge launch diagnose` and `pcbridge launch wait-ready --focus` before runtime assertions.
99
128
  Launch `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context,
@@ -119,3 +148,8 @@ explicit import settings or a non-watched path is required. Local file arguments
119
148
  the workspace; never use `--allow-external-path` without explicit user approval.
120
149
 
121
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.