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.
- package/README.md +218 -52
- package/README.zh-CN.md +210 -51
- package/dist/cli.js +723 -92
- package/dist/config.js +6 -2
- package/dist/daemon/server.js +181 -19
- package/dist/daemon/target-registry.js +61 -3
- package/dist/frontend/server.js +191 -0
- package/dist/frontend/store.js +369 -0
- package/dist/shared/protocol.js +3 -1
- package/dist/snippets.js +764 -30
- package/dist/workspace/manager.js +536 -0
- 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/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 +214 -43
- package/extension/main.js +619 -32
- package/extension/manifest.json +29 -7
- package/extension/popup.html +188 -24
- package/extension/popup.js +199 -10
- package/extension/service-worker.js +268 -17
- package/package.json +4 -1
- package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +97 -24
- package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +167 -52
- package/skills/codex/playcanvas-agent-bridge-cli/agents/openai.yaml +2 -2
- package/skills/cursor/playcanvas-agent-bridge-cli.mdc +63 -23
- package/skills/windsurf/playcanvas-agent-bridge-cli.md +61 -23
|
@@ -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
|
|
|
@@ -17,102 +17,184 @@ pcbridge daemon status
|
|
|
17
17
|
pcbridge targets
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
If
|
|
20
|
+
If `doctor` reports `DAEMON_NOT_LISTENING`, tell the user to run this in a separate terminal:
|
|
21
21
|
|
|
22
22
|
```bash
|
|
23
23
|
pcbridge daemon start
|
|
24
24
|
```
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
Do not start a second daemon for `LOOPBACK_ACCESS_DENIED`. That means the current execution
|
|
27
|
+
environment cannot access `127.0.0.1`; retry with local-loopback permission instead.
|
|
28
|
+
|
|
29
|
+
The directory where `pcbridge daemon start` runs is the workspace root. Choose it intentionally;
|
|
30
|
+
each connected Editor project is mirrored into `<projectId>-<projectName>/` below that directory.
|
|
31
|
+
|
|
32
|
+
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.
|
|
33
|
+
|
|
34
|
+
For the optional custom Editor frontend, use `pcbridge frontend install latest`, confirm
|
|
35
|
+
`pcbridge frontend status`, then use the extension popup to switch between custom and official
|
|
36
|
+
frontend modes. Load focused help with `pcbridge help frontend`.
|
|
37
|
+
The popup remembers that choice per PlayCanvas project and applies it automatically on later
|
|
38
|
+
project-picker and scene Editor navigations; change the remembered mode only through the popup.
|
|
27
39
|
|
|
28
40
|
## Workflow
|
|
29
41
|
|
|
30
|
-
1. Run `pcbridge targets`
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
42
|
+
1. Run `pcbridge targets`. Use `editor:<sceneId>` for Editor writes and `launch:<sceneId>` for
|
|
43
|
+
runtime verification; use `tab:<id>` when either selector is ambiguous.
|
|
44
|
+
2. Run `pcbridge workspace status --target editor:<sceneId>`. Do not write while it reports a conflict or sync error.
|
|
45
|
+
3. Use layered help to load only the command group you need: `pcbridge help`, then `pcbridge help core|workspace|frontend|target|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
|
|
46
|
+
4. Keep temporary scripts, JSON manifests, uploads, and captures inside the selected project workspace.
|
|
47
|
+
5. Use structured commands for small, known operations that map cleanly to one Editor action.
|
|
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
|
+
7. Return compact JSON from snippets. Never return raw `editor`, `Entity`, `Asset`, `entities.root`, or app objects.
|
|
50
|
+
8. Use PlayCanvas history options for writes when available and verify writes with a read-only command.
|
|
51
|
+
|
|
52
|
+
## Workspace
|
|
53
|
+
|
|
54
|
+
```text
|
|
55
|
+
<workspace root>/<projectId>-<projectName>/
|
|
56
|
+
pcbridge.project.json
|
|
57
|
+
assets/ # PlayCanvas folder tree; scripts synchronize automatically
|
|
58
|
+
tmp/ # task scripts, manifests, captures, and conflict copies
|
|
59
|
+
.pcbridge/ # internal index and sync state; do not edit
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Use:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
pcbridge workspace status --target editor:<sceneId>
|
|
66
|
+
pcbridge workspace path --target editor:<sceneId>
|
|
67
|
+
pcbridge workspace sync --target editor:<sceneId>
|
|
68
|
+
pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Existing script contents synchronize in both directions. Create, move, rename, and delete assets
|
|
72
|
+
through structured pcbridge commands; do not perform structural changes by moving or deleting
|
|
73
|
+
mirrored local files. Non-script files are indexed but downloaded only with `workspace pull`.
|
|
74
|
+
|
|
75
|
+
Local file arguments are restricted to the selected project workspace. Never use
|
|
76
|
+
`--allow-external-path` unless the user explicitly asks to use a known external file.
|
|
37
77
|
|
|
38
78
|
## Safe Commands
|
|
39
79
|
|
|
40
80
|
Inspect a scene:
|
|
41
81
|
|
|
42
82
|
```bash
|
|
43
|
-
pcbridge eval --target
|
|
83
|
+
pcbridge eval --target editor:<sceneId> --code "return { href: location.href, hasEditor: !!editor, entityCount: editor.api.globals.entities.list().length }"
|
|
44
84
|
```
|
|
45
85
|
|
|
46
86
|
List entities:
|
|
47
87
|
|
|
48
88
|
```bash
|
|
49
|
-
pcbridge entity list --target
|
|
50
|
-
pcbridge entity list --target
|
|
51
|
-
pcbridge entity list --target
|
|
89
|
+
pcbridge entity list --target editor:<sceneId> --limit 50
|
|
90
|
+
pcbridge entity list --target editor:<sceneId> --name Player --component render
|
|
91
|
+
pcbridge entity list --target editor:<sceneId> --tag enemy
|
|
52
92
|
```
|
|
53
93
|
|
|
54
94
|
Create an entity from JSON:
|
|
55
95
|
|
|
56
96
|
```bash
|
|
57
|
-
pcbridge entity create --target
|
|
58
|
-
pcbridge entity create-many --target
|
|
97
|
+
pcbridge entity create --target editor:<sceneId> --json ./entity.json
|
|
98
|
+
pcbridge entity create-many --target editor:<sceneId> --json ./entities.json
|
|
59
99
|
```
|
|
60
100
|
|
|
61
101
|
Patch an entity:
|
|
62
102
|
|
|
63
103
|
```bash
|
|
64
|
-
pcbridge entity patch --target
|
|
65
|
-
pcbridge entity patch-many --target
|
|
66
|
-
pcbridge entity duplicate --target
|
|
67
|
-
pcbridge entity reparent --target
|
|
104
|
+
pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set name=Player --set position='[0,1,0]'
|
|
105
|
+
pcbridge entity patch-many --target editor:<sceneId> --json ./edits.json
|
|
106
|
+
pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
|
|
107
|
+
pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
|
|
68
108
|
```
|
|
69
109
|
|
|
70
110
|
Modify components and materials:
|
|
71
111
|
|
|
72
112
|
```bash
|
|
73
|
-
pcbridge entity add-component --target
|
|
74
|
-
pcbridge entity add-components --target
|
|
75
|
-
pcbridge entity set-material --target
|
|
76
|
-
pcbridge entity add-script --target
|
|
77
|
-
pcbridge entity
|
|
113
|
+
pcbridge entity add-component --target editor:<sceneId> --id <resource_id> --component render --data '{"type":"box"}'
|
|
114
|
+
pcbridge entity add-components --target editor:<sceneId> --id <resource_id> --json ./components.json
|
|
115
|
+
pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
|
|
116
|
+
pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
|
|
117
|
+
pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
|
|
118
|
+
pcbridge entity delete --target editor:<sceneId> --id <resource_id>
|
|
78
119
|
```
|
|
79
120
|
|
|
121
|
+
Use exactly one of `--asset-id` and `--script-name`. The name form is for a ScriptType registered
|
|
122
|
+
by a bundle or runtime asset and therefore lacking a standalone script asset id. Verify such a
|
|
123
|
+
script in Launch; explicit script reordering is not yet a dedicated command.
|
|
124
|
+
|
|
80
125
|
Work with assets and scripts:
|
|
81
126
|
|
|
82
127
|
```bash
|
|
83
|
-
pcbridge asset list --target
|
|
84
|
-
pcbridge asset create --target
|
|
85
|
-
pcbridge asset folder ensure --target
|
|
86
|
-
pcbridge asset upload --target
|
|
87
|
-
pcbridge asset
|
|
88
|
-
pcbridge
|
|
89
|
-
pcbridge material
|
|
90
|
-
pcbridge
|
|
91
|
-
pcbridge template
|
|
92
|
-
pcbridge
|
|
93
|
-
pcbridge
|
|
94
|
-
pcbridge
|
|
128
|
+
pcbridge asset list --target editor:<sceneId> --type script --limit 50
|
|
129
|
+
pcbridge asset create --target editor:<sceneId> --json ./assets.json
|
|
130
|
+
pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
|
|
131
|
+
pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
|
|
132
|
+
pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
|
|
133
|
+
pcbridge asset instantiate --target editor:<sceneId> --id <template_asset_id>
|
|
134
|
+
pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
|
|
135
|
+
pcbridge material patch --target editor:<sceneId> --asset-id <material_asset_id> --set diffuse='[1,0,0]'
|
|
136
|
+
pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
|
|
137
|
+
pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
|
|
138
|
+
pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
|
|
139
|
+
pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
|
|
140
|
+
pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
|
|
141
|
+
pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
|
|
142
|
+
pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts"
|
|
143
|
+
pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./controller.js --parse --wait
|
|
144
|
+
pcbridge script parse --target editor:<sceneId> --asset-id <id>
|
|
95
145
|
```
|
|
96
146
|
|
|
147
|
+
`template-roots.json` may be `{"entityIds":["root-a","root-b"]}` or an array of entity ids/items.
|
|
148
|
+
`apply-many` validates every root before writing and processes them serially. When an apply is
|
|
149
|
+
needed, completion requires the pipeline callback plus two zero-override observations. `verified`
|
|
150
|
+
only covers the current Editor observer; it does not confirm persistence across an Editor reload.
|
|
151
|
+
|
|
152
|
+
Prefer the completion-checked `--parse --wait` forms after edits. They wait for non-empty stable
|
|
153
|
+
file metadata, verify the remote text, parse it, and read back stable script attributes before
|
|
154
|
+
returning. They do not wait for the workspace mirror to finish a later sync.
|
|
155
|
+
|
|
97
156
|
Scene, store, and viewport:
|
|
98
157
|
|
|
99
158
|
```bash
|
|
100
|
-
pcbridge scene settings get --target
|
|
101
|
-
pcbridge scene settings patch --target
|
|
102
|
-
pcbridge store search --target
|
|
103
|
-
pcbridge store get --target
|
|
104
|
-
pcbridge viewport focus --target
|
|
159
|
+
pcbridge scene settings get --target editor:<sceneId>
|
|
160
|
+
pcbridge scene settings patch --target editor:<sceneId> --json ./scene-settings.json
|
|
161
|
+
pcbridge store search --target editor:<sceneId> --search vehicle --limit 20
|
|
162
|
+
pcbridge store get --target editor:<sceneId> --id <store_asset_id>
|
|
163
|
+
pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
|
|
105
164
|
```
|
|
106
165
|
|
|
107
166
|
Capture the viewport:
|
|
108
167
|
|
|
109
168
|
```bash
|
|
110
|
-
pcbridge viewport capture --target
|
|
169
|
+
pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas-viewport.png
|
|
111
170
|
```
|
|
112
171
|
|
|
172
|
+
Launch runtime debugging:
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
pcbridge launch diagnose --target launch:<sceneId>
|
|
176
|
+
pcbridge launch wait-ready --target launch:<sceneId> --focus --timeout-ms 30000
|
|
177
|
+
pcbridge eval --target launch:<sceneId> --code "return { href: location.href, runtimeCreated: !!runtimeApp, rootChildCount: runtimeApp?.root?.children?.length ?? 0 }"
|
|
178
|
+
pcbridge viewport capture --target launch:<sceneId> --out ./tmp/launch.png
|
|
179
|
+
pcbridge logs get --target launch:<sceneId> --limit 100
|
|
180
|
+
pcbridge logs get --target launch:<sceneId> --level error
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
For Launch, `lifecycleReady` is a best-effort heuristic requiring a runtime app with its own
|
|
184
|
+
graphics canvas/context, an attached scene root, at least one completed frame, and no recognized
|
|
185
|
+
startup splash. Target `ready` additionally requires a visible tab, so use `target focus` or
|
|
186
|
+
`launch wait-ready --focus` for a hidden Launch. These are diagnostic signals, not Engine lifecycle
|
|
187
|
+
events; custom splash screens may be missed. `scriptTypeCount` is diagnostic only. Use the resolved
|
|
188
|
+
`runtimeApp` eval binding instead of calling `Application.getApplication()` yourself.
|
|
189
|
+
|
|
190
|
+
`viewport capture` records the current canvas. It does not emulate a phone viewport or DPR. PNG
|
|
191
|
+
may preserve transparency, and the default `--max-width 1200` may downscale the output; use returned dimensions as
|
|
192
|
+
authoritative.
|
|
193
|
+
|
|
113
194
|
## Asset Organization
|
|
114
195
|
|
|
115
|
-
Create task-scoped folders before uploading generated assets
|
|
196
|
+
Create task-scoped remote folders before uploading generated assets. Keep local generated files
|
|
197
|
+
under the project `tmp/` directory until they are uploaded:
|
|
116
198
|
|
|
117
199
|
```text
|
|
118
200
|
AI Agent Bridge/<task name>/Textures
|
|
@@ -122,18 +204,46 @@ AI Agent Bridge/<task name>/Scripts
|
|
|
122
204
|
|
|
123
205
|
Use stable names that describe the asset purpose. Avoid dumping generated files at the project root.
|
|
124
206
|
|
|
207
|
+
## Large Task Workflow
|
|
208
|
+
|
|
209
|
+
For multi-asset or game-sized tasks:
|
|
210
|
+
|
|
211
|
+
1. Choose an explicit target from `pcbridge targets`, preferably `editor:<sceneId>` for writes or
|
|
212
|
+
`launch:<sceneId>` for tests; use `tab:<id>` to resolve ambiguity.
|
|
213
|
+
2. Confirm `workspace status`, then create task files under `<project>/tmp/<task name>/`.
|
|
214
|
+
3. Put PlayCanvas assets under `AI Agent Bridge/<task name>/{Textures,Materials,Scripts,Templates}`.
|
|
215
|
+
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.
|
|
216
|
+
5. Use `pcbridge script upsert --target editor:<sceneId> --filename <name>.js --file ./script.js --folder "AI Agent Bridge/<task name>/Scripts" --parse --wait` for repeatable script creation or update.
|
|
217
|
+
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.
|
|
218
|
+
7. Verify with read-only commands, a small smoke-test eval, and a capture under `<project>/tmp/captures/`.
|
|
219
|
+
|
|
220
|
+
If repeated manual glue is needed across tasks, improve the CLI or this skill rather than continuing to hand-roll brittle shell/script sequences.
|
|
221
|
+
|
|
222
|
+
## Editor Entity Persistence Notes
|
|
223
|
+
|
|
224
|
+
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.
|
|
225
|
+
|
|
226
|
+
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.
|
|
227
|
+
|
|
228
|
+
Editor entity patches are durable scene edits, not runtime-only preview state. Never apply a
|
|
229
|
+
Template while preview-only `enabled` or visibility changes remain on its source root. Restore and
|
|
230
|
+
read back the original preview values first, then run `template overrides` and `template apply`.
|
|
231
|
+
Prefer Launch eval for temporary runtime test state. `template apply` warns when the override set
|
|
232
|
+
contains an `enabled` change and waits until overrides are stably zero.
|
|
233
|
+
That verification is limited to the current Editor observer and does not prove reload persistence.
|
|
234
|
+
|
|
125
235
|
## Texture Box Pattern
|
|
126
236
|
|
|
127
237
|
For a textured scripted box, compose structured commands instead of writing one large eval:
|
|
128
238
|
|
|
129
239
|
```bash
|
|
130
|
-
pcbridge asset folder ensure --target
|
|
131
|
-
pcbridge asset upload --target
|
|
132
|
-
pcbridge material create --target
|
|
133
|
-
pcbridge script create --target
|
|
134
|
-
pcbridge entity create --target
|
|
135
|
-
pcbridge entity set-material --target
|
|
136
|
-
pcbridge entity add-script --target
|
|
240
|
+
pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Texture Box/Textures"
|
|
241
|
+
pcbridge asset upload --target editor:<sceneId> --file ./image.png --name TextureBoxImage --folder "AI Agent Bridge/Texture Box/Textures"
|
|
242
|
+
pcbridge material create --target editor:<sceneId> --name TextureBoxMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
|
|
243
|
+
pcbridge script create --target editor:<sceneId> --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
|
|
244
|
+
pcbridge entity create --target editor:<sceneId> --json ./box.json
|
|
245
|
+
pcbridge entity set-material --target editor:<sceneId> --id <box_resource_id> --material-id <material_asset_id>
|
|
246
|
+
pcbridge entity add-script --target editor:<sceneId> --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
|
|
137
247
|
```
|
|
138
248
|
|
|
139
249
|
## Eval Snippet Rules
|
|
@@ -144,12 +254,17 @@ The snippet runs inside an async function with these bindings:
|
|
|
144
254
|
editor;
|
|
145
255
|
pc;
|
|
146
256
|
pcui;
|
|
257
|
+
runtimeApp;
|
|
147
258
|
window;
|
|
148
259
|
document;
|
|
149
260
|
command;
|
|
150
261
|
serialize;
|
|
151
262
|
```
|
|
152
263
|
|
|
264
|
+
The final bridge serialization is bounded even when `--full` is used. Return only required leaf
|
|
265
|
+
fields. If a compact projection still contains `[MaxDepth ...]`, use bounded eval options such as
|
|
266
|
+
`--max-depth 8 --max-items 500`; do not return raw Editor or runtime objects.
|
|
267
|
+
|
|
153
268
|
Prefer:
|
|
154
269
|
|
|
155
270
|
```js
|
|
@@ -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,33 +14,73 @@ pcbridge daemon status
|
|
|
14
14
|
pcbridge targets
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
Run `pcbridge daemon start` only for `DAEMON_NOT_LISTENING`; for `LOOPBACK_ACCESS_DENIED`, retry
|
|
18
|
+
with local-loopback permission. If no target appears, ask the user to install/reload the extension.
|
|
18
19
|
|
|
19
|
-
|
|
20
|
+
The daemon start directory is the workspace root. After selecting an explicit target, run
|
|
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}`. Existing scripts
|
|
23
|
+
sync automatically; other files are lazy until
|
|
24
|
+
`pcbridge workspace pull --target editor:<sceneId> --asset <id>`.
|
|
25
|
+
|
|
26
|
+
For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
|
|
27
|
+
`pcbridge frontend status`, and switch custom/official mode from the extension popup.
|
|
28
|
+
The popup remembers that choice per project and reapplies it on later project-picker and scene
|
|
29
|
+
Editor navigations; change the remembered choice only through the popup.
|
|
30
|
+
|
|
31
|
+
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`.
|
|
20
32
|
|
|
21
33
|
Use structured commands for small, known Editor operations:
|
|
22
34
|
|
|
23
35
|
```bash
|
|
24
|
-
pcbridge entity list --target
|
|
25
|
-
pcbridge entity patch --target
|
|
26
|
-
pcbridge entity duplicate --target
|
|
27
|
-
pcbridge entity reparent --target
|
|
28
|
-
pcbridge entity set-material --target
|
|
29
|
-
pcbridge entity add-script --target
|
|
30
|
-
pcbridge
|
|
31
|
-
pcbridge asset
|
|
32
|
-
pcbridge asset
|
|
33
|
-
pcbridge asset
|
|
34
|
-
pcbridge
|
|
35
|
-
pcbridge
|
|
36
|
-
pcbridge
|
|
37
|
-
pcbridge
|
|
38
|
-
pcbridge
|
|
39
|
-
pcbridge
|
|
40
|
-
pcbridge
|
|
41
|
-
pcbridge
|
|
36
|
+
pcbridge entity list --target editor:<sceneId> --limit 50
|
|
37
|
+
pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set name=Player
|
|
38
|
+
pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
|
|
39
|
+
pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
|
|
40
|
+
pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
|
|
41
|
+
pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
|
|
42
|
+
pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
|
|
43
|
+
pcbridge asset list --target editor:<sceneId> --type script
|
|
44
|
+
pcbridge asset create --target editor:<sceneId> --json ./assets.json
|
|
45
|
+
pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
|
|
46
|
+
pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
|
|
47
|
+
pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
|
|
48
|
+
pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
|
|
49
|
+
pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
|
|
50
|
+
pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
|
|
51
|
+
pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
|
|
52
|
+
pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
|
|
53
|
+
pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
|
|
54
|
+
pcbridge scene settings get --target editor:<sceneId>
|
|
55
|
+
pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
|
|
56
|
+
pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
|
|
57
|
+
pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
|
|
58
|
+
pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
|
|
59
|
+
pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
|
|
60
|
+
pcbridge logs get --target launch:<sceneId> --limit 100
|
|
61
|
+
pcbridge logs get --target launch:<sceneId> --level error
|
|
42
62
|
```
|
|
43
63
|
|
|
44
64
|
Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
|
|
45
65
|
|
|
46
|
-
Use `pcbridge
|
|
66
|
+
Use `pcbridge launch diagnose` and `pcbridge launch wait-ready --focus` before runtime assertions.
|
|
67
|
+
Launch `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context,
|
|
68
|
+
attached scene root, a completed frame, and known splash selectors; target `ready` also requires a
|
|
69
|
+
visible tab. These are not Engine lifecycle events, and script type count is diagnostic only. Eval
|
|
70
|
+
snippets include compatibility-resolved `runtimeApp` plus `editor`, `pc`, `pcui`, `window`, `document`,
|
|
71
|
+
`command`, and `serialize`; never return raw app objects. Use bounded `--max-depth`/`--max-items`
|
|
72
|
+
only after projecting required fields.
|
|
73
|
+
|
|
74
|
+
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.
|
|
75
|
+
|
|
76
|
+
Use `editor:<sceneId>` for writes. Use `--script-name` for bundle-registered ScriptTypes. Editor
|
|
77
|
+
patches are durable, so restore preview-only enabled/visibility changes before Template apply.
|
|
78
|
+
Template `verified` covers current Editor overrides, not persistence across a reload. Script
|
|
79
|
+
`--parse --wait` completion checks do not wait for the workspace mirror's later sync.
|
|
80
|
+
Capture does not focus/resize/emulate a mobile viewport and defaults to `--max-width 1200`; use returned dimensions as authoritative.
|
|
81
|
+
|
|
82
|
+
For large eval installs, use `pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./install-args.json --timeout-ms 120000`.
|
|
83
|
+
|
|
84
|
+
For large tasks, choose an explicit target from `pcbridge targets`, keep generated files and captures under the project `tmp/` directory, upload batches with `asset upload-many`, edit tracked scripts under `assets/`, and capture the viewport after smoke tests. File arguments must remain inside the workspace; never use `--allow-external-path` without explicit user approval. If repeated manual glue appears, improve the CLI or this rule.
|
|
85
|
+
|
|
86
|
+
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,34 +10,72 @@ pcbridge daemon status
|
|
|
10
10
|
pcbridge targets
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Run `pcbridge daemon start` only for `DAEMON_NOT_LISTENING`; for `LOOPBACK_ACCESS_DENIED`, retry
|
|
14
|
+
with local-loopback permission. If no target is connected, install/reload the unpacked extension.
|
|
14
15
|
|
|
15
|
-
|
|
16
|
+
The daemon start directory is the workspace root. After selecting an explicit target, run
|
|
17
|
+
`pcbridge workspace status --target editor:<sceneId>` and stop if it reports a conflict or sync
|
|
18
|
+
error. Each project is mirrored under `<projectId>-<projectName>/{assets,tmp}`. Script content syncs
|
|
19
|
+
both ways; other asset files are lazy until explicitly pulled.
|
|
20
|
+
|
|
21
|
+
For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
|
|
22
|
+
`pcbridge frontend status`, and switch custom/official mode from the extension popup.
|
|
23
|
+
The popup remembers that choice per project and reapplies it on later project-picker and scene
|
|
24
|
+
Editor navigations; change the remembered choice only through the popup.
|
|
25
|
+
|
|
26
|
+
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`.
|
|
16
27
|
|
|
17
28
|
Use structured commands for small, known Editor operations:
|
|
18
29
|
|
|
19
30
|
```bash
|
|
20
|
-
pcbridge entity list --target
|
|
21
|
-
pcbridge entity create --target
|
|
22
|
-
pcbridge entity patch --target
|
|
23
|
-
pcbridge entity duplicate --target
|
|
24
|
-
pcbridge entity reparent --target
|
|
25
|
-
pcbridge entity set-material --target
|
|
26
|
-
pcbridge entity add-script --target
|
|
27
|
-
pcbridge
|
|
28
|
-
pcbridge asset
|
|
29
|
-
pcbridge asset
|
|
30
|
-
pcbridge asset
|
|
31
|
-
pcbridge
|
|
32
|
-
pcbridge
|
|
33
|
-
pcbridge
|
|
34
|
-
pcbridge
|
|
35
|
-
pcbridge
|
|
36
|
-
pcbridge
|
|
37
|
-
pcbridge
|
|
38
|
-
pcbridge
|
|
31
|
+
pcbridge entity list --target editor:<sceneId> --limit 50
|
|
32
|
+
pcbridge entity create --target editor:<sceneId> --json ./entity.json
|
|
33
|
+
pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set position='[0,1,0]'
|
|
34
|
+
pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
|
|
35
|
+
pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
|
|
36
|
+
pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
|
|
37
|
+
pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
|
|
38
|
+
pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
|
|
39
|
+
pcbridge asset list --target editor:<sceneId> --type script
|
|
40
|
+
pcbridge asset create --target editor:<sceneId> --json ./assets.json
|
|
41
|
+
pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
|
|
42
|
+
pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
|
|
43
|
+
pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
|
|
44
|
+
pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
|
|
45
|
+
pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
|
|
46
|
+
pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
|
|
47
|
+
pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
|
|
48
|
+
pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
|
|
49
|
+
pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
|
|
50
|
+
pcbridge scene settings get --target editor:<sceneId>
|
|
51
|
+
pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
|
|
52
|
+
pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
|
|
53
|
+
pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
|
|
54
|
+
pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
|
|
55
|
+
pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
|
|
56
|
+
pcbridge logs get --target launch:<sceneId> --limit 100
|
|
57
|
+
pcbridge logs get --target launch:<sceneId> --level error
|
|
39
58
|
```
|
|
40
59
|
|
|
41
60
|
Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
|
|
42
61
|
|
|
43
|
-
Use `pcbridge
|
|
62
|
+
Use `pcbridge launch diagnose` and `pcbridge launch wait-ready --focus` before runtime assertions.
|
|
63
|
+
Launch `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context,
|
|
64
|
+
attached scene root, a completed frame, and known splash selectors; target `ready` also requires a
|
|
65
|
+
visible tab. These are not Engine lifecycle events, and script type count is diagnostic only. Eval
|
|
66
|
+
includes compatibility-resolved `runtimeApp` for Engine V1/V2 plus the existing Editor bindings. Return compact
|
|
67
|
+
JSON; use bounded `--max-depth`/`--max-items` only when a leaf projection is insufficient.
|
|
68
|
+
|
|
69
|
+
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.
|
|
70
|
+
|
|
71
|
+
Use `editor:<sceneId>` for writes and `--script-name` for bundle-registered ScriptTypes. Editor
|
|
72
|
+
patches are durable, so restore preview-only enabled/visibility changes before Template apply.
|
|
73
|
+
Template `verified` covers current Editor overrides, not persistence across a reload. Script
|
|
74
|
+
`--parse --wait` completion checks do not wait for the workspace mirror's later sync.
|
|
75
|
+
Capture records the current canvas, defaults to `--max-width 1200`, and does not emulate a mobile viewport or DPR.
|
|
76
|
+
|
|
77
|
+
For large eval installs, use `pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./install-args.json --timeout-ms 120000`.
|
|
78
|
+
|
|
79
|
+
For large tasks, choose an explicit target from `pcbridge targets`, keep generated files and captures under the project `tmp/` directory, upload batches with `asset upload-many`, edit tracked scripts under `assets/`, and capture the viewport after smoke tests. Local file arguments must remain inside the workspace; never use `--allow-external-path` without explicit user approval. If repeated manual glue appears, improve the CLI or this rule.
|
|
80
|
+
|
|
81
|
+
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.
|