playcanvas-agent-bridge-cli 0.2.2 → 0.4.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.
Files changed (34) hide show
  1. package/README.md +218 -52
  2. package/README.zh-CN.md +210 -51
  3. package/dist/cli.js +723 -92
  4. package/dist/config.js +6 -2
  5. package/dist/daemon/server.js +181 -19
  6. package/dist/daemon/target-registry.js +61 -3
  7. package/dist/frontend/server.js +191 -0
  8. package/dist/frontend/store.js +369 -0
  9. package/dist/shared/protocol.js +3 -1
  10. package/dist/snippets.js +764 -30
  11. package/dist/workspace/manager.js +536 -0
  12. package/extension/icons/concepts/pcbridge-bridge.png +0 -0
  13. package/extension/icons/concepts/pcbridge-cube.png +0 -0
  14. package/extension/icons/concepts/pcbridge-p-active.png +0 -0
  15. package/extension/icons/concepts/pcbridge-p-arch.png +0 -0
  16. package/extension/icons/concepts/pcbridge-p-bridge.png +0 -0
  17. package/extension/icons/concepts/pcbridge-p-emblem.png +0 -0
  18. package/extension/icons/concepts/pcbridge-signal.png +0 -0
  19. package/extension/icons/icon-128.png +0 -0
  20. package/extension/icons/icon-16.png +0 -0
  21. package/extension/icons/icon-32.png +0 -0
  22. package/extension/icons/icon-48.png +0 -0
  23. package/extension/isolated.js +214 -43
  24. package/extension/main.js +619 -32
  25. package/extension/manifest.json +29 -7
  26. package/extension/popup.html +188 -24
  27. package/extension/popup.js +199 -10
  28. package/extension/service-worker.js +268 -17
  29. package/package.json +4 -1
  30. package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +97 -24
  31. package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +167 -52
  32. package/skills/codex/playcanvas-agent-bridge-cli/agents/openai.yaml +2 -2
  33. package/skills/cursor/playcanvas-agent-bridge-cli.mdc +63 -23
  34. package/skills/windsurf/playcanvas-agent-bridge-cli.md +61 -23
@@ -1,3 +1,186 @@
1
+ const FRONTEND_PREFERENCES_KEY = "pcbridgeFrontendPreferences";
2
+ const SCENE_PROJECTS_KEY = "pcbridgeSceneProjects";
3
+ const TAB_PROJECTS_KEY = "pcbridgeTabProjects";
4
+ const tabProjects = new Map();
5
+
6
+ function normalizeId(value) {
7
+ const id = String(value || "").trim();
8
+ return /^\d+$/.test(id) ? id : null;
9
+ }
10
+
11
+ function parseEditorUrl(value) {
12
+ try {
13
+ const url = new URL(value);
14
+ if (
15
+ (url.protocol !== "https:" && url.protocol !== "http:") ||
16
+ url.hostname !== "playcanvas.com"
17
+ ) {
18
+ return null;
19
+ }
20
+
21
+ const projectMatch = url.pathname.match(/^\/editor\/project\/(\d+)(?:\/|$)/);
22
+ const sceneMatch = url.pathname.match(/^\/editor\/scene\/(\d+)(?:\/|$)/);
23
+ if (!projectMatch && !sceneMatch) return null;
24
+ return {
25
+ url,
26
+ projectId: projectMatch ? projectMatch[1] : null,
27
+ sceneId: sceneMatch ? sceneMatch[1] : null
28
+ };
29
+ } catch {
30
+ return null;
31
+ }
32
+ }
33
+
34
+ async function readObject(area, key) {
35
+ if (!area) return {};
36
+ const data = await area.get(key);
37
+ const value = data && data[key];
38
+ return value && typeof value === "object" && !Array.isArray(value) ? value : {};
39
+ }
40
+
41
+ async function rememberTabProject(tabId, projectId) {
42
+ if (!Number.isInteger(tabId) || !projectId) return;
43
+ tabProjects.set(tabId, projectId);
44
+ if (!chrome.storage.session) return;
45
+ const stored = await readObject(chrome.storage.session, TAB_PROJECTS_KEY);
46
+ if (stored[String(tabId)] === projectId) return;
47
+ await chrome.storage.session.set({
48
+ [TAB_PROJECTS_KEY]: { ...stored, [String(tabId)]: projectId }
49
+ });
50
+ }
51
+
52
+ async function forgetTabProject(tabId) {
53
+ tabProjects.delete(tabId);
54
+ if (!chrome.storage.session) return;
55
+ const stored = await readObject(chrome.storage.session, TAB_PROJECTS_KEY);
56
+ if (!Object.hasOwn(stored, String(tabId))) return;
57
+ delete stored[String(tabId)];
58
+ await chrome.storage.session.set({ [TAB_PROJECTS_KEY]: stored });
59
+ }
60
+
61
+ async function getTabProject(tabId) {
62
+ if (!Number.isInteger(tabId)) return null;
63
+ if (tabProjects.has(tabId)) return tabProjects.get(tabId);
64
+ const stored = await readObject(chrome.storage.session, TAB_PROJECTS_KEY);
65
+ const projectId = normalizeId(stored[String(tabId)]);
66
+ if (projectId) tabProjects.set(tabId, projectId);
67
+ return projectId;
68
+ }
69
+
70
+ async function rememberSceneProject(sceneId, projectId) {
71
+ if (!sceneId || !projectId) return;
72
+ const stored = await readObject(chrome.storage.local, SCENE_PROJECTS_KEY);
73
+ if (stored[sceneId] === projectId) return;
74
+ await chrome.storage.local.set({
75
+ [SCENE_PROJECTS_KEY]: { ...stored, [sceneId]: projectId }
76
+ });
77
+ }
78
+
79
+ async function getSceneProject(sceneId) {
80
+ if (!sceneId) return null;
81
+ const stored = await readObject(chrome.storage.local, SCENE_PROJECTS_KEY);
82
+ return normalizeId(stored[sceneId]);
83
+ }
84
+
85
+ async function resolveProjectContext({ url, tabId, projectId, sceneId } = {}) {
86
+ const parsed = parseEditorUrl(url);
87
+ const resolvedSceneId = normalizeId(sceneId) || (parsed && parsed.sceneId);
88
+ let resolvedProjectId = normalizeId(projectId) || (parsed && parsed.projectId);
89
+
90
+ if (!resolvedProjectId && resolvedSceneId) {
91
+ resolvedProjectId = await getSceneProject(resolvedSceneId);
92
+ }
93
+ if (!resolvedProjectId) {
94
+ resolvedProjectId = await getTabProject(tabId);
95
+ }
96
+ if (resolvedProjectId) {
97
+ await rememberTabProject(tabId, resolvedProjectId);
98
+ await rememberSceneProject(resolvedSceneId, resolvedProjectId);
99
+ }
100
+
101
+ return {
102
+ parsed,
103
+ projectId: resolvedProjectId,
104
+ sceneId: resolvedSceneId
105
+ };
106
+ }
107
+
108
+ async function getFrontendPreference(context) {
109
+ const resolved = await resolveProjectContext(context);
110
+ if (!resolved.projectId) return { ok: false, mode: null, projectId: null };
111
+ const preferences = await readObject(chrome.storage.local, FRONTEND_PREFERENCES_KEY);
112
+ const mode = preferences[resolved.projectId];
113
+ return {
114
+ ok: true,
115
+ mode: mode === "custom" || mode === "official" ? mode : null,
116
+ projectId: resolved.projectId
117
+ };
118
+ }
119
+
120
+ async function setFrontendPreference(context, mode) {
121
+ if (mode !== "custom" && mode !== "official") {
122
+ return { ok: false, mode: null, projectId: null };
123
+ }
124
+ const resolved = await resolveProjectContext(context);
125
+ if (!resolved.projectId) return { ok: false, mode: null, projectId: null };
126
+ const preferences = await readObject(chrome.storage.local, FRONTEND_PREFERENCES_KEY);
127
+ await chrome.storage.local.set({
128
+ [FRONTEND_PREFERENCES_KEY]: {
129
+ ...preferences,
130
+ [resolved.projectId]: mode
131
+ }
132
+ });
133
+ return { ok: true, mode, projectId: resolved.projectId };
134
+ }
135
+
136
+ function frontendUrlForMode(value, mode) {
137
+ const parsed = parseEditorUrl(value);
138
+ if (!parsed || (mode !== "custom" && mode !== "official")) return null;
139
+ const hadCustom = parsed.url.searchParams.has("use_local_frontend");
140
+ if (mode === "custom") parsed.url.searchParams.set("use_local_frontend", "");
141
+ else parsed.url.searchParams.delete("use_local_frontend");
142
+ const changed = hadCustom !== parsed.url.searchParams.has("use_local_frontend");
143
+ return { changed, url: parsed.url.toString() };
144
+ }
145
+
146
+ async function applyFrontendPreference(tabId, value, projectId) {
147
+ const preference = await getFrontendPreference({ url: value, tabId, projectId });
148
+ if (!preference.ok || !preference.mode) {
149
+ return { ...preference, redirected: false };
150
+ }
151
+ const next = frontendUrlForMode(value, preference.mode);
152
+ if (!next || !next.changed) return { ...preference, redirected: false };
153
+ await chrome.tabs.update(tabId, { url: next.url });
154
+ return { ...preference, redirected: true, url: next.url };
155
+ }
156
+
157
+ async function loadConfig() {
158
+ try {
159
+ const response = await fetch(chrome.runtime.getURL("config.json"));
160
+ if (response.ok) return response.json();
161
+ } catch {
162
+ // Use the generated-extension defaults below.
163
+ }
164
+ return {
165
+ host: "127.0.0.1",
166
+ port: 17329,
167
+ token: ""
168
+ };
169
+ }
170
+
171
+ async function focusSenderTab(sender) {
172
+ const tabId = sender.tab && sender.tab.id;
173
+ const windowId = sender.tab && sender.tab.windowId;
174
+ if (!Number.isInteger(tabId)) {
175
+ return { ok: false, error: "The requesting PlayCanvas tab is unavailable." };
176
+ }
177
+ if (Number.isInteger(windowId) && chrome.windows && chrome.windows.update) {
178
+ await chrome.windows.update(windowId, { focused: true });
179
+ }
180
+ await chrome.tabs.update(tabId, { active: true });
181
+ return { ok: true, tabId, windowId: Number.isInteger(windowId) ? windowId : null };
182
+ }
183
+
1
184
  chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
2
185
  if (message && message.type === "pcbridge:getTabInfo") {
3
186
  sendResponse({
@@ -8,26 +191,94 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
8
191
  }
9
192
 
10
193
  if (message && message.type === "pcbridge:getConfig") {
11
- fetch(chrome.runtime.getURL("config.json"))
12
- .then((response) => (response.ok ? response.json() : null))
13
- .then((config) => {
14
- sendResponse(
15
- config || {
16
- host: "127.0.0.1",
17
- port: 17329,
18
- token: ""
19
- }
20
- );
194
+ loadConfig().then(sendResponse);
195
+ return true;
196
+ }
197
+
198
+ if (message && message.type === "pcbridge:focusCurrentTab") {
199
+ focusSenderTab(sender)
200
+ .then(sendResponse)
201
+ .catch((error) => sendResponse({ ok: false, error: String(error) }));
202
+ return true;
203
+ }
204
+
205
+ if (message && message.type === "pcbridge:probeDaemon") {
206
+ loadConfig()
207
+ .then(async (config) => {
208
+ if (!config.token) return { reachable: false };
209
+ const host = config.host || "127.0.0.1";
210
+ const port = config.port || 17329;
211
+ try {
212
+ const response = await fetch(`http://${host}:${port}/health`, {
213
+ headers: { "X-PCBridge-Token": config.token }
214
+ });
215
+ return { reachable: response.ok };
216
+ } catch {
217
+ return { reachable: false };
218
+ }
21
219
  })
22
- .catch(() => {
23
- sendResponse({
24
- host: "127.0.0.1",
25
- port: 17329,
26
- token: ""
27
- });
28
- });
220
+ .then(sendResponse);
221
+ return true;
222
+ }
223
+
224
+ if (message && message.type === "pcbridge:getFrontendPreference") {
225
+ getFrontendPreference({
226
+ url: message.url || (sender.tab && sender.tab.url),
227
+ tabId: Number.isInteger(message.tabId) ? message.tabId : sender.tab && sender.tab.id,
228
+ projectId: message.projectId,
229
+ sceneId: message.sceneId
230
+ }).then(sendResponse);
231
+ return true;
232
+ }
233
+
234
+ if (message && message.type === "pcbridge:setFrontendPreference") {
235
+ setFrontendPreference({
236
+ url: message.url || (sender.tab && sender.tab.url),
237
+ tabId: Number.isInteger(message.tabId) ? message.tabId : sender.tab && sender.tab.id,
238
+ projectId: message.projectId,
239
+ sceneId: message.sceneId
240
+ }, message.mode).then(sendResponse);
241
+ return true;
242
+ }
243
+
244
+ if (message && message.type === "pcbridge:rememberProjectContext") {
245
+ resolveProjectContext({
246
+ url: message.url || (sender.tab && sender.tab.url),
247
+ tabId: sender.tab && sender.tab.id,
248
+ projectId: message.projectId,
249
+ sceneId: message.sceneId
250
+ }).then((context) => sendResponse({
251
+ ok: Boolean(context.projectId),
252
+ projectId: context.projectId,
253
+ sceneId: context.sceneId
254
+ }));
255
+ return true;
256
+ }
257
+
258
+ if (message && message.type === "pcbridge:applyFrontendPreference") {
259
+ const tabId = sender.tab && sender.tab.id;
260
+ if (!Number.isInteger(tabId)) {
261
+ sendResponse({ ok: false, redirected: false });
262
+ return false;
263
+ }
264
+ applyFrontendPreference(tabId, message.url || sender.tab.url, message.projectId)
265
+ .then(sendResponse)
266
+ .catch(() => sendResponse({ ok: false, redirected: false }));
29
267
  return true;
30
268
  }
31
269
 
32
270
  return false;
33
271
  });
272
+
273
+ chrome.tabs.onUpdated.addListener((tabId, changeInfo) => {
274
+ if (!changeInfo.url) return;
275
+ if (!parseEditorUrl(changeInfo.url)) {
276
+ void forgetTabProject(tabId);
277
+ return;
278
+ }
279
+ void applyFrontendPreference(tabId, changeInfo.url).catch(() => undefined);
280
+ });
281
+
282
+ chrome.tabs.onRemoved.addListener((tabId) => {
283
+ void forgetTabProject(tabId);
284
+ });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "playcanvas-agent-bridge-cli",
3
- "version": "0.2.2",
3
+ "version": "0.4.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",
@@ -27,6 +27,8 @@
27
27
  "scripts": {
28
28
  "build": "tsc -p tsconfig.json && node -e \"require('fs').chmodSync('dist/cli.js', 0o755)\"",
29
29
  "check": "tsc -p tsconfig.json --noEmit",
30
+ "check:version": "node scripts/check-version.mjs",
31
+ "test": "pnpm check:version && pnpm build && node --test",
30
32
  "prepare": "npm run build"
31
33
  },
32
34
  "keywords": [
@@ -44,6 +46,7 @@
44
46
  "registry": "https://registry.npmjs.org/"
45
47
  },
46
48
  "dependencies": {
49
+ "tar": "^7.5.22",
47
50
  "ws": "^8.18.3"
48
51
  },
49
52
  "devDependencies": {
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: playcanvas-agent-bridge-cli
3
- description: Control an already-open PlayCanvas Editor scene through pcbridge CLI commands and the bundled Chrome extension. Use for PlayCanvas Editor inspection, entity/asset/script edits, eval snippets, and viewport captures without DevTools or browser automation.
3
+ description: Control an already-open PlayCanvas Editor scene or Launch page and manage the optional custom Editor frontend through pcbridge CLI commands and the bundled Chrome extension. Use for PlayCanvas Editor inspection, entity/asset/script edits, Launch runtime debugging, eval snippets, logs, viewport captures, and published Editor frontend selection without DevTools or browser automation.
4
4
  ---
5
5
 
6
6
  # PlayCanvas Agent Bridge CLI
@@ -13,49 +13,122 @@ pcbridge daemon status
13
13
  pcbridge targets
14
14
  ```
15
15
 
16
- If the daemon is offline, ask the user to run `pcbridge daemon start` in another terminal. If no PlayCanvas target appears, ask the user to run `pcbridge install-extension`, load the printed directory in `chrome://extensions`, and refresh the Editor tab.
16
+ If `doctor` reports `DAEMON_NOT_LISTENING`, ask the user to run `pcbridge daemon start` in another
17
+ terminal. For `LOOPBACK_ACCESS_DENIED`, retry with local-loopback permission instead of starting a
18
+ second daemon. If no PlayCanvas target appears, ask the user to run `pcbridge install-extension`,
19
+ load the printed directory in `chrome://extensions`, and refresh the Editor or Launch tab.
20
+
21
+ The directory where `pcbridge daemon start` runs is the workspace root. Each ready Editor project
22
+ is mirrored into `<projectId>-<projectName>/` below it. After choosing an explicit target, run
23
+ `pcbridge workspace status --target editor:<sceneId>` and do not write while it reports a conflict
24
+ or sync error.
25
+
26
+ Use `pcbridge frontend install latest` and `pcbridge frontend status` when the user wants the
27
+ published custom Editor build. The extension popup switches between custom and official modes.
28
+ The popup remembers that choice per PlayCanvas project and applies it automatically on later
29
+ project-picker and scene Editor navigations; change the remembered mode only through the popup.
17
30
 
18
31
  Use layered help to load only the command surface you need:
19
32
 
20
33
  ```bash
21
34
  pcbridge help
35
+ pcbridge help core
36
+ pcbridge help material
37
+ pcbridge help script
38
+ pcbridge help store
39
+ pcbridge help target
40
+ pcbridge help workspace
41
+ pcbridge help frontend
22
42
  pcbridge help entity
23
43
  pcbridge help asset
24
44
  pcbridge help template
25
45
  pcbridge help scene
26
46
  pcbridge help viewport
47
+ pcbridge help launch
48
+ pcbridge help logs
27
49
  pcbridge help eval
28
50
  ```
29
51
 
52
+ Workspace layout:
53
+
54
+ ```text
55
+ <workspace root>/<projectId>-<projectName>/
56
+ pcbridge.project.json
57
+ assets/ # remote folder tree and synchronized scripts
58
+ tmp/ # task scripts, manifests, captures, and conflict copies
59
+ .pcbridge/ # internal state; do not edit
60
+ ```
61
+
62
+ Existing script contents synchronize in both directions. Use structured commands for asset create,
63
+ move, rename, and delete operations. Other asset files remain lazy until
64
+ `pcbridge workspace pull --target editor:<sceneId> --asset <assetId>` is requested. Local file
65
+ arguments must stay inside the selected project workspace. Do not use `--allow-external-path`
66
+ unless the user explicitly asks to use a known external file.
67
+
30
68
  Use structured commands for small, known Editor operations:
31
69
 
32
70
  ```bash
33
- pcbridge entity list --target current --limit 50
34
- pcbridge entity create --target current --json ./entity.json
35
- pcbridge entity create-many --target current --json ./entities.json
36
- pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
37
- pcbridge entity duplicate --target current --id <resource_id>
38
- pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
39
- pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
40
- pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
41
- pcbridge asset list --target current --type script
42
- pcbridge asset create --target current --json ./assets.json
43
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/My Task/Textures"
44
- pcbridge asset upload --target current --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
45
- pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
46
- pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
47
- pcbridge template instantiate --target current --id <template_asset_id>
48
- pcbridge scene settings get --target current
49
- pcbridge viewport focus --target current --id <resource_id> --view perspective
50
- pcbridge script create --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
51
- pcbridge script set-text --target current --asset-id <id> --file ./script.js
52
- pcbridge viewport capture --target current --out ./tmp/playcanvas.png
71
+ pcbridge entity list --target editor:<sceneId> --limit 50
72
+ pcbridge entity create --target editor:<sceneId> --json ./entity.json
73
+ pcbridge entity create-many --target editor:<sceneId> --json ./entities.json
74
+ pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set position='[0,1,0]'
75
+ pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
76
+ pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
77
+ pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
78
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
79
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
80
+ pcbridge asset list --target editor:<sceneId> --type script
81
+ pcbridge asset create --target editor:<sceneId> --json ./assets.json
82
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
83
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
84
+ pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
85
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
86
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
87
+ pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
88
+ pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
89
+ pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
90
+ pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
91
+ pcbridge scene settings get --target editor:<sceneId>
92
+ pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
93
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
94
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
95
+ pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
96
+ pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
97
+ pcbridge logs get --target launch:<sceneId> --limit 100
98
+ pcbridge logs get --target launch:<sceneId> --level error
53
99
  ```
54
100
 
55
101
  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:
56
102
 
57
103
  ```bash
58
- pcbridge eval --target current --code "return { href: location.href, entityCount: editor.api.globals.entities.list().length }"
104
+ pcbridge eval --target editor:<sceneId> --code "return { href: location.href, entityCount: editor.api.globals.entities.list().length }"
105
+ pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./install-args.json --timeout-ms 120000
106
+ pcbridge launch diagnose --target launch:<sceneId>
107
+ pcbridge launch wait-ready --target launch:<sceneId> --focus --timeout-ms 30000
108
+ pcbridge eval --target launch:<sceneId> --code "return { runtimeCreated: !!runtimeApp, rootChildCount: runtimeApp?.root?.children?.length ?? 0 }"
59
109
  ```
60
110
 
61
- Eval snippets run in an async function with `editor`, `pc`, `pcui`, `window`, `document`, `command`, and `serialize`. Return compact JSON only. Do not return raw PlayCanvas Editor objects. Use `{ history: true }` for Editor mutations when available, and verify changes with a read-only command.
111
+ Eval snippets run in an async function with `editor`, `pc`, `pcui`, `runtimeApp`, `window`,
112
+ `document`, `command`, and `serialize`. `runtimeApp` uses a compatibility resolver for Engine V1/V2. Return compact
113
+ JSON only; bounded `--max-depth`/`--max-items` are available when projection is insufficient. Do
114
+ not return raw PlayCanvas Editor or runtime objects. Use `{ history: true }` for Editor mutations
115
+ when available, and verify changes with a read-only command.
116
+
117
+ For Launch runtime debugging, target `launch:<sceneId>` or `tab:<id>` and use `pcbridge eval`, `pcbridge viewport capture`, and `pcbridge logs get`. Editor-only structured entity/asset/script commands require an Editor target.
118
+
119
+ Use `editor:<sceneId>` for writes and `launch:<sceneId>` for runtime tests. Launch
120
+ `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context, attached
121
+ scene root, a completed frame, and recognized splash state; target `ready` also requires visibility.
122
+ These are not Engine lifecycle events, and script type count is diagnostic only. For a hidden tab,
123
+ use `launch diagnose` and `launch wait-ready --focus`. Capture records the
124
+ current canvas, defaults to `--max-width 1200`, and does not emulate a mobile viewport or DPR. Use `--script-name` for bundle- or
125
+ runtime-registered ScriptTypes that have no standalone asset id.
126
+
127
+ Editor patches are durable. Restore preview-only enabled/visibility changes before Template apply,
128
+ then verify overrides. Template `verified` covers the current Editor observer, not reload
129
+ persistence. Prefer `script upsert --parse --wait` after script edits; its completion check does not
130
+ wait for a later workspace mirror sync.
131
+
132
+ 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.
133
+
134
+ 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.