playcanvas-agent-bridge-cli 0.2.2 → 0.3.0

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.
@@ -8,19 +8,105 @@ async function loadConfig() {
8
8
  }
9
9
  }
10
10
 
11
+ async function loadFrontendStatus(config) {
12
+ if (!config || !config.token) return null;
13
+ try {
14
+ const host = config.host || "127.0.0.1";
15
+ const port = config.port || 17329;
16
+ const response = await fetch(`http://${host}:${port}/frontend/status`, {
17
+ headers: {
18
+ "X-PCBridge-Token": config.token,
19
+ },
20
+ });
21
+ if (!response.ok) return null;
22
+ const envelope = await response.json();
23
+ return envelope.ok ? envelope.data : null;
24
+ } catch {
25
+ return null;
26
+ }
27
+ }
28
+
29
+ function isEditorUrl(url) {
30
+ return Boolean(
31
+ url &&
32
+ (url.protocol === "https:" || url.protocol === "http:") &&
33
+ url.hostname === "playcanvas.com" &&
34
+ url.pathname.startsWith("/editor"),
35
+ );
36
+ }
37
+
38
+ async function switchFrontend(active, url, custom) {
39
+ if (!active || !url) return;
40
+ if (custom) {
41
+ url.searchParams.set("use_local_frontend", "");
42
+ } else {
43
+ url.searchParams.delete("use_local_frontend");
44
+ }
45
+ await chrome.tabs.update(active.id, { url: url.toString() });
46
+ window.close();
47
+ }
48
+
11
49
  async function main() {
12
50
  const config = await loadConfig();
13
51
  const daemon = document.getElementById("daemon");
14
52
  const tab = document.getElementById("tab");
15
-
16
- daemon.textContent = config
17
- ? `${config.host || "127.0.0.1"}:${config.port || 17329}`
18
- : "Run pcbridge install-extension";
53
+ const frontend = document.getElementById("frontend");
54
+ const mode = document.getElementById("mode");
55
+ const message = document.getElementById("message");
56
+ const useCustom = document.getElementById("use-custom");
57
+ const useOfficial = document.getElementById("use-official");
19
58
 
20
59
  const [active] = await chrome.tabs.query({ active: true, currentWindow: true });
21
- tab.textContent = active && active.url && active.url.includes("playcanvas.com/editor")
60
+ const url = active && active.url ? new URL(active.url) : null;
61
+ const isEditor = isEditorUrl(url);
62
+ const isLaunch = Boolean(url && url.hostname === "launch.playcanvas.com");
63
+ const customMode = Boolean(isEditor && url.searchParams.has("use_local_frontend"));
64
+ const frontendStatus = await loadFrontendStatus(config);
65
+ const serverReady = Boolean(
66
+ frontendStatus &&
67
+ frontendStatus.ready &&
68
+ frontendStatus.server &&
69
+ frontendStatus.server.listening,
70
+ );
71
+
72
+ daemon.textContent = frontendStatus
73
+ ? `${config.host || "127.0.0.1"}:${config.port || 17329} connected`
74
+ : "Not reachable";
75
+
76
+ tab.textContent = isEditor
22
77
  ? "PlayCanvas Editor"
23
- : "Open a PlayCanvas Editor tab";
78
+ : isLaunch
79
+ ? "PlayCanvas Launch"
80
+ : "Open a PlayCanvas Editor or Launch tab";
81
+
82
+ frontend.textContent = frontendStatus && frontendStatus.activeRelease
83
+ ? frontendStatus.activeRelease
84
+ : "Not installed";
85
+ mode.textContent = isEditor
86
+ ? customMode
87
+ ? "Custom"
88
+ : "Official"
89
+ : "Unavailable";
90
+
91
+ useCustom.disabled = !isEditor || !serverReady;
92
+ useOfficial.disabled = !isEditor || !customMode;
93
+
94
+ if (!isEditor) {
95
+ message.textContent = "Open a playcanvas.com Editor tab to switch frontend versions.";
96
+ } else if (!frontendStatus) {
97
+ message.textContent = "Start the daemon. Official mode remains available.";
98
+ } else if (!frontendStatus.ready) {
99
+ message.textContent = "Run: pcbridge frontend install latest";
100
+ } else if (!frontendStatus.server.listening) {
101
+ message.textContent = "Port 3487 is unavailable. Check pcbridge frontend status.";
102
+ } else {
103
+ message.textContent = "Switching reloads this Editor tab and preserves its other URL parameters.";
104
+ }
105
+
106
+ useCustom.addEventListener("click", () => switchFrontend(active, url, true));
107
+ useOfficial.addEventListener("click", () => switchFrontend(active, url, false));
24
108
  }
25
109
 
26
- main();
110
+ main().catch((error) => {
111
+ document.getElementById("message").textContent = String(error);
112
+ });
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.3.0",
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,17 +13,23 @@ 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 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 or Launch tab.
17
+
18
+ Use `pcbridge frontend install latest` and `pcbridge frontend status` when the user wants the
19
+ published custom Editor build. The extension popup switches between custom and official modes.
17
20
 
18
21
  Use layered help to load only the command surface you need:
19
22
 
20
23
  ```bash
21
24
  pcbridge help
25
+ pcbridge help frontend
22
26
  pcbridge help entity
23
27
  pcbridge help asset
24
28
  pcbridge help template
25
29
  pcbridge help scene
26
30
  pcbridge help viewport
31
+ pcbridge help launch
32
+ pcbridge help logs
27
33
  pcbridge help eval
28
34
  ```
29
35
 
@@ -42,20 +48,32 @@ pcbridge asset list --target current --type script
42
48
  pcbridge asset create --target current --json ./assets.json
43
49
  pcbridge asset folder ensure --target current --path "AI Agent Bridge/My Task/Textures"
44
50
  pcbridge asset upload --target current --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
51
+ pcbridge asset upload-many --target current --json ./upload-manifest.json
45
52
  pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
46
53
  pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
47
54
  pcbridge template instantiate --target current --id <template_asset_id>
48
55
  pcbridge scene settings get --target current
49
56
  pcbridge viewport focus --target current --id <resource_id> --view perspective
57
+ pcbridge script upsert --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse
50
58
  pcbridge script create --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
51
59
  pcbridge script set-text --target current --asset-id <id> --file ./script.js
52
60
  pcbridge viewport capture --target current --out ./tmp/playcanvas.png
61
+ pcbridge logs get --target launch:<sceneId> --limit 100
62
+ pcbridge logs get --target launch:<sceneId> --level error
53
63
  ```
54
64
 
55
65
  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
66
 
57
67
  ```bash
58
68
  pcbridge eval --target current --code "return { href: location.href, entityCount: editor.api.globals.entities.list().length }"
69
+ pcbridge eval --target current --file ./install.js --args-json ./install-args.json --timeout-ms 120000
70
+ pcbridge eval --target launch:<sceneId> --code "return { href: location.href, hasPc: !!pc, canvasCount: document.querySelectorAll('canvas').length }"
59
71
  ```
60
72
 
61
73
  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.
74
+
75
+ 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.
76
+
77
+ For large PlayCanvas tasks, choose an explicit target from `pcbridge targets`, keep task files in a local folder, upload assets with an upload manifest, use `script upsert` for repeatable script updates, and capture the viewport after smoke tests. If the same manual glue repeats across tasks, improve the CLI or this skill instead of continuing the brittle sequence.
78
+
79
+ 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.
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  name: playcanvas-agent-bridge-cli
3
- description: Control an already-open PlayCanvas Editor scene through the pcbridge CLI and Chrome extension. Use when Codex needs to inspect or modify PlayCanvas Editor targets, entities, assets, scripts, scene data, or viewport captures without DevTools, mouse/keyboard automation, MCP, or browser console scripting.
3
+ description: Control an already-open PlayCanvas Editor scene or Launch page and manage the optional custom Editor frontend through the pcbridge CLI and Chrome extension. Use when Codex needs to inspect or modify PlayCanvas Editor targets, debug Launch runtime pages, read logs, run eval snippets, capture viewports, or install and select a published Editor frontend without DevTools, mouse/keyboard automation, MCP, or browser console scripting.
4
4
  ---
5
5
 
6
6
  # PlayCanvas Agent Bridge CLI
7
7
 
8
- Use `pcbridge` to automate PlayCanvas Editor through a local daemon and Chrome extension. The CLI is the interface; this skill only tells the agent how to use it safely.
8
+ Use `pcbridge` to automate PlayCanvas Editor and PlayCanvas Launch pages through a local daemon and Chrome extension. The CLI is the interface; this skill only tells the agent how to use it safely.
9
9
 
10
10
  ## Quick Start
11
11
 
@@ -23,14 +23,18 @@ If the daemon is offline, tell the user to run this in a separate terminal:
23
23
  pcbridge daemon start
24
24
  ```
25
25
 
26
- If no target appears, tell the user to run `pcbridge install-extension`, load the printed directory in `chrome://extensions`, then refresh the PlayCanvas Editor tab.
26
+ If no target appears, tell the user to run `pcbridge install-extension`, load the printed directory in `chrome://extensions`, then refresh the PlayCanvas Editor or Launch tab.
27
+
28
+ For the optional custom Editor frontend, use `pcbridge frontend install latest`, confirm
29
+ `pcbridge frontend status`, then use the extension popup to switch between custom and official
30
+ frontend modes. Load focused help with `pcbridge help frontend`.
27
31
 
28
32
  ## Workflow
29
33
 
30
34
  1. Run `pcbridge targets` and choose an explicit target when possible.
31
- 2. Use layered help to load only the command group you need: `pcbridge help`, then `pcbridge help entity|asset|material|template|script|scene|store|viewport|eval`.
35
+ 2. Use layered help to load only the command group you need: `pcbridge help`, then `pcbridge help frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
32
36
  3. Use structured commands for small, known operations that map cleanly to one Editor action.
33
- 4. Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, and large multi-step scene edits where one script is clearer than many CLI calls.
37
+ 4. 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.
34
38
  5. Return compact JSON from snippets. Never return raw `editor`, `Entity`, `Asset`, `entities.root`, or app objects.
35
39
  6. Use PlayCanvas history options for writes when available.
36
40
  7. Verify writes with a read-only command after mutation.
@@ -84,11 +88,13 @@ pcbridge asset list --target current --type script --limit 50
84
88
  pcbridge asset create --target current --json ./assets.json
85
89
  pcbridge asset folder ensure --target current --path "AI Agent Bridge/My Task/Textures"
86
90
  pcbridge asset upload --target current --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
91
+ pcbridge asset upload-many --target current --json ./upload-manifest.json
87
92
  pcbridge asset instantiate --target current --id <template_asset_id>
88
93
  pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
89
94
  pcbridge material patch --target current --asset-id <material_asset_id> --set diffuse='[1,0,0]'
90
95
  pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
91
96
  pcbridge template instantiate --target current --id <template_asset_id>
97
+ pcbridge script upsert --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts" --parse
92
98
  pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts"
93
99
  pcbridge script set-text --target current --asset-id <id> --file ./controller.js
94
100
  pcbridge script parse --target current --asset-id <id>
@@ -110,6 +116,15 @@ Capture the viewport:
110
116
  pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
111
117
  ```
112
118
 
119
+ Launch runtime debugging:
120
+
121
+ ```bash
122
+ pcbridge eval --target launch:<sceneId> --code "return { href: location.href, hasPc: !!pc, canvasCount: document.querySelectorAll('canvas').length }"
123
+ pcbridge viewport capture --target launch:<sceneId> --out ./tmp/launch.png
124
+ pcbridge logs get --target launch:<sceneId> --limit 100
125
+ pcbridge logs get --target launch:<sceneId> --level error
126
+ ```
127
+
113
128
  ## Asset Organization
114
129
 
115
130
  Create task-scoped folders before uploading generated assets:
@@ -122,6 +137,26 @@ AI Agent Bridge/<task name>/Scripts
122
137
 
123
138
  Use stable names that describe the asset purpose. Avoid dumping generated files at the project root.
124
139
 
140
+ ## Large Task Workflow
141
+
142
+ For multi-asset or game-sized tasks:
143
+
144
+ 1. Choose an explicit target from `pcbridge targets`, preferably `scene:<sceneId>` or `tab:<id>`.
145
+ 2. Create a project-local task folder for generated scripts, manifests, captures, and temporary assets.
146
+ 3. Put PlayCanvas assets under `AI Agent Bridge/<task name>/{Textures,Materials,Scripts,Templates}`.
147
+ 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.
148
+ 5. Use `pcbridge script upsert --filename <name>.js --file ./script.js --folder "AI Agent Bridge/<task name>/Scripts" --parse` for repeatable script creation or update.
149
+ 6. Use `pcbridge eval --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.
150
+ 7. Verify with read-only commands, a small smoke-test eval, and `pcbridge viewport capture --out ./task/captures/preview.png`.
151
+
152
+ If repeated manual glue is needed across tasks, improve the CLI or this skill rather than continuing to hand-roll brittle shell/script sequences.
153
+
154
+ ## Editor Entity Persistence Notes
155
+
156
+ Do not pre-place runtime-generated content just to prove a game exists. For roguelike maps, procedural levels, particles, pickups, and enemies that are generated at launch, keep the durable Editor surface small: a root entity, script component, camera/light helpers when useful, and persistent assets/scripts.
157
+
158
+ When Editor entities do need to be created or replaced, prefer structured commands such as `entity create`, `entity create-many`, `entity add-script`, `entity set-material`, and `entity patch-many`. In current PlayCanvas Editor builds, a large `eval` script that creates many entities in a tight loop can briefly show objects in the viewport and then lose them from the Editor data model. For large static previews, create in small batches, pause between batches when needed, then immediately verify with `entity list` by name/tag before capturing the viewport.
159
+
125
160
  ## Texture Box Pattern
126
161
 
127
162
  For a textured scripted box, compose structured commands instead of writing one large eval:
@@ -1,4 +1,4 @@
1
1
  interface:
2
2
  display_name: "PlayCanvas Agent Bridge"
3
- short_description: "Control open PlayCanvas Editor scenes through pcbridge."
4
- default_prompt: "Use pcbridge to inspect or edit the open PlayCanvas Editor scene."
3
+ short_description: "Control open PlayCanvas Editor and Launch pages through pcbridge."
4
+ default_prompt: "Use pcbridge to inspect or edit the open PlayCanvas Editor scene, or debug the matching Launch page."
@@ -1,10 +1,10 @@
1
1
  ---
2
- description: Use pcbridge to control open PlayCanvas Editor tabs from Cursor.
2
+ description: Use pcbridge to control open PlayCanvas Editor and Launch tabs from Cursor.
3
3
  globs:
4
4
  alwaysApply: false
5
5
  ---
6
6
 
7
- Use `pcbridge` for PlayCanvas Editor automation. Do not use DevTools, mouse/keyboard browser automation, or raw console typing.
7
+ Use `pcbridge` for PlayCanvas Editor automation and PlayCanvas Launch runtime debugging. Do not use DevTools, mouse/keyboard browser automation, or raw console typing.
8
8
 
9
9
  Setup checks:
10
10
 
@@ -14,9 +14,12 @@ pcbridge daemon status
14
14
  pcbridge targets
15
15
  ```
16
16
 
17
- If needed, ask the user to run `pcbridge daemon start`. If no target appears, ask them to run `pcbridge install-extension`, load the printed extension directory in `chrome://extensions`, and refresh PlayCanvas Editor.
17
+ If needed, ask the user to run `pcbridge daemon start`. If no target appears, ask them to run `pcbridge install-extension`, load the printed extension directory in `chrome://extensions`, and refresh PlayCanvas Editor or Launch.
18
18
 
19
- Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help entity|asset|material|template|script|scene|store|viewport|eval`.
19
+ For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
20
+ `pcbridge frontend status`, and switch custom/official mode from the extension popup.
21
+
22
+ Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
20
23
 
21
24
  Use structured commands for small, known Editor operations:
22
25
 
@@ -31,16 +34,26 @@ pcbridge asset list --target current --type script
31
34
  pcbridge asset create --target current --json ./assets.json
32
35
  pcbridge asset folder ensure --target current --path "AI Agent Bridge/My Task/Textures"
33
36
  pcbridge asset upload --target current --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
37
+ pcbridge asset upload-many --target current --json ./upload-manifest.json
34
38
  pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
35
39
  pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
36
40
  pcbridge template instantiate --target current --id <template_asset_id>
37
41
  pcbridge scene settings get --target current
38
42
  pcbridge viewport focus --target current --id <resource_id> --view perspective
43
+ pcbridge script upsert --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse
39
44
  pcbridge script create --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
40
45
  pcbridge script set-text --target current --asset-id <id> --file ./script.js
41
46
  pcbridge viewport capture --target current --out ./tmp/playcanvas.png
47
+ pcbridge logs get --target launch:<sceneId> --limit 100
48
+ pcbridge logs get --target launch:<sceneId> --level error
42
49
  ```
43
50
 
44
51
  Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
45
52
 
46
- Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, and large multi-step scene edits. Snippets run with `editor`, `pc`, `pcui`, `window`, `document`, `command`, and `serialize`. Return compact JSON; never return raw `editor`, `Entity`, `Asset`, or app objects.
53
+ Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, Launch runtime debugging, and large multi-step scene edits. Use `pcbridge eval --file ./install.js --args-json ./args.json --timeout-ms 120000` when local configuration is too large to embed in code or the install can exceed the default 15s timeout. Snippets run with `editor`, `pc`, `pcui`, `window`, `document`, `command`, and `serialize`. Return compact JSON; never return raw `editor`, `Entity`, `Asset`, or app objects.
54
+
55
+ 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.
56
+
57
+ For large tasks, choose an explicit target from `pcbridge targets`, keep generated files and captures in a local task folder, upload batches with `asset upload-many`, update scripts with `script upsert`, and capture the viewport after smoke tests. If repeated manual glue appears, improve the CLI or this rule.
58
+
59
+ 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.
@@ -1,6 +1,6 @@
1
1
  # PlayCanvas Agent Bridge CLI
2
2
 
3
- Use `pcbridge` to automate an already-open PlayCanvas Editor tab through the local daemon and Chrome extension.
3
+ Use `pcbridge` to automate an already-open PlayCanvas Editor tab or debug a PlayCanvas Launch tab through the local daemon and Chrome extension.
4
4
 
5
5
  Start with:
6
6
 
@@ -10,9 +10,12 @@ pcbridge daemon status
10
10
  pcbridge targets
11
11
  ```
12
12
 
13
- If the daemon is offline, ask the user to run `pcbridge daemon start`. If no target is connected, ask the user to run `pcbridge install-extension`, load the printed unpacked extension path in `chrome://extensions`, and refresh the Editor tab.
13
+ If the daemon is offline, ask the user to run `pcbridge daemon start`. If no target is connected, ask the user to run `pcbridge install-extension`, load the printed unpacked extension path in `chrome://extensions`, and refresh the Editor or Launch tab.
14
14
 
15
- Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help entity|asset|material|template|script|scene|store|viewport|eval`.
15
+ For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
16
+ `pcbridge frontend status`, and switch custom/official mode from the extension popup.
17
+
18
+ Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
16
19
 
17
20
  Use structured commands for small, known Editor operations:
18
21
 
@@ -28,16 +31,26 @@ pcbridge asset list --target current --type script
28
31
  pcbridge asset create --target current --json ./assets.json
29
32
  pcbridge asset folder ensure --target current --path "AI Agent Bridge/My Task/Textures"
30
33
  pcbridge asset upload --target current --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
34
+ pcbridge asset upload-many --target current --json ./upload-manifest.json
31
35
  pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
32
36
  pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
33
37
  pcbridge template instantiate --target current --id <template_asset_id>
34
38
  pcbridge scene settings get --target current
35
39
  pcbridge viewport focus --target current --id <resource_id> --view perspective
40
+ pcbridge script upsert --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse
36
41
  pcbridge script create --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
37
42
  pcbridge script set-text --target current --asset-id <id> --file ./script.js
38
43
  pcbridge viewport capture --target current --out ./tmp/playcanvas.png
44
+ pcbridge logs get --target launch:<sceneId> --limit 100
45
+ pcbridge logs get --target launch:<sceneId> --level error
39
46
  ```
40
47
 
41
48
  Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
42
49
 
43
- Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, and large multi-step scene edits. Return compact JSON and never return raw PlayCanvas Editor objects. Use history-enabled mutations when available and verify writes with a read-only command.
50
+ Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, Launch runtime debugging, and large multi-step scene edits. Use `pcbridge eval --file ./install.js --args-json ./args.json --timeout-ms 120000` when local configuration is too large to embed in code or the install can exceed the default 15s timeout. Return compact JSON and never return raw PlayCanvas Editor objects. Use history-enabled mutations when available and verify writes with a read-only command.
51
+
52
+ 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.
53
+
54
+ For large tasks, choose an explicit target from `pcbridge targets`, keep generated files and captures in a local task folder, upload batches with `asset upload-many`, update scripts with `script upsert`, and capture the viewport after smoke tests. If repeated manual glue appears, improve the CLI or this rule.
55
+
56
+ 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.