playcanvas-agent-bridge-cli 0.6.1 → 0.7.0

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.
Files changed (42) hide show
  1. package/README.md +148 -31
  2. package/README.zh-CN.md +137 -33
  3. package/dist/cli.js +514 -95
  4. package/dist/config.js +23 -1
  5. package/dist/daemon/server.js +336 -28
  6. package/dist/daemon/target-registry.js +3 -0
  7. package/dist/plugins/host.js +260 -0
  8. package/dist/plugins/store.js +567 -0
  9. package/dist/processing/manager.js +265 -0
  10. package/dist/processing/tools.js +97 -0
  11. package/dist/snippets.js +27 -0
  12. package/dist/updates.js +475 -0
  13. package/dist/workspace/json-sync.js +821 -0
  14. package/dist/workspace/manager.js +1973 -326
  15. package/extension/icons/icon-128.png +0 -0
  16. package/extension/icons/icon-16.png +0 -0
  17. package/extension/icons/icon-256.png +0 -0
  18. package/extension/icons/icon-32.png +0 -0
  19. package/extension/icons/icon-48.png +0 -0
  20. package/extension/isolated.js +59 -2
  21. package/extension/main.js +770 -275
  22. package/extension/manifest.json +60 -10
  23. package/extension/popup.html +115 -3
  24. package/extension/popup.js +398 -14
  25. package/extension/service-worker.js +221 -4
  26. package/package.json +18 -18
  27. package/plugins/index.json +14 -0
  28. package/plugins/tinyapp-builder/node/builder.js +589 -0
  29. package/plugins/tinyapp-builder/node/index.js +30 -0
  30. package/plugins/tinyapp-builder/package.json +13 -0
  31. package/plugins/tinyapp-builder/page/editor.js +249 -0
  32. package/plugins/tinyapp-builder/pcbridge-plugin.json +28 -0
  33. package/skills/claude/pcbridge-plugin-authoring/SKILL.md +220 -0
  34. package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +99 -43
  35. package/skills/codex/pcbridge-plugin-authoring/SKILL.md +220 -0
  36. package/skills/codex/pcbridge-plugin-authoring/agents/openai.yaml +4 -0
  37. package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +89 -62
  38. package/skills/cursor/pcbridge-plugin-authoring.mdc +221 -0
  39. package/skills/cursor/playcanvas-agent-bridge-cli.mdc +69 -33
  40. package/skills/windsurf/pcbridge-plugin-authoring.md +215 -0
  41. package/skills/windsurf/playcanvas-agent-bridge-cli.md +68 -33
  42. package/dist/builder/manager.js +0 -564
@@ -17,38 +17,57 @@ 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, record the workspace root from
21
- `pcbridge daemon status`. Run
22
- `npm install -g 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
26
- `pcbridge install-extension --no-open`; the user must manually click **Reload** in
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
20
+ CLI responses attach `meta.updates` when a newer `pcbridge` release, local component version mismatch,
21
+ or official plugin update is available. Check updates with `pcbridge update status --refresh` or
22
+ `pcbridge plugin list --refresh`. Apply a one-click core update with `pcbridge update` (or
23
+ `pcbridge update --plugins`), which upgrades the global package, refreshes installed skills,
24
+ rewrites `~/.pcbridge/extension`, triggers Chrome extension reload + PlayCanvas tab refresh
25
+ (`--no-reload-tabs` skips tab refresh), and restarts the running daemon in-place. Update official
26
+ plugins independently without restarting the daemon via `pcbridge plugin update <id>` or
27
+ `pcbridge plugin update --all` (or the extension popup **Plugins** tab). Update the independently published Editor build with
30
28
  `pcbridge frontend update` and `frontend status`; a frontend-only update needs no daemon restart,
31
- but the Editor tab must be refreshed and custom mode selected in the popup when necessary. Do not
32
- claim completion before these manual steps are confirmed.
29
+ but the Editor tab must be refreshed and custom mode selected in the popup when necessary.
33
30
 
34
31
  The current directory is the default workspace root; `daemon start/restart --workspace <directory>`
35
32
  selects it explicitly, and `daemon stop` stops the authenticated daemon. After selecting a target, run
36
33
  `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}`. Prefer local
38
- operations for file-backed Assets: edit scripts under `assets/`; create files/folders there to
39
- upload through PlayCanvas processing; rename or move locally to preserve the remote Asset ID.
40
- Deleting locally only clears the cache, never the remote Asset. Scripts are eager and binaries are
41
- lazy; use `pcbridge workspace pull --target editor:<sceneId> --asset <id>` before editing a missing
42
- binary. Generated GLB Model/Container/material Assets and font atlases are lazy, read-only
43
- projections: edit the source Asset. Derivative edits or moves are quarantined, restored from
44
- `.pcbridge/objects`, and never uploaded. `tmp/` is never synced.
45
- After a local write, poll `workspace status` until `synced`; a brief `local-change` is expected.
46
- If it does not converge, run one `workspace sync` and inspect status plus `tmp/conflicts/`.
34
+ or sync error. Project files live under `<projectId>-<projectName>/{pcbridge.project.json,scenes,assets,tmp}`.
35
+ Inspect local files first (0 RPC) to understand the project: read `pcbridge.project.json` (scenes list,
36
+ full asset catalog, and lazy binary `meta` such as texture dimensions), read `scenes/<name>.<sceneId>.scene.json`
37
+ (DFS-ordered `entities` + `settings`), and search `scenes/` + `assets/` with `rg` before calling RPCs.
38
+
39
+ Sync is event-driven via WebSocket `workspace:delta` and targeted `fs.watch` dirty paths (zero idle polling):
40
+ - Tier 1 eager bidirectional: text assets (`script`, `text`, `json`, `html`, `css`, `shader`) and structured
41
+ JSON data assets (`material`, `template`, `cubemap`, `sprite`, `animstategraph`, `bundle`, projected as
42
+ `<name>.<type>.json`) up to the direct-sync limit (default 2 MB, adjustable 1–10 MB via the extension popup
43
+ slider or `pcbridge workspace settings --eager-max-mb <1..10>`).
44
+ - Scenes: the active open scene has `"$pcbridge": { "active": true }` (`0o644` writable, auto-reconciling
45
+ `parent <-> children`); inactive scenes have `"$pcbridge": { "active": false, "readonly": true }` (`0o444`
46
+ read-only — run `pcbridge scene open --target editor:<currentSceneId> --id <targetSceneId>` before editing).
47
+ - Structured JSON assets and the active `.scene.json` use property-path 3-way merge against `.pcbridge/baselines/`
48
+ so non-overlapping local and Editor edits merge automatically; same-path conflicts write `.local`, `.remote`,
49
+ and `.conflict.json` under `tmp/conflicts/`.
50
+ - Create files under `assets/` (including new `*.<type>.json` assets) to create remote folders/Assets; rename or
51
+ move locally to preserve the Asset ID via `$pcbridge.id`, inode, or MD5. **Deleting a local Tier 1 eagerly
52
+ synced file backs it up to `tmp/trash/local/` AND deletes the remote Asset** (delete Tier 1 files only when
53
+ remote deletion is intended). Images, models, audio, fonts, and over-limit files are Tier 2 lazy (use
54
+ `pcbridge workspace pull --target editor:<sceneId> --asset <id>` before modifying missing bytes; deleting a
55
+ pulled Tier 2 file only evicts local cache).
56
+ - Binary derivatives (`container`, `model`, font atlases) remain lazy and read-only (`0o444`), whereas structured
57
+ JSON assets linked to a source model (such as FBX/GLB-imported `material` files) are writable (`0o644`) and
58
+ keep `$pcbridge.sourceAssetId` for provenance. `tmp/` is never synced.
59
+ After a local write, allow ~0.5–1s for debounce and poll `workspace status` until `synced` (do not mix local saves
60
+ and CLI write RPCs on the same asset/scene concurrently). If it does not converge, run one `workspace sync` and
61
+ inspect status plus `tmp/conflicts/`.
47
62
  Read schema-v3 `pcbridge.project.json.assets`: `folder` is the remote display path,
48
63
  `projectionPath` is the unique local path, and `origin`/`remoteFile`/`local` describe role,
49
64
  effective metadata, presence, writability, and hashes. Only collisions gain
50
65
  `.__pc_<type>_<assetId>`. Treat that asset catalog as pcbridge-managed. Confirmed remote
51
66
  deletions are quarantined under `tmp/trash/remote/`; `tmp/conflicts/` contains content divergence.
67
+ Optional features ship as plugins: `pcbridge plugin list` shows installed and available plugins with
68
+ their actions, and `pcbridge plugin call <id> <action> --target editor:<sceneId> --params '<json>'`
69
+ runs one. Use the pcbridge-plugin-authoring rule to create or change a plugin.
70
+ With the official `tinyapp-builder` plugin enabled (`pcbridge plugin add tinyapp-builder`),
52
71
  Template selection exposes pcbridge Tiny Builder for direct S3 object uploads; project `.env`
53
72
  overrides workspace-root `.env`. A build materializes every primary dependency plus texture
54
73
  variants and additional font maps under the Asset's remote folder in `assets/`, then uploads only
@@ -61,12 +80,16 @@ For the optional published Editor build, use `pcbridge frontend install latest`,
61
80
  The popup remembers that choice per project and reapplies it on later project-picker and scene
62
81
  Editor navigations; change the remembered choice only through the popup.
63
82
 
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`.
83
+ Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help core|target|workspace|plugin|processing|import|frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
65
84
 
66
- Use structured commands for scene structure, Asset metadata, explicit transfers, and verification.
67
- For normal file-content changes, prefer editing the tracked local file under `assets/`:
85
+ Prefer local file edits for scripts, shaders, text, `*.material.json` / `*.template.json` data, and multi-property
86
+ edits in the active `.scene.json`. Use structured commands for Editor pipelines (`scene open`,
87
+ `template instantiate/create/overrides/apply`, `script parse`, `import`), explicit transfers, and live verification:
68
88
 
69
89
  ```bash
90
+ pcbridge workspace settings --eager-max-mb 2
91
+ pcbridge scene list --target editor:<sceneId>
92
+ pcbridge scene open --target editor:<sceneId> --id <otherSceneId>
70
93
  pcbridge entity list --target editor:<sceneId> --limit 50
71
94
  pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set name=Player
72
95
  pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
@@ -76,27 +99,35 @@ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-
76
99
  pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
77
100
  pcbridge asset list --target editor:<sceneId> --type script
78
101
  pcbridge asset create --target editor:<sceneId> --json ./assets.json
79
- pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
80
- pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
102
+ pcbridge asset folder ensure --target editor:<sceneId> --path "My Task/Textures"
103
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "My Task/Textures"
81
104
  pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
82
- pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
83
- pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
105
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "My Task/Materials" --diffuse-map <texture_asset_id>
106
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "My Task/Templates"
84
107
  pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
85
108
  pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
86
109
  pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
87
110
  pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
88
111
  pcbridge scene settings get --target editor:<sceneId>
89
112
  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 "AI Agent Bridge/My Task/Scripts" --parse --wait
91
- pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
113
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "My Task/Scripts" --parse --wait
114
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "My Task/Scripts"
92
115
  pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
93
116
  pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
94
117
  pcbridge logs get --target launch:<sceneId> --limit 100
95
118
  pcbridge logs get --target launch:<sceneId> --level error
96
119
  ```
97
120
 
98
- Put final file-backed assets under `assets/AI Agent Bridge/<task name>/...`; keep disposable
99
- generation files under `tmp/<task name>/`.
121
+ Before creating asset folders, inspect the project's existing directory tree and comparable
122
+ resources. Prefer reusing suitable folders and follow the project's naming language, casing,
123
+ separators, hierarchy, and resource grouping when new folders are needed. Organize related assets
124
+ by task or feature within that structure; if the project groups by resource type first, preserve
125
+ that layout rather than imposing a task-first hierarchy. Do not create an `AI Agent Bridge` folder
126
+ by default. If no convention exists, use a descriptive task folder with resource subfolders as needed.
127
+
128
+ Keep final file-backed assets in the project `assets/` tree and intermediate or disposable files
129
+ under `tmp/<task name>/` so the watcher does not upload them. Paths in command examples are
130
+ illustrative; adapt them to the project's existing conventions before creating folders.
100
131
 
101
132
  Use `pcbridge launch diagnose` and `pcbridge launch wait-ready --focus` before runtime assertions.
102
133
  Launch `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context,
@@ -123,3 +154,8 @@ explicit import settings or a non-watched path is required. File arguments must
123
154
  workspace; never use `--allow-external-path` without explicit user approval.
124
155
 
125
156
  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.
157
+
158
+
159
+ ## Self-hosted local processing
160
+
161
+ 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.
@@ -0,0 +1,215 @@
1
+ # pcbridge Plugin Authoring
2
+
3
+ A pcbridge plugin is an optional package that users add, enable, disable, and remove
4
+ independently. It is **not** the Chrome extension: the extension is a fixed part of pcbridge,
5
+ while plugins are loaded by the pcbridge daemon and delivered to pages through that extension.
6
+ Different users enable different plugins (a modeller's Blender sync, a programmer's Editor
7
+ buttons), so never add plugin features to pcbridge core or to the extension source.
8
+
9
+ ## Where plugin code runs
10
+
11
+ | Runtime | Entry in the manifest | Runs in | Use it for |
12
+ | --- | --- | --- | --- |
13
+ | node | `node` | The local pcbridge daemon (Bun) | Files, network, credentials, child processes, local apps (Blender, DCC tools), heavy work |
14
+ | page | `page.editor`, `page.launch` | The PlayCanvas Editor / Launch page (MAIN world) | Editor UI, `editor.api.globals` reads and writes, runtime inspection |
15
+ | extension | none | Isolated world, service worker, popup | Not extensible. It only relays messages and hosts the **Plugins** management tab |
16
+
17
+ Plugins cannot ship code into the extension runtime: Manifest V3 forbids running code that is not
18
+ packaged with the extension, and that runtime holds the daemon session token. A page script
19
+ therefore has no `chrome.*` API and no token; anything privileged goes through a node action.
20
+
21
+ ```text
22
+ pcbridge plugin call <id> <action> ─┐
23
+ page: plugin.call(action, params) ─┴─> node: plugin.handle(action, fn)
24
+ node: plugin.callPage(target, name, params) ──> page: plugin.handle(name, fn)
25
+ ```
26
+
27
+ ## Package layout
28
+
29
+ ```text
30
+ my-plugin/
31
+ pcbridge-plugin.json # manifest (required)
32
+ node/index.js # optional node entry
33
+ page/editor.js # optional Editor page script
34
+ page/launch.js # optional Launch page script
35
+ package.json # optional; only when the node side has npm dependencies
36
+ ```
37
+
38
+ `pcbridge-plugin.json`:
39
+
40
+ ```json
41
+ {
42
+ "id": "my-plugin",
43
+ "name": "My Plugin",
44
+ "version": "1.0.0",
45
+ "apiVersion": 1,
46
+ "minPcbridgeVersion": "0.7.0",
47
+ "description": "One sentence shown in plugin lists.",
48
+ "node": "node/index.js",
49
+ "page": { "editor": "page/editor.js", "launch": "page/launch.js" },
50
+ "actions": {
51
+ "export": {
52
+ "description": "What the action does and returns.",
53
+ "params": { "assetId": "Asset id (required).", "format": "glb or fbx; default glb." }
54
+ }
55
+ }
56
+ }
57
+ ```
58
+
59
+ Manifest rules:
60
+
61
+ - `id`: 2-49 characters, lowercase letters, digits, and hyphens. It names the plugin in the CLI,
62
+ in RPC routes, and in the install directory; never change it after release.
63
+ - `name`, `version` (semantic version), and `apiVersion: 1` are required.
64
+ - `minPcbridgeVersion` (optional semantic version) declares the minimum `pcbridge` core version required to install or update this plugin.
65
+ - At least one of `node`, `page.editor`, `page.launch` is required. Every entry is a relative path
66
+ to an existing file inside the plugin directory.
67
+ - `actions` documents the node actions for other agents (`pcbridge plugin info <id>`). Keep it in
68
+ step with the `plugin.handle` calls in the node entry.
69
+ - Bump `version` on every released change.
70
+
71
+ ## Node entry
72
+
73
+ An ES module (JavaScript or TypeScript; the daemon runs on Bun) that exports `activate(plugin)`.
74
+ `activate` may be async. It runs when the daemon starts and whenever the plugin is added, enabled,
75
+ updated, or reloaded.
76
+
77
+ ```js
78
+ export function activate(plugin) {
79
+ plugin.handle("export", async (params, { target }) => {
80
+ if (!target || target.kind !== "editor") throw new Error("export requires an Editor target.");
81
+ const selection = await plugin.callPage(target, "selection");
82
+ return { exported: selection.length };
83
+ });
84
+ const timer = setInterval(() => { /* ... */ }, 5000);
85
+ plugin.onDispose(() => clearInterval(timer));
86
+ }
87
+ ```
88
+
89
+ | Member | Purpose |
90
+ | --- | --- |
91
+ | `plugin.id`, `plugin.version`, `plugin.dir` | Identity and the absolute plugin directory |
92
+ | `plugin.handle(name, fn)` | Register an action. `fn(params, { target })` returns JSON-serializable data or throws an `Error` (an optional string `code` becomes the CLI error code) |
93
+ | `plugin.callPage(target, name, params?, timeoutMs?)` | Call a handler registered by this plugin's page script; resolves with its result |
94
+ | `plugin.rpc(target, method, params?, timeoutMs?)` | Call a built-in bridge method, for example `bridge:eval` with `{ code, args }` |
95
+ | `plugin.targets()` | Connected targets (`id`, `kind`, `ready`, `projectId`, `sceneId`, ...) for node-initiated work |
96
+ | `plugin.workspace.rootDir` | The daemon workspace root |
97
+ | `plugin.workspace.status(target)` | Workspace status, including `projectDirectory` and `tmpDirectory` |
98
+ | `plugin.workspace.prepareAssetFiles(target, assetIds)` | Materialize asset files locally; returns `{ projectDirectory, tmpDirectory, assets: [{ id, name, type, filename, path, hash }] }` |
99
+ | `plugin.workspace.prepareAssetResources(target, requests)` | Materialize auxiliary files such as texture variants: `[{ assetId, filename, url, hash? }]` |
100
+ | `plugin.log(message)` | Write to the daemon log |
101
+ | `plugin.onDispose(fn)` | Register cleanup; runs on disable, remove, reload, update, and daemon stop |
102
+
103
+ `target` in an action context is the `--target` of the CLI call, the calling tab for a page call,
104
+ otherwise the most recent ready target, otherwise `null`. Functions that take a target accept that
105
+ object or a selector string such as `tab:5` or `editor:<sceneId>`.
106
+
107
+ ## Page script
108
+
109
+ A single classic script. pcbridge runs its text as the body of an async function once the target
110
+ is ready (Editor: `editor.api.globals` exists; Launch: the app has started in a visible tab), with
111
+ `plugin`, `editor`, `pc`, `pcui`, and `runtimeApp` in scope. `import` and `export` are not
112
+ available; bundle to one file if you need modules.
113
+
114
+ ```js
115
+ const button = new pcui.Button({ text: "Export selection" });
116
+ button.class.add("my-plugin-export");
117
+ editor.call("layout.toolbar").append(button);
118
+ button.on("click", async () => {
119
+ const result = await plugin.call("export", { format: "glb" });
120
+ console.info("[my-plugin] exported", result.exported);
121
+ });
122
+
123
+ plugin.handle("selection", () =>
124
+ editor.api.globals.selection.items.map((item) => String(item.get("resource_id") || item.get("id"))));
125
+
126
+ plugin.onDispose(() => button.destroy());
127
+ ```
128
+
129
+ | Member | Purpose |
130
+ | --- | --- |
131
+ | `plugin.id`, `plugin.version`, `plugin.kind` | Identity; `kind` is `"editor"` or `"launch"` |
132
+ | `plugin.handle(name, fn)` | Register a handler for `plugin.callPage` on the node side; return plain JSON |
133
+ | `plugin.call(action, params?, timeoutMs?)` | Call a node action of the same plugin; the target is this tab |
134
+ | `plugin.onDispose(fn)` | Register cleanup; runs when the plugin is disabled, removed, or its code changes |
135
+
136
+ Enabling, disabling, and reloading take effect in open pages immediately; no page refresh is
137
+ needed. A script whose text is unchanged is not re-run.
138
+
139
+ ## Rules
140
+
141
+ 1. **Split by capability.** Credentials, file paths, and network calls to other services stay in
142
+ node. Page scripts only touch the page. Never send secrets to a page or return them from an
143
+ action.
144
+ 2. **Everything is disposable.** Whatever `activate` or a page script creates (timers, sockets,
145
+ servers, child processes, DOM and pcui elements, event subscriptions via `handle.unbind()`)
146
+ must be undone in `onDispose`. A reload must not leave duplicates.
147
+ 3. **Top level must be fast.** Page activation times out after 10 seconds and `activate` blocks
148
+ other plugin operations; start long work in the background and report it through an action
149
+ such as `status`.
150
+ 4. **Plain JSON across boundaries.** Never return Observers, Entities, DOM nodes, or class
151
+ instances. Pass asset ids and local paths instead of file contents.
152
+ 5. **Catch errors in your own callbacks.** An uncaught exception in a node timer or socket callback
153
+ can stop the daemon. If a plugin prevents the daemon from starting, stop the daemon and run
154
+ `pcbridge plugin disable <id>`; management commands work on disk while the daemon is down.
155
+ 6. **Namespace by plugin id.** CSS classes, `localStorage` keys, and global names start with the id.
156
+ 7. **Feature-detect Editor and Engine APIs** and use `{ history: true }` for Editor mutations when
157
+ available, as in `pcbridge eval` snippets.
158
+ 8. **Declare npm dependencies** in the plugin's own `package.json` `dependencies`. pcbridge runs
159
+ `bun install --production` when the plugin is added or updated. For `--link` plugins run
160
+ `bun install` in the directory yourself. Do not rely on pcbridge's own dependencies.
161
+ 9. Keep plugin source outside any project `assets/` directory; the workspace watcher uploads files
162
+ created there.
163
+
164
+ ## Develop and verify
165
+
166
+ ```bash
167
+ pcbridge plugin add ./my-plugin --link # use the directory in place
168
+ pcbridge plugin list # state must be "active"; read error and pages[]
169
+ pcbridge plugin call my-plugin export --target editor:<sceneId> --params '{"format":"glb"}'
170
+ pcbridge plugin reload my-plugin # after every edit to node or page files
171
+ pcbridge eval --target editor:<sceneId> --code "return !!document.querySelector('.my-plugin-export')"
172
+ pcbridge logs get --target editor:<sceneId> --level error
173
+ ```
174
+
175
+ `plugin list` and `plugin info <id>` report `state` (`active`, `error`, `disabled`, or `stopped`
176
+ when the daemon is not running), the node activation `error`, and one `pages[]` entry per connected
177
+ target with the page script result. Treat a plugin as working only when the state is `active`,
178
+ every `pages[]` entry is `ok`, each action returns the expected data, and the page effect is
179
+ confirmed with `eval` or a viewport capture. `--params-json <file>` reads parameters from a file
180
+ inside the project workspace.
181
+
182
+ Other management commands, also available in the extension popup under **Plugins**:
183
+
184
+ ```bash
185
+ pcbridge plugin enable|disable|remove <id>
186
+ pcbridge plugin update <id> # re-fetch from the recorded source, reinstall dependencies, reload
187
+ pcbridge plugin update --all # update all outdated installed plugins
188
+ pcbridge plugin list --refresh # refresh remote official plugin catalog and versions
189
+ pcbridge help plugin
190
+ ```
191
+
192
+ ## Distribute through GitHub
193
+
194
+ Publish the plugin directory in a public GitHub repository, at the root or in a subdirectory, and
195
+ tag releases. Users install and update with:
196
+
197
+ ```bash
198
+ pcbridge plugin add github:<owner>/<repo> # default branch, plugin at the root
199
+ pcbridge plugin add github:<owner>/<repo>/plugins/my-plugin#v1.2.0 # subdirectory, pinned tag
200
+ pcbridge plugin update my-plugin # same source and ref again
201
+ ```
202
+
203
+ A source without `#ref` follows the default branch, so `update` picks up new commits; a pinned
204
+ `#ref` only changes when the plugin is removed and added again with another ref. Commit built
205
+ output if the plugin needs a build step, because pcbridge installs the repository files as they
206
+ are. Plugins run with full local and page access; tell users to add only sources they trust.
207
+
208
+ ## Reference implementation
209
+
210
+ `tinyapp-builder` is the official plugin shipped with pcbridge (`pcbridge plugin add
211
+ tinyapp-builder`, source under `plugins/tinyapp-builder/` of the pcbridge package). It shows a
212
+ node entry with background jobs and npm dependencies, an Editor page script that injects an
213
+ Inspector panel and serves `callPage` requests, and a complete `actions` section.
214
+ When adding or bumping an official plugin under `plugins/<id>/`, run `bun run plugins:sync` to
215
+ synchronize `plugins/index.json` (`bun run check:version` enforces this).
@@ -13,38 +13,56 @@ 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, record the workspace root from
17
- `pcbridge daemon status`. Run
18
- `npm install -g 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
22
- `pcbridge install-extension --no-open`; the user must manually click **Reload** in
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
16
+ CLI responses attach `meta.updates` when a newer `pcbridge` release, local component version mismatch,
17
+ or official plugin update is available. Check updates with `pcbridge update status --refresh` or
18
+ `pcbridge plugin list --refresh`. Apply a one-click core update with `pcbridge update` (or
19
+ `pcbridge update --plugins`), which upgrades the global package, refreshes installed skills,
20
+ rewrites `~/.pcbridge/extension`, triggers Chrome extension reload + PlayCanvas tab refresh
21
+ (`--no-reload-tabs` skips tab refresh), and restarts the running daemon in-place. Update official
22
+ plugins independently without restarting the daemon via `pcbridge plugin update <id>` or
23
+ `pcbridge plugin update --all` (or the extension popup **Plugins** tab). Update the independently published Editor build with
26
24
  `pcbridge frontend update` and `frontend status`; a frontend-only update needs no daemon restart,
27
- but the Editor tab must be refreshed and custom mode selected in the popup when necessary. Do not
28
- claim completion before these manual steps are confirmed.
25
+ but the Editor tab must be refreshed and custom mode selected in the popup when necessary.
29
26
 
30
27
  The current directory is the default workspace root; `daemon start/restart --workspace <directory>`
31
28
  selects it explicitly, and `daemon stop` stops the authenticated daemon. After selecting a target, run
32
29
  `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/`.
30
+ error. Each project is mirrored under `<projectId>-<projectName>/{pcbridge.project.json,scenes,assets,tmp}`.
31
+ Inspect local files first (0 RPC) to understand the project: read `pcbridge.project.json` (scenes list,
32
+ full asset catalog, and lazy binary `meta` such as texture dimensions), read `scenes/<name>.<sceneId>.scene.json`
33
+ (DFS-ordered `entities` + `settings`), and search `scenes/` + `assets/` with `rg` before calling RPCs.
34
+
35
+ Sync is event-driven via WebSocket `workspace:delta` and targeted `fs.watch` dirty paths (zero idle polling):
36
+ - Tier 1 eager bidirectional: text assets (`script`, `text`, `json`, `html`, `css`, `shader`) and structured
37
+ JSON data assets (`material`, `template`, `cubemap`, `sprite`, `animstategraph`, `bundle`, projected as
38
+ `<name>.<type>.json`) up to the direct-sync limit (default 2 MB, adjustable 1–10 MB via the extension popup
39
+ slider or `pcbridge workspace settings --eager-max-mb <1..10>`).
40
+ - Scenes: the active open scene has `"$pcbridge": { "active": true }` (`0o644` writable, auto-reconciling
41
+ `parent <-> children`); inactive scenes have `"$pcbridge": { "active": false, "readonly": true }` (`0o444`
42
+ read-only — run `pcbridge scene open --target editor:<currentSceneId> --id <targetSceneId>` before editing).
43
+ - Structured JSON assets and the active `.scene.json` use property-path 3-way merge against `.pcbridge/baselines/`
44
+ so non-overlapping local and Editor edits merge automatically; same-path conflicts write `.local`, `.remote`,
45
+ and `.conflict.json` under `tmp/conflicts/`.
46
+ - Create files under `assets/` (including new `*.<type>.json` assets) to create remote folders/Assets; rename or
47
+ move locally to preserve the Asset ID via `$pcbridge.id`, inode, or MD5. **Deleting a local Tier 1 eagerly
48
+ synced file backs it up to `tmp/trash/local/` AND deletes the remote Asset** (delete Tier 1 files only when
49
+ remote deletion is intended). Images, models, audio, fonts, and over-limit files are Tier 2 lazy (use
50
+ `workspace pull --asset <id>` before modifying missing bytes; deleting a pulled Tier 2 file only evicts local cache).
51
+ - Binary derivatives (`container`, `model`, font atlases) remain lazy and read-only (`0o444`), whereas structured
52
+ JSON assets linked to a source model (such as FBX/GLB-imported `material` files) are writable (`0o644`) and
53
+ keep `$pcbridge.sourceAssetId` for provenance. `tmp/` is never synchronized.
54
+ After local writes, allow ~0.5–1s for debounce and poll `workspace status` until `synced` (do not mix local saves
55
+ and CLI write RPCs on the same asset/scene concurrently). If it does not converge, run one `workspace sync` and
56
+ inspect status plus `tmp/conflicts/`.
43
57
  Read schema-v3 `pcbridge.project.json.assets`: `folder` is the remote display path,
44
58
  `projectionPath` is the unique local path, and `origin`/`remoteFile`/`local` describe role,
45
59
  effective metadata, presence, writability, and hashes. Only collisions gain
46
60
  `.__pc_<type>_<assetId>`. Treat that asset catalog as pcbridge-managed. Confirmed remote
47
61
  deletions are quarantined under `tmp/trash/remote/`; `tmp/conflicts/` contains content divergence.
62
+ Optional features ship as plugins: `pcbridge plugin list` shows installed and available plugins with
63
+ their actions, and `pcbridge plugin call <id> <action> --target editor:<sceneId> --params '<json>'`
64
+ runs one. Use the pcbridge-plugin-authoring rule to create or change a plugin.
65
+ With the official `tinyapp-builder` plugin enabled (`pcbridge plugin add tinyapp-builder`),
48
66
  Template selection exposes pcbridge Tiny Builder for direct S3 object uploads; project `.env`
49
67
  overrides workspace-root `.env`. A build materializes every primary dependency plus texture
50
68
  variants and additional font maps under the Asset's remote folder in `assets/`, then uploads only
@@ -57,12 +75,16 @@ For the optional published Editor build, use `pcbridge frontend install latest`,
57
75
  The popup remembers that choice per project and reapplies it on later project-picker and scene
58
76
  Editor navigations; change the remembered choice only through the popup.
59
77
 
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`.
78
+ Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help core|target|workspace|plugin|processing|import|frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
61
79
 
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/`:
80
+ Prefer local file edits for scripts, shaders, text, `*.material.json` / `*.template.json` data, and multi-property
81
+ edits in the active `.scene.json`. Use structured commands for Editor pipelines (`scene open`,
82
+ `template instantiate/create/overrides/apply`, `script parse`, `import`), explicit transfers, and live verification:
64
83
 
65
84
  ```bash
85
+ pcbridge workspace settings --eager-max-mb 2
86
+ pcbridge scene list --target editor:<sceneId>
87
+ pcbridge scene open --target editor:<sceneId> --id <otherSceneId>
66
88
  pcbridge entity list --target editor:<sceneId> --limit 50
67
89
  pcbridge entity create --target editor:<sceneId> --json ./entity.json
68
90
  pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set position='[0,1,0]'
@@ -73,27 +95,35 @@ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-
73
95
  pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
74
96
  pcbridge asset list --target editor:<sceneId> --type script
75
97
  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"
98
+ pcbridge asset folder ensure --target editor:<sceneId> --path "My Task/Textures"
99
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "My Task/Textures"
78
100
  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"
101
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "My Task/Materials" --diffuse-map <texture_asset_id>
102
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "My Task/Templates"
81
103
  pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
82
104
  pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
83
105
  pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
84
106
  pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
85
107
  pcbridge scene settings get --target editor:<sceneId>
86
108
  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"
109
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "My Task/Scripts" --parse --wait
110
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "My Task/Scripts"
89
111
  pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
90
112
  pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
91
113
  pcbridge logs get --target launch:<sceneId> --limit 100
92
114
  pcbridge logs get --target launch:<sceneId> --level error
93
115
  ```
94
116
 
95
- Put final file-backed assets under `assets/AI Agent Bridge/<task name>/...`; keep disposable
96
- generation files under `tmp/<task name>/`.
117
+ Before creating asset folders, inspect the project's existing directory tree and comparable
118
+ resources. Prefer reusing suitable folders and follow the project's naming language, casing,
119
+ separators, hierarchy, and resource grouping when new folders are needed. Organize related assets
120
+ by task or feature within that structure; if the project groups by resource type first, preserve
121
+ that layout rather than imposing a task-first hierarchy. Do not create an `AI Agent Bridge` folder
122
+ by default. If no convention exists, use a descriptive task folder with resource subfolders as needed.
123
+
124
+ Keep final file-backed assets in the project `assets/` tree and intermediate or disposable files
125
+ under `tmp/<task name>/` so the watcher does not upload them. Paths in command examples are
126
+ illustrative; adapt them to the project's existing conventions before creating folders.
97
127
 
98
128
  Use `pcbridge launch diagnose` and `pcbridge launch wait-ready --focus` before runtime assertions.
99
129
  Launch `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context,
@@ -119,3 +149,8 @@ explicit import settings or a non-watched path is required. Local file arguments
119
149
  the workspace; never use `--allow-external-path` without explicit user approval.
120
150
 
121
151
  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.
152
+
153
+
154
+ ## Self-hosted local processing
155
+
156
+ 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.