playcanvas-agent-bridge-cli 0.3.0 → 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 +138 -58
- package/README.zh-CN.md +134 -58
- package/dist/cli.js +483 -87
- package/dist/config.js +1 -1
- package/dist/daemon/server.js +133 -6
- package/dist/daemon/target-registry.js +43 -3
- package/dist/shared/protocol.js +3 -1
- package/dist/snippets.js +726 -69
- 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 +90 -15
- package/extension/main.js +383 -24
- package/extension/manifest.json +14 -2
- package/extension/popup.html +179 -56
- package/extension/popup.js +161 -58
- package/extension/service-worker.js +268 -17
- package/package.json +1 -1
- package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +83 -28
- package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +137 -57
- package/skills/cursor/playcanvas-agent-bridge-cli.mdc +51 -24
- package/skills/windsurf/playcanvas-agent-bridge-cli.md +50 -25
|
@@ -17,117 +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
|
+
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
|
+
|
|
26
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.
|
|
27
33
|
|
|
28
34
|
For the optional custom Editor frontend, use `pcbridge frontend install latest`, confirm
|
|
29
35
|
`pcbridge frontend status`, then use the extension popup to switch between custom and official
|
|
30
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.
|
|
31
39
|
|
|
32
40
|
## Workflow
|
|
33
41
|
|
|
34
|
-
1. Run `pcbridge targets`
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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.
|
|
41
77
|
|
|
42
78
|
## Safe Commands
|
|
43
79
|
|
|
44
80
|
Inspect a scene:
|
|
45
81
|
|
|
46
82
|
```bash
|
|
47
|
-
pcbridge eval --target
|
|
83
|
+
pcbridge eval --target editor:<sceneId> --code "return { href: location.href, hasEditor: !!editor, entityCount: editor.api.globals.entities.list().length }"
|
|
48
84
|
```
|
|
49
85
|
|
|
50
86
|
List entities:
|
|
51
87
|
|
|
52
88
|
```bash
|
|
53
|
-
pcbridge entity list --target
|
|
54
|
-
pcbridge entity list --target
|
|
55
|
-
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
|
|
56
92
|
```
|
|
57
93
|
|
|
58
94
|
Create an entity from JSON:
|
|
59
95
|
|
|
60
96
|
```bash
|
|
61
|
-
pcbridge entity create --target
|
|
62
|
-
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
|
|
63
99
|
```
|
|
64
100
|
|
|
65
101
|
Patch an entity:
|
|
66
102
|
|
|
67
103
|
```bash
|
|
68
|
-
pcbridge entity patch --target
|
|
69
|
-
pcbridge entity patch-many --target
|
|
70
|
-
pcbridge entity duplicate --target
|
|
71
|
-
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>
|
|
72
108
|
```
|
|
73
109
|
|
|
74
110
|
Modify components and materials:
|
|
75
111
|
|
|
76
112
|
```bash
|
|
77
|
-
pcbridge entity add-component --target
|
|
78
|
-
pcbridge entity add-components --target
|
|
79
|
-
pcbridge entity set-material --target
|
|
80
|
-
pcbridge entity add-script --target
|
|
81
|
-
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>
|
|
82
119
|
```
|
|
83
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
|
+
|
|
84
125
|
Work with assets and scripts:
|
|
85
126
|
|
|
86
127
|
```bash
|
|
87
|
-
pcbridge asset list --target
|
|
88
|
-
pcbridge asset create --target
|
|
89
|
-
pcbridge asset folder ensure --target
|
|
90
|
-
pcbridge asset upload --target
|
|
91
|
-
pcbridge asset upload-many --target
|
|
92
|
-
pcbridge asset instantiate --target
|
|
93
|
-
pcbridge material create --target
|
|
94
|
-
pcbridge material patch --target
|
|
95
|
-
pcbridge template create --target
|
|
96
|
-
pcbridge template instantiate --target
|
|
97
|
-
pcbridge
|
|
98
|
-
pcbridge
|
|
99
|
-
pcbridge
|
|
100
|
-
pcbridge script
|
|
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>
|
|
101
145
|
```
|
|
102
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
|
+
|
|
103
156
|
Scene, store, and viewport:
|
|
104
157
|
|
|
105
158
|
```bash
|
|
106
|
-
pcbridge scene settings get --target
|
|
107
|
-
pcbridge scene settings patch --target
|
|
108
|
-
pcbridge store search --target
|
|
109
|
-
pcbridge store get --target
|
|
110
|
-
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
|
|
111
164
|
```
|
|
112
165
|
|
|
113
166
|
Capture the viewport:
|
|
114
167
|
|
|
115
168
|
```bash
|
|
116
|
-
pcbridge viewport capture --target
|
|
169
|
+
pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas-viewport.png
|
|
117
170
|
```
|
|
118
171
|
|
|
119
172
|
Launch runtime debugging:
|
|
120
173
|
|
|
121
174
|
```bash
|
|
122
|
-
pcbridge
|
|
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 }"
|
|
123
178
|
pcbridge viewport capture --target launch:<sceneId> --out ./tmp/launch.png
|
|
124
179
|
pcbridge logs get --target launch:<sceneId> --limit 100
|
|
125
180
|
pcbridge logs get --target launch:<sceneId> --level error
|
|
126
181
|
```
|
|
127
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
|
+
|
|
128
194
|
## Asset Organization
|
|
129
195
|
|
|
130
|
-
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:
|
|
131
198
|
|
|
132
199
|
```text
|
|
133
200
|
AI Agent Bridge/<task name>/Textures
|
|
@@ -141,13 +208,14 @@ Use stable names that describe the asset purpose. Avoid dumping generated files
|
|
|
141
208
|
|
|
142
209
|
For multi-asset or game-sized tasks:
|
|
143
210
|
|
|
144
|
-
1. Choose an explicit target from `pcbridge targets`, preferably `
|
|
145
|
-
|
|
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>/`.
|
|
146
214
|
3. Put PlayCanvas assets under `AI Agent Bridge/<task name>/{Textures,Materials,Scripts,Templates}`.
|
|
147
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.
|
|
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
|
|
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/`.
|
|
151
219
|
|
|
152
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.
|
|
153
221
|
|
|
@@ -157,18 +225,25 @@ Do not pre-place runtime-generated content just to prove a game exists. For rogu
|
|
|
157
225
|
|
|
158
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.
|
|
159
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
|
+
|
|
160
235
|
## Texture Box Pattern
|
|
161
236
|
|
|
162
237
|
For a textured scripted box, compose structured commands instead of writing one large eval:
|
|
163
238
|
|
|
164
239
|
```bash
|
|
165
|
-
pcbridge asset folder ensure --target
|
|
166
|
-
pcbridge asset upload --target
|
|
167
|
-
pcbridge material create --target
|
|
168
|
-
pcbridge script create --target
|
|
169
|
-
pcbridge entity create --target
|
|
170
|
-
pcbridge entity set-material --target
|
|
171
|
-
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}'
|
|
172
247
|
```
|
|
173
248
|
|
|
174
249
|
## Eval Snippet Rules
|
|
@@ -179,12 +254,17 @@ The snippet runs inside an async function with these bindings:
|
|
|
179
254
|
editor;
|
|
180
255
|
pc;
|
|
181
256
|
pcui;
|
|
257
|
+
runtimeApp;
|
|
182
258
|
window;
|
|
183
259
|
document;
|
|
184
260
|
command;
|
|
185
261
|
serialize;
|
|
186
262
|
```
|
|
187
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
|
+
|
|
188
268
|
Prefer:
|
|
189
269
|
|
|
190
270
|
```js
|
|
@@ -14,46 +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.
|
|
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>`.
|
|
18
25
|
|
|
19
26
|
For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
|
|
20
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.
|
|
21
30
|
|
|
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`.
|
|
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`.
|
|
23
32
|
|
|
24
33
|
Use structured commands for small, known Editor operations:
|
|
25
34
|
|
|
26
35
|
```bash
|
|
27
|
-
pcbridge entity list --target
|
|
28
|
-
pcbridge entity patch --target
|
|
29
|
-
pcbridge entity duplicate --target
|
|
30
|
-
pcbridge entity reparent --target
|
|
31
|
-
pcbridge entity set-material --target
|
|
32
|
-
pcbridge entity add-script --target
|
|
33
|
-
pcbridge
|
|
34
|
-
pcbridge asset
|
|
35
|
-
pcbridge asset
|
|
36
|
-
pcbridge asset
|
|
37
|
-
pcbridge asset upload
|
|
38
|
-
pcbridge
|
|
39
|
-
pcbridge
|
|
40
|
-
pcbridge template
|
|
41
|
-
pcbridge
|
|
42
|
-
pcbridge
|
|
43
|
-
pcbridge
|
|
44
|
-
pcbridge
|
|
45
|
-
pcbridge
|
|
46
|
-
pcbridge viewport
|
|
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
|
|
47
60
|
pcbridge logs get --target launch:<sceneId> --limit 100
|
|
48
61
|
pcbridge logs get --target launch:<sceneId> --level error
|
|
49
62
|
```
|
|
50
63
|
|
|
51
64
|
Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
|
|
52
65
|
|
|
53
|
-
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.
|
|
54
73
|
|
|
55
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.
|
|
56
75
|
|
|
57
|
-
|
|
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.
|
|
58
85
|
|
|
59
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.
|
|
@@ -10,47 +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.
|
|
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.
|
|
14
20
|
|
|
15
21
|
For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
|
|
16
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.
|
|
17
25
|
|
|
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`.
|
|
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`.
|
|
19
27
|
|
|
20
28
|
Use structured commands for small, known Editor operations:
|
|
21
29
|
|
|
22
30
|
```bash
|
|
23
|
-
pcbridge entity list --target
|
|
24
|
-
pcbridge entity create --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 asset upload
|
|
35
|
-
pcbridge
|
|
36
|
-
pcbridge
|
|
37
|
-
pcbridge template
|
|
38
|
-
pcbridge
|
|
39
|
-
pcbridge
|
|
40
|
-
pcbridge
|
|
41
|
-
pcbridge
|
|
42
|
-
pcbridge
|
|
43
|
-
pcbridge viewport
|
|
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
|
|
44
56
|
pcbridge logs get --target launch:<sceneId> --limit 100
|
|
45
57
|
pcbridge logs get --target launch:<sceneId> --level error
|
|
46
58
|
```
|
|
47
59
|
|
|
48
60
|
Put generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`.
|
|
49
61
|
|
|
50
|
-
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.
|
|
51
68
|
|
|
52
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.
|
|
53
70
|
|
|
54
|
-
|
|
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.
|
|
55
80
|
|
|
56
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.
|