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.
- package/README.md +148 -31
- package/README.zh-CN.md +137 -33
- package/dist/cli.js +514 -95
- package/dist/config.js +23 -1
- package/dist/daemon/server.js +336 -28
- package/dist/daemon/target-registry.js +3 -0
- package/dist/plugins/host.js +260 -0
- package/dist/plugins/store.js +567 -0
- package/dist/processing/manager.js +265 -0
- package/dist/processing/tools.js +97 -0
- package/dist/snippets.js +27 -0
- package/dist/updates.js +475 -0
- package/dist/workspace/json-sync.js +821 -0
- package/dist/workspace/manager.js +1973 -326
- package/extension/icons/icon-128.png +0 -0
- package/extension/icons/icon-16.png +0 -0
- package/extension/icons/icon-256.png +0 -0
- package/extension/icons/icon-32.png +0 -0
- package/extension/icons/icon-48.png +0 -0
- package/extension/isolated.js +59 -2
- package/extension/main.js +770 -275
- package/extension/manifest.json +60 -10
- package/extension/popup.html +115 -3
- package/extension/popup.js +398 -14
- package/extension/service-worker.js +221 -4
- package/package.json +18 -18
- package/plugins/index.json +14 -0
- package/plugins/tinyapp-builder/node/builder.js +589 -0
- package/plugins/tinyapp-builder/node/index.js +30 -0
- package/plugins/tinyapp-builder/package.json +13 -0
- package/plugins/tinyapp-builder/page/editor.js +249 -0
- package/plugins/tinyapp-builder/pcbridge-plugin.json +28 -0
- package/skills/claude/pcbridge-plugin-authoring/SKILL.md +220 -0
- package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +99 -43
- package/skills/codex/pcbridge-plugin-authoring/SKILL.md +220 -0
- package/skills/codex/pcbridge-plugin-authoring/agents/openai.yaml +4 -0
- package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +89 -62
- package/skills/cursor/pcbridge-plugin-authoring.mdc +221 -0
- package/skills/cursor/playcanvas-agent-bridge-cli.mdc +69 -33
- package/skills/windsurf/pcbridge-plugin-authoring.md +215 -0
- package/skills/windsurf/playcanvas-agent-bridge-cli.md +68 -33
- package/dist/builder/manager.js +0 -564
|
@@ -0,0 +1,249 @@
|
|
|
1
|
+
// Runs in the PlayCanvas Editor page once the Editor is ready.
|
|
2
|
+
// In scope: plugin, editor, pc, pcui, runtimeApp.
|
|
3
|
+
|
|
4
|
+
function plainAssetJson(asset) {
|
|
5
|
+
if (!asset) return null;
|
|
6
|
+
if (typeof asset.json === "function") return asset.json();
|
|
7
|
+
if (asset.observer && typeof asset.observer.json === "function") return asset.observer.json();
|
|
8
|
+
return null;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
function collectAssetReferences(assets, value, ids, depth = 0) {
|
|
12
|
+
if (!value || typeof value !== "object" || depth > 100) return;
|
|
13
|
+
for (const [key, child] of Object.entries(value)) {
|
|
14
|
+
if (["id", "path", "uniqueId", "scope", "testTemplate"].includes(key)) continue;
|
|
15
|
+
if (Number.isInteger(child)) {
|
|
16
|
+
const referenced = assets.get(Number(child));
|
|
17
|
+
const id = String(child);
|
|
18
|
+
if (referenced && !ids.has(id)) {
|
|
19
|
+
ids.add(id);
|
|
20
|
+
collectAssetReferences(assets, plainAssetJson(referenced), ids, depth + 1);
|
|
21
|
+
}
|
|
22
|
+
} else if (child && typeof child === "object") {
|
|
23
|
+
collectAssetReferences(assets, child, ids, depth + 1);
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
function templateScriptNames(templateData) {
|
|
29
|
+
const names = new Set();
|
|
30
|
+
for (const entity of Object.values((templateData && templateData.entities) || {})) {
|
|
31
|
+
const scripts = entity && entity.components && entity.components.script &&
|
|
32
|
+
entity.components.script.scripts;
|
|
33
|
+
for (const name of Object.keys(scripts || {})) names.add(name);
|
|
34
|
+
}
|
|
35
|
+
return [...names];
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function templateChildren(templateData) {
|
|
39
|
+
const ids = new Set();
|
|
40
|
+
for (const entity of Object.values((templateData && templateData.entities) || {})) {
|
|
41
|
+
const attributes = entity && entity.components && entity.components.script &&
|
|
42
|
+
entity.components.script.scripts &&
|
|
43
|
+
entity.components.script.scripts.sdsTinyRootHandler &&
|
|
44
|
+
entity.components.script.scripts.sdsTinyRootHandler.attributes;
|
|
45
|
+
if (attributes && attributes.type === "testTemplate" && Number.isInteger(attributes.testTemplate)) {
|
|
46
|
+
ids.add(String(attributes.testTemplate));
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
return [...ids];
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
plugin.handle("collectTemplateDependencies", (params) => {
|
|
53
|
+
const assets = editor.api.globals.assets;
|
|
54
|
+
const template = assets.get(Number(params.assetId));
|
|
55
|
+
if (!template || template.get("type") !== "template") {
|
|
56
|
+
throw new Error("Template asset not found: " + params.assetId);
|
|
57
|
+
}
|
|
58
|
+
const templateJson = plainAssetJson(template);
|
|
59
|
+
if (!templateJson || !templateJson.data) {
|
|
60
|
+
throw new Error("Template asset has no serializable data: " + params.assetId);
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
const ids = new Set();
|
|
64
|
+
collectAssetReferences(assets, templateJson.data, ids);
|
|
65
|
+
const scripts = [];
|
|
66
|
+
for (const name of templateScriptNames(templateJson.data)) {
|
|
67
|
+
const scriptAsset =
|
|
68
|
+
(typeof assets.getAssetForScript === "function" && assets.getAssetForScript(name)) ||
|
|
69
|
+
(editor.assets && typeof editor.assets.getAssetForScript === "function" &&
|
|
70
|
+
editor.assets.getAssetForScript(name)) ||
|
|
71
|
+
assets.list().find((asset) =>
|
|
72
|
+
asset.get("type") === "script" &&
|
|
73
|
+
(asset.get("name") === name || asset.get("data.scripts." + name) !== undefined)
|
|
74
|
+
);
|
|
75
|
+
if (!scriptAsset) continue;
|
|
76
|
+
const scriptJson = plainAssetJson(scriptAsset);
|
|
77
|
+
const filename = scriptJson && scriptJson.file && scriptJson.file.filename;
|
|
78
|
+
if (
|
|
79
|
+
name.startsWith("sds") ||
|
|
80
|
+
String(filename || (scriptJson && scriptJson.name) || "").startsWith("sds")
|
|
81
|
+
) continue;
|
|
82
|
+
ids.add(String(scriptAsset.get("id")));
|
|
83
|
+
scripts.push({ name, assetId: String(scriptAsset.get("id")) });
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
return {
|
|
87
|
+
template: templateJson,
|
|
88
|
+
assets: [...ids].map((id) => plainAssetJson(assets.get(Number(id)))).filter(Boolean),
|
|
89
|
+
scripts,
|
|
90
|
+
childTemplateIds: templateChildren(templateJson.data),
|
|
91
|
+
projectUrl: window.config && window.config.project && window.config.project.id
|
|
92
|
+
? "https://playcanvas.com/project/" + window.config.project.id + "/overview"
|
|
93
|
+
: null,
|
|
94
|
+
sceneUrl: location.href
|
|
95
|
+
};
|
|
96
|
+
});
|
|
97
|
+
|
|
98
|
+
let panel = null;
|
|
99
|
+
let refreshTimer = null;
|
|
100
|
+
let selectedTemplateId = null;
|
|
101
|
+
let selectedTemplateAsset = null;
|
|
102
|
+
|
|
103
|
+
function selectedAssetState() {
|
|
104
|
+
try {
|
|
105
|
+
const items = editor.call && editor.call("selector:items");
|
|
106
|
+
if (Array.isArray(items)) return { known: true, asset: items[0] || null };
|
|
107
|
+
} catch {
|
|
108
|
+
// Fall through to the public selection API.
|
|
109
|
+
}
|
|
110
|
+
const selection = editor.api.globals.selection;
|
|
111
|
+
const items = selection && (
|
|
112
|
+
(Array.isArray(selection.items) && selection.items) ||
|
|
113
|
+
(typeof selection.list === "function" && selection.list()) ||
|
|
114
|
+
(typeof selection.get === "function" && selection.get())
|
|
115
|
+
);
|
|
116
|
+
return Array.isArray(items)
|
|
117
|
+
? { known: true, asset: items[0] || null }
|
|
118
|
+
: { known: false, asset: null };
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
function destroyPanel() {
|
|
122
|
+
if (panel && typeof panel.destroy === "function") panel.destroy();
|
|
123
|
+
panel = null;
|
|
124
|
+
selectedTemplateId = null;
|
|
125
|
+
selectedTemplateAsset = null;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
function panelIsAttached(layout) {
|
|
129
|
+
if (!panel || panel.destroyed === true) return false;
|
|
130
|
+
if (panel.dom && typeof panel.dom.isConnected === "boolean") return panel.dom.isConnected;
|
|
131
|
+
if ("parent" in panel) return panel.parent === layout;
|
|
132
|
+
return true;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
function appendRow(container, labelText, control) {
|
|
136
|
+
const row = new pcui.Container();
|
|
137
|
+
row.flex = true;
|
|
138
|
+
row.flexDirection = "row";
|
|
139
|
+
row.append(new pcui.Label({ text: labelText }));
|
|
140
|
+
row.append(control);
|
|
141
|
+
container.append(row);
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
function showPanel(asset) {
|
|
145
|
+
const type = asset && typeof asset.get === "function" ? asset.get("type") : null;
|
|
146
|
+
const id = asset && typeof asset.get === "function" ? String(asset.get("id")) : null;
|
|
147
|
+
if (type !== "template" || !id) {
|
|
148
|
+
destroyPanel();
|
|
149
|
+
return;
|
|
150
|
+
}
|
|
151
|
+
const layout = editor.call && editor.call("layout.attributes");
|
|
152
|
+
if (!pcui || !pcui.Container || !pcui.Button || !pcui.Label || !pcui.TextInput || !layout) return;
|
|
153
|
+
if (panel && selectedTemplateId === id && panelIsAttached(layout)) return;
|
|
154
|
+
destroyPanel();
|
|
155
|
+
|
|
156
|
+
const projectId = window.config && window.config.project && window.config.project.id
|
|
157
|
+
? String(window.config.project.id)
|
|
158
|
+
: "project";
|
|
159
|
+
const suffixKey = `pcbridge:builder:${id}:suffix`;
|
|
160
|
+
const prefixKey = `pcbridge:builder:${projectId}:prefix`;
|
|
161
|
+
const urlKey = `pcbridge:builder:${id}:url`;
|
|
162
|
+
const container = new pcui.Container();
|
|
163
|
+
container.flex = true;
|
|
164
|
+
container.flexDirection = "column";
|
|
165
|
+
if (container.class && typeof container.class.add === "function") {
|
|
166
|
+
container.class.add("pcbridge-tiny-builder");
|
|
167
|
+
}
|
|
168
|
+
container.append(new pcui.Label({ text: "pcbridge Tiny Builder" }));
|
|
169
|
+
const prefixInput = new pcui.TextInput({ value: localStorage.getItem(prefixKey) || "" });
|
|
170
|
+
const suffixInput = new pcui.TextInput({ value: localStorage.getItem(suffixKey) || "" });
|
|
171
|
+
if (typeof prefixInput.on === "function") {
|
|
172
|
+
prefixInput.on("change", () => localStorage.setItem(prefixKey, String(prefixInput.value || "")));
|
|
173
|
+
suffixInput.on("change", () => localStorage.setItem(suffixKey, String(suffixInput.value || "")));
|
|
174
|
+
}
|
|
175
|
+
appendRow(container, "上传目录", prefixInput);
|
|
176
|
+
appendRow(container, "文件后缀", suffixInput);
|
|
177
|
+
const pathLabel = new pcui.Label({ text: localStorage.getItem(urlKey) || "" });
|
|
178
|
+
appendRow(container, "引用路径", pathLabel);
|
|
179
|
+
const buildButton = new pcui.Button({ text: "构建并上传到 S3" });
|
|
180
|
+
const copyButton = new pcui.Button({ text: "复制引用路径" });
|
|
181
|
+
const logLabel = new pcui.Label({ text: "从项目 .env 或工作区 .env 读取 S3 配置" });
|
|
182
|
+
copyButton.on("click", () => {
|
|
183
|
+
if (pathLabel.text) void navigator.clipboard.writeText(pathLabel.text);
|
|
184
|
+
});
|
|
185
|
+
buildButton.on("click", async () => {
|
|
186
|
+
buildButton.enabled = false;
|
|
187
|
+
try {
|
|
188
|
+
let job = await plugin.call("start", {
|
|
189
|
+
templateAssetId: id,
|
|
190
|
+
suffix: String(suffixInput.value || ""),
|
|
191
|
+
prefix: String(prefixInput.value || "")
|
|
192
|
+
});
|
|
193
|
+
while (job.state !== "completed" && job.state !== "error") {
|
|
194
|
+
logLabel.text = job.message || job.state;
|
|
195
|
+
await new Promise((resolve) => setTimeout(resolve, 1000));
|
|
196
|
+
job = await plugin.call("status", { jobId: job.id }, 30000);
|
|
197
|
+
}
|
|
198
|
+
if (job.state === "error") throw new Error(job.error || "Template build failed.");
|
|
199
|
+
pathLabel.text = job.publicUrl || "";
|
|
200
|
+
localStorage.setItem(urlKey, pathLabel.text);
|
|
201
|
+
logLabel.text = job.message || "上传完成";
|
|
202
|
+
} catch (error) {
|
|
203
|
+
logLabel.text = "构建失败: " + String((error && error.message) || error);
|
|
204
|
+
} finally {
|
|
205
|
+
buildButton.enabled = true;
|
|
206
|
+
}
|
|
207
|
+
});
|
|
208
|
+
container.append(buildButton);
|
|
209
|
+
container.append(copyButton);
|
|
210
|
+
container.append(logLabel);
|
|
211
|
+
layout.append(container);
|
|
212
|
+
panel = container;
|
|
213
|
+
selectedTemplateId = id;
|
|
214
|
+
selectedTemplateAsset = asset;
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
function refreshPanel(asset) {
|
|
218
|
+
const selection = selectedAssetState();
|
|
219
|
+
if (selection.known) showPanel(selection.asset);
|
|
220
|
+
else showPanel(asset || selectedTemplateAsset);
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
function scheduleRefresh(asset) {
|
|
224
|
+
if (refreshTimer !== null) clearTimeout(refreshTimer);
|
|
225
|
+
refreshTimer = setTimeout(() => {
|
|
226
|
+
refreshTimer = null;
|
|
227
|
+
refreshPanel(asset);
|
|
228
|
+
}, 150);
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
const subscriptions = [];
|
|
232
|
+
for (const selection of [editor.selection, editor.api.globals.selection]) {
|
|
233
|
+
if (!selection || typeof selection.on !== "function") continue;
|
|
234
|
+
subscriptions.push(selection.on("add", (asset) => scheduleRefresh(asset)));
|
|
235
|
+
subscriptions.push(selection.on("remove", () => scheduleRefresh()));
|
|
236
|
+
subscriptions.push(selection.on("change", () => scheduleRefresh()));
|
|
237
|
+
}
|
|
238
|
+
// The Inspector rebuilds its layout on reselection, so the panel is re-attached periodically.
|
|
239
|
+
const attachTimer = setInterval(() => refreshPanel(), 1000);
|
|
240
|
+
refreshPanel();
|
|
241
|
+
|
|
242
|
+
plugin.onDispose(() => {
|
|
243
|
+
clearInterval(attachTimer);
|
|
244
|
+
if (refreshTimer !== null) clearTimeout(refreshTimer);
|
|
245
|
+
for (const handle of subscriptions) {
|
|
246
|
+
if (handle && typeof handle.unbind === "function") handle.unbind();
|
|
247
|
+
}
|
|
248
|
+
destroyPanel();
|
|
249
|
+
});
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "tinyapp-builder",
|
|
3
|
+
"name": "Tiny Builder",
|
|
4
|
+
"version": "1.0.0",
|
|
5
|
+
"apiVersion": 1,
|
|
6
|
+
"minPcbridgeVersion": "0.7.0",
|
|
7
|
+
"description": "Build a PlayCanvas Template Asset into a TinyApp bundle and upload it to S3-compatible storage.",
|
|
8
|
+
"node": "node/index.js",
|
|
9
|
+
"page": {
|
|
10
|
+
"editor": "page/editor.js"
|
|
11
|
+
},
|
|
12
|
+
"actions": {
|
|
13
|
+
"start": {
|
|
14
|
+
"description": "Start a Template build job for an Editor target and return the job status.",
|
|
15
|
+
"params": {
|
|
16
|
+
"templateAssetId": "Template Asset id (required).",
|
|
17
|
+
"suffix": "Appended to the build name; ${time} expands to a timestamp.",
|
|
18
|
+
"prefix": "S3 key prefix; overrides PCBRIDGE_S3_PREFIX."
|
|
19
|
+
}
|
|
20
|
+
},
|
|
21
|
+
"status": {
|
|
22
|
+
"description": "Return the status of a build job.",
|
|
23
|
+
"params": {
|
|
24
|
+
"jobId": "Job id returned by start (required)."
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
}
|
|
@@ -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).
|