playcanvas-agent-bridge-cli 0.5.1 → 0.5.3
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 +11 -8
- package/README.zh-CN.md +13 -6
- package/dist/config.js +1 -1
- package/dist/workspace/manager.js +286 -17
- package/extension/icons/icon-128.png +0 -0
- package/extension/icons/icon-16.png +0 -0
- package/extension/icons/icon-32.png +0 -0
- package/extension/icons/icon-48.png +0 -0
- package/extension/isolated.js +1 -0
- package/extension/main.js +62 -6
- package/extension/manifest.json +1 -1
- package/package.json +1 -1
- package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +27 -11
- package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +30 -19
- package/skills/cursor/playcanvas-agent-bridge-cli.mdc +17 -6
- package/skills/windsurf/playcanvas-agent-bridge-cli.md +17 -5
- package/extension/icons/concepts/pcbridge-bridge.png +0 -0
- package/extension/icons/concepts/pcbridge-cube.png +0 -0
- package/extension/icons/concepts/pcbridge-p-active.png +0 -0
- package/extension/icons/concepts/pcbridge-p-arch.png +0 -0
- package/extension/icons/concepts/pcbridge-p-bridge.png +0 -0
- package/extension/icons/concepts/pcbridge-p-emblem.png +0 -0
- package/extension/icons/concepts/pcbridge-signal.png +0 -0
package/README.md
CHANGED
|
@@ -20,7 +20,7 @@ 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 track repository version `0.5.
|
|
23
|
+
The commands documented below track repository version `0.5.3`. npm installs the latest stable
|
|
24
24
|
release; use the GitHub install when testing changes that have not been released yet.
|
|
25
25
|
|
|
26
26
|
One-shot with npx:
|
|
@@ -105,7 +105,7 @@ When a ready Editor connects, pcbridge creates `<projectId>-<projectName>/` auto
|
|
|
105
105
|
```text
|
|
106
106
|
1552681-pcbridge-test/
|
|
107
107
|
├── pcbridge.project.json # project metadata plus the agent-readable asset catalog
|
|
108
|
-
├── assets/ # PlayCanvas folder mirror
|
|
108
|
+
├── assets/ # PlayCanvas folder mirror; scripts eager, binary assets lazy
|
|
109
109
|
├── tmp/ # builds, cache, conflicts, captures, and quarantined remote deletions
|
|
110
110
|
└── .pcbridge/ # internal sync state; do not edit
|
|
111
111
|
```
|
|
@@ -119,12 +119,15 @@ pcbridge workspace sync --target editor:<sceneId>
|
|
|
119
119
|
pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
|
|
120
120
|
```
|
|
121
121
|
|
|
122
|
-
Scripts
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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.
|
|
128
131
|
|
|
129
132
|
`pcbridge.project.json` schema v2 stores every asset id, type, PlayCanvas folder, project-relative
|
|
130
133
|
`assets/...` file path, download presence, and the remote/local/base MD5 values. Agents may read
|
package/README.zh-CN.md
CHANGED
|
@@ -13,7 +13,7 @@ npm install -g playcanvas-agent-bridge-cli
|
|
|
13
13
|
pcbridge install-skill --agent all
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
下文命令跟随仓库版 `0.5.
|
|
16
|
+
下文命令跟随仓库版 `0.5.3`。npm 安装的是最新稳定版本;测试尚未发布的改动时请使用
|
|
17
17
|
GitHub 安装。
|
|
18
18
|
|
|
19
19
|
如果要测试尚未发布的改动,也可以直接从这个 GitHub 仓库安装:
|
|
@@ -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
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
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 可以
|
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.
|
|
7
|
+
export const VERSION = "0.5.3";
|
|
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
|
-
|
|
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:
|
|
209
|
-
hash:
|
|
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:
|
|
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:
|
|
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
|
-
|
|
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
|
|
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 (
|
|
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
|
-
|
|
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
|
-
|
|
980
|
-
|
|
981
|
-
|
|
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);
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/extension/isolated.js
CHANGED
|
@@ -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
|
|
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")
|
|
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
|
}
|
package/extension/manifest.json
CHANGED
|
@@ -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.
|
|
5
|
+
"version": "0.5.3",
|
|
6
6
|
"permissions": ["activeTab", "storage"],
|
|
7
7
|
"host_permissions": [
|
|
8
8
|
"http://playcanvas.com/*",
|
package/package.json
CHANGED
|
@@ -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
|
|
58
|
-
tmp/ #
|
|
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
|
-
|
|
63
|
-
|
|
64
|
-
|
|
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
|
|
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
|
|
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.
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
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
|
|
47
|
-
5. Use structured commands for
|
|
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;
|
|
58
|
-
tmp/ #
|
|
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
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
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
|
|
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
|
|
208
|
-
|
|
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>/
|
|
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
|
|
225
|
-
3. Put
|
|
226
|
-
4. Use `
|
|
227
|
-
5. Use `
|
|
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.
|
|
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}`.
|
|
23
|
-
|
|
24
|
-
|
|
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
|
|
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
|
|
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
|
|
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}`.
|
|
19
|
-
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|