playcanvas-agent-bridge-cli 0.2.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,162 @@
1
+ # playcanvas-agent-bridge-cli
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.
4
+
5
+ The core interface is the `pcbridge` command plus a local daemon and a Chrome Manifest V3 extension. MCP is intentionally not required.
6
+
7
+ ## Install
8
+
9
+ When published to npm:
10
+
11
+ ```bash
12
+ npm install -g playcanvas-agent-bridge-cli
13
+ pcbridge install-skill --agent all
14
+ ```
15
+
16
+ From this GitHub repository before npm publishing:
17
+
18
+ ```bash
19
+ npm install -g github:Q-My99/playcanvas-agent-bridge-cli
20
+ pcbridge install-skill --agent all
21
+ ```
22
+
23
+ One-shot with npx:
24
+
25
+ ```bash
26
+ npx github:Q-My99/playcanvas-agent-bridge-cli doctor
27
+ npx github:Q-My99/playcanvas-agent-bridge-cli install-skill --agent all
28
+ ```
29
+
30
+ ## Install the Chrome extension
31
+
32
+ Run:
33
+
34
+ ```bash
35
+ pcbridge install-extension
36
+ ```
37
+
38
+ The command generates a local unpacked extension directory at:
39
+
40
+ ```text
41
+ ~/.pcbridge/extension
42
+ ```
43
+
44
+ On Windows this path is under your user home directory. The path printed by
45
+ `pcbridge install-extension` is the source of truth.
46
+
47
+ Then in Chrome:
48
+
49
+ 1. Open `chrome://extensions`.
50
+ 2. Enable Developer Mode.
51
+ 3. Click Load unpacked.
52
+ 4. Select the exact directory printed by `pcbridge install-extension`.
53
+ 5. Open or refresh a PlayCanvas Editor page.
54
+
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
+
57
+ ## Start the bridge
58
+
59
+ ```bash
60
+ pcbridge daemon start
61
+ ```
62
+
63
+ In another terminal:
64
+
65
+ ```bash
66
+ pcbridge doctor
67
+ pcbridge targets
68
+ pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor }"
69
+ ```
70
+
71
+ ## Common commands
72
+
73
+ ```bash
74
+ pcbridge entity list --target current --limit 50
75
+ pcbridge entity create --target current --json ./entity.json
76
+ pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
77
+ pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
78
+ pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
79
+ pcbridge entity delete --target current --id <resource_id>
80
+
81
+ pcbridge asset list --target current --type script
82
+ pcbridge asset get --target current --id <asset_id>
83
+ pcbridge asset folder ensure --target current --path "AI Agent Bridge/Demo/Textures"
84
+ pcbridge asset upload --target current --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
85
+ pcbridge asset delete --target current --id <asset_id>
86
+
87
+ pcbridge material create --target current --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
88
+
89
+ pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
90
+ pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js
91
+ pcbridge script parse --target current --asset-id <asset_id>
92
+
93
+ pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
94
+ ```
95
+
96
+ ## Texture + material + script workflow
97
+
98
+ ```bash
99
+ pcbridge asset folder ensure --target current --path "AI Agent Bridge/Texture Box/Textures"
100
+ pcbridge asset upload --target current --file ./cat.png --name CatTexture --folder "AI Agent Bridge/Texture Box/Textures"
101
+
102
+ pcbridge material create --target current --name CatMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
103
+
104
+ pcbridge script create --target current --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
105
+
106
+ pcbridge entity create --target current --json ./box.json
107
+ pcbridge entity set-material --target current --id <box_resource_id> --material-id <material_asset_id>
108
+ pcbridge entity add-script --target current --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
109
+ ```
110
+
111
+ ## Target selection
112
+
113
+ ```bash
114
+ pcbridge targets
115
+ pcbridge eval --target current --code "return location.href"
116
+ pcbridge eval --target tab:123 --code "return location.href"
117
+ pcbridge eval --target scene:987654 --code "return location.href"
118
+ pcbridge eval --target project:123456 --code "return location.href"
119
+ ```
120
+
121
+ `current` means the most recently seen ready PlayCanvas Editor target.
122
+
123
+ ## Agent skills
124
+
125
+ Install rules/skills for common agents:
126
+
127
+ ```bash
128
+ pcbridge install-skill --agent codex
129
+ pcbridge install-skill --agent claude
130
+ pcbridge install-skill --agent cursor
131
+ pcbridge install-skill --agent windsurf
132
+ pcbridge install-skill --agent all
133
+ ```
134
+
135
+ Installed locations:
136
+
137
+ - Codex: `~/.codex/skills/playcanvas-agent-bridge-cli`
138
+ - Claude: `~/.claude/skills/playcanvas-agent-bridge-cli`
139
+ - Cursor: `~/.cursor/rules/playcanvas-agent-bridge-cli.mdc`
140
+ - Windsurf: `~/.windsurf/rules/playcanvas-agent-bridge-cli.md`
141
+
142
+ ## Security model
143
+
144
+ This is a local trusted developer tool. It executes JavaScript inside PlayCanvas Editor pages that you already have open.
145
+
146
+ Safeguards:
147
+
148
+ - daemon binds only to `127.0.0.1`;
149
+ - CLI, daemon, and extension share a local session token;
150
+ - extension matches only PlayCanvas Editor URLs;
151
+ - CLI output uses compact JSON envelopes;
152
+ - structured write commands require explicit IDs or JSON files.
153
+
154
+ ## Development
155
+
156
+ ```bash
157
+ pnpm install
158
+ pnpm build
159
+ node dist/cli.js doctor
160
+ ```
161
+
162
+ Use `bun` for one-off TypeScript scripts if you add them.
@@ -0,0 +1,162 @@
1
+ # playcanvas-agent-bridge-cli
2
+
3
+ 这是一个 CLI 优先的本地自动化桥,用来让 Codex、Claude Code、Cursor、Windsurf 等 AI 编程 agent 控制已经打开的 PlayCanvas Editor 场景。
4
+
5
+ 核心接口是 `pcbridge` 命令、本地 daemon 和 Chrome Manifest V3 插件。MCP 不是核心依赖,之后可以作为薄适配层再加。
6
+
7
+ ## 安装
8
+
9
+ 发布到 npm 后:
10
+
11
+ ```bash
12
+ npm install -g playcanvas-agent-bridge-cli
13
+ pcbridge install-skill --agent all
14
+ ```
15
+
16
+ 在 npm 发布前,也可以直接从这个 GitHub 仓库安装:
17
+
18
+ ```bash
19
+ npm install -g github:Q-My99/playcanvas-agent-bridge-cli
20
+ pcbridge install-skill --agent all
21
+ ```
22
+
23
+ 用 npx 一次性运行:
24
+
25
+ ```bash
26
+ npx github:Q-My99/playcanvas-agent-bridge-cli doctor
27
+ npx github:Q-My99/playcanvas-agent-bridge-cli install-skill --agent all
28
+ ```
29
+
30
+ ## 安装 Chrome 插件
31
+
32
+ 运行:
33
+
34
+ ```bash
35
+ pcbridge install-extension
36
+ ```
37
+
38
+ 这个命令会生成一个本地可加载插件目录:
39
+
40
+ ```text
41
+ ~/.pcbridge/extension
42
+ ```
43
+
44
+ 在 Windows 上,这个目录会位于你的用户主目录下。请以
45
+ `pcbridge install-extension` 实际打印出来的路径为准。
46
+
47
+ 然后在 Chrome 中操作:
48
+
49
+ 1. 打开 `chrome://extensions`。
50
+ 2. 开启 Developer Mode。
51
+ 3. 点击 Load unpacked。
52
+ 4. 选择 `pcbridge install-extension` 打印出来的那个目录。
53
+ 5. 打开或刷新 PlayCanvas Editor 页面。
54
+
55
+ 注意:生成目录里的 `config.json` 包含本地 session token。请加载 `~/.pcbridge/extension`,不要直接加载仓库里的原始 `extension/` 目录。
56
+
57
+ ## 启动桥接
58
+
59
+ ```bash
60
+ pcbridge daemon start
61
+ ```
62
+
63
+ 另开一个终端检查:
64
+
65
+ ```bash
66
+ pcbridge doctor
67
+ pcbridge targets
68
+ pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor }"
69
+ ```
70
+
71
+ ## 常用命令
72
+
73
+ ```bash
74
+ pcbridge entity list --target current --limit 50
75
+ pcbridge entity create --target current --json ./entity.json
76
+ pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
77
+ pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
78
+ pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
79
+ pcbridge entity delete --target current --id <resource_id>
80
+
81
+ pcbridge asset list --target current --type script
82
+ pcbridge asset get --target current --id <asset_id>
83
+ pcbridge asset folder ensure --target current --path "AI Agent Bridge/Demo/Textures"
84
+ pcbridge asset upload --target current --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
85
+ pcbridge asset delete --target current --id <asset_id>
86
+
87
+ pcbridge material create --target current --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
88
+
89
+ pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
90
+ pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js
91
+ pcbridge script parse --target current --asset-id <asset_id>
92
+
93
+ pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
94
+ ```
95
+
96
+ ## 贴图 + 材质 + 脚本工作流
97
+
98
+ ```bash
99
+ pcbridge asset folder ensure --target current --path "AI Agent Bridge/Texture Box/Textures"
100
+ pcbridge asset upload --target current --file ./cat.png --name CatTexture --folder "AI Agent Bridge/Texture Box/Textures"
101
+
102
+ pcbridge material create --target current --name CatMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
103
+
104
+ pcbridge script create --target current --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
105
+
106
+ pcbridge entity create --target current --json ./box.json
107
+ pcbridge entity set-material --target current --id <box_resource_id> --material-id <material_asset_id>
108
+ pcbridge entity add-script --target current --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
109
+ ```
110
+
111
+ ## 目标选择
112
+
113
+ ```bash
114
+ pcbridge targets
115
+ pcbridge eval --target current --code "return location.href"
116
+ pcbridge eval --target tab:123 --code "return location.href"
117
+ pcbridge eval --target scene:987654 --code "return location.href"
118
+ pcbridge eval --target project:123456 --code "return location.href"
119
+ ```
120
+
121
+ `current` 表示最近可用的 PlayCanvas Editor 目标页。
122
+
123
+ ## Agent skill / rules
124
+
125
+ 安装各家 agent 的使用说明:
126
+
127
+ ```bash
128
+ pcbridge install-skill --agent codex
129
+ pcbridge install-skill --agent claude
130
+ pcbridge install-skill --agent cursor
131
+ pcbridge install-skill --agent windsurf
132
+ pcbridge install-skill --agent all
133
+ ```
134
+
135
+ 安装位置:
136
+
137
+ - Codex: `~/.codex/skills/playcanvas-agent-bridge-cli`
138
+ - Claude: `~/.claude/skills/playcanvas-agent-bridge-cli`
139
+ - Cursor: `~/.cursor/rules/playcanvas-agent-bridge-cli.mdc`
140
+ - Windsurf: `~/.windsurf/rules/playcanvas-agent-bridge-cli.md`
141
+
142
+ ## 安全模型
143
+
144
+ 这是一个本地可信开发工具,会在你已经打开的 PlayCanvas Editor 页面内执行 JavaScript。
145
+
146
+ 基础防护:
147
+
148
+ - daemon 只绑定 `127.0.0.1`;
149
+ - CLI、daemon、插件共享本地 session token;
150
+ - 插件只匹配 PlayCanvas Editor URL;
151
+ - CLI 输出统一使用紧凑 JSON envelope;
152
+ - 结构化写命令要求明确 ID 或 JSON 文件。
153
+
154
+ ## 开发
155
+
156
+ ```bash
157
+ pnpm install
158
+ pnpm build
159
+ node dist/cli.js doctor
160
+ ```
161
+
162
+ 如果以后添加一次性 TypeScript 脚本,优先用 `bun` 执行。