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/README.md CHANGED
@@ -68,29 +68,70 @@ pcbridge targets
68
68
  pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor }"
69
69
  ```
70
70
 
71
+ ## Progressive help
72
+
73
+ The CLI exposes layered help so agents can load only the command surface they need:
74
+
75
+ ```bash
76
+ pcbridge help
77
+ pcbridge help entity
78
+ pcbridge help asset
79
+ pcbridge help material
80
+ pcbridge help template
81
+ pcbridge help script
82
+ pcbridge help scene
83
+ pcbridge help store
84
+ pcbridge help viewport
85
+ pcbridge help eval
86
+ ```
87
+
88
+ Use structured commands for small, known operations that map cleanly to one Editor action. Use
89
+ `pcbridge eval` for exploratory work, custom Editor/Engine API workflows, and large multi-step
90
+ scene edits where one script is clearer and faster than many CLI calls.
91
+
71
92
  ## Common commands
72
93
 
73
94
  ```bash
74
95
  pcbridge entity list --target current --limit 50
96
+ pcbridge entity list --target current --tag enemy --component render
75
97
  pcbridge entity create --target current --json ./entity.json
98
+ pcbridge entity create-many --target current --json ./entities.json
76
99
  pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
100
+ pcbridge entity patch-many --target current --json ./edits.json
101
+ pcbridge entity duplicate --target current --id <resource_id>
102
+ pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
77
103
  pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
78
104
  pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
79
105
  pcbridge entity delete --target current --id <resource_id>
80
106
 
81
107
  pcbridge asset list --target current --type script
108
+ pcbridge asset list --target current --tag generated
82
109
  pcbridge asset get --target current --id <asset_id>
110
+ pcbridge asset create --target current --json ./assets.json
83
111
  pcbridge asset folder ensure --target current --path "AI Agent Bridge/Demo/Textures"
84
112
  pcbridge asset upload --target current --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
113
+ pcbridge asset instantiate --target current --id <template_asset_id>
85
114
  pcbridge asset delete --target current --id <asset_id>
86
115
 
87
116
  pcbridge material create --target current --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
117
+ pcbridge material patch --target current --asset-id <asset_id> --set diffuse='[1,0,0]'
118
+
119
+ pcbridge template create --target current --entity-id <resource_id> --name DemoTemplate --folder "AI Agent Bridge/Demo/Templates"
120
+ pcbridge template instantiate --target current --id <template_asset_id>
88
121
 
89
122
  pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
90
123
  pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js
91
124
  pcbridge script parse --target current --asset-id <asset_id>
92
125
 
126
+ pcbridge scene settings get --target current
127
+ pcbridge scene settings patch --target current --set physics.gravity='[0,-9.8,0]'
128
+
129
+ pcbridge store search --target current --search vehicle --limit 20
130
+ pcbridge store get --target current --id <store_asset_id>
131
+ pcbridge store download --target current --id <store_asset_id> --name Vehicle --license-json ./license.json
132
+
93
133
  pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
134
+ pcbridge viewport focus --target current --id <resource_id> --view perspective
94
135
  ```
95
136
 
96
137
  ## Texture + material + script workflow
package/README.zh-CN.md CHANGED
@@ -68,29 +68,69 @@ pcbridge targets
68
68
  pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor }"
69
69
  ```
70
70
 
71
+ ## 渐进式 help
72
+
73
+ CLI 提供分层 help,方便 agent 只加载当前需要的命令面:
74
+
75
+ ```bash
76
+ pcbridge help
77
+ pcbridge help entity
78
+ pcbridge help asset
79
+ pcbridge help material
80
+ pcbridge help template
81
+ pcbridge help script
82
+ pcbridge help scene
83
+ pcbridge help store
84
+ pcbridge help viewport
85
+ pcbridge help eval
86
+ ```
87
+
88
+ 小而明确、能对应到单个 Editor 操作的任务优先用结构化命令。探索 API、自定义
89
+ Editor/Engine 工作流、大量多步骤场景修改,则优先用 `pcbridge eval`,一段脚本通常更清楚也更快。
90
+
71
91
  ## 常用命令
72
92
 
73
93
  ```bash
74
94
  pcbridge entity list --target current --limit 50
95
+ pcbridge entity list --target current --tag enemy --component render
75
96
  pcbridge entity create --target current --json ./entity.json
97
+ pcbridge entity create-many --target current --json ./entities.json
76
98
  pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
99
+ pcbridge entity patch-many --target current --json ./edits.json
100
+ pcbridge entity duplicate --target current --id <resource_id>
101
+ pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
77
102
  pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
78
103
  pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
79
104
  pcbridge entity delete --target current --id <resource_id>
80
105
 
81
106
  pcbridge asset list --target current --type script
107
+ pcbridge asset list --target current --tag generated
82
108
  pcbridge asset get --target current --id <asset_id>
109
+ pcbridge asset create --target current --json ./assets.json
83
110
  pcbridge asset folder ensure --target current --path "AI Agent Bridge/Demo/Textures"
84
111
  pcbridge asset upload --target current --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
112
+ pcbridge asset instantiate --target current --id <template_asset_id>
85
113
  pcbridge asset delete --target current --id <asset_id>
86
114
 
87
115
  pcbridge material create --target current --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
116
+ pcbridge material patch --target current --asset-id <asset_id> --set diffuse='[1,0,0]'
117
+
118
+ pcbridge template create --target current --entity-id <resource_id> --name DemoTemplate --folder "AI Agent Bridge/Demo/Templates"
119
+ pcbridge template instantiate --target current --id <template_asset_id>
88
120
 
89
121
  pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
90
122
  pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js
91
123
  pcbridge script parse --target current --asset-id <asset_id>
92
124
 
125
+ pcbridge scene settings get --target current
126
+ pcbridge scene settings patch --target current --set physics.gravity='[0,-9.8,0]'
127
+
128
+ pcbridge store search --target current --search vehicle --limit 20
129
+ pcbridge store get --target current --id <store_asset_id>
130
+ pcbridge store download --target current --id <store_asset_id> --name Vehicle --license-json ./license.json
131
+
93
132
  pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
133
+ pcbridge viewport focus --target current --id <resource_id> --view perspective
94
134
  ```
95
135
 
96
136
  ## 贴图 + 材质 + 脚本工作流
package/dist/cli.js CHANGED
@@ -7,7 +7,7 @@ import { basename, dirname, extname, join } from "node:path";
7
7
  import { fileURLToPath } from "node:url";
8
8
  import { CONFIG_DIR, DEFAULT_HOST, DEFAULT_PORT, EXTENSION_INSTALL_DIR, VERSION, copyDir, findPackageRoot, readOrCreateSession, readSessionIfExists, } from "./config.js";
9
9
  import { createDaemonServer } from "./daemon/server.js";
10
- import { assetDeleteSnippet, assetFolderEnsureSnippet, assetGetSnippet, assetListSnippet, assetUploadSnippet, entityAddComponentSnippet, entityAddScriptSnippet, entityCreateSnippet, entityDeleteSnippet, entityGetSnippet, entityListSnippet, entityPatchSnippet, entityRemoveComponentSnippet, entitySetMaterialSnippet, materialCreateSnippet, scriptCreateSnippet, scriptParseSnippet, scriptSetTextSnippet, } from "./snippets.js";
10
+ import { assetDeleteSnippet, assetFolderEnsureSnippet, assetCreateManySnippet, assetGetSnippet, assetInstantiateTemplateSnippet, assetListSnippet, entityAddComponentsSnippet, entityAddComponentSnippet, entityAddScriptSnippet, entityCreateManySnippet, entityCreateSnippet, entityDeleteSnippet, entityDuplicateSnippet, entityGetSnippet, entityListSnippet, entityPatchManySnippet, entityPatchSnippet, entityReparentSnippet, entityRemoveComponentsSnippet, entityRemoveComponentSnippet, entitySetMaterialSnippet, materialCreateSnippet, materialPatchSnippet, sceneSettingsGetSnippet, sceneSettingsPatchSnippet, scriptCreateSnippet, scriptParseSnippet, scriptSetTextSnippet, storeDownloadSnippet, storeGetSnippet, storeSearchSnippet, templateCreateSnippet, } from "./snippets.js";
11
11
  import { fail, ok } from "./shared/protocol.js";
12
12
  function parseArgs(argv) {
13
13
  const parsed = { _: [], flags: {} };
@@ -242,17 +242,58 @@ async function doctor() {
242
242
  nextActions.push("Run pcbridge daemon start in a terminal.");
243
243
  }
244
244
  const extensionExists = Boolean(session) && (await pathExists(EXTENSION_INSTALL_DIR));
245
+ let generatedExtensionVersion = null;
246
+ if (extensionExists) {
247
+ try {
248
+ const manifest = JSON.parse(await readFile(join(EXTENSION_INSTALL_DIR, "manifest.json"), "utf8"));
249
+ generatedExtensionVersion = manifest.version || null;
250
+ }
251
+ catch {
252
+ generatedExtensionVersion = null;
253
+ }
254
+ }
245
255
  checks.push({
246
256
  name: "extension",
247
- ok: extensionExists,
257
+ ok: extensionExists && generatedExtensionVersion === VERSION,
248
258
  path: EXTENSION_INSTALL_DIR,
249
- message: extensionExists
250
- ? "Generated unpacked extension directory exists."
251
- : "Generated unpacked extension directory was not found.",
259
+ version: generatedExtensionVersion,
260
+ expectedVersion: VERSION,
261
+ message: extensionExists && generatedExtensionVersion === VERSION
262
+ ? "Generated unpacked extension directory exists and matches package version."
263
+ : extensionExists
264
+ ? "Generated unpacked extension version does not match package version."
265
+ : "Generated unpacked extension directory was not found.",
252
266
  });
253
267
  if (!extensionExists) {
254
268
  nextActions.push("Run pcbridge install-extension and load the printed directory in Chrome.");
255
269
  }
270
+ else if (generatedExtensionVersion !== VERSION) {
271
+ nextActions.push("Run pcbridge install-extension --no-open, then reload the unpacked extension in Chrome.");
272
+ }
273
+ try {
274
+ const targets = await fetchDaemon("/targets");
275
+ if (targets.ok && Array.isArray(targets.data)) {
276
+ const connectedVersions = targets.data
277
+ .map((target) => (target && typeof target === "object" && !Array.isArray(target) ? target.extensionVersion : null))
278
+ .filter(Boolean);
279
+ const mismatched = connectedVersions.filter((version) => version !== VERSION);
280
+ checks.push({
281
+ name: "connected-extension-version",
282
+ ok: mismatched.length === 0,
283
+ versions: connectedVersions,
284
+ expectedVersion: VERSION,
285
+ message: mismatched.length
286
+ ? "One or more connected Editor tabs are using an older extension version."
287
+ : "Connected extension versions match the package version.",
288
+ });
289
+ if (mismatched.length) {
290
+ nextActions.push("Reload the unpacked extension and refresh the PlayCanvas Editor tab.");
291
+ }
292
+ }
293
+ }
294
+ catch {
295
+ // Daemon reachability is already reported above.
296
+ }
256
297
  return ok({
257
298
  version: VERSION,
258
299
  configDir: CONFIG_DIR,
@@ -407,6 +448,7 @@ async function handleEntity(args) {
407
448
  return listEnvelope(await rpcEval(args, entityListSnippet(), {
408
449
  name: flagString(args, "name") || null,
409
450
  component: flagString(args, "component") || null,
451
+ tag: flagString(args, "tag") || null,
410
452
  limit: Number(flagString(args, "limit", "50")),
411
453
  offset: Number(flagString(args, "offset", "0")),
412
454
  full: flagBool(args, "full"),
@@ -425,12 +467,56 @@ async function handleEntity(args) {
425
467
  const data = JSON.parse(await readFile(file, "utf8"));
426
468
  return rpcEval(args, entityCreateSnippet(), { data });
427
469
  }
470
+ if (subcommand === "create-many") {
471
+ const file = flagString(args, "json");
472
+ if (!file)
473
+ return fail("INVALID_REQUEST", "entity create-many requires --json <file>.");
474
+ const data = JSON.parse(await readFile(file, "utf8"));
475
+ const entities = Array.isArray(data)
476
+ ? data
477
+ : objectJson(data, "entity create-many data").entities;
478
+ return rpcEval(args, entityCreateManySnippet(), { entities: entities || [] }, 30000);
479
+ }
428
480
  if (subcommand === "patch") {
429
481
  const id = flagString(args, "id");
430
482
  if (!id)
431
483
  return fail("INVALID_REQUEST", "entity patch requires --id.");
432
484
  return rpcEval(args, entityPatchSnippet(), { id, sets: parseSets(flagList(args, "set")) });
433
485
  }
486
+ if (subcommand === "patch-many") {
487
+ const file = flagString(args, "json");
488
+ if (!file)
489
+ return fail("INVALID_REQUEST", "entity patch-many requires --json <file>.");
490
+ const data = JSON.parse(await readFile(file, "utf8"));
491
+ const edits = Array.isArray(data)
492
+ ? data
493
+ : objectJson(data, "entity patch-many data").edits;
494
+ return rpcEval(args, entityPatchManySnippet(), { edits: edits || [] }, 30000);
495
+ }
496
+ if (subcommand === "duplicate") {
497
+ const ids = flagList(args, "id");
498
+ const id = flagString(args, "id");
499
+ if (!ids.length && !id)
500
+ return fail("INVALID_REQUEST", "entity duplicate requires --id.");
501
+ return rpcEval(args, entityDuplicateSnippet(), {
502
+ ids: ids,
503
+ id: id || null,
504
+ rename: !flagBool(args, "no-rename"),
505
+ select: !flagBool(args, "no-select"),
506
+ });
507
+ }
508
+ if (subcommand === "reparent") {
509
+ const id = flagString(args, "id");
510
+ const parent = flagString(args, "parent");
511
+ if (!id || !parent)
512
+ return fail("INVALID_REQUEST", "entity reparent requires --id and --parent.");
513
+ return rpcEval(args, entityReparentSnippet(), {
514
+ id,
515
+ parent,
516
+ index: flagString(args, "index") === undefined ? null : Number(flagString(args, "index")),
517
+ preserveTransform: !flagBool(args, "no-preserve-transform"),
518
+ });
519
+ }
434
520
  if (subcommand === "delete") {
435
521
  const ids = flagList(args, "id");
436
522
  const id = flagString(args, "id");
@@ -452,13 +538,42 @@ async function handleEntity(args) {
452
538
  data: objectJson(data, "component data"),
453
539
  });
454
540
  }
541
+ if (subcommand === "add-components") {
542
+ const id = flagString(args, "id");
543
+ const data = await readJsonFlag(args, "json");
544
+ if (!id || data === undefined) {
545
+ return fail("INVALID_REQUEST", "entity add-components requires --id and --json <file>.");
546
+ }
547
+ return rpcEval(args, entityAddComponentsSnippet(), {
548
+ id,
549
+ components: objectJson(data, "components"),
550
+ });
551
+ }
455
552
  if (subcommand === "remove-component") {
456
553
  const id = flagString(args, "id");
554
+ const components = flagList(args, "component");
457
555
  const component = flagString(args, "component");
458
- if (!id || !component) {
556
+ if (!id || (!components.length && !component)) {
459
557
  return fail("INVALID_REQUEST", "entity remove-component requires --id and --component.");
460
558
  }
461
- return rpcEval(args, entityRemoveComponentSnippet(), { id, component });
559
+ if (components.length > 1) {
560
+ return rpcEval(args, entityRemoveComponentsSnippet(), {
561
+ id,
562
+ components: components,
563
+ });
564
+ }
565
+ return rpcEval(args, entityRemoveComponentSnippet(), { id, component: component || components[0] });
566
+ }
567
+ if (subcommand === "remove-components") {
568
+ const id = flagString(args, "id");
569
+ const components = flagList(args, "component");
570
+ if (!id || !components.length) {
571
+ return fail("INVALID_REQUEST", "entity remove-components requires --id and at least one --component.");
572
+ }
573
+ return rpcEval(args, entityRemoveComponentsSnippet(), {
574
+ id,
575
+ components: components,
576
+ });
462
577
  }
463
578
  if (subcommand === "set-material") {
464
579
  const id = flagString(args, "id");
@@ -495,6 +610,7 @@ async function handleAsset(args) {
495
610
  return listEnvelope(await rpcEval(args, assetListSnippet(), {
496
611
  name: flagString(args, "name") || null,
497
612
  type: flagString(args, "type") || null,
613
+ tag: flagString(args, "tag") || null,
498
614
  limit: Number(flagString(args, "limit", "50")),
499
615
  offset: Number(flagString(args, "offset", "0")),
500
616
  full: flagBool(args, "full"),
@@ -506,12 +622,32 @@ async function handleAsset(args) {
506
622
  return fail("INVALID_REQUEST", "asset get requires --id.");
507
623
  return rpcEval(args, assetGetSnippet(), { id, full: flagBool(args, "full") });
508
624
  }
625
+ if (subcommand === "create") {
626
+ const file = flagString(args, "json");
627
+ if (!file)
628
+ return fail("INVALID_REQUEST", "asset create requires --json <file>.");
629
+ const data = JSON.parse(await readFile(file, "utf8"));
630
+ const assets = Array.isArray(data)
631
+ ? data
632
+ : objectJson(data, "asset create data").assets || [data];
633
+ return rpcEval(args, assetCreateManySnippet(), { assets }, 60000);
634
+ }
509
635
  if (subcommand === "folder" && args._[2] === "ensure") {
510
636
  const path = flagString(args, "path");
511
637
  if (!path)
512
638
  return fail("INVALID_REQUEST", "asset folder ensure requires --path.");
513
639
  return rpcEval(args, assetFolderEnsureSnippet(), { path });
514
640
  }
641
+ if (subcommand === "instantiate") {
642
+ const ids = flagList(args, "id");
643
+ const id = flagString(args, "id");
644
+ if (!ids.length && !id)
645
+ return fail("INVALID_REQUEST", "asset instantiate requires --id.");
646
+ return rpcEval(args, assetInstantiateTemplateSnippet(), {
647
+ ids: ids,
648
+ id: id || null,
649
+ }, 60000);
650
+ }
515
651
  if (subcommand === "upload") {
516
652
  const file = flagString(args, "file");
517
653
  if (!file)
@@ -521,7 +657,7 @@ async function handleAsset(args) {
521
657
  if (!type)
522
658
  return fail("INVALID_REQUEST", "asset upload requires --type for this file.");
523
659
  const filename = flagString(args, "filename") || basename(file);
524
- return rpcEval(args, assetUploadSnippet(), {
660
+ return rpcCall(args, "bridge:uploadAsset", {
525
661
  base64: fileBuffer.toString("base64"),
526
662
  mime: flagString(args, "mime") || inferMime(file),
527
663
  name: flagString(args, "name") || nameFromFile(file),
@@ -560,8 +696,57 @@ async function handleMaterial(args) {
560
696
  preload: !flagBool(args, "no-preload"),
561
697
  }, 30000);
562
698
  }
699
+ if (subcommand === "patch") {
700
+ const assetId = flagString(args, "asset-id") || flagString(args, "id");
701
+ if (!assetId)
702
+ return fail("INVALID_REQUEST", "material patch requires --asset-id.");
703
+ const data = (await readJsonFlag(args, "json")) ??
704
+ (flagString(args, "data") ? parseJsonValue(flagString(args, "data") || "{}") : {});
705
+ return rpcEval(args, materialPatchSnippet(), {
706
+ assetId,
707
+ data: objectJson(data, "material data"),
708
+ sets: parseSets(flagList(args, "set")),
709
+ });
710
+ }
711
+ if (subcommand === "set-diffuse") {
712
+ const assetId = flagString(args, "asset-id") || flagString(args, "id");
713
+ const color = flagString(args, "color");
714
+ if (!assetId || !color)
715
+ return fail("INVALID_REQUEST", "material set-diffuse requires --asset-id and --color.");
716
+ return rpcEval(args, materialPatchSnippet(), {
717
+ assetId,
718
+ data: { diffuse: parseJsonValue(color) },
719
+ sets: [],
720
+ });
721
+ }
563
722
  return fail("UNKNOWN_COMMAND", `Unknown material command: ${subcommand || ""}`);
564
723
  }
724
+ async function handleTemplate(args) {
725
+ const subcommand = args._[1];
726
+ if (subcommand === "create") {
727
+ const entityId = flagString(args, "entity-id") || flagString(args, "id");
728
+ if (!entityId)
729
+ return fail("INVALID_REQUEST", "template create requires --entity-id.");
730
+ return rpcEval(args, templateCreateSnippet(), {
731
+ entityId,
732
+ name: flagString(args, "name") || null,
733
+ folder: flagString(args, "folder") || null,
734
+ folderId: flagString(args, "folder-id") || null,
735
+ preload: !flagBool(args, "no-preload"),
736
+ }, 60000);
737
+ }
738
+ if (subcommand === "instantiate") {
739
+ const ids = flagList(args, "id");
740
+ const id = flagString(args, "id");
741
+ if (!ids.length && !id)
742
+ return fail("INVALID_REQUEST", "template instantiate requires --id.");
743
+ return rpcEval(args, assetInstantiateTemplateSnippet(), {
744
+ ids: ids,
745
+ id: id || null,
746
+ }, 60000);
747
+ }
748
+ return fail("UNKNOWN_COMMAND", `Unknown template command: ${subcommand || ""}`);
749
+ }
565
750
  async function handleScript(args) {
566
751
  const subcommand = args._[1];
567
752
  if (subcommand === "create") {
@@ -597,8 +782,74 @@ async function handleScript(args) {
597
782
  }
598
783
  return fail("UNKNOWN_COMMAND", `Unknown script command: ${subcommand || ""}`);
599
784
  }
785
+ async function handleScene(args) {
786
+ const subcommand = args._[1];
787
+ if (subcommand === "settings" && (args._[2] || "get") === "get") {
788
+ return rpcEval(args, sceneSettingsGetSnippet());
789
+ }
790
+ if (subcommand === "settings" && args._[2] === "patch") {
791
+ const data = (await readJsonFlag(args, "json")) ?? {};
792
+ const sets = parseSets(flagList(args, "set"));
793
+ if (!Object.keys(objectJson(data, "scene settings")).length && !sets.length) {
794
+ return fail("INVALID_REQUEST", "scene settings patch requires --json <file> or --set path=value.");
795
+ }
796
+ return rpcEval(args, sceneSettingsPatchSnippet(), {
797
+ settings: objectJson(data, "scene settings"),
798
+ sets,
799
+ });
800
+ }
801
+ return fail("UNKNOWN_COMMAND", `Unknown scene command: ${[subcommand, args._[2]].filter(Boolean).join(" ")}`);
802
+ }
803
+ async function handleStore(args) {
804
+ const subcommand = args._[1] || "search";
805
+ if (subcommand === "search") {
806
+ const search = flagString(args, "search") || flagString(args, "q");
807
+ if (!search)
808
+ return fail("INVALID_REQUEST", "store search requires --search.");
809
+ return rpcEval(args, storeSearchSnippet(), {
810
+ search,
811
+ order: flagString(args, "order") || null,
812
+ skip: Number(flagString(args, "skip", "0")),
813
+ limit: Number(flagString(args, "limit", "20")),
814
+ }, 30000);
815
+ }
816
+ if (subcommand === "get") {
817
+ const id = flagString(args, "id");
818
+ if (!id)
819
+ return fail("INVALID_REQUEST", "store get requires --id.");
820
+ return rpcEval(args, storeGetSnippet(), { id }, 30000);
821
+ }
822
+ if (subcommand === "download") {
823
+ const id = flagString(args, "id");
824
+ const name = flagString(args, "name");
825
+ const license = await readJsonFlag(args, "license-json");
826
+ if (!id || !name || license === undefined) {
827
+ return fail("INVALID_REQUEST", "store download requires --id, --name, and --license-json.");
828
+ }
829
+ return rpcEval(args, storeDownloadSnippet(), {
830
+ id,
831
+ name,
832
+ license: objectJson(license, "license"),
833
+ folderId: flagString(args, "folder-id") || null,
834
+ }, 120000);
835
+ }
836
+ return fail("UNKNOWN_COMMAND", `Unknown store command: ${subcommand}`);
837
+ }
600
838
  async function handleViewport(args) {
601
839
  const subcommand = args._[1];
840
+ if (subcommand === "focus") {
841
+ const ids = flagList(args, "id");
842
+ const id = flagString(args, "id");
843
+ if (!ids.length && !id)
844
+ return fail("INVALID_REQUEST", "viewport focus requires --id.");
845
+ return rpcCall(args, "bridge:focusViewport", {
846
+ ids: ids,
847
+ id: id || null,
848
+ view: flagString(args, "view") || null,
849
+ yaw: flagString(args, "yaw") === undefined ? null : Number(flagString(args, "yaw")),
850
+ pitch: flagString(args, "pitch") === undefined ? null : Number(flagString(args, "pitch")),
851
+ });
852
+ }
602
853
  if (subcommand !== "capture") {
603
854
  return fail("UNKNOWN_COMMAND", `Unknown viewport command: ${subcommand || ""}`);
604
855
  }
@@ -622,27 +873,102 @@ async function handleViewport(args) {
622
873
  }
623
874
  return raw;
624
875
  }
625
- function usage() {
626
- return ok({
627
- usage: [
876
+ function help(group = "overview") {
877
+ const groups = {
878
+ overview: [
879
+ "pcbridge help core",
880
+ "pcbridge help entity",
881
+ "pcbridge help asset",
882
+ "pcbridge help material",
883
+ "pcbridge help template",
884
+ "pcbridge help script",
885
+ "pcbridge help scene",
886
+ "pcbridge help store",
887
+ "pcbridge help viewport",
888
+ "pcbridge help eval",
889
+ ],
890
+ core: [
628
891
  "pcbridge doctor",
629
892
  "pcbridge install-extension",
630
893
  "pcbridge install-skill --agent codex|claude|cursor|windsurf|all",
631
894
  "pcbridge daemon start",
632
895
  "pcbridge daemon status",
633
896
  "pcbridge targets",
634
- "pcbridge eval --target current --code \"return location.href\"",
635
- "pcbridge entity list --target current",
636
- "pcbridge asset list --target current --type script",
637
- "pcbridge asset upload --target current --file ./texture.png --folder \"AI Agent Bridge/Textures\"",
638
- "pcbridge material create --target current --name Mat --diffuse-map <asset_id>",
639
- "pcbridge script create --target current --filename controller.js --file ./controller.js",
897
+ "pcbridge version",
898
+ ],
899
+ entity: [
900
+ "pcbridge entity list --target current --limit 50 [--name Player] [--component render] [--tag enemy] [--full]",
901
+ "pcbridge entity get --target current --id <resource_id> [--full]",
902
+ "pcbridge entity create --target current --json ./entity.json",
903
+ "pcbridge entity create-many --target current --json ./entities.json",
904
+ "pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'",
905
+ "pcbridge entity patch-many --target current --json ./edits.json",
906
+ "pcbridge entity duplicate --target current --id <resource_id>",
907
+ "pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id> [--index 0] [--no-preserve-transform]",
908
+ "pcbridge entity add-component --target current --id <resource_id> --component render --data '{\"type\":\"box\"}'",
909
+ "pcbridge entity add-components --target current --id <resource_id> --json ./components.json",
910
+ "pcbridge entity remove-component --target current --id <resource_id> --component render",
640
911
  "pcbridge entity set-material --target current --id <resource_id> --material-id <asset_id>",
641
- "pcbridge entity add-script --target current --id <resource_id> --script-name controller",
642
- "pcbridge viewport capture --target current --out ./tmp/viewport.png",
912
+ "pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes-json ./attrs.json",
913
+ "pcbridge entity delete --target current --id <resource_id>",
914
+ ],
915
+ asset: [
916
+ "pcbridge asset list --target current [--type script] [--name controller] [--tag ui] [--limit 50] [--full]",
917
+ "pcbridge asset get --target current --id <asset_id> [--full]",
918
+ "pcbridge asset create --target current --json ./assets.json",
919
+ "pcbridge asset folder ensure --target current --path \"AI Agent Bridge/Task/Textures\"",
920
+ "pcbridge asset upload --target current --file ./texture.png --folder \"AI Agent Bridge/Task/Textures\"",
921
+ "pcbridge asset instantiate --target current --id <template_asset_id>",
922
+ "pcbridge asset delete --target current --id <asset_id>",
923
+ ],
924
+ material: [
925
+ "pcbridge material create --target current --name Mat --diffuse-map <texture_asset_id>",
926
+ "pcbridge material patch --target current --asset-id <asset_id> --set diffuse='[1,0,0]'",
927
+ "pcbridge material patch --target current --asset-id <asset_id> --json ./material-data.json",
928
+ "pcbridge material set-diffuse --target current --asset-id <asset_id> --color '[1,0,0]'",
929
+ ],
930
+ template: [
931
+ "pcbridge template create --target current --entity-id <resource_id> --name TemplateName --folder \"AI Agent Bridge/Task/Templates\"",
932
+ "pcbridge template instantiate --target current --id <template_asset_id>",
643
933
  ],
934
+ script: [
935
+ "pcbridge script create --target current --filename controller.js --file ./controller.js",
936
+ "pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js",
937
+ "pcbridge script parse --target current --asset-id <asset_id>",
938
+ ],
939
+ scene: [
940
+ "pcbridge scene settings get --target current",
941
+ "pcbridge scene settings patch --target current --json ./scene-settings.json",
942
+ "pcbridge scene settings patch --target current --set render.fog='\"linear\"' --set physics.gravity='[0,-9.8,0]'",
943
+ ],
944
+ store: [
945
+ "pcbridge store search --target current --search vehicle --limit 20",
946
+ "pcbridge store get --target current --id <store_asset_id>",
947
+ "pcbridge store download --target current --id <store_asset_id> --name AssetName --license-json ./license.json",
948
+ ],
949
+ viewport: [
950
+ "pcbridge viewport capture --target current --out ./tmp/viewport.png [--format png|webp]",
951
+ "pcbridge viewport focus --target current --id <resource_id> [--view perspective|top|bottom|front|back|left|right]",
952
+ ],
953
+ eval: [
954
+ "Use eval for custom Editor/Engine workflows, large multi-step scene edits, exploratory API inspection, and operations not yet structured.",
955
+ "pcbridge eval --target current --code \"return { href: location.href, hasEditor: !!editor }\"",
956
+ "pcbridge eval --target current --file ./task.js",
957
+ "pcbridge eval --target current --stdin",
958
+ ],
959
+ };
960
+ const commands = groups[group];
961
+ if (!commands) {
962
+ return fail("UNKNOWN_HELP_TOPIC", `Unknown help topic: ${group}.`, undefined, Object.keys(groups));
963
+ }
964
+ return ok({
965
+ topic: group,
966
+ commands,
644
967
  });
645
968
  }
969
+ function usage() {
970
+ return help("overview");
971
+ }
646
972
  async function main() {
647
973
  const args = parseArgs(process.argv.slice(2));
648
974
  const command = args._[0] || "help";
@@ -651,8 +977,11 @@ async function main() {
651
977
  return;
652
978
  }
653
979
  try {
654
- if (command === "help" || command === "--help" || command === "-h") {
655
- print(usage());
980
+ if (command !== "help" && args._[1] === "help") {
981
+ print(help(command));
982
+ }
983
+ else if (command === "help" || command === "--help" || command === "-h") {
984
+ print(help(args._[1] || "overview"));
656
985
  }
657
986
  else if (command === "doctor") {
658
987
  print(await doctor());
@@ -678,9 +1007,18 @@ async function main() {
678
1007
  else if (command === "material") {
679
1008
  print(await handleMaterial(args));
680
1009
  }
1010
+ else if (command === "template") {
1011
+ print(await handleTemplate(args));
1012
+ }
681
1013
  else if (command === "script") {
682
1014
  print(await handleScript(args));
683
1015
  }
1016
+ else if (command === "scene") {
1017
+ print(await handleScene(args));
1018
+ }
1019
+ else if (command === "store") {
1020
+ print(await handleStore(args));
1021
+ }
684
1022
  else if (command === "viewport") {
685
1023
  print(await handleViewport(args));
686
1024
  }
package/dist/config.js CHANGED
@@ -4,7 +4,7 @@ import { existsSync } from "node:fs";
4
4
  import { homedir } from "node:os";
5
5
  import { dirname, join, resolve } from "node:path";
6
6
  import { fileURLToPath } from "node:url";
7
- export const VERSION = "0.2.1";
7
+ export const VERSION = "0.2.2";
8
8
  export const DEFAULT_HOST = "127.0.0.1";
9
9
  export const DEFAULT_PORT = 17329;
10
10
  export const CONFIG_DIR = join(homedir(), ".pcbridge");