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