playcanvas-agent-bridge-cli 0.2.1 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/extension/main.js CHANGED
@@ -128,6 +128,78 @@
128
128
  };
129
129
  }
130
130
 
131
+ function readAsset(asset) {
132
+ const get = (path) => {
133
+ try {
134
+ return asset.get(path);
135
+ } catch {
136
+ return undefined;
137
+ }
138
+ };
139
+ const path = get("path") || [];
140
+ return {
141
+ id: get("id"),
142
+ name: get("name"),
143
+ type: get("type"),
144
+ path,
145
+ folder: Array.isArray(path) && path.length ? path[path.length - 1] : null,
146
+ tags: get("tags") || [],
147
+ file: get("file") || null
148
+ };
149
+ }
150
+
151
+ function splitAssetPath(path) {
152
+ if (Array.isArray(path)) return path.map(String).map((part) => part.trim()).filter(Boolean);
153
+ return String(path || "")
154
+ .split("/")
155
+ .map((part) => part.trim())
156
+ .filter(Boolean);
157
+ }
158
+
159
+ function isChildFolder(asset, name, parent) {
160
+ if (!asset || asset.get("type") !== "folder" || asset.get("name") !== name) return false;
161
+ const path = asset.get("path") || [];
162
+ if (!parent) return path.length === 0;
163
+ return path[path.length - 1] === parent.get("id");
164
+ }
165
+
166
+ async function ensureFolderPath(assets, path) {
167
+ const created = [];
168
+ let parent = null;
169
+ for (const name of splitAssetPath(path)) {
170
+ let folder = assets.list().find((asset) => isChildFolder(asset, name, parent));
171
+ if (!folder) {
172
+ folder = await assets.createFolder({ name, folder: parent || undefined });
173
+ created.push(folder);
174
+ }
175
+ parent = folder;
176
+ }
177
+ return { folder: parent, created };
178
+ }
179
+
180
+ async function resolveFolder(assets, params) {
181
+ if (params.folderId !== undefined && params.folderId !== null && params.folderId !== "") {
182
+ const folder = assets.get(Number(params.folderId));
183
+ if (!folder || folder.get("type") !== "folder") {
184
+ throw new Error("Folder asset not found: " + params.folderId);
185
+ }
186
+ return { folder, created: [] };
187
+ }
188
+ if (params.folder) {
189
+ return ensureFolderPath(assets, params.folder);
190
+ }
191
+ return { folder: null, created: [] };
192
+ }
193
+
194
+ function bytesFromBase64(base64) {
195
+ const binary = atob(base64);
196
+ const bytes = new Uint8Array(binary.length);
197
+ for (let index = 0; index < binary.length; index += 1) {
198
+ bytes[index] = binary.charCodeAt(index);
199
+ }
200
+ return bytes;
201
+ }
202
+
131
203
  function withTimeout(promise, timeoutMs) {
132
204
  return new Promise((resolve, reject) => {
133
205
  const timer = setTimeout(() => reject(new Error(`Timed out after ${timeoutMs}ms.`)), timeoutMs);
@@ -240,11 +312,95 @@
240
312
  };
241
313
  }
242
314
 
315
+ async function uploadAsset(params) {
316
+ if (!params.base64) throw new Error("base64 file content is required.");
317
+ if (!params.name) throw new Error("name is required.");
318
+ if (!params.type) throw new Error("type is required.");
319
+
320
+ const assets = window.editor.api.globals.assets;
321
+ const folderResult = await resolveFolder(assets, params);
322
+ const blob = new Blob([bytesFromBase64(params.base64)], {
323
+ type: params.mime || "application/octet-stream"
324
+ });
325
+ const asset = await assets.upload(
326
+ {
327
+ name: params.name,
328
+ type: params.type,
329
+ folder: folderResult.folder || undefined,
330
+ filename: params.filename || params.name,
331
+ file: blob,
332
+ preload: params.preload !== false
333
+ },
334
+ null
335
+ );
336
+ return {
337
+ asset: readAsset(asset),
338
+ createdFolders: folderResult.created.map(readAsset)
339
+ };
340
+ }
341
+
342
+ function focusViewport(params) {
343
+ const ids = Array.isArray(params.ids) && params.ids.length ? params.ids : [params.id];
344
+ const entitiesApi = window.editor.api.globals.entities;
345
+ const entities = ids.map((id) => entitiesApi.get(id)).filter(Boolean);
346
+ if (!entities.length) {
347
+ throw new Error("No valid entities found.");
348
+ }
349
+
350
+ window.editor.api.globals.selection.set(entities, { history: true });
351
+
352
+ const camera = window.editor.call("camera:current");
353
+ if (!camera) {
354
+ throw new Error("Could not retrieve current camera.");
355
+ }
356
+ const aabb = window.editor.call("selection:aabb");
357
+ if (!aabb) {
358
+ throw new Error("Could not calculate selection bounds.");
359
+ }
360
+
361
+ let distance = Math.max(aabb.halfExtents.x, aabb.halfExtents.y, aabb.halfExtents.z);
362
+ distance /= Math.tan(0.5 * camera.camera.fov * Math.PI / 180.0);
363
+ distance = distance * 1.1 + 1;
364
+
365
+ if (params.view) {
366
+ const views = {
367
+ top: [-90, 0],
368
+ bottom: [90, 0],
369
+ front: [0, 0],
370
+ back: [0, 180],
371
+ left: [0, -90],
372
+ right: [0, 90],
373
+ perspective: [-25, 45]
374
+ };
375
+ const angles = views[params.view];
376
+ if (angles) {
377
+ camera.setEulerAngles(angles[0], angles[1], 0);
378
+ }
379
+ } else if (
380
+ (params.yaw !== undefined && params.yaw !== null) ||
381
+ (params.pitch !== undefined && params.pitch !== null)
382
+ ) {
383
+ const yaw = params.yaw ?? 45;
384
+ const pitch = params.pitch ?? -25;
385
+ camera.setEulerAngles(pitch, yaw, 0);
386
+ }
387
+
388
+ window.editor.call("camera:focus", aabb.center, distance);
389
+ return {
390
+ focused: ids,
391
+ view: params.view || null,
392
+ yaw: params.yaw ?? null,
393
+ pitch: params.pitch ?? null
394
+ };
395
+ }
396
+
243
397
  async function callMethod(method, params, requestId) {
244
398
  if (method === "bridge:ping") return { pong: true, href: location.href };
245
399
  if (method === "bridge:describeTarget") return describeTarget();
246
400
  if (method === "bridge:eval") return evalInPage(params || {}, requestId);
247
401
  if (method === "bridge:captureViewport") return captureViewport(params || {});
402
+ if (method === "bridge:uploadAsset") return uploadAsset(params || {});
403
+ if (method === "bridge:focusViewport") return focusViewport(params || {});
248
404
  throw new Error(`Unknown bridge method: ${method}`);
249
405
  }
250
406
 
@@ -2,7 +2,7 @@
2
2
  "manifest_version": 3,
3
3
  "name": "PlayCanvas Agent Bridge",
4
4
  "description": "Connects open PlayCanvas Editor tabs to the local pcbridge daemon.",
5
- "version": "0.2.1",
5
+ "version": "0.2.2",
6
6
  "permissions": ["activeTab", "storage"],
7
7
  "host_permissions": [
8
8
  "http://playcanvas.com/*",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "playcanvas-agent-bridge-cli",
3
- "version": "0.2.1",
3
+ "version": "0.2.2",
4
4
  "description": "CLI-first local bridge for automating open PlayCanvas Editor tabs from AI coding agents.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -15,24 +15,44 @@ pcbridge targets
15
15
 
16
16
  If the daemon is offline, ask the user to run `pcbridge daemon start` in another terminal. If no PlayCanvas target appears, ask the user to run `pcbridge install-extension`, load the printed directory in `chrome://extensions`, and refresh the Editor tab.
17
17
 
18
- Prefer structured commands:
18
+ Use layered help to load only the command surface you need:
19
+
20
+ ```bash
21
+ pcbridge help
22
+ pcbridge help entity
23
+ pcbridge help asset
24
+ pcbridge help template
25
+ pcbridge help scene
26
+ pcbridge help viewport
27
+ pcbridge help eval
28
+ ```
29
+
30
+ Use structured commands for small, known Editor operations:
19
31
 
20
32
  ```bash
21
33
  pcbridge entity list --target current --limit 50
22
34
  pcbridge entity create --target current --json ./entity.json
35
+ pcbridge entity create-many --target current --json ./entities.json
23
36
  pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
37
+ pcbridge entity duplicate --target current --id <resource_id>
38
+ pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
24
39
  pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
25
40
  pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
26
41
  pcbridge asset list --target current --type script
42
+ pcbridge asset create --target current --json ./assets.json
27
43
  pcbridge asset folder ensure --target current --path "AI Agent Bridge/My Task/Textures"
28
44
  pcbridge asset upload --target current --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
29
45
  pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
46
+ pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
47
+ pcbridge template instantiate --target current --id <template_asset_id>
48
+ pcbridge scene settings get --target current
49
+ pcbridge viewport focus --target current --id <resource_id> --view perspective
30
50
  pcbridge script create --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
31
51
  pcbridge script set-text --target current --asset-id <id> --file ./script.js
32
52
  pcbridge viewport capture --target current --out ./tmp/playcanvas.png
33
53
  ```
34
54
 
35
- Organize generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`. Use `pcbridge eval` only for custom work:
55
+ Organize generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`. Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, and large multi-step scene edits:
36
56
 
37
57
  ```bash
38
58
  pcbridge eval --target current --code "return { href: location.href, entityCount: editor.api.globals.entities.list().length }"
@@ -28,11 +28,12 @@ If no target appears, tell the user to run `pcbridge install-extension`, load th
28
28
  ## Workflow
29
29
 
30
30
  1. Run `pcbridge targets` and choose an explicit target when possible.
31
- 2. Prefer structured commands for common tasks: `entity`, `asset`, `material`, `script`, and `viewport`.
32
- 3. Use `pcbridge eval` only for custom Editor API work.
33
- 4. Return compact JSON from snippets. Never return raw `editor`, `Entity`, `Asset`, `entities.root`, or app objects.
34
- 5. Use PlayCanvas history options for writes when available.
35
- 6. Verify writes with a read-only command after mutation.
31
+ 2. Use layered help to load only the command group you need: `pcbridge help`, then `pcbridge help entity|asset|material|template|script|scene|store|viewport|eval`.
32
+ 3. Use structured commands for small, known operations that map cleanly to one Editor action.
33
+ 4. Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, and large multi-step scene edits where one script is clearer than many CLI calls.
34
+ 5. Return compact JSON from snippets. Never return raw `editor`, `Entity`, `Asset`, `entities.root`, or app objects.
35
+ 6. Use PlayCanvas history options for writes when available.
36
+ 7. Verify writes with a read-only command after mutation.
36
37
 
37
38
  ## Safe Commands
38
39
 
@@ -47,24 +48,30 @@ List entities:
47
48
  ```bash
48
49
  pcbridge entity list --target current --limit 50
49
50
  pcbridge entity list --target scene:<sceneId> --name Player --component render
51
+ pcbridge entity list --target current --tag enemy
50
52
  ```
51
53
 
52
54
  Create an entity from JSON:
53
55
 
54
56
  ```bash
55
57
  pcbridge entity create --target current --json ./entity.json
58
+ pcbridge entity create-many --target current --json ./entities.json
56
59
  ```
57
60
 
58
61
  Patch an entity:
59
62
 
60
63
  ```bash
61
64
  pcbridge entity patch --target current --id <resource_id> --set name=Player --set position='[0,1,0]'
65
+ pcbridge entity patch-many --target current --json ./edits.json
66
+ pcbridge entity duplicate --target current --id <resource_id>
67
+ pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
62
68
  ```
63
69
 
64
70
  Modify components and materials:
65
71
 
66
72
  ```bash
67
73
  pcbridge entity add-component --target current --id <resource_id> --component render --data '{"type":"box"}'
74
+ pcbridge entity add-components --target current --id <resource_id> --json ./components.json
68
75
  pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
69
76
  pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
70
77
  pcbridge entity delete --target current --id <resource_id>
@@ -74,14 +81,29 @@ Work with assets and scripts:
74
81
 
75
82
  ```bash
76
83
  pcbridge asset list --target current --type script --limit 50
84
+ pcbridge asset create --target current --json ./assets.json
77
85
  pcbridge asset folder ensure --target current --path "AI Agent Bridge/My Task/Textures"
78
86
  pcbridge asset upload --target current --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
87
+ pcbridge asset instantiate --target current --id <template_asset_id>
79
88
  pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
89
+ pcbridge material patch --target current --asset-id <material_asset_id> --set diffuse='[1,0,0]'
90
+ pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
91
+ pcbridge template instantiate --target current --id <template_asset_id>
80
92
  pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts"
81
93
  pcbridge script set-text --target current --asset-id <id> --file ./controller.js
82
94
  pcbridge script parse --target current --asset-id <id>
83
95
  ```
84
96
 
97
+ Scene, store, and viewport:
98
+
99
+ ```bash
100
+ pcbridge scene settings get --target current
101
+ pcbridge scene settings patch --target current --json ./scene-settings.json
102
+ pcbridge store search --target current --search vehicle --limit 20
103
+ pcbridge store get --target current --id <store_asset_id>
104
+ pcbridge viewport focus --target current --id <resource_id> --view perspective
105
+ ```
106
+
85
107
  Capture the viewport:
86
108
 
87
109
  ```bash
@@ -16,17 +16,26 @@ pcbridge targets
16
16
 
17
17
  If needed, ask the user to run `pcbridge daemon start`. If no target appears, ask them to run `pcbridge install-extension`, load the printed extension directory in `chrome://extensions`, and refresh PlayCanvas Editor.
18
18
 
19
- Prefer structured commands:
19
+ Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help entity|asset|material|template|script|scene|store|viewport|eval`.
20
+
21
+ Use structured commands for small, known Editor operations:
20
22
 
21
23
  ```bash
22
24
  pcbridge entity list --target current --limit 50
23
25
  pcbridge entity patch --target current --id <resource_id> --set name=Player
26
+ pcbridge entity duplicate --target current --id <resource_id>
27
+ pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
24
28
  pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
25
29
  pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
26
30
  pcbridge asset list --target current --type script
31
+ pcbridge asset create --target current --json ./assets.json
27
32
  pcbridge asset folder ensure --target current --path "AI Agent Bridge/My Task/Textures"
28
33
  pcbridge asset upload --target current --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
29
34
  pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
35
+ pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
36
+ pcbridge template instantiate --target current --id <template_asset_id>
37
+ pcbridge scene settings get --target current
38
+ pcbridge viewport focus --target current --id <resource_id> --view perspective
30
39
  pcbridge script create --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
31
40
  pcbridge script set-text --target current --asset-id <id> --file ./script.js
32
41
  pcbridge viewport capture --target current --out ./tmp/playcanvas.png
@@ -34,4 +43,4 @@ pcbridge viewport capture --target current --out ./tmp/playcanvas.png
34
43
 
35
44
  Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
36
45
 
37
- Use `pcbridge eval` only for custom Editor API work. Snippets run with `editor`, `pc`, `pcui`, `window`, `document`, `command`, and `serialize`. Return compact JSON; never return raw `editor`, `Entity`, `Asset`, or app objects.
46
+ Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, and large multi-step scene edits. Snippets run with `editor`, `pc`, `pcui`, `window`, `document`, `command`, and `serialize`. Return compact JSON; never return raw `editor`, `Entity`, `Asset`, or app objects.
@@ -12,18 +12,27 @@ pcbridge targets
12
12
 
13
13
  If the daemon is offline, ask the user to run `pcbridge daemon start`. If no target is connected, ask the user to run `pcbridge install-extension`, load the printed unpacked extension path in `chrome://extensions`, and refresh the Editor tab.
14
14
 
15
- Prefer structured commands over eval:
15
+ Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help entity|asset|material|template|script|scene|store|viewport|eval`.
16
+
17
+ Use structured commands for small, known Editor operations:
16
18
 
17
19
  ```bash
18
20
  pcbridge entity list --target current --limit 50
19
21
  pcbridge entity create --target current --json ./entity.json
20
22
  pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
23
+ pcbridge entity duplicate --target current --id <resource_id>
24
+ pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
21
25
  pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
22
26
  pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
23
27
  pcbridge asset list --target current --type script
28
+ pcbridge asset create --target current --json ./assets.json
24
29
  pcbridge asset folder ensure --target current --path "AI Agent Bridge/My Task/Textures"
25
30
  pcbridge asset upload --target current --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
26
31
  pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
32
+ pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
33
+ pcbridge template instantiate --target current --id <template_asset_id>
34
+ pcbridge scene settings get --target current
35
+ pcbridge viewport focus --target current --id <resource_id> --view perspective
27
36
  pcbridge script create --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
28
37
  pcbridge script set-text --target current --asset-id <id> --file ./script.js
29
38
  pcbridge viewport capture --target current --out ./tmp/playcanvas.png
@@ -31,4 +40,4 @@ pcbridge viewport capture --target current --out ./tmp/playcanvas.png
31
40
 
32
41
  Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
33
42
 
34
- Use `pcbridge eval` only for custom Editor API snippets. Return compact JSON and never return raw PlayCanvas Editor objects. Use history-enabled mutations when available and verify writes with a read-only command.
43
+ Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, and large multi-step scene edits. Return compact JSON and never return raw PlayCanvas Editor objects. Use history-enabled mutations when available and verify writes with a read-only command.