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.
- package/README.md +93 -7
- package/README.zh-CN.md +89 -6
- package/dist/cli.js +257 -22
- package/dist/config.js +6 -2
- package/dist/daemon/server.js +50 -15
- package/dist/daemon/target-registry.js +19 -1
- package/dist/frontend/server.js +191 -0
- package/dist/frontend/store.js +369 -0
- package/dist/snippets.js +77 -0
- package/extension/isolated.js +126 -30
- package/extension/main.js +257 -29
- package/extension/manifest.json +16 -6
- package/extension/popup.html +42 -1
- package/extension/popup.js +93 -7
- package/package.json +4 -1
- package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +20 -2
- package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +40 -5
- package/skills/codex/playcanvas-agent-bridge-cli/agents/openai.yaml +2 -2
- package/skills/cursor/playcanvas-agent-bridge-cli.mdc +18 -5
- package/skills/windsurf/playcanvas-agent-bridge-cli.md +17 -4
package/extension/popup.js
CHANGED
|
@@ -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
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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
|
-
|
|
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
|
-
:
|
|
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.
|
|
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,
|
|
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,
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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.
|