playcanvas-agent-bridge-cli 0.2.1 → 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 CHANGED
@@ -1,6 +1,6 @@
1
1
  # playcanvas-agent-bridge-cli
2
2
 
3
- CLI-first local automation for controlling an already-open PlayCanvas Editor scene from AI coding agents such as Codex, Claude Code, Cursor, and Windsurf.
3
+ CLI-first local automation for controlling already-open PlayCanvas Editor scenes and PlayCanvas Launch pages from AI coding agents such as Codex, Claude Code, Cursor, and Windsurf.
4
4
 
5
5
  The core interface is the `pcbridge` command plus a local daemon and a Chrome Manifest V3 extension. MCP is intentionally not required.
6
6
 
@@ -50,10 +50,38 @@ Then in Chrome:
50
50
  2. Enable Developer Mode.
51
51
  3. Click Load unpacked.
52
52
  4. Select the exact directory printed by `pcbridge install-extension`.
53
- 5. Open or refresh a PlayCanvas Editor page.
53
+ 5. Open or refresh a PlayCanvas Editor page or a PlayCanvas Launch page.
54
54
 
55
55
  The generated extension directory contains a local session token in `config.json`, so load that generated directory rather than the raw `extension/` folder from the repo.
56
56
 
57
+ ## Use the custom Editor frontend
58
+
59
+ The Editor build is not bundled in the npm package. Download the latest published build from
60
+ `Q-My99/playcanvas-editor`, verify its release metadata and SHA-256, then activate it locally:
61
+
62
+ ```bash
63
+ pcbridge frontend install latest
64
+ pcbridge frontend status
65
+ pcbridge daemon start
66
+ ```
67
+
68
+ The daemon serves the active build from `http://localhost:3487`. On a
69
+ `https://playcanvas.com/editor/...` tab, open the extension popup and choose **Use custom
70
+ frontend**. Choose **Use official frontend** to remove `use_local_frontend` and reload the same
71
+ Editor URL with the official frontend.
72
+
73
+ Manage installed releases explicitly when needed:
74
+
75
+ ```bash
76
+ pcbridge frontend list
77
+ pcbridge frontend update
78
+ pcbridge frontend use playcanvas-editor-v2.28.1-r1
79
+ pcbridge frontend remove playcanvas-editor-v2.28.1-r1
80
+ ```
81
+
82
+ Downloaded builds live under `~/.pcbridge/frontends/`. Removing the active release is refused
83
+ until another installed release is selected.
84
+
57
85
  ## Start the bridge
58
86
 
59
87
  ```bash
@@ -66,31 +94,103 @@ In another terminal:
66
94
  pcbridge doctor
67
95
  pcbridge targets
68
96
  pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor }"
97
+ pcbridge eval --target launch:<sceneId> --code "return { href: location.href, hasPc: !!pc }"
69
98
  ```
70
99
 
100
+ ## Progressive help
101
+
102
+ The CLI exposes layered help so agents can load only the command surface they need:
103
+
104
+ ```bash
105
+ pcbridge help
106
+ pcbridge help frontend
107
+ pcbridge help entity
108
+ pcbridge help asset
109
+ pcbridge help material
110
+ pcbridge help template
111
+ pcbridge help script
112
+ pcbridge help scene
113
+ pcbridge help store
114
+ pcbridge help viewport
115
+ pcbridge help launch
116
+ pcbridge help logs
117
+ pcbridge help eval
118
+ ```
119
+
120
+ Use structured commands for small, known operations that map cleanly to one Editor action. Use
121
+ `pcbridge eval` for exploratory work, custom Editor/Engine API workflows, Launch debugging, and
122
+ large multi-step scene edits where one script is clearer and faster than many CLI calls.
123
+
71
124
  ## Common commands
72
125
 
73
126
  ```bash
74
127
  pcbridge entity list --target current --limit 50
128
+ pcbridge entity list --target current --tag enemy --component render
75
129
  pcbridge entity create --target current --json ./entity.json
130
+ pcbridge entity create-many --target current --json ./entities.json
76
131
  pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
132
+ pcbridge entity patch-many --target current --json ./edits.json
133
+ pcbridge entity duplicate --target current --id <resource_id>
134
+ pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
77
135
  pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
78
136
  pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
79
137
  pcbridge entity delete --target current --id <resource_id>
80
138
 
81
139
  pcbridge asset list --target current --type script
140
+ pcbridge asset list --target current --tag generated
82
141
  pcbridge asset get --target current --id <asset_id>
142
+ pcbridge asset create --target current --json ./assets.json
83
143
  pcbridge asset folder ensure --target current --path "AI Agent Bridge/Demo/Textures"
84
144
  pcbridge asset upload --target current --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
145
+ pcbridge asset upload-many --target current --json ./upload-manifest.json
146
+ pcbridge asset instantiate --target current --id <template_asset_id>
85
147
  pcbridge asset delete --target current --id <asset_id>
86
148
 
87
149
  pcbridge material create --target current --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
150
+ pcbridge material patch --target current --asset-id <asset_id> --set diffuse='[1,0,0]'
151
+
152
+ pcbridge template create --target current --entity-id <resource_id> --name DemoTemplate --folder "AI Agent Bridge/Demo/Templates"
153
+ pcbridge template instantiate --target current --id <template_asset_id>
88
154
 
89
155
  pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
156
+ pcbridge script upsert --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts" --parse
90
157
  pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js
91
158
  pcbridge script parse --target current --asset-id <asset_id>
92
159
 
160
+ pcbridge scene settings get --target current
161
+ pcbridge scene settings patch --target current --set physics.gravity='[0,-9.8,0]'
162
+
163
+ pcbridge store search --target current --search vehicle --limit 20
164
+ pcbridge store get --target current --id <store_asset_id>
165
+ pcbridge store download --target current --id <store_asset_id> --name Vehicle --license-json ./license.json
166
+
93
167
  pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
168
+ pcbridge viewport focus --target current --id <resource_id> --view perspective
169
+
170
+ pcbridge logs get --target current --limit 100
171
+ pcbridge logs get --target launch:<sceneId> --level error
172
+ pcbridge logs clear --target current
173
+ ```
174
+
175
+ For task-sized installs, keep upload manifests next to the generated files. Relative `file` paths are resolved from the manifest location:
176
+
177
+ ```json
178
+ {
179
+ "assets": [
180
+ {
181
+ "key": "player",
182
+ "file": "final/player.png",
183
+ "name": "DemoPlayer",
184
+ "folder": "AI Agent Bridge/Demo/Textures"
185
+ }
186
+ ]
187
+ }
188
+ ```
189
+
190
+ Use `eval --args-json` when a large Editor script needs local configuration without embedding JSON into source:
191
+
192
+ ```bash
193
+ pcbridge eval --target current --file ./install-scene.js --args-json ./install-args.json
94
194
  ```
95
195
 
96
196
  ## Texture + material + script workflow
@@ -116,9 +216,15 @@ pcbridge eval --target current --code "return location.href"
116
216
  pcbridge eval --target tab:123 --code "return location.href"
117
217
  pcbridge eval --target scene:987654 --code "return location.href"
118
218
  pcbridge eval --target project:123456 --code "return location.href"
219
+ pcbridge eval --target launch:987654 --code "return { href: location.href, hasPc: !!pc }"
220
+ pcbridge viewport capture --target launch:987654 --out ./tmp/launch.png
221
+ pcbridge logs get --target launch:987654 --limit 100
119
222
  ```
120
223
 
121
- `current` means the most recently seen ready PlayCanvas Editor target.
224
+ `current` means the most recently seen ready PlayCanvas target. If both the Editor and Launch page
225
+ are open for the same scene, use `tab:<id>`, `editor:<sceneId>`, or `launch:<sceneId>` to avoid
226
+ ambiguity. Editor-only structured commands require an Editor target; `eval`, `viewport capture`,
227
+ and `logs` also work on Launch targets.
122
228
 
123
229
  ## Agent skills
124
230
 
@@ -141,13 +247,15 @@ Installed locations:
141
247
 
142
248
  ## Security model
143
249
 
144
- This is a local trusted developer tool. It executes JavaScript inside PlayCanvas Editor pages that you already have open.
250
+ This is a local trusted developer tool. It executes JavaScript inside PlayCanvas Editor and Launch pages that you already have open.
145
251
 
146
252
  Safeguards:
147
253
 
148
254
  - daemon binds only to `127.0.0.1`;
255
+ - the frontend server binds only to `127.0.0.1`, validates the Host header, and serves only files
256
+ under the active verified release;
149
257
  - CLI, daemon, and extension share a local session token;
150
- - extension matches only PlayCanvas Editor URLs;
258
+ - extension matches only PlayCanvas Editor and Launch URLs;
151
259
  - CLI output uses compact JSON envelopes;
152
260
  - structured write commands require explicit IDs or JSON files.
153
261
 
@@ -160,3 +268,22 @@ node dist/cli.js doctor
160
268
  ```
161
269
 
162
270
  Use `bun` for one-off TypeScript scripts if you add them.
271
+
272
+ ## Publishing to npm (maintainers)
273
+
274
+ Publishing uses npm Trusted Publishing through `.github/workflows/npm-publish.yml`; the GitHub
275
+ repository does not need an `NPM_TOKEN` secret.
276
+
277
+ 1. Update the same stable version in `package.json`, `src/config.ts`, and
278
+ `extension/manifest.json`.
279
+ 2. Run `pnpm test`, commit the release to `main`, and push `main`.
280
+ 3. Create and push the matching tag, for example:
281
+
282
+ ```bash
283
+ git tag v0.3.0
284
+ git push origin v0.3.0
285
+ ```
286
+
287
+ The workflow rejects tags that do not match the package version or whose commit is not on `main`.
288
+ Configure the npm package's Trusted Publisher with GitHub user `Q-My99`, repository
289
+ `playcanvas-agent-bridge-cli`, and workflow filename `npm-publish.yml` before pushing the tag.
package/README.zh-CN.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # playcanvas-agent-bridge-cli
2
2
 
3
- 这是一个 CLI 优先的本地自动化桥,用来让 Codex、Claude Code、Cursor、Windsurf 等 AI 编程 agent 控制已经打开的 PlayCanvas Editor 场景。
3
+ 这是一个 CLI 优先的本地自动化桥,用来让 Codex、Claude Code、Cursor、Windsurf 等 AI 编程 agent 控制已经打开的 PlayCanvas Editor 场景和 PlayCanvas Launch 页面。
4
4
 
5
5
  核心接口是 `pcbridge` 命令、本地 daemon 和 Chrome Manifest V3 插件。MCP 不是核心依赖,之后可以作为薄适配层再加。
6
6
 
@@ -50,10 +50,38 @@ pcbridge install-extension
50
50
  2. 开启 Developer Mode。
51
51
  3. 点击 Load unpacked。
52
52
  4. 选择 `pcbridge install-extension` 打印出来的那个目录。
53
- 5. 打开或刷新 PlayCanvas Editor 页面。
53
+ 5. 打开或刷新 PlayCanvas Editor 页面或 PlayCanvas Launch 页面。
54
54
 
55
55
  注意:生成目录里的 `config.json` 包含本地 session token。请加载 `~/.pcbridge/extension`,不要直接加载仓库里的原始 `extension/` 目录。
56
56
 
57
+ ## 使用自构建 Editor 前端
58
+
59
+ Editor 构建产物不会打进 npm 包。下面的命令会从 `Q-My99/playcanvas-editor` 下载最新
60
+ Release,校验发布清单、文件大小和 SHA-256,然后在本地激活:
61
+
62
+ ```bash
63
+ pcbridge frontend install latest
64
+ pcbridge frontend status
65
+ pcbridge daemon start
66
+ ```
67
+
68
+ daemon 会在 `http://localhost:3487` 提供当前激活的构建。打开
69
+ `https://playcanvas.com/editor/...` 页面后,在插件 popup 中点击 **Use custom frontend**。
70
+ 点击 **Use official frontend** 会删除 `use_local_frontend` 参数,并用官方前端重新加载同一个
71
+ Editor URL。
72
+
73
+ 需要时可以显式管理本地版本:
74
+
75
+ ```bash
76
+ pcbridge frontend list
77
+ pcbridge frontend update
78
+ pcbridge frontend use playcanvas-editor-v2.28.1-r1
79
+ pcbridge frontend remove playcanvas-editor-v2.28.1-r1
80
+ ```
81
+
82
+ 下载的构建保存在 `~/.pcbridge/frontends/`。当前激活的版本不能直接删除,需要先切换到
83
+ 另一个已安装版本。
84
+
57
85
  ## 启动桥接
58
86
 
59
87
  ```bash
@@ -66,31 +94,102 @@ pcbridge daemon start
66
94
  pcbridge doctor
67
95
  pcbridge targets
68
96
  pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor }"
97
+ pcbridge eval --target launch:<sceneId> --code "return { href: location.href, hasPc: !!pc }"
69
98
  ```
70
99
 
100
+ ## 渐进式 help
101
+
102
+ CLI 提供分层 help,方便 agent 只加载当前需要的命令面:
103
+
104
+ ```bash
105
+ pcbridge help
106
+ pcbridge help frontend
107
+ pcbridge help entity
108
+ pcbridge help asset
109
+ pcbridge help material
110
+ pcbridge help template
111
+ pcbridge help script
112
+ pcbridge help scene
113
+ pcbridge help store
114
+ pcbridge help viewport
115
+ pcbridge help launch
116
+ pcbridge help logs
117
+ pcbridge help eval
118
+ ```
119
+
120
+ 小而明确、能对应到单个 Editor 操作的任务优先用结构化命令。探索 API、自定义
121
+ Editor/Engine 工作流、Launch 调试、大量多步骤场景修改,则优先用 `pcbridge eval`,一段脚本通常更清楚也更快。
122
+
71
123
  ## 常用命令
72
124
 
73
125
  ```bash
74
126
  pcbridge entity list --target current --limit 50
127
+ pcbridge entity list --target current --tag enemy --component render
75
128
  pcbridge entity create --target current --json ./entity.json
129
+ pcbridge entity create-many --target current --json ./entities.json
76
130
  pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
131
+ pcbridge entity patch-many --target current --json ./edits.json
132
+ pcbridge entity duplicate --target current --id <resource_id>
133
+ pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
77
134
  pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
78
135
  pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
79
136
  pcbridge entity delete --target current --id <resource_id>
80
137
 
81
138
  pcbridge asset list --target current --type script
139
+ pcbridge asset list --target current --tag generated
82
140
  pcbridge asset get --target current --id <asset_id>
141
+ pcbridge asset create --target current --json ./assets.json
83
142
  pcbridge asset folder ensure --target current --path "AI Agent Bridge/Demo/Textures"
84
143
  pcbridge asset upload --target current --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
144
+ pcbridge asset upload-many --target current --json ./upload-manifest.json
145
+ pcbridge asset instantiate --target current --id <template_asset_id>
85
146
  pcbridge asset delete --target current --id <asset_id>
86
147
 
87
148
  pcbridge material create --target current --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
149
+ pcbridge material patch --target current --asset-id <asset_id> --set diffuse='[1,0,0]'
150
+
151
+ pcbridge template create --target current --entity-id <resource_id> --name DemoTemplate --folder "AI Agent Bridge/Demo/Templates"
152
+ pcbridge template instantiate --target current --id <template_asset_id>
88
153
 
89
154
  pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
155
+ pcbridge script upsert --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts" --parse
90
156
  pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js
91
157
  pcbridge script parse --target current --asset-id <asset_id>
92
158
 
159
+ pcbridge scene settings get --target current
160
+ pcbridge scene settings patch --target current --set physics.gravity='[0,-9.8,0]'
161
+
162
+ pcbridge store search --target current --search vehicle --limit 20
163
+ pcbridge store get --target current --id <store_asset_id>
164
+ pcbridge store download --target current --id <store_asset_id> --name Vehicle --license-json ./license.json
165
+
93
166
  pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
167
+ pcbridge viewport focus --target current --id <resource_id> --view perspective
168
+
169
+ pcbridge logs get --target current --limit 100
170
+ pcbridge logs get --target launch:<sceneId> --level error
171
+ pcbridge logs clear --target current
172
+ ```
173
+
174
+ 大型任务可以把上传清单放在生成文件旁边。`file` 的相对路径会按清单文件所在目录解析:
175
+
176
+ ```json
177
+ {
178
+ "assets": [
179
+ {
180
+ "key": "player",
181
+ "file": "final/player.png",
182
+ "name": "DemoPlayer",
183
+ "folder": "AI Agent Bridge/Demo/Textures"
184
+ }
185
+ ]
186
+ }
187
+ ```
188
+
189
+ 当较大的 Editor 脚本需要本地配置时,用 `eval --args-json`,避免把 JSON 直接拼进代码里:
190
+
191
+ ```bash
192
+ pcbridge eval --target current --file ./install-scene.js --args-json ./install-args.json
94
193
  ```
95
194
 
96
195
  ## 贴图 + 材质 + 脚本工作流
@@ -116,9 +215,14 @@ pcbridge eval --target current --code "return location.href"
116
215
  pcbridge eval --target tab:123 --code "return location.href"
117
216
  pcbridge eval --target scene:987654 --code "return location.href"
118
217
  pcbridge eval --target project:123456 --code "return location.href"
218
+ pcbridge eval --target launch:987654 --code "return { href: location.href, hasPc: !!pc }"
219
+ pcbridge viewport capture --target launch:987654 --out ./tmp/launch.png
220
+ pcbridge logs get --target launch:987654 --limit 100
119
221
  ```
120
222
 
121
- `current` 表示最近可用的 PlayCanvas Editor 目标页。
223
+ `current` 表示最近可用的 PlayCanvas 目标页。如果同一个 scene 同时打开了 Editor 和 Launch
224
+ 页面,请使用 `tab:<id>`、`editor:<sceneId>` 或 `launch:<sceneId>` 避免歧义。结构化编辑命令需要
225
+ Editor 目标;`eval`、`viewport capture` 和 `logs` 也可以用于 Launch 目标。
122
226
 
123
227
  ## Agent skill / rules
124
228
 
@@ -141,13 +245,14 @@ pcbridge install-skill --agent all
141
245
 
142
246
  ## 安全模型
143
247
 
144
- 这是一个本地可信开发工具,会在你已经打开的 PlayCanvas Editor 页面内执行 JavaScript。
248
+ 这是一个本地可信开发工具,会在你已经打开的 PlayCanvas Editor 和 Launch 页面内执行 JavaScript。
145
249
 
146
250
  基础防护:
147
251
 
148
252
  - daemon 只绑定 `127.0.0.1`;
253
+ - frontend 服务只绑定 `127.0.0.1`,会校验 Host,并且只提供当前已校验 Release 目录内的文件;
149
254
  - CLI、daemon、插件共享本地 session token;
150
- - 插件只匹配 PlayCanvas Editor URL;
255
+ - 插件只匹配 PlayCanvas Editor 和 Launch URL;
151
256
  - CLI 输出统一使用紧凑 JSON envelope;
152
257
  - 结构化写命令要求明确 ID 或 JSON 文件。
153
258
 
@@ -160,3 +265,21 @@ node dist/cli.js doctor
160
265
  ```
161
266
 
162
267
  如果以后添加一次性 TypeScript 脚本,优先用 `bun` 执行。
268
+
269
+ ## 发布到 npm(维护者)
270
+
271
+ 发布流程通过 `.github/workflows/npm-publish.yml` 使用 npm Trusted Publishing,GitHub
272
+ 仓库不需要保存 `NPM_TOKEN`。
273
+
274
+ 1. 在 `package.json`、`src/config.ts` 和 `extension/manifest.json` 中同步更新同一个稳定版本号。
275
+ 2. 运行 `pnpm test`,把发布提交合并并推送到 `main`。
276
+ 3. 创建并推送匹配的 tag,例如:
277
+
278
+ ```bash
279
+ git tag v0.3.0
280
+ git push origin v0.3.0
281
+ ```
282
+
283
+ 如果 tag 与包版本不一致,或者 tag 对应的提交不属于 `main`,workflow 会拒绝发布。
284
+ 推送 tag 前,需要在 npm 包设置中把 GitHub 用户设为 `Q-My99`、仓库设为
285
+ `playcanvas-agent-bridge-cli`、workflow 文件名设为 `npm-publish.yml`。