playcanvas-agent-bridge-cli 0.5.0 → 0.5.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
@@ -20,9 +20,8 @@ npm install -g github:Q-My99/playcanvas-agent-bridge-cli
20
20
  pcbridge install-skill --agent all
21
21
  ```
22
22
 
23
- The commands documented below include repository version `0.5.0`. Until that version is published,
24
- the npm `latest` release (`0.3.0` as of 2026-08-04) does not contain every command described here;
25
- use the GitHub install when testing these unreleased changes.
23
+ The commands documented below track repository version `0.5.2`. npm installs the latest stable
24
+ release; use the GitHub install when testing changes that have not been released yet.
26
25
 
27
26
  One-shot with npx:
28
27
 
@@ -106,7 +105,7 @@ When a ready Editor connects, pcbridge creates `<projectId>-<projectName>/` auto
106
105
  ```text
107
106
  1552681-pcbridge-test/
108
107
  ├── pcbridge.project.json # project metadata plus the agent-readable asset catalog
109
- ├── assets/ # PlayCanvas folder mirror with bidirectional file-content sync
108
+ ├── assets/ # PlayCanvas folder mirror; scripts eager, binary assets lazy
110
109
  ├── tmp/ # builds, cache, conflicts, captures, and quarantined remote deletions
111
110
  └── .pcbridge/ # internal sync state; do not edit
112
111
  ```
@@ -120,12 +119,15 @@ pcbridge workspace sync --target editor:<sceneId>
120
119
  pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
121
120
  ```
122
121
 
123
- Scripts, images, models, audio, and other asset files synchronize in both directions. The initial
124
- mirror downloads project files. Later refreshes read the complete Asset metadata snapshot but reuse
125
- cached local size/mtime/MD5 values and transfer file content only when it is missing or changed.
126
- A local-only edit uploads, a remote-only edit downloads, and concurrent edits preserve both text or
127
- binary copies under `tmp/conflicts/`. Create, move, rename, and delete assets through structured
128
- pcbridge commands; `workspace pull` remains available for an explicit single-file refresh.
122
+ Scripts are eagerly mirrored and kept close to real time. Images, models, audio, fonts, and other
123
+ binary assets are lazy: refresh records the Asset metadata and PlayCanvas MD5 without downloading
124
+ file contents. Use `workspace pull`, or let Tiny Builder fetch the dependencies needed for a build.
125
+ Existing binary files under `assets/` are retained and remain bidirectional. Local edits upload,
126
+ remote edits download according to the sync baseline, and concurrent edits preserve both copies under
127
+ `tmp/conflicts/`. New local files are uploaded into their matching folder and PlayCanvas decides the
128
+ imported type; local folders are created remotely. Renames and moves preserve the Asset ID. Deleting
129
+ a local file only clears the local cache and never deletes the remote Asset. The `tmp/` tree is
130
+ agent-owned and excluded from workspace synchronization.
129
131
 
130
132
  `pcbridge.project.json` schema v2 stores every asset id, type, PlayCanvas folder, project-relative
131
133
  `assets/...` file path, download presence, and the remote/local/base MD5 values. Agents may read
package/README.zh-CN.md CHANGED
@@ -13,8 +13,8 @@ npm install -g playcanvas-agent-bridge-cli
13
13
  pcbridge install-skill --agent all
14
14
  ```
15
15
 
16
- 下文命令包含仓库版 `0.5.0` 的尚未发布改动。在该版本发布前,npm 的 `latest`(截至
17
- 2026-08-04 为 `0.3.0`)不包含这里列出的全部命令;测试本轮新能力时请使用 GitHub 安装。
16
+ 下文命令跟随仓库版 `0.5.2`。npm 安装的是最新稳定版本;测试尚未发布的改动时请使用
17
+ GitHub 安装。
18
18
 
19
19
  如果要测试尚未发布的改动,也可以直接从这个 GitHub 仓库安装:
20
20
 
@@ -119,11 +119,18 @@ pcbridge workspace sync --target editor:<sceneId>
119
119
  pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
120
120
  ```
121
121
 
122
- 脚本、图片、模型、音频等文件内容都保持双向同步。首次建立镜像会下载项目文件;之后每轮
123
- 刷新只读取完整 Asset 元数据,并用 PlayCanvas MD5 与本地缓存的 size/mtime/MD5 判断变化,
124
- 不会重复全量传输文件内容。本地单边修改会上传,远端单边修改会下载;同时修改时不会覆盖
125
- 任一版本,文本和二进制冲突副本都写入 `tmp/conflicts/`。资源的新建、移动、重命名和删除
126
- 仍应使用 pcbridge 结构化命令;`workspace pull` 可用于显式重新拉取单个文件。
122
+ 脚本默认实时同步到本地;图片、模型、音频、字体等二进制资源默认只同步 Asset 元数据,
123
+ 不会在首次建立镜像时下载文件内容。需要本地文件时使用 `workspace pull`,或由 Tiny Builder
124
+ 在构建实际依赖时按需拉取。已经存在于 `assets/` 的本地二进制文件会保留并参与双向同步。
125
+ 刷新只读取完整 Asset 元数据,并用 PlayCanvas MD5 与本地缓存的 size/mtime/MD5 判断变化。
126
+ 本地修改会自动上传,远端修改会按基线判断并下载;同时修改时不会覆盖任一版本,文本和二进制
127
+ 冲突副本都写入 `tmp/conflicts/`。
128
+
129
+ daemon 会监控项目 `assets/` 目录:本地新增文件会上传到对应目录,由 PlayCanvas 自行判断资源
130
+ 类型并完成导入,然后重新读取远端 Asset 列表;本地目录会自动映射为 PlayCanvas Folder。
131
+ 本地重命名和移动会保持同一个 Asset ID,并同步远端名称和目录。删除本地文件只视为清理本地
132
+ 缓存,不会删除 PlayCanvas 远端 Asset;远端删除仍会隔离到 `tmp/trash/remote/`。`tmp/` 下的
133
+ 构建、缓存和 agent 临时文件完全不参与 workspace 同步。
127
134
 
128
135
  schema v2 的 `pcbridge.project.json` 会记录每个 asset 的 id、类型、PlayCanvas 文件夹、相对
129
136
  项目根目录的 `assets/...` 文件路径、是否已下载,以及远端、本地和同步基线 MD5。agent 可以
@@ -331,8 +331,9 @@ export class BuilderManager {
331
331
  const originalFilename = asset.file?.filename;
332
332
  const local = preparedById.get(id);
333
333
  if (output.file && local?.path && local.filename) {
334
- const key = `${prefix}/${buildName}/${id}/${safeSegment(local.filename, `asset-${id}`)}`;
335
- output.file.url = publicObjectUrl(settings.publicBaseUrl, key);
334
+ const relativeUrl = `${buildName}/${id}/${safeSegment(local.filename, `asset-${id}`)}`;
335
+ const key = `${prefix}/${relativeUrl}`;
336
+ output.file.url = relativeUrl;
336
337
  uploads.set(key, {
337
338
  key,
338
339
  path: local.path,
@@ -344,8 +345,9 @@ export class BuilderManager {
344
345
  if (!variant.url || !variant.filename)
345
346
  continue;
346
347
  const cached = await this.#cacheRemoteFile(job.info, prepared.projectDirectory, id, variant.filename, variant.url, variant.hash);
347
- const key = `${prefix}/${buildName}/${id}/${safeSegment(variant.filename, "variant.bin")}`;
348
- variant.url = publicObjectUrl(settings.publicBaseUrl, key);
348
+ const relativeUrl = `${buildName}/${id}/${safeSegment(variant.filename, "variant.bin")}`;
349
+ const key = `${prefix}/${relativeUrl}`;
350
+ variant.url = relativeUrl;
349
351
  uploads.set(key, {
350
352
  key,
351
353
  path: cached.path,
@@ -385,8 +387,9 @@ export class BuilderManager {
385
387
  if (scriptText.trim()) {
386
388
  const scriptPath = join(buildRoot, "gamescript.js");
387
389
  await writeFile(scriptPath, scriptText);
388
- const key = `${prefix}/${buildName}/gamescript.js`;
389
- rootData.scriptUrl = publicObjectUrl(settings.publicBaseUrl, key);
390
+ const relativeUrl = `${buildName}/gamescript.js`;
391
+ const key = `${prefix}/${relativeUrl}`;
392
+ rootData.scriptUrl = relativeUrl;
390
393
  uploads.set(key, {
391
394
  key,
392
395
  path: scriptPath,
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.5.0";
7
+ export const VERSION = "0.5.2";
8
8
  export const DEFAULT_HOST = "127.0.0.1";
9
9
  export const DEFAULT_PORT = 17329;
10
10
  export const DEFAULT_FRONTEND_PORT = 3487;
@@ -1,5 +1,6 @@
1
1
  import { createHash, randomUUID } from "node:crypto";
2
2
  import { existsSync } from "node:fs";
3
+ import { watch } from "node:fs";
3
4
  import { copyFile, lstat, mkdir, readFile, readdir, rename, rmdir, stat, writeFile, } from "node:fs/promises";
4
5
  import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
5
6
  const PROJECT_FILE = "pcbridge.project.json";
@@ -7,6 +8,8 @@ const LEGACY_INDEX_FILE = join(".pcbridge", "asset-index.json");
7
8
  const LEGACY_INDEX_BACKUP_FILE = join(".pcbridge", "asset-index.v1.json");
8
9
  const SYNC_STATE_FILE = join(".pcbridge", "sync-state.json");
9
10
  const DEFAULT_REFRESH_INTERVAL_MS = 5000;
11
+ const DEFAULT_LOCAL_CHANGE_DEBOUNCE_MS = 350;
12
+ const PENDING_LOCAL_FILE_TTL_MS = 5 * 60 * 1000;
10
13
  function hashContent(value) {
11
14
  return createHash("md5").update(value).digest("hex");
12
15
  }
@@ -57,6 +60,11 @@ function asObject(value) {
57
60
  }
58
61
  return value;
59
62
  }
63
+ function isDerivedAsset(asset) {
64
+ return asset.source_asset_id !== undefined &&
65
+ asset.source_asset_id !== null &&
66
+ asset.source_asset_id !== "";
67
+ }
60
68
  async function atomicWrite(path, value) {
61
69
  await mkdir(dirname(path), { recursive: true });
62
70
  const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
@@ -84,10 +92,14 @@ export class WorkspaceManager {
84
92
  #requestTarget;
85
93
  #records = new Map();
86
94
  #refreshTimer = null;
95
+ #watchers = new Map();
96
+ #watchTimers = new Map();
97
+ #localChangeDebounceMs;
87
98
  constructor(options) {
88
99
  this.rootDir = resolve(options.rootDir);
89
100
  this.#requestTarget = options.requestTarget;
90
101
  const interval = options.refreshIntervalMs ?? DEFAULT_REFRESH_INTERVAL_MS;
102
+ this.#localChangeDebounceMs = options.localChangeDebounceMs ?? DEFAULT_LOCAL_CHANGE_DEBOUNCE_MS;
91
103
  if (interval > 0) {
92
104
  this.#refreshTimer = setInterval(() => {
93
105
  for (const record of this.#records.values()) {
@@ -104,6 +116,13 @@ export class WorkspaceManager {
104
116
  this.#refreshTimer = null;
105
117
  }
106
118
  await Promise.all(Array.from(this.#records.values(), (record) => record.syncPromise).filter(Boolean));
119
+ for (const watchers of this.#watchers.values())
120
+ for (const watcher of watchers)
121
+ watcher.close();
122
+ this.#watchers.clear();
123
+ for (const timer of this.#watchTimers.values())
124
+ clearTimeout(timer);
125
+ this.#watchTimers.clear();
107
126
  }
108
127
  async handleTarget(info) {
109
128
  if (info.kind !== "editor" ||
@@ -125,6 +144,7 @@ export class WorkspaceManager {
125
144
  record.projectName = info.projectName;
126
145
  record.branchName = info.branchName || record.branchName;
127
146
  await this.#writeManifest(record);
147
+ this.#ensureWatcher(record);
128
148
  await this.#sync(record, false);
129
149
  }
130
150
  markDisconnected(info) {
@@ -175,7 +195,9 @@ export class WorkspaceManager {
175
195
  record.targetId = info.id;
176
196
  record.targetInfo = info;
177
197
  record.connected = true;
178
- await this.#sync(record, true);
198
+ // A build only needs the selected dependency metadata and files. Do not
199
+ // turn lazy binary synchronization back into a full project download.
200
+ await this.#sync(record, false);
179
201
  return this.#status(record);
180
202
  }
181
203
  async prepareAssetFiles(info, assetIds) {
@@ -200,13 +222,20 @@ export class WorkspaceManager {
200
222
  if (entry.localPath && !existsSync(this.#assetPath(record, entry.localPath))) {
201
223
  await this.#downloadAsset(record, entry);
202
224
  }
225
+ let preparedPath = entry.localPath ? this.#assetPath(record, entry.localPath) : null;
226
+ let preparedHash = entry.localHash;
227
+ if (!preparedPath && entry.filename && entry.remoteFileHash) {
228
+ const cached = await this.#prepareCachedAsset(record, entry);
229
+ preparedPath = cached.path;
230
+ preparedHash = cached.hash;
231
+ }
203
232
  assets.push({
204
233
  id,
205
234
  name: entry.name,
206
235
  type: entry.type,
207
236
  filename: entry.filename,
208
- path: entry.localPath ? this.#assetPath(record, entry.localPath) : null,
209
- hash: entry.localHash,
237
+ path: preparedPath,
238
+ hash: preparedHash,
210
239
  });
211
240
  }
212
241
  await this.#persist(record);
@@ -295,10 +324,65 @@ export class WorkspaceManager {
295
324
  legacyIndexPath: legacyPrimary?.schemaVersion === 1 ? legacyPrimaryPath : null,
296
325
  index,
297
326
  syncPromise: null,
327
+ pendingLocalFiles: new Map(),
298
328
  };
299
329
  this.#records.set(record.projectId, record);
300
330
  return record;
301
331
  }
332
+ #ensureWatcher(record) {
333
+ if (this.#watchers.has(record.projectId))
334
+ return;
335
+ const watchers = new Set();
336
+ this.#watchers.set(record.projectId, watchers);
337
+ const schedule = (filename) => {
338
+ if (!filename)
339
+ return;
340
+ const relativeName = toPosixPath(String(filename));
341
+ if (relativeName.startsWith(".pcbridge/") || relativeName.startsWith("tmp/") || relativeName.includes("/tmp/"))
342
+ return;
343
+ const existing = this.#watchTimers.get(record.projectId);
344
+ if (existing)
345
+ clearTimeout(existing);
346
+ const timer = setTimeout(() => {
347
+ this.#watchTimers.delete(record.projectId);
348
+ if (record.connected)
349
+ void this.#sync(record, true);
350
+ }, this.#localChangeDebounceMs);
351
+ timer.unref();
352
+ this.#watchTimers.set(record.projectId, timer);
353
+ };
354
+ try {
355
+ const watcher = watch(record.assetsDirectory, { recursive: true }, (_event, filename) => {
356
+ schedule(filename);
357
+ });
358
+ watcher.on("error", (error) => { record.lastWarning = `Local workspace watcher stopped: ${String(error)}`; });
359
+ watchers.add(watcher);
360
+ }
361
+ catch (error) {
362
+ // Some Linux Node builds do not support recursive fs.watch. Watch each
363
+ // existing directory instead; new directories are picked up on sync.
364
+ const attach = async (directory) => {
365
+ let watcher;
366
+ try {
367
+ watcher = watch(directory, (_event, filename) => schedule(filename));
368
+ }
369
+ catch {
370
+ return;
371
+ }
372
+ watchers.add(watcher);
373
+ let children;
374
+ try {
375
+ children = await readdir(directory, { withFileTypes: true });
376
+ }
377
+ catch {
378
+ return;
379
+ }
380
+ await Promise.all(children.filter((child) => child.isDirectory()).map((child) => attach(join(directory, child.name))));
381
+ };
382
+ void attach(record.assetsDirectory);
383
+ record.lastWarning = `Recursive local watcher unavailable; using directory watchers (${String(error)})`;
384
+ }
385
+ }
302
386
  async #findProjectDirectory(projectId) {
303
387
  let entries;
304
388
  try {
@@ -346,7 +430,7 @@ export class WorkspaceManager {
346
430
  filename: asset.file?.filename || null,
347
431
  remoteFileSize: asset.file?.size ?? null,
348
432
  remoteFileHash: asset.file?.hash.remote || null,
349
- localHash: present ? asset.file?.hash.local || null : null,
433
+ localHash: asset.file?.hash.local || null,
350
434
  lastSyncedHash: asset.file?.hash.base || null,
351
435
  legacyLastSyncedSha256: syncState?.entries?.[id]?.legacyLastSyncedSha256,
352
436
  pendingRemoteHash: syncState?.entries?.[id]?.pendingRemoteHash,
@@ -429,7 +513,7 @@ export class WorkspaceManager {
429
513
  hash: {
430
514
  algorithm: "md5",
431
515
  remote: entry.remoteFileHash,
432
- local: present ? entry.localHash : null,
516
+ local: entry.localHash,
433
517
  base: entry.lastSyncedHash,
434
518
  matches: entry.remoteFileHash && present && entry.localHash
435
519
  ? entry.remoteFileHash === entry.localHash
@@ -570,6 +654,7 @@ export class WorkspaceManager {
570
654
  action: "comparing",
571
655
  };
572
656
  await this.#applySnapshot(record, assets, force);
657
+ await this.#uploadUnindexedFiles(record);
573
658
  record.lastSyncedAt = new Date().toISOString();
574
659
  const entries = Object.values(record.index.entries);
575
660
  record.state = entries.some((entry) => entry.status === "conflict")
@@ -594,6 +679,104 @@ export class WorkspaceManager {
594
679
  record.syncProgress = null;
595
680
  }
596
681
  }
682
+ async #uploadUnindexedFiles(record) {
683
+ const now = Date.now();
684
+ for (const [path, pending] of record.pendingLocalFiles) {
685
+ if (now - pending.createdAt > PENDING_LOCAL_FILE_TTL_MS)
686
+ record.pendingLocalFiles.delete(path);
687
+ }
688
+ const known = new Set(Object.values(record.index.entries)
689
+ .map((entry) => entry.localPath ? toPosixPath(entry.localPath) : null)
690
+ .filter(Boolean));
691
+ for (const path of record.pendingLocalFiles.keys())
692
+ known.add(path);
693
+ const files = [];
694
+ const visit = async (directory, relativeDirectory) => {
695
+ let children;
696
+ try {
697
+ children = await readdir(directory, { withFileTypes: true });
698
+ }
699
+ catch {
700
+ return;
701
+ }
702
+ for (const child of children) {
703
+ if (child.name.startsWith(".") || child.name === "tmp")
704
+ continue;
705
+ const relativePath = relativeDirectory ? join(relativeDirectory, child.name) : child.name;
706
+ const path = join(directory, child.name);
707
+ if (child.isDirectory())
708
+ await visit(path, relativePath);
709
+ else if (child.isFile() && !known.has(toPosixPath(relativePath)))
710
+ files.push(relativePath);
711
+ }
712
+ };
713
+ await visit(record.assetsDirectory, "");
714
+ for (const relativePath of files) {
715
+ const path = this.#assetPath(record, relativePath);
716
+ const content = await readFile(path);
717
+ const contentHash = hashContent(content);
718
+ const normalizedPath = toPosixPath(relativePath);
719
+ const parts = relativePath.split(/[\\/]/g);
720
+ const filename = parts.pop() || "asset.bin";
721
+ const folder = parts.join("/");
722
+ const renamed = Object.values(record.index.entries).find((entry) => entry.type !== "folder" && entry.localPath && !existsSync(this.#assetPath(record, entry.localPath)) &&
723
+ entry.localHash === contentHash);
724
+ if (renamed) {
725
+ const renameResponse = await this.#requestTarget(record.targetId, "bridge:renameAsset", {
726
+ assetId: renamed.id,
727
+ name: filename,
728
+ filename,
729
+ folder,
730
+ }, 60000);
731
+ if (renameResponse.ok) {
732
+ record.pendingLocalFiles.set(normalizedPath, {
733
+ assetId: renamed.id,
734
+ hash: contentHash,
735
+ createdAt: Date.now(),
736
+ });
737
+ const refresh = await this.#requestTarget(record.targetId, "bridge:workspaceSnapshot", {}, 60000);
738
+ if (refresh.ok) {
739
+ const snapshot = asObject(refresh.data);
740
+ const refreshedAssets = Array.isArray(snapshot.assets) ? snapshot.assets : [];
741
+ if (refreshedAssets.length)
742
+ await this.#applySnapshot(record, refreshedAssets, false);
743
+ }
744
+ continue;
745
+ }
746
+ }
747
+ const response = await this.#requestTarget(record.targetId, "bridge:uploadAsset", {
748
+ name: filename,
749
+ filename,
750
+ folder,
751
+ base64: content.toString("base64"),
752
+ }, 120000);
753
+ if (!response.ok) {
754
+ record.lastWarning = `Failed to upload local file ${relativePath}: ${response.error.message}`;
755
+ continue;
756
+ }
757
+ const data = asObject(response.data);
758
+ const uploaded = data.asset;
759
+ if (uploaded && typeof uploaded === "object" && !Array.isArray(uploaded)) {
760
+ const uploadedId = uploaded.id;
761
+ if (uploadedId !== undefined && uploadedId !== null) {
762
+ record.pendingLocalFiles.set(normalizedPath, {
763
+ assetId: String(uploadedId),
764
+ hash: contentHash,
765
+ createdAt: Date.now(),
766
+ });
767
+ }
768
+ const refresh = await this.#requestTarget(record.targetId, "bridge:workspaceSnapshot", {}, 60000);
769
+ if (refresh.ok) {
770
+ const snapshot = asObject(refresh.data);
771
+ const refreshedAssets = Array.isArray(snapshot.assets)
772
+ ? snapshot.assets
773
+ : [];
774
+ if (refreshedAssets.length)
775
+ await this.#applySnapshot(record, refreshedAssets, false);
776
+ }
777
+ }
778
+ }
779
+ }
597
780
  #acceptSnapshot(record, assets) {
598
781
  const previousIds = Object.keys(record.index.entries);
599
782
  if (!previousIds.length) {
@@ -659,7 +842,9 @@ export class WorkspaceManager {
659
842
  }
660
843
  const previous = record.index.entries;
661
844
  const next = {};
662
- for (const asset of assets) {
845
+ const staleDerivedPaths = [];
846
+ const orderedAssets = [...assets].sort((left, right) => Number(isDerivedAsset(left)) - Number(isDerivedAsset(right)));
847
+ for (const asset of orderedAssets) {
663
848
  const id = String(asset.id);
664
849
  const parentIds = (asset.path || []).map(String);
665
850
  const parent = parentIds.length ? folderPaths.get(parentIds[parentIds.length - 1]) || [] : [];
@@ -682,8 +867,10 @@ export class WorkspaceManager {
682
867
  };
683
868
  continue;
684
869
  }
870
+ const derived = isDerivedAsset(asset);
685
871
  const remoteFilename = asset.file?.filename || (asset.type === "script" ? asset.name : null);
686
- const localName = remoteFilename ? allocateName(parent, remoteFilename, id) : null;
872
+ const localFilename = asset.source && asset.name ? asset.name : remoteFilename;
873
+ const localName = !derived && localFilename ? allocateName(parent, localFilename, id) : null;
687
874
  const localPath = localName ? join(...parent, localName) : null;
688
875
  const old = previous[id];
689
876
  const entry = {
@@ -717,7 +904,21 @@ export class WorkspaceManager {
717
904
  if (!existsSync(newPath))
718
905
  await rename(oldPath, newPath);
719
906
  }
720
- if (asset.type === "script" && localPath) {
907
+ if (derived) {
908
+ // PlayCanvas generated Model/Container/Texture assets are outputs of a
909
+ // source import (for example GLB). They are remote catalog entries,
910
+ // not local source files and must never be uploaded back.
911
+ entry.localPath = null;
912
+ entry.downloaded = false;
913
+ entry.localHash = null;
914
+ entry.localFileSize = undefined;
915
+ entry.localMtimeMs = undefined;
916
+ entry.status = "indexed";
917
+ delete entry.error;
918
+ if (old?.localPath)
919
+ staleDerivedPaths.push({ id, path: old.localPath });
920
+ }
921
+ else if (asset.type === "script" && localPath) {
721
922
  await this.#reconcileScript(record, entry, old, force);
722
923
  }
723
924
  else if (localPath) {
@@ -727,6 +928,17 @@ export class WorkspaceManager {
727
928
  record.syncProgress.completed += 1;
728
929
  }
729
930
  const deletionBatch = new Date().toISOString().replaceAll(":", "-");
931
+ const activeLocalPaths = new Set(Object.values(next).map((entry) => entry.localPath).filter(Boolean));
932
+ for (const stale of staleDerivedPaths) {
933
+ if (activeLocalPaths.has(stale.path))
934
+ continue;
935
+ const source = this.#assetPath(record, stale.path);
936
+ if (!existsSync(source))
937
+ continue;
938
+ const destination = join(record.tmpDirectory, "trash", "derived", deletionBatch, `${stale.id}-${safeWorkspaceName(basename(stale.path), `asset-${stale.id}`)}`);
939
+ await mkdir(dirname(destination), { recursive: true });
940
+ await rename(source, destination);
941
+ }
730
942
  for (const [id, old] of Object.entries(previous)) {
731
943
  if (next[id] || !old.localPath || !existsSync(this.#assetPath(record, old.localPath)))
732
944
  continue;
@@ -752,6 +964,12 @@ export class WorkspaceManager {
752
964
  updatedAt: new Date().toISOString(),
753
965
  entries: next,
754
966
  };
967
+ for (const [path, pending] of record.pendingLocalFiles) {
968
+ const entry = next[pending.assetId];
969
+ if (entry?.localPath && toPosixPath(entry.localPath) === path) {
970
+ record.pendingLocalFiles.delete(path);
971
+ }
972
+ }
755
973
  }
756
974
  async #localFileSnapshot(record, entry, old) {
757
975
  if (!entry.localPath)
@@ -815,6 +1033,20 @@ export class WorkspaceManager {
815
1033
  delete entry.error;
816
1034
  return { path, size: remote.content.byteLength, hash: remote.hash };
817
1035
  }
1036
+ async #prepareCachedAsset(record, entry) {
1037
+ if (!entry.filename)
1038
+ throw new Error(`Asset ${entry.id} has no cacheable filename.`);
1039
+ const path = join(record.tmpDirectory, "cache", "assets", safeAssetName(entry.id, "asset"), safeAssetName(entry.filename, "file.bin"));
1040
+ if (existsSync(path)) {
1041
+ const content = await readFile(path);
1042
+ const hash = hashContent(content);
1043
+ if (!entry.remoteFileHash || hash === entry.remoteFileHash)
1044
+ return { path, hash };
1045
+ }
1046
+ const remote = await this.#readRemoteAsset(record, entry);
1047
+ await atomicWrite(path, remote.content);
1048
+ return { path, hash: remote.hash };
1049
+ }
818
1050
  async #uploadBinary(record, entry, content, localHash) {
819
1051
  if (record.syncProgress) {
820
1052
  record.syncProgress.assetId = entry.id;
@@ -859,7 +1091,11 @@ export class WorkspaceManager {
859
1091
  const baseline = old?.lastSyncedHash || null;
860
1092
  const advertisedRemoteHash = entry.remoteFileHash;
861
1093
  if (!local) {
862
- await this.#downloadAsset(record, entry);
1094
+ // Binary assets are lazy. Keep the catalog and remote hash locally, and
1095
+ // only fetch bytes through workspace pull or a Template build.
1096
+ entry.downloaded = false;
1097
+ entry.status = "indexed";
1098
+ delete entry.error;
863
1099
  return;
864
1100
  }
865
1101
  entry.localHash = local.hash;
@@ -942,6 +1178,44 @@ export class WorkspaceManager {
942
1178
  old?.pendingRemoteHash &&
943
1179
  localHash === old.pendingRemoteHash &&
944
1180
  advertisedRemoteHash !== old.pendingRemoteHash) {
1181
+ if (record.syncProgress) {
1182
+ record.syncProgress.assetId = entry.id;
1183
+ record.syncProgress.action = "downloading";
1184
+ }
1185
+ const response = await this.#requestTarget(record.targetId, "bridge:readAssetText", { assetId: entry.id }, 30000);
1186
+ if (!response.ok) {
1187
+ entry.localHash = localHash;
1188
+ entry.pendingRemoteHash = old.pendingRemoteHash;
1189
+ entry.downloaded = true;
1190
+ entry.status = "local-change";
1191
+ entry.error = response.error.message;
1192
+ return;
1193
+ }
1194
+ const data = asObject(response.data);
1195
+ const pendingRemoteContent = typeof data.text === "string" ? data.text : "";
1196
+ const pendingRemoteHash = hashContent(pendingRemoteContent);
1197
+ entry.remoteFileHash = pendingRemoteHash;
1198
+ if (pendingRemoteHash === old.pendingRemoteHash) {
1199
+ entry.localHash = localHash;
1200
+ entry.lastSyncedHash = localHash;
1201
+ entry.downloaded = true;
1202
+ entry.status = "synced";
1203
+ delete entry.legacyLastSyncedSha256;
1204
+ delete entry.pendingRemoteHash;
1205
+ delete entry.error;
1206
+ return;
1207
+ }
1208
+ if (pendingRemoteHash !== baseline) {
1209
+ await atomicWrite(path, pendingRemoteContent);
1210
+ entry.localHash = pendingRemoteHash;
1211
+ entry.lastSyncedHash = pendingRemoteHash;
1212
+ entry.downloaded = true;
1213
+ entry.status = "synced";
1214
+ delete entry.legacyLastSyncedSha256;
1215
+ delete entry.pendingRemoteHash;
1216
+ delete entry.error;
1217
+ return;
1218
+ }
945
1219
  entry.localHash = localHash;
946
1220
  entry.pendingRemoteHash = old.pendingRemoteHash;
947
1221
  entry.downloaded = true;
@@ -976,14 +1250,9 @@ export class WorkspaceManager {
976
1250
  const data = asObject(response.data);
977
1251
  const remoteContent = typeof data.text === "string" ? data.text : "";
978
1252
  const remoteHash = hashContent(remoteContent);
979
- if (advertisedRemoteHash && advertisedRemoteHash !== remoteHash) {
980
- entry.localHash = localHash;
981
- entry.status = "error";
982
- entry.error =
983
- `Remote script ${entry.id} changed while it was being read: ` +
984
- `expected ${advertisedRemoteHash}, received ${remoteHash}.`;
985
- return;
986
- }
1253
+ // The Editor observer can lag behind the asset file endpoint immediately
1254
+ // after a save. The text response is authoritative for this reconciliation
1255
+ // pass; the next snapshot will catch up to its hash.
987
1256
  entry.remoteFileHash = remoteHash;
988
1257
  if (localContent === null) {
989
1258
  await atomicWrite(path, remoteContent);
@@ -143,6 +143,7 @@
143
143
  async function callDaemon(path, method, body) {
144
144
  const allowed =
145
145
  (path === "/builder/jobs" && method === "POST") ||
146
+ (path === "/workspace/sync" && method === "POST") ||
146
147
  (/^\/builder\/jobs\/[^/]+$/.test(path) && method === "GET");
147
148
  if (!allowed) throw new Error("Unsupported pcbridge browser request.");
148
149
  const payload = body && typeof body === "object" ? { ...body } : {};
package/extension/main.js CHANGED
@@ -13,6 +13,8 @@
13
13
  let builderRefreshTimer = null;
14
14
  let selectedTemplateId = null;
15
15
  let selectedTemplateAsset = null;
16
+ let workspaceEventsInstalled = false;
17
+ let workspaceSyncTimer = null;
16
18
 
17
19
  function formatLogArg(value) {
18
20
  if (typeof value === "string") return value;
@@ -511,6 +513,8 @@
511
513
  id: get("id"),
512
514
  name: get("name"),
513
515
  type: get("type"),
516
+ source: get("source") || false,
517
+ source_asset_id: get("source_asset_id") || null,
514
518
  path,
515
519
  folder: Array.isArray(path) && path.length ? path[path.length - 1] : null,
516
520
  tags: get("tags") || [],
@@ -619,6 +623,30 @@
619
623
  };
620
624
  }
621
625
 
626
+ function scheduleWorkspaceSync() {
627
+ if (workspaceSyncTimer) clearTimeout(workspaceSyncTimer);
628
+ workspaceSyncTimer = setTimeout(() => {
629
+ workspaceSyncTimer = null;
630
+ void daemonRequest("/workspace/sync", "POST", {}, 60000).catch(() => undefined);
631
+ }, 250);
632
+ }
633
+
634
+ function installWorkspaceEvents() {
635
+ if (workspaceEventsInstalled || !window.editor?.api?.globals?.assets) return;
636
+ const assets = window.editor.api.globals.assets;
637
+ workspaceEventsInstalled = true;
638
+ const observe = (asset) => {
639
+ if (!asset || typeof asset.on !== "function") return;
640
+ for (const event of ["file:hash:set", "file:filename:set", "path:set", "name:set"]) {
641
+ try { asset.on(event, scheduleWorkspaceSync); } catch { /* optional observer event */ }
642
+ }
643
+ };
644
+ for (const asset of assets.list()) observe(asset);
645
+ for (const event of ["add", "remove", "move", "load:all"]) {
646
+ try { assets.on(event, (asset) => { observe(asset); scheduleWorkspaceSync(); }); } catch { /* optional assets event */ }
647
+ }
648
+ }
649
+
622
650
  async function readAssetText(params) {
623
651
  const asset = requireEditorAsset(params.assetId);
624
652
  if (asset.get("type") !== "script") {
@@ -723,6 +751,30 @@
723
751
  };
724
752
  }
725
753
 
754
+ async function renameAsset(params) {
755
+ const asset = requireEditorAsset(params.assetId);
756
+ const assets = window.editor.api.globals.assets;
757
+ const folderResult = await resolveFolder(assets, params);
758
+ const filename = String(params.filename || asset.get("file.filename") || asset.get("name") || "asset.bin");
759
+ const name = String(params.name || filename);
760
+ await new Promise((resolve, reject) => {
761
+ const error = window.editor.call("assets:rename", asset.observer, name, (callbackError) => {
762
+ if (callbackError) reject(new Error(String(callbackError)));
763
+ else resolve();
764
+ });
765
+ if (error) reject(new Error(String(error)));
766
+ });
767
+ if (typeof window.editor.call === "function" && Object.prototype.hasOwnProperty.call(params, "folder")) {
768
+ const error = window.editor.call(
769
+ "assets:fs:move",
770
+ [asset.observer],
771
+ folderResult.folder ? folderResult.folder.observer : null
772
+ );
773
+ if (error) throw new Error(String(error));
774
+ }
775
+ return { asset: readAsset(asset), createdFolders: folderResult.created.map(readAsset) };
776
+ }
777
+
726
778
  async function writeScriptText(params) {
727
779
  const asset = requireEditorAsset(params.assetId);
728
780
  if (asset.get("type") !== "script") {
@@ -1257,22 +1309,22 @@
1257
1309
  async function uploadAsset(params) {
1258
1310
  if (!params.base64) throw new Error("base64 file content is required.");
1259
1311
  if (!params.name) throw new Error("name is required.");
1260
- if (!params.type) throw new Error("type is required.");
1261
1312
 
1262
1313
  const assets = window.editor.api.globals.assets;
1263
1314
  const folderResult = await resolveFolder(assets, params);
1264
1315
  const blob = new Blob([bytesFromBase64(params.base64)], {
1265
1316
  type: params.mime || "application/octet-stream"
1266
1317
  });
1267
- const asset = await assets.upload(
1268
- {
1318
+ const uploadData = {
1269
1319
  name: params.name,
1270
- type: params.type,
1271
1320
  folder: folderResult.folder || undefined,
1272
1321
  filename: params.filename || params.name,
1273
1322
  file: blob,
1274
1323
  preload: params.preload !== false
1275
- },
1324
+ };
1325
+ if (params.type) uploadData.type = params.type;
1326
+ const asset = await assets.upload(
1327
+ uploadData,
1276
1328
  null
1277
1329
  );
1278
1330
  return {
@@ -1345,12 +1397,16 @@
1345
1397
  if (method === "bridge:clearLogs") return clearLogs();
1346
1398
  if (method === "bridge:uploadAsset") return uploadAsset(params || {});
1347
1399
  if (method === "bridge:focusViewport") return focusViewport(params || {});
1348
- if (method === "bridge:workspaceSnapshot") return workspaceSnapshot();
1400
+ if (method === "bridge:workspaceSnapshot") {
1401
+ installWorkspaceEvents();
1402
+ return workspaceSnapshot();
1403
+ }
1349
1404
  if (method === "bridge:collectTemplateDependencies") return collectTemplateDependencies(params || {});
1350
1405
  if (method === "bridge:readAssetText") return readAssetText(params || {});
1351
1406
  if (method === "bridge:readAssetFile") return readAssetFile(params || {});
1352
1407
  if (method === "bridge:readAssetResource") return readAssetResource(params || {});
1353
1408
  if (method === "bridge:writeAssetFile") return writeAssetFile(params || {});
1409
+ if (method === "bridge:renameAsset") return renameAsset(params || {});
1354
1410
  if (method === "bridge:writeScriptText") return writeScriptText(params || {});
1355
1411
  throw new Error(`Unknown bridge method: ${method}`);
1356
1412
  }
@@ -2,7 +2,7 @@
2
2
  "manifest_version": 3,
3
3
  "name": "PlayCanvas Agent Bridge",
4
4
  "description": "Connects open PlayCanvas Editor and Launch tabs to the local pcbridge daemon.",
5
- "version": "0.5.0",
5
+ "version": "0.5.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.5.0",
3
+ "version": "0.5.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",
@@ -54,14 +54,22 @@ Workspace layout:
54
54
  ```text
55
55
  <workspace root>/<projectId>-<projectName>/
56
56
  pcbridge.project.json # project metadata and agent-readable asset catalog
57
- assets/ # remote folder tree and synchronized asset file contents
58
- tmp/ # task files, builds, cache, conflicts, captures, and deletion quarantine
57
+ assets/ # remote folder tree; scripts eager, binary file contents lazy
58
+ tmp/ # agent files, builds, cache, conflicts, captures, and deletion quarantine; never synchronized
59
59
  .pcbridge/ # internal state; do not edit
60
60
  ```
61
61
 
62
- Existing script and binary asset contents synchronize in both directions. Use structured commands
63
- for asset create, move, rename, and delete operations. `pcbridge workspace pull --target
64
- editor:<sceneId> --asset <assetId>` explicitly refreshes one file. Local file
62
+ Prefer local operations for file-backed Assets. Edit scripts under `assets/`; create files and
63
+ folders there to upload them through PlayCanvas processing; and rename or move local files to keep
64
+ the same remote Asset ID. Deleting a local file only clears its local cache and does not delete the
65
+ remote Asset. Use `asset delete --id <id>` only for intentional remote deletion. Scripts are eager,
66
+ while binary contents are lazy; use `pcbridge workspace pull --target editor:<sceneId> --asset
67
+ <assetId>` before modifying a missing remote binary. Edit a source GLB rather than its generated
68
+ Model/Container/material derivatives.
69
+
70
+ After local writes, wait for the watcher and poll `workspace status` until `synced`. A brief
71
+ `local-change` is normal. If it does not converge, run one `workspace sync`, inspect status and
72
+ `tmp/conflicts/`, and never overwrite a conflict automatically. Local file
65
73
  arguments must stay inside the selected project workspace. Do not use `--allow-external-path`
66
74
  unless the user explicitly asks to use a known external file.
67
75
  Read `pcbridge.project.json.assets` to resolve asset ids to project-relative `assets/...` paths and
@@ -75,7 +83,8 @@ dependencies, fills the workspace cache, and uploads individual S3 objects witho
75
83
  `pcbridge builder start --target editor:<sceneId> --asset <id>` and
76
84
  `pcbridge builder status --job <jobId>`.
77
85
 
78
- Use structured commands for small, known Editor operations:
86
+ Use structured commands for scene structure, Asset metadata, explicit transfers, and verification.
87
+ For ordinary file-content edits, prefer the tracked file under `assets/`:
79
88
 
80
89
  ```bash
81
90
  pcbridge entity list --target editor:<sceneId> --limit 50
@@ -108,7 +117,9 @@ pcbridge logs get --target launch:<sceneId> --limit 100
108
117
  pcbridge logs get --target launch:<sceneId> --level error
109
118
  ```
110
119
 
111
- 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:
120
+ Organize final file-backed assets under `assets/AI Agent Bridge/<task name>/...` and disposable
121
+ generation files under `tmp/<task name>/`. Use `pcbridge eval` for exploratory API inspection,
122
+ custom Editor/Engine workflows, and large multi-step scene edits:
112
123
 
113
124
  ```bash
114
125
  pcbridge eval --target editor:<sceneId> --code "return { href: location.href, entityCount: editor.api.globals.entities.list().length }"
@@ -136,9 +147,14 @@ runtime-registered ScriptTypes that have no standalone asset id.
136
147
 
137
148
  Editor patches are durable. Restore preview-only enabled/visibility changes before Template apply,
138
149
  then verify overrides. Template `verified` covers the current Editor observer, not reload
139
- persistence. Prefer `script upsert --parse --wait` after script edits; its completion check does not
140
- wait for a later workspace mirror sync.
141
-
142
- For large PlayCanvas tasks, choose an explicit target from `pcbridge targets`, confirm `workspace status`, keep task files under the project `tmp/` directory, upload assets with an upload manifest, edit tracked scripts under `assets/`, and capture the viewport under `tmp/captures/` after smoke tests. If the same manual glue repeats across tasks, improve the CLI or this skill instead of continuing the brittle sequence.
150
+ persistence. For an existing script, edit the local file, wait for workspace sync, then use
151
+ `script parse` when parse verification is needed. Reserve `script upsert --parse --wait` for
152
+ recovery or workflows that intentionally bypass the mirror.
153
+
154
+ For large PlayCanvas tasks, choose an explicit target from `pcbridge targets`, confirm
155
+ `workspace status` is `synced`, keep disposable task files under `tmp/`, and put final scripts,
156
+ textures, models, and audio directly under `assets/`. Wait for workspace sync before structured
157
+ scene edits or runtime verification. Use upload manifests only when explicit import settings or a
158
+ non-watched source path is required, then capture under `tmp/captures/` after smoke tests.
143
159
 
144
160
  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.
@@ -43,8 +43,8 @@ project-picker and scene Editor navigations; change the remembered mode only thr
43
43
  runtime verification; use `tab:<id>` when either selector is ambiguous.
44
44
  2. Run `pcbridge workspace status --target editor:<sceneId>`. Do not write while it reports a conflict or sync error.
45
45
  3. Use layered help to load only the command group you need: `pcbridge help`, then `pcbridge help core|workspace|frontend|target|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
46
- 4. Keep temporary scripts, JSON manifests, uploads, and captures inside the selected project workspace.
47
- 5. Use structured commands for small, known operations that map cleanly to one Editor action.
46
+ 4. Edit asset file contents locally under the selected project's `assets/` tree and let the daemon synchronize them. Keep temporary files, manifests, and captures under `tmp/`, which is not synchronized.
47
+ 5. Use structured commands for scene structure and non-file Asset operations that map cleanly to one Editor action.
48
48
  6. Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, Launch runtime debugging, and large multi-step scene edits where one script is clearer than many CLI calls.
49
49
  7. Return compact JSON from snippets. Never return raw `editor`, `Entity`, `Asset`, `entities.root`, or app objects.
50
50
  8. Use PlayCanvas history options for writes when available and verify writes with a read-only command.
@@ -54,8 +54,8 @@ project-picker and scene Editor navigations; change the remembered mode only thr
54
54
  ```text
55
55
  <workspace root>/<projectId>-<projectName>/
56
56
  pcbridge.project.json # project metadata and agent-readable asset catalog
57
- assets/ # PlayCanvas folder tree; all asset file contents synchronize automatically
58
- tmp/ # task files, builds, cache, conflicts, captures, and deletion quarantine
57
+ assets/ # PlayCanvas folder tree; scripts eager, binary file contents lazy
58
+ tmp/ # agent files, builds, cache, conflicts, captures, and deletion quarantine; never synchronized
59
59
  .pcbridge/ # internal sync state; do not edit
60
60
  ```
61
61
 
@@ -68,10 +68,20 @@ pcbridge workspace sync --target editor:<sceneId>
68
68
  pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
69
69
  ```
70
70
 
71
- Existing script and binary asset contents synchronize in both directions. Create, move, rename,
72
- and delete assets through structured pcbridge commands; do not perform structural changes by moving
73
- or deleting mirrored local files. `workspace pull` explicitly refreshes one file but is not needed
74
- for normal synchronization.
71
+ Prefer local file operations for file-backed Assets:
72
+
73
+ - Edit existing scripts directly under `assets/`; the watcher uploads them to PlayCanvas.
74
+ - Create files and folders under `assets/` to upload them into the matching remote folder. Let PlayCanvas infer and process the Asset type.
75
+ - Rename or move a local file to rename or move the same remote Asset ID.
76
+ - Deleting a local file only removes the local lazy cache. It does not delete the remote Asset; use `pcbridge asset delete --id <id>` only when remote deletion is explicitly intended.
77
+ - Scripts are downloaded eagerly. Binary files are lazy; run `workspace pull --asset <id>` before modifying a remote binary that is not present locally.
78
+ - PlayCanvas-generated derivatives such as GLB Model/Container/material outputs are catalog-only. Edit the source GLB, not a derivative.
79
+
80
+ After a local edit, allow the watcher to react, then poll `workspace status` until it reports
81
+ `synced`. A brief yellow `local-change` is expected. Do not declare completion or alternate to
82
+ remote editing while the same file is pending. If it does not converge, run one explicit
83
+ `workspace sync`, inspect `lastError`, `lastWarning`, and `tmp/conflicts/`, and do not overwrite
84
+ a conflict automatically.
75
85
  Read `pcbridge.project.json.assets` to resolve asset ids to project-relative `assets/...` paths and
76
86
  compare remote, local, and base MD5 values. The catalog is managed by pcbridge; do not edit it to
77
87
  request remote asset operations. Confirmed remote deletions are quarantined under
@@ -133,7 +143,8 @@ Use exactly one of `--asset-id` and `--script-name`. The name form is for a Scri
133
143
  by a bundle or runtime asset and therefore lacking a standalone script asset id. Verify such a
134
144
  script in Launch; explicit script reordering is not yet a dedicated command.
135
145
 
136
- Work with assets and scripts:
146
+ Work with asset metadata, explicit transfers, and script verification. For ordinary file-content
147
+ edits, prefer editing the tracked local file under `assets/` over `script set-text` or re-uploading it:
137
148
 
138
149
  ```bash
139
150
  pcbridge asset list --target editor:<sceneId> --type script --limit 50
@@ -204,13 +215,13 @@ authoritative.
204
215
 
205
216
  ## Asset Organization
206
217
 
207
- Create task-scoped remote folders before uploading generated assets. Keep local generated files
208
- under the project `tmp/` directory until they are uploaded:
218
+ Create synchronized files directly under a task-scoped path in the project `assets/` tree. Keep
219
+ intermediate or disposable generation files under `tmp/` so the watcher does not upload them:
209
220
 
210
221
  ```text
211
- AI Agent Bridge/<task name>/Textures
212
- AI Agent Bridge/<task name>/Materials
213
- AI Agent Bridge/<task name>/Scripts
222
+ assets/AI Agent Bridge/<task name>/Textures
223
+ assets/AI Agent Bridge/<task name>/Models
224
+ assets/AI Agent Bridge/<task name>/Scripts
214
225
  ```
215
226
 
216
227
  Use stable names that describe the asset purpose. Avoid dumping generated files at the project root.
@@ -221,12 +232,12 @@ For multi-asset or game-sized tasks:
221
232
 
222
233
  1. Choose an explicit target from `pcbridge targets`, preferably `editor:<sceneId>` for writes or
223
234
  `launch:<sceneId>` for tests; use `tab:<id>` to resolve ambiguity.
224
- 2. Confirm `workspace status`, then create task files under `<project>/tmp/<task name>/`.
225
- 3. Put PlayCanvas assets under `AI Agent Bridge/<task name>/{Textures,Materials,Scripts,Templates}`.
226
- 4. Use `pcbridge asset upload-many --json ./upload-manifest.json` for batches. In the manifest, each item needs `file` and may include `key`, `name`, `filename`, `type`, `mime`, `folder`, `folderId`, and `preload`. Relative `file` paths resolve from the manifest file; `key` is returned for later argument mapping but is not sent to PlayCanvas.
227
- 5. Use `pcbridge script upsert --target editor:<sceneId> --filename <name>.js --file ./script.js --folder "AI Agent Bridge/<task name>/Scripts" --parse --wait` for repeatable script creation or update.
235
+ 2. Confirm `workspace status` is `synced`. Put disposable generation inputs under `<project>/tmp/<task name>/`.
236
+ 3. Put final scripts, textures, models, audio, and other file-backed Assets under `<project>/assets/AI Agent Bridge/<task name>/...`; create or edit them locally and wait for synchronization.
237
+ 4. Use `asset upload-many` only when explicit upload settings or a non-watched source path is required. Do not upload a file again when it is already tracked under `assets/`.
238
+ 5. For an existing script, edit its local file. Use `script parse` after synchronization when parse verification is needed; reserve `script upsert --parse --wait` for recovery or workflows that intentionally bypass the mirror.
228
239
  6. Use `pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./args.json --timeout-ms 120000` for large scene installation scripts. The JSON object is available as `command.args`; increase `--timeout-ms` instead of splitting a coherent install script just to avoid the default 15s timeout.
229
- 7. Verify with read-only commands, a small smoke-test eval, and a capture under `<project>/tmp/captures/`.
240
+ 7. Wait for `workspace status` to become `synced`, then verify with read-only commands, a small smoke-test eval, and a capture under `<project>/tmp/captures/`.
230
241
 
231
242
  If repeated manual glue is needed across tasks, improve the CLI or this skill rather than continuing to hand-roll brittle shell/script sequences.
232
243
 
@@ -19,9 +19,14 @@ with local-loopback permission. If no target appears, ask the user to install/re
19
19
 
20
20
  The daemon start directory is the workspace root. After selecting an explicit target, run
21
21
  `pcbridge workspace status --target editor:<sceneId>` and do not write while it reports a conflict
22
- or sync error. Project files live under `<projectId>-<projectName>/{assets,tmp}`. Script and binary
23
- asset contents synchronize automatically; `pcbridge workspace pull --target editor:<sceneId>
24
- --asset <id>` explicitly refreshes one file.
22
+ or sync error. Project files live under `<projectId>-<projectName>/{assets,tmp}`. Prefer local
23
+ operations for file-backed Assets: edit scripts under `assets/`; create files/folders there to
24
+ upload through PlayCanvas processing; rename or move locally to preserve the remote Asset ID.
25
+ Deleting locally only clears the cache, never the remote Asset. Scripts are eager and binaries are
26
+ lazy; use `pcbridge workspace pull --target editor:<sceneId> --asset <id>` before editing a missing
27
+ binary. Edit source GLBs, not generated Model/Container/material derivatives. `tmp/` is never synced.
28
+ After a local write, poll `workspace status` until `synced`; a brief `local-change` is expected.
29
+ If it does not converge, run one `workspace sync` and inspect status plus `tmp/conflicts/`.
25
30
  Read `pcbridge.project.json.assets` for asset ids, types, project-relative file paths, presence, and
26
31
  remote/local/base MD5 values. Treat that asset catalog as pcbridge-managed. Confirmed remote
27
32
  deletions are quarantined under `tmp/trash/remote/`; `tmp/conflicts/` contains content divergence.
@@ -35,7 +40,8 @@ Editor navigations; change the remembered choice only through the popup.
35
40
 
36
41
  Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help target|workspace|frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
37
42
 
38
- Use structured commands for small, known Editor operations:
43
+ Use structured commands for scene structure, Asset metadata, explicit transfers, and verification.
44
+ For normal file-content changes, prefer editing the tracked local file under `assets/`:
39
45
 
40
46
  ```bash
41
47
  pcbridge entity list --target editor:<sceneId> --limit 50
@@ -66,7 +72,8 @@ pcbridge logs get --target launch:<sceneId> --limit 100
66
72
  pcbridge logs get --target launch:<sceneId> --level error
67
73
  ```
68
74
 
69
- Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
75
+ Put final file-backed assets under `assets/AI Agent Bridge/<task name>/...`; keep disposable
76
+ generation files under `tmp/<task name>/`.
70
77
 
71
78
  Use `pcbridge launch diagnose` and `pcbridge launch wait-ready --focus` before runtime assertions.
72
79
  Launch `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context,
@@ -86,6 +93,10 @@ Capture does not focus/resize/emulate a mobile viewport and defaults to `--max-w
86
93
 
87
94
  For large eval installs, use `pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./install-args.json --timeout-ms 120000`.
88
95
 
89
- For large tasks, choose an explicit target from `pcbridge targets`, keep generated files and captures under the project `tmp/` directory, upload batches with `asset upload-many`, edit tracked scripts under `assets/`, and capture the viewport after smoke tests. File arguments must remain inside the workspace; never use `--allow-external-path` without explicit user approval. If repeated manual glue appears, improve the CLI or this rule.
96
+ For large tasks, choose an explicit target, confirm the workspace is `synced`, keep disposable files
97
+ and captures under `tmp/`, and put final scripts, textures, models, and audio directly under
98
+ `assets/`. Wait for sync before scene writes or runtime tests. Use `asset upload-many` only when
99
+ explicit import settings or a non-watched path is required. File arguments must remain inside the
100
+ workspace; never use `--allow-external-path` without explicit user approval.
90
101
 
91
102
  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.
@@ -15,8 +15,14 @@ with local-loopback permission. If no target is connected, install/reload the un
15
15
 
16
16
  The daemon start directory is the workspace root. After selecting an explicit target, run
17
17
  `pcbridge workspace status --target editor:<sceneId>` and stop if it reports a conflict or sync
18
- error. Each project is mirrored under `<projectId>-<projectName>/{assets,tmp}`. Script and binary
19
- asset contents synchronize both ways; `workspace pull` explicitly refreshes one file.
18
+ error. Each project is mirrored under `<projectId>-<projectName>/{assets,tmp}`. Prefer local
19
+ operations for file-backed Assets: edit scripts under `assets/`; create files/folders there to
20
+ upload through PlayCanvas processing; rename or move locally to preserve the remote Asset ID.
21
+ Deleting locally only clears the cache, never the remote Asset. Scripts are eager and binaries are
22
+ lazy; use `workspace pull` before editing a missing binary. Edit source GLBs, not generated
23
+ Model/Container/material derivatives. `tmp/` is never synchronized. After local writes, poll
24
+ `workspace status` until `synced`; a brief `local-change` is expected. If it does not converge,
25
+ run one `workspace sync` and inspect status plus `tmp/conflicts/`.
20
26
  Read `pcbridge.project.json.assets` for asset ids, types, project-relative file paths, presence, and
21
27
  remote/local/base MD5 values. Treat that asset catalog as pcbridge-managed. Confirmed remote
22
28
  deletions are quarantined under `tmp/trash/remote/`; `tmp/conflicts/` contains content divergence.
@@ -30,7 +36,8 @@ Editor navigations; change the remembered choice only through the popup.
30
36
 
31
37
  Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help target|workspace|frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
32
38
 
33
- Use structured commands for small, known Editor operations:
39
+ Use structured commands for scene structure, Asset metadata, explicit transfers, and verification.
40
+ For normal file-content changes, prefer editing the tracked local file under `assets/`:
34
41
 
35
42
  ```bash
36
43
  pcbridge entity list --target editor:<sceneId> --limit 50
@@ -62,7 +69,8 @@ pcbridge logs get --target launch:<sceneId> --limit 100
62
69
  pcbridge logs get --target launch:<sceneId> --level error
63
70
  ```
64
71
 
65
- Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
72
+ Put final file-backed assets under `assets/AI Agent Bridge/<task name>/...`; keep disposable
73
+ generation files under `tmp/<task name>/`.
66
74
 
67
75
  Use `pcbridge launch diagnose` and `pcbridge launch wait-ready --focus` before runtime assertions.
68
76
  Launch `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context,
@@ -81,6 +89,10 @@ Capture records the current canvas, defaults to `--max-width 1200`, and does not
81
89
 
82
90
  For large eval installs, use `pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./install-args.json --timeout-ms 120000`.
83
91
 
84
- For large tasks, choose an explicit target from `pcbridge targets`, keep generated files and captures under the project `tmp/` directory, upload batches with `asset upload-many`, edit tracked scripts under `assets/`, and capture the viewport after smoke tests. Local file arguments must remain inside the workspace; never use `--allow-external-path` without explicit user approval. If repeated manual glue appears, improve the CLI or this rule.
92
+ For large tasks, choose an explicit target, confirm the workspace is `synced`, keep disposable files
93
+ and captures under `tmp/`, and put final scripts, textures, models, and audio directly under
94
+ `assets/`. Wait for sync before scene writes or runtime tests. Use `asset upload-many` only when
95
+ explicit import settings or a non-watched path is required. Local file arguments must remain inside
96
+ the workspace; never use `--allow-external-path` without explicit user approval.
85
97
 
86
98
  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.