cortico-world-buckshot 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.1
+
+- 中英双语 README 与市场简介(`cortico.locales`),写清安装前准备(游戏版本、植入资源包、存档、多人需要 Steam);原 README 的实现与验证说明挪到 `docs/internals.md`;新增图标;补 `cortico.tags`、`author`、`bugs`。
+  Bilingual README and market descriptions (`cortico.locales`) with a before-you-install section (game build, implant pack, save data, Steam for multiplayer); the old README's implementation and test notes moved to `docs/internals.md`; new icon; `cortico.tags`, `author` and `bugs` added.
+- WebUI 恶魔轮盘页加「本地加入」:游戏在多人大厅建好房间后，在本机再开一个游戏窗口进这个房间，操作员和 bot 两人对打。新配置 `localPeer`(名字、显示器、静音),新事件 `buckshot.peer`。联网玩家可以同时在房间里;本地玩家对局中途离开时所有人回大厅。
+  The WebUI page adds Local join: once the game hosts a multiplayer lobby, a second game window on this machine joins it so the operator can play the bot. New `localPeer` settings (name, screen, mute) and a `buckshot.peer` event. Steam players can share the lobby; if the local player leaves mid-match, everyone returns to the lobby.
+
 ## 0.2.0
 
 - 适配 Cortico 0.2.0(扩展契约 world 6):浏览器界面改名 WebUI,面板源码移到 `src/webui/`,产物为 `dist/webui.js`;需要 Cortico 0.2.0 或更新版本。

package/README.md

@@ -1,44 +1,163 @@
-# `src/definition.ts`: cortico-world-buckshot
+# 恶魔轮盘 · Buckshot Roulette
 
-> 此乃直播测试验证之后的world，和其他 Persona / 非直播场景的兼容性有待测试。
+[中文](#中文) · [English](#english)
 
-Buckshot Roulette 的 Cortico World 扩展，契约版本 world 5，支持 Windows Steam v2.2.0.6。
+让 Coo 玩 Steam 版《恶魔轮盘》(Buckshot Roulette),游戏里的事推给 Coo,Coo 自己拿枪、开枪、用道具。
+Lets Coo play Buckshot Roulette on Steam: game events reach Coo, and Coo picks up the shotgun, fires and uses items itself.
 
-## 接入
+## 中文
 
-在本目录执行 `pnpm install`，从 Cortico 扩展页安装本目录，重启 Cortico。启用 World，在恶魔轮盘页的配置里将 `worlds.buckshot.executableFile` 设为原版 `Buckshot Roulette.exe`。激活不检查游戏程序；`buckshot_start` 启动游戏时校验。
+装填、开枪、道具、生命计数和字幕实时推给 Coo,关键时刻附一张游戏截图。Coo 用工具操作桌上的目标和菜单,单人剧情、Double or Nothing 和多人房间都能玩;操作员也可以在本机再开一个游戏窗口,和 Coo 同桌对打。适合直播里让 Coo 自己玩、自己解说。
 
-启动校验整个程序的 SHA-256；其他版本拒绝植入。构造和扩展检查不需要游戏文件。
+此乃直播测试验证之后的 World,是 CortiV 直播里用过的参考实现,和其他 Persona、非直播场景的兼容性有待测试。
 
-## 资源植入与存档
+### 功能
 
-`src/implant.ts` 读取程序尾部的 Godot PCK v2，生成本机启动资源包。桥脚本先加载原程序资源，脚本观察点记录已经呈现的装填、射击、道具、弹药揭示、生命显示、复苏、字幕和结算。交互调用原版按钮及交互入口，游戏执行权限、动画、随机数和存档逻辑。
+- 启动和关闭游戏(`buckshot_start`、`buckshot_close`)。启动时校验游戏版本,生成植入资源包,原游戏文件不改。
+- 读当前状态:场景、可操作的目标、生命、道具、本次装填公开的实弹与空包数、已退出和已揭示的弹药(`buckshot_observe`)。
+- 操作桌上的目标和菜单:拿枪、选择朝谁开枪、拿道具、用道具、签名、开箱领奖、加倍或收款、改设置(`buckshot_act`)。操作后等动画结算完才回执,回执里带这期间的枪声、道具和字幕,以及结算后的画面。
+- 发键盘、鼠标、手柄输入和游戏里定义的输入动作,填文字框或把大厅编号放进剪贴板。
+- 随时截一张游戏画面(`buckshot_glance`)。
+- 事件:装填、开枪、退弹、弹药揭示、逆转、道具使用、生命变化、除颤器复苏、字幕、新一轮、多人回合与方向、结算、胜利奖金,以及开枪、揭示、复苏、字幕和结算后的截图。
+- 只给 Coo 画面上公开的信息。未揭示的弹序、庄家的决策、其他玩家私下看到的弹药都不提供。
+- 本地加入:游戏在多人大厅建好房间后,在本机再开一个游戏窗口进这个房间,操作员用鼠标和 Coo 对打。
 
-资源包位于 `runtimeDir`，留空使用 `<deployment>/runtimes/buckshot`。程序文件不被写入，缓存按源码和游戏版本区分并校验哈希。游戏资产与还原出的脚本不随扩展分发。
+### 安装前准备
 
-每个 runtimeDir 对应 `%APPDATA%/Cortico/Buckshot/<profile>` 下的独立游戏存档。剧情通关与 Double or Nothing 解锁由游戏写入该存档。
+1. **游戏**:在 Windows 上用 Steam 购买并安装《Buckshot Roulette》。只支持 Steam Windows 版 **v2.2.0.6**:World 启动游戏时核对 `Buckshot Roulette.exe` 的大小与 SHA-256(`df2f8a31…1b1663`),对不上就拒绝启动。游戏程序在 Steam 库里右键游戏,「管理」→「浏览本地文件」打开的目录里。
+2. **植入件**:不用编译,也不用手动放文件。植入件源码是仓里的 `src/native/bridge.gd`(桥脚本)和 `src/implant.ts`(往游戏脚本里加观察点的位置)。World 第一次启动游戏时读出 exe 里的游戏资源,加上桥脚本,在本机生成启动资源包,默认放在部署目录的 `runtimes/buckshot/`,再用 `--main-pack` 让游戏加载它。游戏文件不被写入,游戏资源也不随扩展分发。
+3. **存档**:World 启动的游戏用单独的存档,在 `%APPDATA%/Cortico/Buckshot/<profile>` 下,和你平时玩的存档分开。剧情通关、解锁 Double or Nothing 都记在这份存档里。
+4. **多人**:多人房间走 Steam 大厅,需要 Steam 客户端登录在线。
 
-## 工具与直播事件
+确认装好:启用 World 后在 World 页签点「启动游戏」,状态变成「已连接」就可以了。没连上时看部署目录 `data/buckshot/game.log`。
 
-- `buckshot_start` 启动；`buckshot_close` 关闭本 World 启动的进程。
-- `buckshot_observe` 返回环境、镜头目标、画面文字、生命显示、道具、公开弹药信息和操作目标。
-- `buckshot_act` 使用目标 id 与同次观察的 revision 操作。版本或权限变化时拒绝输入。操作类工具（act、input、key、pointer、controller）不结束本轮，等游戏回到可操作状态或对局结果变化后返回（`src/settle.ts`），这期间的观察写进回执、不另发事件，回执附结算后的画面；超过 `settleTimeoutMs`（默认 30 秒）先返回，之后的变化作为事件送达。
-- `buckshot_input` 触发游戏输入动作；`buckshot_key`、`buckshot_pointer` 和 `buckshot_controller` 发送键盘、鼠标和手柄输入。
-- `buckshot_type` 填写有焦点的文字框，或写入剪贴板供游戏粘贴大厅编号。
-- `buckshot_glance` 返回游戏渲染器的 PNG，供 bot 主动查看。
+### 安装
 
-`buckshot.state` 描述场景与流程变化。`load`、`shot`、`item`、`reveal`、`ejection`、`inversion`、`health`、`revival`、`dialogue`、`round`、`turn`、`turnorder` 和 `result` 事件使用中文事实描述。环境与关键动作附带枪桌、金属器具、声音和道具意象；角色心情与未发生的结果不写入事件。字幕在完整显示后投递。
+在 Cortico 或 Coopanion 的扩展页搜 `cortico-world-buckshot` 安装,重启后在 World 总览里启用。命令行:
 
-`buckshot.frame` 附带当前渲染帧及采集时的观察。场景与操作阶段变化、开枪、弹药揭示、复苏、字幕和结算会请求截图；重叠请求合并，默认最短间隔 1500 ms。`screenshotEvents.enabled` 控制自动图像事件，`screenshotEvents.minIntervalMs` 配置间隔。主动截图独立于自动事件开关。无画面模式不支持截图。
+```bash
+cd extensions
+corepack pnpm add cortico-world-buckshot
+```
 
-`display.screenIndex` 从 0 开始选择显示器，留空由游戏选择；`display.muteAudio` 使用静音音频驱动。这两项在下次启动生效。
+启用后在恶魔轮盘页的配置里把「游戏程序」选成 `Buckshot Roulette.exe`。没配也能启用,启动游戏时才检查。
 
-未揭示的弹序、庄家决策和其他玩家的私人揭示不进入协议。损坏或遮蔽的生命显示返回未知。反转未知弹药不公布其原种类。断连与回执超时不重放输入。
+### 使用
 
-## 验证
+- **启动**:World 页签的「游戏」卡片点「启动游戏」,或者让 Coo 调用 `buckshot_start`。卡片上显示状态、场景、模式、轮次和本地玩家状态。
+- **Coo 怎么玩**:游戏连上后,Coo 收到可操作目标的变化,自己选目标操作。装填、开枪、字幕这些事件和截图到了,Coo 会接着行动或说话,说什么由 Coo 决定。
+- **看画面**:「查看画面」在卡片里显示当前游戏画面。
+- **本地加入**:先让 Coo 在多人模式里建好房间、停在大厅,再点「本地加入」。本机多开一个游戏窗口,以「本地玩家名字」进房间,你用鼠标操作。房主照常开局。点「退出本地」关掉这个窗口。
+- **关闭**:「关闭游戏」只关本 World 启动的游戏。默认 World 停止时也会关掉游戏。
 
-`pnpm test` 验证本地端口、认证、消息分段、断连、回执超时、二进制资源包、直播描述和扩展声明。`pnpm run typecheck` 检查 TypeScript；`pnpm build:web` 构建 WebUI 面板。
+### 配置
 
-`pnpm check:game <exe>` 校验安装，附加 `--launch` 可验证启动与连接；`--mute --screen=1` 选择静音和第二个显示器。`pnpm check:native <exe>` 使用无窗口游戏引擎运行自有场景，验证显示文字、权限、旧版本输入拒绝、公开弹药记录、结算和场景重置。测试套件不启动游戏或 bot。
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `worlds.buckshot.executableFile` | 空 | 游戏程序 `Buckshot Roulette.exe` 的路径 |
+| `worlds.buckshot.runtimeDir` | 空 | 植入资源包目录;留空用部署目录的 `runtimes/buckshot` |
+| `worlds.buckshot.closeOnStop` | `true` | World 停止时关闭游戏 |
+| `worlds.buckshot.settleTimeoutMs` | `30000` | 操作后等游戏回到可操作状态的最长时间;超过后先回执,之后的变化作为事件送达 |
+| `worlds.buckshot.screenshotEvents.enabled` | `true` | 关键时刻自动推截图 |
+| `worlds.buckshot.screenshotEvents.minIntervalMs` | `1500` | 自动截图最短间隔 |
+| `worlds.buckshot.display.screenIndex` | 空 | 游戏开在第几个显示器,从 0 开始;留空由游戏选 |
+| `worlds.buckshot.display.muteAudio` | `false` | 静音启动 |
+| `worlds.buckshot.localPeer.name` | `Player 2` | 本地加入时的玩家名字 |
+| `worlds.buckshot.localPeer.muteAudio` | `true` | 本地客户端静音,免得直播里声音放两遍 |
 
-真实游戏验证使用独立存档，覆盖剧情三轮、奖金结算、解锁及进入 Double or Nothing、全部九种单人道具、加倍和收款、设置开关、语言与按键重绑。多人验证覆盖本地玩家道具、四座射击、干扰器灯色、换向、自由观察、鼠标与手柄轴、死亡及三轮结算；其余玩家由禁用网络的本地模拟客户端驱动。自定义页面覆盖轮次数值、生命、右键和滚轮操作。真实 Steam 联机和邀请窗口需要在线客户端，尚未进行跨账号验收。
+显示器和静音在下次启动游戏时生效。其余见 `src/config.ts`。
+
+### 限制与常见问题
+
+- 只支持 Steam Windows 版 v2.2.0.6。Steam 更新游戏后 exe 的哈希会变,World 会拒绝启动,要等扩展适配新版本。
+- 本地玩家占一个座位,能进房间的联网玩家少一个(4 人房最多再进 2 名)。联网玩家的大厅名单里看不到本地玩家,对局里本地玩家的名字可能显示为空。本地玩家对局中途离开时,房主让所有人回到大厅。
+- 真实 Steam 跨账号联机还没验收过。Steam 邀请窗口不在游戏画面里,Coo 操作不到。
+- 事件和截图会频繁触发 Coo 的回合,token 用得快。可以关掉自动截图或调大间隔。
+
+实现、协议和验证记录见 [docs/internals.md](https://github.com/Phantivia/cortico-world-buckshot/blob/main/docs/internals.md)。
+
+## English
+
+Shell loads, shots, items, health counters and dialogue reach Coo as they happen, with a screenshot at key moments. Coo works the table targets and menus through tools and can play the story, Double or Nothing and multiplayer lobbies. The operator can also open a second game window on the same PC and sit at the table against Coo. It is meant for streams where Coo plays and commentates on its own.
+
+This World was verified on live streams. It is the reference implementation used on CortiV streams; compatibility with other Personas and non-streaming setups has not been tested.
+
+### Features
+
+- Starts and closes the game (`buckshot_start`, `buckshot_close`). Starting checks the game version and builds an implant pack; the game files are never modified.
+- Reads the current state: scene, operable targets, health, items, the live and blank counts of the current load, and the shells ejected or revealed so far (`buckshot_observe`).
+- Operates table targets and menus: pick up the shotgun, choose who to shoot, take and use items, sign the waiver, open the briefcase, double or cash out, change settings (`buckshot_act`). The reply waits until the animation settles and includes the shots, items and dialogue from that time plus a screenshot.
+- Sends keyboard, mouse and gamepad input and the game's own input actions, types into text fields or puts a lobby id on the clipboard.
+- Takes a screenshot on demand (`buckshot_glance`).
+- Events: loads, shots, ejections, reveals, inversions, item use, health changes, defibrillator revivals, dialogue, new rounds, multiplayer turns and direction, results and prize money, plus screenshots after shots, reveals, revivals, dialogue and results.
+- Coo only gets what the screen shows. The unrevealed shell order, the dealer's decisions and other players' private reveals are left out.
+- Local join: once the game hosts a multiplayer lobby, a second game window on this PC joins it so the operator can play Coo with the mouse.
+
+### Before you install
+
+1. **The game**: buy and install Buckshot Roulette through Steam on Windows. Only the Steam Windows build **v2.2.0.6** is supported. When starting the game the World checks the size and SHA-256 (`df2f8a31…1b1663`) of `Buckshot Roulette.exe` and refuses any other build. To find the exe, right-click the game in your Steam library and choose Manage → Browse local files.
+2. **The implant**: nothing to compile or copy by hand. Its sources are `src/native/bridge.gd` (the bridge script) and `src/implant.ts` (where it hooks into the game's scripts). The first time the World starts the game it reads the game's resources out of the exe, adds the bridge script and writes a startup pack on this machine, by default in `runtimes/buckshot/` under the deployment, then launches the game with `--main-pack` pointing at it. The game files are not written to, and no game assets ship with the extension.
+3. **Save data**: the game started by the World keeps its own save under `%APPDATA%/Cortico/Buckshot/<profile>`, apart from your normal save. Story completion and the Double or Nothing unlock are stored there.
+4. **Multiplayer**: lobbies go through Steam, so the Steam client must be signed in and online.
+
+To check: enable the World, click 启动游戏 (Start game) in the World tab, and wait for the status to read 已连接 (connected). If it does not connect, look at `data/buckshot/game.log` in the deployment.
+
+### Install
+
+Search for `cortico-world-buckshot` on the Extensions page in Cortico or Coopanion, install it, restart, and enable it in the World overview. From the command line:
+
+```bash
+cd extensions
+corepack pnpm add cortico-world-buckshot
+```
+
+Then set 游戏程序 (game executable) in the Buckshot Roulette page's settings to `Buckshot Roulette.exe`. The World can be enabled without it; the path is checked when the game starts.
+
+### Usage
+
+- **Start**: click 启动游戏 on the 游戏 card in the World tab, or let Coo call `buckshot_start`. The card shows the status, scene, mode, round and the local player's state.
+- **How Coo plays**: once the game is connected, Coo is told when the operable targets change and picks targets on its own. When loads, shots, dialogue or screenshots arrive, Coo acts or talks next; what it says is up to Coo.
+- **View**: 查看画面 shows the current game view on the card.
+- **Local join**: have Coo host a multiplayer lobby and stay on the lobby screen, then click 本地加入. A second game window opens on this PC and joins under the local player name; you play it with the mouse. The host starts the match as usual. 退出本地 closes that window.
+- **Close**: 关闭游戏 closes only the game this World started. By default the game also closes when the World stops.
+
+### Configuration
+
+| Key | Default | Description |
+|---|---|---|
+| `worlds.buckshot.executableFile` | empty | Path to `Buckshot Roulette.exe` |
+| `worlds.buckshot.runtimeDir` | empty | Where the implant pack goes; empty uses `runtimes/buckshot` in the deployment |
+| `worlds.buckshot.closeOnStop` | `true` | Close the game when the World stops |
+| `worlds.buckshot.settleTimeoutMs` | `30000` | How long an action waits for the game to be operable again; after that the reply returns and later changes arrive as events |
+| `worlds.buckshot.screenshotEvents.enabled` | `true` | Send screenshots at key moments |
+| `worlds.buckshot.screenshotEvents.minIntervalMs` | `1500` | Minimum gap between automatic screenshots |
+| `worlds.buckshot.display.screenIndex` | empty | Monitor for the game, from 0; empty lets the game choose |
+| `worlds.buckshot.display.muteAudio` | `false` | Start the game muted |
+| `worlds.buckshot.localPeer.name` | `Player 2` | Local player name for local join |
+| `worlds.buckshot.localPeer.muteAudio` | `true` | Mute the local client so the stream does not hear the audio twice |
+
+Monitor and mute settings apply the next time the game starts. The rest are in `src/config.ts`.
+
+### Limitations and FAQ
+
+- Only the Steam Windows build v2.2.0.6 works. A Steam update changes the exe hash, and the World will refuse to start until the extension supports the new build.
+- The local player takes a seat, so one fewer online player fits (a 4-player lobby takes 2 more). Online players do not see the local player in the lobby list, and its name may show as blank in the match. If the local player leaves mid-match, the host sends everyone back to the lobby.
+- Real cross-account Steam multiplayer has not been verified. The Steam invite window is outside the game view, so Coo cannot use it.
+- Events and screenshots start Coo's turns often, so token use adds up. Turn off automatic screenshots or raise the interval to cut it.
+
+Implementation, protocol and test notes: [docs/internals.md](https://github.com/Phantivia/cortico-world-buckshot/blob/main/docs/internals.md).
+
+## 开发 · Development
+
+```bash
+corepack pnpm install
+corepack pnpm typecheck
+corepack pnpm test
+corepack pnpm build:web   # dist/webui.js; also runs on prepack
+```
+
+`corepack pnpm check:game <exe>` checks a game install (`--launch` also starts it); `corepack pnpm check:native <exe>` runs the bridge in the game's headless engine. Details in [docs/internals.md](https://github.com/Phantivia/cortico-world-buckshot/blob/main/docs/internals.md).
+
+## 许可 · License
+
+MIT

package/assets/icon.svg

@@ -0,0 +1,58 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#4a1c24"/>
+      <stop offset="1" stop-color="#1e0b10"/>
+    </linearGradient>
+    <linearGradient id="live" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#ff6b78"/>
+      <stop offset="1" stop-color="#d9324a"/>
+    </linearGradient>
+    <linearGradient id="blank" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#8fc6ff"/>
+      <stop offset="1" stop-color="#4f86d6"/>
+    </linearGradient>
+    <linearGradient id="brass" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#ffe08a"/>
+      <stop offset="1" stop-color="#d9a634"/>
+    </linearGradient>
+    <filter id="glow" x="-40%" y="-40%" width="180%" height="180%">
+      <feGaussianBlur stdDeviation="16"/>
+    </filter>
+    <g id="shell">
+      <!-- crimped top and paper hull -->
+      <path d="M -40 26 Q -40 0 -14 0 L 14 0 Q 40 0 40 26 L 40 156 L -40 156 Z"/>
+      <!-- crimp folds -->
+      <path d="M -20 4 L -12 22 M 0 2 L 0 22 M 20 4 L 12 22" stroke="#ffffff" stroke-opacity="0.45" stroke-width="5" stroke-linecap="round" fill="none"/>
+      <!-- highlight -->
+      <rect x="-27" y="34" width="11" height="112" rx="5.5" fill="#ffffff" fill-opacity="0.45"/>
+      <!-- brass head and rim -->
+      <rect x="-42" y="150" width="84" height="50" rx="6" fill="url(#brass)"/>
+      <rect x="-50" y="194" width="100" height="18" rx="6" fill="url(#brass)"/>
+      <rect x="-30" y="160" width="9" height="30" rx="4.5" fill="#ffffff" fill-opacity="0.55"/>
+    </g>
+  </defs>
+
+  <rect width="512" height="512" rx="112" fill="url(#bg)"/>
+
+  <!-- warm light over the table -->
+  <ellipse cx="256" cy="200" rx="150" ry="110" fill="#ff5a6a" fill-opacity="0.18" filter="url(#glow)"/>
+
+  <!-- a live shell and a blank shell -->
+  <g transform="translate(192 186) rotate(-10) translate(0 -106)">
+    <use href="#shell" fill="url(#live)"/>
+  </g>
+  <g transform="translate(320 186) rotate(10) translate(0 -106)">
+    <use href="#shell" fill="url(#blank)"/>
+  </g>
+
+  <!-- Coo's eyes, watching the shells -->
+  <g>
+    <circle cx="198" cy="378" r="48" fill="#22e3ee"/>
+    <circle cx="198" cy="378" r="29" fill="#111322"/>
+    <circle cx="209" cy="367" r="9" fill="#ffffff"/>
+    <circle cx="314" cy="378" r="48" fill="#22e3ee"/>
+    <circle cx="314" cy="378" r="29" fill="#111322"/>
+    <circle cx="325" cy="367" r="9" fill="#ffffff"/>
+  </g>
+</svg>

package/describe.json

@@ -451,6 +451,14 @@
       },
       "trigger": "debounce"
     },
+    {
+      "type": "buckshot.peer",
+      "description": {
+        "zh": "WebUI「本地加入」的本地玩家进入或离开了多人房间。",
+        "en": "The local player started from the WebUI joined or left the multiplayer lobby."
+      },
+      "trigger": "debounce"
+    },
     {
       "type": "buckshot.clipboard",
       "description": {

package/dist/webui.js

@@ -9,10 +9,12 @@ var game = {
     const start = ui.button("\u542F\u52A8\u6E38\u620F", { variant: "primary" });
     const stop = ui.button("\u5173\u95ED\u6E38\u620F", { variant: "danger" });
     const capture = ui.button("\u67E5\u770B\u753B\u9762");
+    const peerJoin = ui.button("\u672C\u5730\u52A0\u5165");
+    const peerLeave = ui.button("\u9000\u51FA\u672C\u5730");
     const preview = ui.h("img");
     preview.alt = "\u6E38\u620F\u5F53\u524D\u753B\u9762";
     preview.style.cssText = "display:none;width:100%;height:auto;margin-top:12px;";
-    actions.append(start, stop, capture);
+    actions.append(start, stop, capture, peerJoin, peerLeave);
     card.body.append(status, message, actions, preview);
     ctx.root.append(card.el);
     let busy = false;
@@ -25,19 +27,22 @@ var game = {
         { k: "\u72B6\u6001", v: ui.pill({ offline: "\u672A\u542F\u52A8", loading: "\u542F\u52A8\u4E2D", online: "\u5DF2\u8FDE\u63A5", error: "\u542F\u52A8\u5931\u8D25" }[state.state], state.state === "online" ? "on" : "off") },
         { k: "\u573A\u666F", v: state.scene ?? "\u2014" },
         { k: "\u6A21\u5F0F", v: state.mode ?? "\u2014" },
-        { k: "\u8F6E\u6B21", v: state.round === void 0 ? "\u2014" : String(state.round) }
+        { k: "\u8F6E\u6B21", v: state.round === void 0 ? "\u2014" : String(state.round) },
+        { k: "\u672C\u5730\u73A9\u5BB6", v: ui.pill({ offline: "\u672A\u52A0\u5165", starting: "\u542F\u52A8\u4E2D", menu: "\u672A\u8FDB\u623F\u95F4", joined: "\u5728\u623F\u95F4\u91CC" }[state.peer], state.peer === "joined" ? "on" : "off") }
       ]));
-      message.textContent = state.error;
+      message.textContent = state.error || state.peerError;
       start.disabled = busy || state.state === "online" || state.state === "loading";
       stop.disabled = busy || !state.stoppable;
       capture.disabled = busy || state.state !== "online";
+      peerJoin.disabled = busy || state.state !== "online" || state.peer !== "offline";
+      peerLeave.disabled = busy || state.peer === "offline";
     }
     async function refresh() {
       if (!ctx.signal.aborted) render(await ctx.invoke("state"));
     }
     async function act(method) {
       busy = true;
-      start.disabled = stop.disabled = capture.disabled = true;
+      start.disabled = stop.disabled = capture.disabled = peerJoin.disabled = peerLeave.disabled = true;
       try {
         render(await ctx.invoke(method));
         await ctx.refresh();
@@ -54,6 +59,12 @@ var game = {
     stop.addEventListener("click", () => {
       void act("stop");
     }, { signal: ctx.signal });
+    peerJoin.addEventListener("click", () => {
+      void act("peerJoin");
+    }, { signal: ctx.signal });
+    peerLeave.addEventListener("click", () => {
+      void act("peerLeave");
+    }, { signal: ctx.signal });
     capture.addEventListener("click", () => {
       void ctx.invokeBinary("capture").then((blob) => {
         if (ctx.signal.aborted) return;

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "cortico-world-buckshot",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
-  "description": "Buckshot Roulette game events and player actions for Cortico. 此乃直播测试验证之后的world，和其他 Persona / 非直播场景的兼容性有待测试。",
+  "description": "Lets a Cortico bot play Buckshot Roulette (Steam, Windows) through live game events and in-game actions; verified on live streams, compatibility with other Personas and non-streaming setups is untested.",
+  "author": "Phantivia",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Phantivia/cortico-world-buckshot.git"
   },
   "homepage": "https://github.com/Phantivia/cortico-world-buckshot#readme",
+  "bugs": {
+    "url": "https://github.com/Phantivia/cortico-world-buckshot/issues"
+  },
   "keywords": [
     "cortico-world",
     "cortico",
@@ -26,6 +30,24 @@
     "kind": "world",
     "api": 6,
     "displayName": "恶魔轮盘",
+    "icon": "assets/icon.png",
+    "tags": [
+      "streaming",
+      "game",
+      "external-setup",
+      "experimental",
+      "high-cost"
+    ],
+    "locales": {
+      "zh": {
+        "displayName": "恶魔轮盘",
+        "description": "让 Coo 玩 Steam 版《恶魔轮盘》:装填、开枪、道具、生命和字幕实时推给 Coo,Coo 自己拿枪、用道具、点菜单。\n\n**功能**\n- 单人剧情、Double or Nothing 与多人房间都能玩\n- 装填数、揭示的弹药、生命和字幕作为事件推给 Coo,关键时刻附游戏截图\n- Coo 用工具操作桌上目标、菜单和设置,也能发键盘、鼠标、手柄输入\n- 本地加入:操作员在本机再开一个游戏窗口,和 Coo 同桌对打\n- WebUI 页签可启动、关闭游戏,查看当前画面\n\n**安装后还需要**\n1. 在 Windows 上通过 Steam 安装《Buckshot Roulette》,版本须为 v2.2.0.6\n2. 在 World 页的配置里把「游戏程序」指向 `Buckshot Roulette.exe`\n3. 植入资源包由 World 首次启动游戏时自动生成,无需编译\n4. 详细步骤见 [README](https://github.com/Phantivia/cortico-world-buckshot#安装前准备)\n\n仅 Windows。CortiV 直播验证过的参考实现,和其他 Persona、非直播场景的兼容性有待测试。"
+      },
+      "en": {
+        "displayName": "Buckshot Roulette",
+        "description": "Lets Coo play Buckshot Roulette (Steam): loads, shots, items, health and dialogue reach Coo as they happen, and Coo picks up the shotgun, uses items and works the menus itself.\n\n**Features**\n- Plays the story, Double or Nothing and multiplayer lobbies\n- Shell counts, revealed shells, health and dialogue arrive as events, with a screenshot at key moments\n- Coo operates table targets, menus and settings through tools, and can send keyboard, mouse and gamepad input\n- Local join: the operator opens a second game window on the same PC and plays Coo at the same table\n- The WebUI tab starts and closes the game and shows the current view\n\n**After installing you also need**\n1. Buckshot Roulette from Steam on Windows, version v2.2.0.6\n2. Set 游戏程序 (game executable) in the World page settings to `Buckshot Roulette.exe`\n3. The implant pack is generated automatically the first time the World starts the game; nothing to compile\n4. Full steps in the [README](https://github.com/Phantivia/cortico-world-buckshot#before-you-install)\n\nWindows only. A reference implementation verified on CortiV live streams; compatibility with other Personas and non-streaming use has not been tested."
+      }
+    },
     "webUiClient": "dist/webui.js",
     "describe": "describe.json"
   },
@@ -33,6 +55,7 @@
     "src",
     "scripts",
     "dist",
+    "assets",
     "describe.json",
     "CHANGELOG.md",
     "README.md",

package/scripts/check-local-peer.ts

@@ -0,0 +1,183 @@
+// Live check of local peer with the real game. The host process hosts a lobby, a local peer joins it, the match starts
+// and both sides pick up items and fire; each side prints what it saw.
+// --with-remote adds a mock Steam player: another local process the host counts as a Steam member and that sees the
+// member list Steam would show it. It checks three players together, the local peer leaving mid-match (everyone goes
+// back to the lobby) and the Steam player leaving mid-match (the others play on).
+// Usage: pnpm tsx scripts/check-local-peer.ts <Buckshot Roulette.exe> [--with-remote] [--screen=<index>]
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { createWriteStream } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { BuckshotBridge } from '../src/bridge.ts';
+import { prepareImplant } from '../src/implant.ts';
+import { LOCAL_PEER_ID, LocalPeer } from '../src/peer.ts';
+import type { BuckshotSnapshot } from '../src/protocol.ts';
+import { renderSnapshot } from '../src/render.ts';
+
+const REMOTE_ID = '76561190000000002';
+const args = process.argv.slice(2);
+const executableFile = args.find((value) => !value.startsWith('--'));
+if (!executableFile) throw new Error('Usage: pnpm tsx scripts/check-local-peer.ts <Buckshot Roulette.exe> [--with-remote]');
+const withRemote = args.includes('--with-remote');
+const screen = args.find((value) => value.startsWith('--screen='))?.slice('--screen='.length);
+const runtimeDir = resolve('scratch/local-peer-check');
+await mkdir(runtimeDir, { recursive: true });
+const sleep = (ms: number) => new Promise((done) => setTimeout(done, ms));
+
+async function snapshot(bridge: BuckshotBridge): Promise<BuckshotSnapshot> {
+  const reply = await bridge.request('snapshot', {}, 10000);
+  if (!reply.snapshot) throw new Error(reply.detail);
+  return reply.snapshot;
+}
+
+async function waitFor(bridge: BuckshotBridge, what: string, test: (s: BuckshotSnapshot) => boolean, ms = 60000): Promise<BuckshotSnapshot> {
+  const deadline = Date.now() + ms;
+  while (Date.now() < deadline) {
+    const current = await snapshot(bridge);
+    if (test(current)) return current;
+    await sleep(500);
+  }
+  throw new Error(`Timed out waiting for ${what}`);
+}
+
+async function press(bridge: BuckshotBridge, label: RegExp, ms = 60000): Promise<void> {
+  const current = await waitFor(bridge, String(label), (s) => s.actions.some((a) => label.test(a.label)), ms);
+  const target = current.actions.find((a) => label.test(a.label))!;
+  const reply = await bridge.request('act', { target: target.id, revision: current.revision }, 10000);
+  console.log(`press ${target.label}: ${reply.detail}`);
+}
+
+function check(condition: boolean, message: string): void {
+  if (!condition) throw new Error(`CHECK FAILED: ${message}`);
+  console.log(`ok: ${message}`);
+}
+
+const players = (s: BuckshotSnapshot) => (s.players ?? []).map((p) => `${p.seat}:${p.name || '(空)'}:${p.health ?? '?'}`).sort().join(' ');
+const seatsAndHealth = (s: BuckshotSnapshot) => (s.players ?? []).map((p) => `${p.seat}:${p.health ?? '?'}`).sort().join(' ');
+const inMatch = (count: number) => (s: BuckshotSnapshot) => s.mode === 'multiplayer' && (s.players?.length ?? 0) === count;
+
+/** Whoever can act picks up items or the shotgun and fires at another seat, until `shots` shots or the time runs out. */
+async function play(sides: Array<[string, BuckshotBridge]>, shots: number, ms: number): Promise<number> {
+  const deadline = Date.now() + ms;
+  let fired = 0;
+  while (Date.now() < deadline && fired < shots) {
+    for (const [name, bridge] of sides) {
+      const current = await snapshot(bridge).catch(() => null);
+      if (!current) continue;
+      const target = current.actions.find((a) => /^shoot seat/.test(a.label) && a.side !== String(current.localSeat))
+        ?? current.actions.find((a) => /shotgun/.test(a.label))
+        ?? current.actions.find((a) => a.kind === 'multiplayer interaction' && !/^shoot seat|^jam/.test(a.label));
+      if (!target) continue;
+      const reply = await bridge.request('act', { target: target.id, revision: current.revision }, 10000);
+      console.log(`[${name}] act ${target.label}: ${reply.detail}`);
+      if (/^shoot seat/.test(target.label)) fired++;
+      await sleep(1500);
+    }
+    await sleep(1000);
+  }
+  return fired;
+}
+
+const hostPack = await prepareImplant(executableFile, runtimeDir);
+const peerPack = await prepareImplant(executableFile, runtimeDir, 'local-peer');
+const remotePack = withRemote ? await prepareImplant(executableFile, runtimeDir, 'mock-remote') : '';
+const host = new BuckshotBridge();
+const port = await host.start();
+const log = createWriteStream(join(runtimeDir, 'host.log'));
+const game = spawn(executableFile, ['--windowed', '--audio-driver', 'Dummy', ...(screen ? ['--screen', screen] : []), '--main-pack', hostPack, '--', `--cortico-executable=${executableFile}`, `--cortico-port=${port}`, `--cortico-token=${host.token}`], { cwd: dirname(executableFile), stdio: ['ignore', 'pipe', 'pipe'] });
+game.stdout?.pipe(log); game.stderr?.pipe(log);
+host.on('observation', (event: { kind: string; facts: unknown }) => { if (['load', 'shot', 'health', 'result'].includes(event.kind)) console.log(`[host] ${event.kind} ${JSON.stringify(event.facts)}`); });
+
+const peers: LocalPeer[] = [];
+async function enter(id: string, name: string, pack: string, mock: boolean): Promise<LocalPeer> {
+  let joined = false;
+  const peer = new LocalPeer(host, { id, mockSteamPlayer: mock, executableFile: executableFile!, packFile: pack, logFile: join(runtimeDir, `${mock ? 'remote' : 'peer'}.log`), name, screenIndex: null, muteAudio: true, startupTimeoutMs: 60000, actionTimeoutMs: 10000,
+    onChange: (change) => { if (change === 'joined') joined = true; console.log(`${name} ${change}`); } });
+  peers.push(peer);
+  const lobby = await host.request('peer_lobby', { peer: id }, 10000);
+  if (!lobby.ok) throw new Error(lobby.detail);
+  await peer.start((lobby as { lobby?: string }).lobby ?? '');
+  for (let i = 0; i < 60 && !joined; i++) await sleep(1000);
+  if (!joined) throw new Error(`${name} did not join`);
+  return peer;
+}
+
+async function memberLimit(): Promise<unknown> {
+  return (await host.request('peer_lobby', { peer: LOCAL_PEER_ID }, 10000) as { memberLimit?: unknown }).memberLimit;
+}
+
+try {
+  await once(host, 'connected');
+  await press(host, /^skip intro$/, 15000).catch(() => undefined);
+  await press(host, /^start multiplayer/);
+  await waitFor(host, 'lobby scene', (s) => s.scene === 'mp_lobby');
+  await press(host, /^create lobby/);
+  for (let i = 0; !(await host.request('peer_lobby', { peer: LOCAL_PEER_ID }, 10000)).ok; i++) {
+    if (i === 60) throw new Error('the host did not open a lobby');
+    await sleep(1000);
+  }
+  console.log(`member limit before: ${await memberLimit()}`);
+
+  if (!withRemote) {
+    const peer = await enter(LOCAL_PEER_ID, 'Player 2', peerPack, false);
+    await sleep(4000);
+    await press(host, /^start game/);
+    const views: Array<[string, BuckshotBridge]> = [['host', host], ['peer', peer.bridge]];
+    for (const [name, bridge] of views) console.log(`${name}: ${players(await waitFor(bridge, `${name} match`, inMatch(2), 90000))}`);
+    await play(views, 6, 240000);
+    for (const [name, bridge] of views) {
+      const frame = await bridge.request('capture', {}, 10000);
+      if (frame.png) await writeFile(join(runtimeDir, `${name}.png`), Buffer.from(frame.png, 'base64'));
+      console.log(`--- ${name}\n${renderSnapshot(await snapshot(bridge))}`);
+    }
+  } else {
+    // 1. a Steam player and the local peer in one lobby
+    const remote = await enter(REMOTE_ID, 'Remote', remotePack, true);
+    let peer = await enter(LOCAL_PEER_ID, 'Player 2', peerPack, false);
+    check(await memberLimit() === 3, 'the local peer takes one of four Steam seats');
+    await sleep(4000);
+    const lobbyText = async (bridge: BuckshotBridge) => (await snapshot(bridge)).texts.join(' | ');
+    const [hostLobby, remoteLobby, peerLobby] = [await lobbyText(host), await lobbyText(remote.bridge), await lobbyText(peer.bridge)];
+    console.log(`host lobby: ${hostLobby}\nremote lobby: ${remoteLobby}\npeer lobby: ${peerLobby}`);
+    check(hostLobby.includes('Player 2') && hostLobby.includes('Remote'), 'the host lists both');
+    check(!remoteLobby.includes('Player 2'), 'the Steam player does not list the local peer, as with Steam');
+
+    // 2. three players in a match; the Steam player seats the local peer from the host's setup
+    await press(host, /^start game/);
+    let views: Array<[string, BuckshotBridge]> = [['host', host], ['remote', remote.bridge], ['peer', peer.bridge]];
+    for (const [name, bridge] of views) console.log(`${name}: ${players(await waitFor(bridge, `${name} match`, inMatch(3), 90000))}`);
+    await play(views, 4, 200000);
+    await sleep(3000);
+    const seen = await Promise.all(views.map(async ([, bridge]) => seatsAndHealth(await snapshot(bridge))));
+    console.log(`seats and health: ${seen.join(' / ')}`);
+    check(seen.every((value) => value === seen[0]), 'seats and health agree on all three');
+
+    // 3. the local peer leaves mid-match: everyone goes back to the lobby
+    await peer.stop();
+    for (const [name, bridge] of [['host', host], ['remote', remote.bridge]] as const) await waitFor(bridge, `${name} back in lobby`, (s) => s.scene === 'mp_lobby', 60000);
+    check(true, 'host and Steam player are back in the lobby');
+    for (let i = 0; !(await host.request('peer_lobby', { peer: LOCAL_PEER_ID }, 10000)).ok; i++) {
+      if (i === 60) throw new Error('the host lobby did not reopen');
+      await sleep(1000);
+    }
+    check(await memberLimit() === 4, 'the seat is back for Steam');
+
+    // 4. the local peer comes back; this time the Steam player leaves mid-match and the other two play on
+    peer = await enter(LOCAL_PEER_ID, 'Player 2', peerPack, false);
+    await sleep(4000);
+    await press(host, /^start game/);
+    views = [['host', host], ['remote', remote.bridge], ['peer', peer.bridge]];
+    for (const [name, bridge] of views) await waitFor(bridge, `${name} match`, inMatch(3), 90000);
+    await play(views, 1, 120000);
+    await remote.stop();
+    views = [['host', host], ['peer', peer.bridge]];
+    for (const [name, bridge] of views) console.log(`${name} after the Steam player left: ${players(await waitFor(bridge, `${name} two players`, inMatch(2), 60000))}`);
+    check(await play(views, 2, 150000) === 2, 'host and local peer play on');
+  }
+} finally {
+  for (const peer of peers) await peer.stop();
+  await host.request('quit', {}, 3000).catch(() => undefined);
+  if (game.exitCode === null) { const closed = once(game, 'close'); if (game.kill()) await closed; }
+  await host.stop();
+}

package/src/bridge.ts

@@ -91,6 +91,8 @@ export class BuckshotBridge extends EventEmitter {
         request.resolve(reply);
         break;
       }
+      // local peer traffic, relayed by LocalPeer
+      case 'net': case 'roster': case 'peer': this.emit(message.kind, message); break;
       default: throw new Error('Unknown game bridge message');
     }
   }
@@ -114,6 +116,11 @@ export class BuckshotBridge extends EventEmitter {
     });
   }
 
+  /** A request the game does not answer. */
+  send(action: string, args: Record<string, unknown>): void {
+    if (this.socket && !this.socket.destroyed) this.socket.write(JSON.stringify({ action, ...args }) + '\n');
+  }
+
   private rejectPending(error: Error): void {
     for (const request of this.pending.values()) { clearTimeout(request.timer); request.reject(error); }
     this.pending.clear();

package/src/config.ts

@@ -10,6 +10,7 @@ export interface BuckshotConfigSection {
   settleTimeoutMs: number;
   screenshotEvents: { enabled: boolean; minIntervalMs: number };
   display: { screenIndex: number | null; muteAudio: boolean };
+  localPeer: { name: string; screenIndex: number | null; muteAudio: boolean };
 }
 
 export const BUCKSHOT_DEFAULTS: BuckshotConfigSection = {
@@ -17,6 +18,7 @@ export const BUCKSHOT_DEFAULTS: BuckshotConfigSection = {
   startupTimeoutMs: 30000, actionTimeoutMs: 10000, settleTimeoutMs: 30000,
   screenshotEvents: { enabled: true, minIntervalMs: 1500 },
   display: { screenIndex: null, muteAudio: false },
+  localPeer: { name: 'Player 2', screenIndex: null, muteAudio: true },
 };
 
 export const BUCKSHOT_CONFIG_GROUP: ConfigGroup = {
@@ -32,6 +34,9 @@ export const BUCKSHOT_CONFIG_GROUP: ConfigGroup = {
       'worlds.buckshot.screenshotEvents.minIntervalMs': { type: 'integer', title: '截图最短间隔', minimum: 500, 'x-suffix': 'ms', 'x-hot': true },
       'worlds.buckshot.display.screenIndex': { type: 'integer', title: '显示器编号', minimum: 0, nullable: true, description: '从 0 开始；留空由游戏选择。', 'x-hot': false },
       'worlds.buckshot.display.muteAudio': { type: 'boolean', title: '静音启动', 'x-hot': false },
+      'worlds.buckshot.localPeer.name': { type: 'string', title: '本地玩家名字', description: '本地加入时在房间里显示的名字。', 'x-hot': true },
+      'worlds.buckshot.localPeer.screenIndex': { type: 'integer', title: '本地客户端显示器', minimum: 0, nullable: true, description: '从 0 开始；留空由游戏选择。', 'x-hot': true },
+      'worlds.buckshot.localPeer.muteAudio': { type: 'boolean', title: '本地客户端静音', description: '两个游戏同放声音时，直播里会听到两遍。', 'x-hot': true },
     },
   },
 };

package/src/definition.ts

@@ -144,6 +144,11 @@ export const BUCKSHOT: WorldDefinition<BuckshotConfigSection> = {
         description: { zh: '对局结算画面:单人胜利的奖金,或多人对局的结果。', en: 'The results screen: the prize money for a single-player win, or the multiplayer result.' },
         trigger: 'debounce',
       },
+      {
+        type: 'buckshot.peer',
+        description: { zh: 'WebUI「本地加入」的本地玩家进入或离开了多人房间。', en: 'The local player started from the WebUI joined or left the multiplayer lobby.' },
+        trigger: 'debounce',
+      },
       {
         type: 'buckshot.clipboard',
         description: { zh: '游戏把多人大厅编号复制到了剪贴板。', en: 'The game copied the multiplayer lobby id to the clipboard.' },

package/src/implant.ts

@@ -8,7 +8,7 @@ import { readPack, readResource, writePatchedPack } from './pck.ts';
 const BRIDGE_FILE = fileURLToPath(new URL('./native/bridge.gd', import.meta.url));
 const BRIDGE_NODE = 'get_node("/root/CorticoBridge")';
 
-export interface ScriptHook { path: string; anchor: string; insertion: string; before?: boolean; occurrences?: number; }
+export interface ScriptHook { path: string; anchor: string; insertion: string; before?: boolean; replace?: boolean; occurrences?: number; }
 
 export const BUCKSHOT_SCRIPT_HOOKS: readonly ScriptHook[] = [
   { path: 'scripts/ShellSpawner.gd', anchor: '\tanim_compartment.play("show shells")\n', insertion: `\t${BRIDGE_NODE}.ObserveLoad(temp_live, temp_blank)\n` },
@@ -43,13 +43,34 @@ export const BUCKSHOT_SCRIPT_HOOKS: readonly ScriptHook[] = [
   { path: 'multiplayer/scripts/global scripts/MP_OutroManager.gd', anchor: '\tdialogue_results.ShowText_Forever(tr("MP_UI MATCH RESULTS"))\n', insertion: `\t${BRIDGE_NODE}.ObserveOutcome("completed")\n` },
   { path: 'multiplayer/scripts/user scripts/MP_ShotgunInteraction.gd', anchor: '\tvar current_shell = intermediary.game_state.MAIN_shooter_shell\n', insertion: `\t${BRIDGE_NODE}.ObserveShot(str(active_shooter_socket_self), str(active_shooter_socket_target), current_shell)\n` },
   ...['firstperson', 'thirdperson'].map((person): ScriptHook => ({ path: 'multiplayer/scripts/user scripts/MP_ItemInteraction.gd', anchor: `\tanimator_items_${person}.play(animation_name)\n`, insertion: `\t${BRIDGE_NODE}.ObserveItem(str(properties.socket_number), active_id, properties.intermediary.game_state.MAIN_item_resource_array)\n` })),
+  // Local peer: a second game process sits in the host's lobby as a member Steam does not know about. Its packets,
+  // membership and name go through CorticoBridge, which hands every other member to Steam.
+  ...([
+    ['multiplayer/scripts/MP_PacketManager.gd', 'Steam.sendP2PPacket(', 'SendP2PPacket(', 2],
+    ['multiplayer/scripts/MP_PacketManager.gd', 'Steam.getAvailableP2PPacketSize(0)', 'GetAvailableP2PPacketSize(0)', 2],
+    ['multiplayer/scripts/MP_PacketManager.gd', 'Steam.readP2PPacket(packet_size, 0)', 'ReadP2PPacket(packet_size, 0)', 1],
+    ['multiplayer/scripts/MP_PacketManager.gd', 'Steam.getFriendPersonaName(', 'PersonaName(', 1],
+    ['multiplayer/scripts/MP_LobbyManager.gd', 'Steam.getNumLobbyMembers(', 'NumLobbyMembers(', 1],
+    ['multiplayer/scripts/MP_LobbyManager.gd', 'Steam.getLobbyMemberByIndex(', 'LobbyMemberByIndex(', 1],
+    ['multiplayer/scripts/MP_LobbyManager.gd', 'Steam.getLobbyOwner(', 'LobbyOwner(', 2],
+    ['multiplayer/scripts/MP_LobbyManager.gd', 'Steam.joinLobby(', 'JoinLobby(', 1],
+    ['multiplayer/scripts/MP_LobbyManager.gd', 'Steam.leaveLobby(', 'LeaveLobby(', 1],
+    ['multiplayer/scripts/MP_LobbyManager.gd', 'Steam.getFriendPersonaName(', 'PersonaName(', 4],
+    ['multiplayer/scripts/MP_LobbyManager.gd', 'Steam.setLobbyMemberLimit(', 'SetLobbyMemberLimit(', 2],
+    ['multiplayer/scripts/global scripts/MP_OutroManager.gd', 'Steam.getFriendPersonaName(', 'PersonaName(', 6],
+    ['multiplayer/scripts/global scripts/MP_UserInstanceHandler.gd', 'Steam.getFriendPersonaName(', 'PersonaName(', 1],
+    ['multiplayer/scripts/user scripts/MP_UserStateManager.gd', 'Steam.getFriendPersonaName(', 'PersonaName(', 1],
+  ] as const).map(([path, anchor, call, occurrences]): ScriptHook => ({ path, anchor, insertion: `${BRIDGE_NODE}.${call}`, replace: true, occurrences })),
+  // The local peer leaves Steam uninitialised, so it never acts as the account the host is signed in with.
+  { path: 'scripts/Steam.gd', anchor: 'func InitializeSteam():\n', insertion: `\tif ${BRIDGE_NODE}.IsLocalPeer(): return\n` },
+  { path: 'scripts/Steam.gd', anchor: '\tif GlobalVariables.mp_debugging: STEAM_ID = 1234\n', insertion: `\t${BRIDGE_NODE}.AdoptPeerIdentity(self)\n` },
 ];
 
 export function applyHook(source: string, hook: ScriptHook): string {
   const segments = source.split(hook.anchor);
   if (segments.length === 1) throw new Error(`Game hook anchor missing: ${hook.path}`);
   if (segments.length - 1 !== (hook.occurrences ?? 1)) throw new Error(`Ambiguous game hook anchor: ${hook.path}`);
-  return segments.join(hook.before ? hook.insertion + hook.anchor : hook.anchor + hook.insertion);
+  return segments.join(hook.replace ? hook.insertion : hook.before ? hook.insertion + hook.anchor : hook.anchor + hook.insertion);
 }
 
 /** Adds an autoload to ECFG without re-encoding existing Variant values. */
@@ -96,10 +117,11 @@ export function setProjectSettings(project: Buffer, values: ReadonlyMap<string,
   return Buffer.concat([header, ...records]);
 }
 
-export async function prepareImplant(executableFile: string, runtimeDir: string): Promise<string> {
+/** A `profile` such as 'local-peer' builds the pack for another local process, which keeps its settings and saves apart. */
+export async function prepareImplant(executableFile: string, runtimeDir: string, profile = ''): Promise<string> {
   await verifyInstallation(executableFile);
   const bridge = await readFile(BRIDGE_FILE);
-  const saveProfile = createHash('sha256').update(resolve(runtimeDir)).digest('hex').slice(0, 16);
+  const saveProfile = createHash('sha256').update(resolve(runtimeDir)).update(profile ? `:${profile}` : '').digest('hex').slice(0, 16);
   const revision = createHash('sha256').update(bridge).update(JSON.stringify(BUCKSHOT_SCRIPT_HOOKS)).update(setProjectSettings.toString()).update(prepareImplant.toString()).update(saveProfile).digest('hex');
   const directory = join(runtimeDir, BUCKSHOT_PROFILE.id, revision);
   const outputFile = join(directory, 'buckshot.pck');

package/src/native/bridge.gd

@@ -25,12 +25,23 @@ var scene_id = 0
 var seat_health = {}
 var outcome = {}
 var multiplayer_status = {}
+# Local peer, in the second process: its lobby member id and name, and the host's lobby as the host last reported it.
+var peer_id = 0
+var peer_name = ""
+var roster = {"lobby": 0, "owner": 0, "members": []}
+# Local peers, in the host process: member id -> {name, mock}, and the member list each was last sent.
+var local_peers = {}
+var last_rosters = {}
+# Packets relayed between host and local peer, read before Steam's.
+var relay_inbox = []
 
 func _init():
 	for arg in OS.get_cmdline_user_args():
 		if arg.begins_with("--cortico-executable="):
 			if !ProjectSettings.load_resource_pack(arg.trim_prefix("--cortico-executable="), false):
 				push_error("Cortico could not load the original game resource pack")
+		if arg.begins_with("--cortico-peer-id="): peer_id = int(arg.trim_prefix("--cortico-peer-id="))
+		if arg.begins_with("--cortico-peer-name="): peer_name = arg.trim_prefix("--cortico-peer-name=")
 
 func _ready():
 	process_mode = Node.PROCESS_MODE_ALWAYS
@@ -95,6 +106,7 @@ func _process(delta):
 	if elapsed >= 0.1:
 		elapsed = 0
 		Publish()
+		PublishRoster()
 	for action in held_actions.keys():
 		if Time.get_ticks_msec() >= held_actions[action]:
 			ReleaseAction(action)
@@ -527,6 +539,32 @@ func Handle(request):
 				else: held_controller_buttons.erase(button)
 			Reply(id, true, "input delivered")
 		"capture": Capture(id)
+		"net":
+			relay_inbox.append({"steam_id_remote": int(request.get("from", "0")), "data": Marshalls.base64_to_raw(str(request.get("data", "")))})
+		"peer_lobby":
+			var refusal = PeerRefusal(int(request.get("peer", "0")))
+			Reply(id, refusal == "", refusal if refusal != "" else "lobby open", {"lobby": str(get_node("/root/GlobalSteam").LOBBY_ID), "memberLimit": MemberLimit()})
+		"peer_attach": AttachPeer(id, int(request.get("peer", "0")), str(request.get("name", "")), bool(request.get("mock", false)))
+		"peer_detach":
+			DetachPeer(int(request.get("peer", "0")))
+			Reply(id, true, "local peer detached")
+		"peer_enter":
+			var scene = get_tree().current_scene
+			if peer_id == 0 or scene == null or scene.scene_file_path.get_file().get_basename() != "menu":
+				Reply(id, false, "the local peer can enter a lobby only from the main menu")
+				return
+			# as MP_CommandLineChecker.JoinGameOutsideLobby: the lobby scene joins this id once its intro ends
+			var globals = get_node("/root/GlobalVariables")
+			globals.lobby_id_found_in_command_line = int(request.get("lobby", "0"))
+			globals.running_short_intro_in_lobby_scene = true
+			globals.command_line_checked = true
+			get_tree().change_scene_to_file("res://multiplayer/scenes/mp_lobby.tscn")
+			Reply(id, true, "entering lobby")
+		"peer_joined":
+			SetRoster(request.get("roster", {}), false)
+			var response = Steam.CHAT_ROOM_ENTER_RESPONSE_SUCCESS if request.get("ok", false) else Steam.CHAT_ROOM_ENTER_RESPONSE_DOESNT_EXIST
+			Steam.lobby_joined.emit(int(request.get("lobby", "0")), 0, false, response)
+		"roster": SetRoster(request.get("roster", {}), true)
 		"quit":
 			ReleaseInputs()
 			Reply(id, true, "closing owned game")
@@ -591,3 +629,163 @@ func Capture(id):
 	await RenderingServer.frame_post_draw
 	var image = get_viewport().get_texture().get_image()
 	Reply(id, true, "captured", {"png": Marshalls.raw_to_base64(image.save_png_to_buffer())})
+
+# Local peer. The host keeps its Steam lobby; one more game process on this machine sits in it as a member Steam does not
+# know about. The calls below stand in for Steam's in the multiplayer scripts and give Steam everything else, so with no
+# local peer the game behaves as it does without the bridge. Member ids cross the bridge as strings: they exceed 2^53.
+#
+# Steam players can share the lobby: the host hands out seats and relays every packet, so their unmodified games seat the
+# local peer from the host's setup packet although Steam never lists it to them. Two things only Steam would tell them
+# are covered here: the seat the local peer takes (the Steam member limit drops by one) and its leaving mid-match,
+# which they could not see, so everyone goes back to the lobby. A local peer started with mock set is checked as such a
+# Steam player instead: it counts as one and its member list leaves the real local peer out, as Steam's would.
+
+func IsLocalPeer():
+	return peer_id != 0
+
+func AdoptPeerIdentity(steam):
+	if peer_id == 0: return
+	steam.STEAM_ID = peer_id
+	steam.STEAM_NAME = peer_name
+	steam.ONLINE = true
+
+func Lobby():
+	return get_node("/root/GlobalSteam").LOBBY_ID
+
+func SendP2PPacket(target, data, send_type, channel):
+	if peer_id != 0:
+		# members accept packets from the host only; the host relays the rest
+		if target == roster.owner: Send({"kind": "net", "from": str(peer_id), "to": str(target), "data": Marshalls.raw_to_base64(data)})
+		return true
+	if local_peers.has(target):
+		Send({"kind": "net", "from": str(get_node("/root/GlobalSteam").STEAM_ID), "to": str(target), "data": Marshalls.raw_to_base64(data)})
+		return true
+	return Steam.sendP2PPacket(target, data, send_type, channel)
+
+func GetAvailableP2PPacketSize(channel):
+	if relay_inbox.size() > 0: return relay_inbox[0].data.size()
+	if peer_id != 0: return 0
+	return Steam.getAvailableP2PPacketSize(channel)
+
+func ReadP2PPacket(size, channel):
+	if relay_inbox.size() > 0: return relay_inbox.pop_front()
+	if peer_id != 0: return {}
+	return Steam.readP2PPacket(size, channel)
+
+func NumLobbyMembers(lobby):
+	if peer_id != 0: return roster.members.size()
+	return Steam.getNumLobbyMembers(lobby) + (local_peers.size() if lobby == Lobby() else 0)
+
+func LobbyMemberByIndex(lobby, index):
+	if peer_id != 0: return roster.members[index].id
+	var count = Steam.getNumLobbyMembers(lobby)
+	if index < count or lobby != Lobby(): return Steam.getLobbyMemberByIndex(lobby, index)
+	return local_peers.keys()[index - count]
+
+func LobbyOwner(lobby):
+	if peer_id != 0: return roster.owner
+	return Steam.getLobbyOwner(lobby)
+
+func JoinLobby(lobby):
+	if peer_id == 0:
+		Steam.joinLobby(lobby)
+		return
+	# answered by a peer_joined request once the host has the peer in its lobby
+	Send({"kind": "peer", "event": "join", "lobby": str(lobby)})
+
+func LeaveLobby(lobby):
+	if peer_id != 0:
+		roster = {"lobby": 0, "owner": 0, "members": []}
+		Send({"kind": "peer", "event": "leave"})
+		return
+	Steam.leaveLobby(lobby)
+	if lobby != Lobby(): return
+	# As Steam would tell them: the host left and the lobby passed to them. A local peer mid-match exits as from a host
+	# that disconnected; one on the lobby screen holds a lobby nobody else is in.
+	for member in local_peers.keys():
+		Send({"kind": "roster", "peer": str(member), "roster": {"lobby": str(lobby), "owner": str(member), "members": [{"id": str(member), "name": local_peers[member].name}]}})
+	local_peers.clear()
+	last_rosters.clear()
+
+func SetLobbyMemberLimit(lobby, limit):
+	Steam.setLobbyMemberLimit(lobby, limit - RealPeerCount() if lobby == Lobby() else limit)
+
+func PersonaName(id):
+	if local_peers.has(id): return local_peers[id].name
+	if peer_id == 0: return Steam.getFriendPersonaName(id)
+	for member in roster.members:
+		if member.id == id: return member.name
+	return ""
+
+func RealPeerCount():
+	var count = 0
+	for member in local_peers.keys():
+		if !local_peers[member].mock: count += 1
+	return count
+
+## Members Steam lists, with mock Steam players counted among them.
+func SteamMemberCount():
+	return Steam.getNumLobbyMembers(Lobby()) + local_peers.size() - RealPeerCount()
+
+## Why this process cannot take `member` into its lobby now, or "".
+func PeerRefusal(member):
+	var steam = get_node("/root/GlobalSteam")
+	var scene = get_tree().current_scene
+	if peer_id != 0 or member == 0: return "not a host process"
+	if steam.LOBBY_ID == 0 or steam.STEAM_ID != steam.HOST_ID: return "not hosting a lobby"
+	if scene == null or scene.scene_file_path.get_file().get_basename() != "mp_lobby": return "not on the lobby screen"
+	if !local_peers.has(member) and SteamMemberCount() + RealPeerCount() >= steam.lobby_player_limit: return "the lobby is full"
+	return ""
+
+func AttachPeer(id, member, name, mock):
+	var refusal = PeerRefusal(member)
+	if refusal != "":
+		Reply(id, false, refusal)
+		return
+	var steam = get_node("/root/GlobalSteam")
+	local_peers[member] = {"name": name, "mock": mock}
+	if !mock: SetLobbyMemberLimit(steam.LOBBY_ID, steam.lobby_player_limit)
+	Steam.lobby_chat_update.emit(steam.LOBBY_ID, member, member, Steam.CHAT_MEMBER_STATE_CHANGE_ENTERED)
+	Reply(id, true, "local peer attached", {"roster": Roster(member), "memberLimit": MemberLimit()})
+
+func DetachPeer(member):
+	if !local_peers.has(member): return
+	var mock = local_peers[member].mock
+	local_peers.erase(member)
+	last_rosters.erase(member)
+	var steam = get_node("/root/GlobalSteam")
+	var handler = First("MP_UserInstanceHandler.gd")
+	if !mock and handler != null and SteamMemberCount() > 1 and handler.removing_instances and !handler.intermediary.game_state.MAIN_running_win_routine:
+		handler.Packet_ExitGameWithLobby()
+	Steam.lobby_chat_update.emit(steam.LOBBY_ID, member, member, Steam.CHAT_MEMBER_STATE_CHANGE_LEFT)
+	if !mock: SetLobbyMemberLimit(steam.LOBBY_ID, steam.lobby_player_limit)
+
+func MemberLimit():
+	return Steam.call("getLobbyMemberLimit", Lobby()) if Steam.has_method("getLobbyMemberLimit") else null
+
+## The member list `member` sees: all of it, or for a mock Steam player what Steam would list.
+func Roster(member):
+	var steam = get_node("/root/GlobalSteam")
+	var members = []
+	for entry in steam.LOBBY_MEMBERS:
+		if local_peers[member].mock and local_peers.has(entry.steam_id) and !local_peers[entry.steam_id].mock: continue
+		members.append({"id": str(entry.steam_id), "name": entry.steam_name})
+	return {"lobby": str(steam.LOBBY_ID), "owner": str(steam.HOST_ID), "members": members}
+
+func PublishRoster():
+	for member in local_peers.keys():
+		var current = Roster(member)
+		var serialized = JSON.stringify(current)
+		if serialized == last_rosters.get(member, ""): continue
+		last_rosters[member] = serialized
+		Send({"kind": "roster", "peer": str(member), "roster": current})
+
+func SetRoster(value, announce):
+	if !(value is Dictionary): return
+	var members = []
+	for member in value.get("members", []): members.append({"id": int(member.get("id", "0")), "name": str(member.get("name", ""))})
+	var next = {"lobby": int(value.get("lobby", "0")), "owner": int(value.get("owner", "0")), "members": members}
+	if JSON.stringify(next) == JSON.stringify(roster): return
+	roster = next
+	# as Steam's lobby_chat_update: the lobby scripts read the members again
+	if announce and Lobby() != 0 and Lobby() == roster.lobby: Steam.lobby_chat_update.emit(roster.lobby, roster.owner, roster.owner, Steam.CHAT_MEMBER_STATE_CHANGE_ENTERED)

package/src/peer.ts

@@ -0,0 +1,135 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
+import { dirname } from 'node:path';
+import { BuckshotBridge } from './bridge.ts';
+import type { BuckshotSnapshot } from './protocol.ts';
+
+/** The lobby member id the local peer takes; no Steam account has it. Strings, since ids exceed 2^53. */
+export const LOCAL_PEER_ID = '76561190000000001';
+
+export interface LocalPeerOptions {
+  /** The lobby member id, LOCAL_PEER_ID unless a check runs several peers. */
+  id: string;
+  /** Checks how Steam players fare: the host counts this peer as one and lists it what Steam would. */
+  mockSteamPlayer?: boolean;
+  executableFile: string;
+  packFile: string;
+  logFile: string;
+  name: string;
+  screenIndex: number | null;
+  muteAudio: boolean;
+  startupTimeoutMs: number;
+  actionTimeoutMs: number;
+  /** Called when the peer enters or leaves the host's lobby, and when its process ends. */
+  onChange(change: 'joined' | 'left' | 'closed'): void;
+}
+
+/**
+ * A second game process on this machine that joins the host game's multiplayer lobby. The host keeps its Steam lobby;
+ * the peer never initialises Steam and sits in that lobby as a member only the two bridges know about. Its packets,
+ * the host's member list and its join and leave requests pass through here.
+ */
+export class LocalPeer {
+  readonly bridge = new BuckshotBridge();
+  private game: ChildProcess | null = null;
+  private requests = Promise.resolve();
+  private detached = false;
+  joined = false;
+
+  constructor(private readonly host: BuckshotBridge, private readonly options: LocalPeerOptions) {}
+
+  get running(): boolean { return this.game !== null && this.game.exitCode === null; }
+
+  /** Starts the peer and sends it from its main menu into the host's lobby `lobby`. */
+  async start(lobby: string): Promise<void> {
+    const { options, bridge, host } = this;
+    const port = await bridge.start();
+    const log = createWriteStream(options.logFile, { flags: 'a' });
+    log.on('error', () => undefined);
+    const args = ['--windowed'];
+    if (options.screenIndex !== null) args.push('--screen', String(options.screenIndex));
+    if (options.muteAudio) args.push('--audio-driver', 'Dummy');
+    const game = spawn(options.executableFile, [...args, '--main-pack', options.packFile, '--', `--cortico-executable=${options.executableFile}`, `--cortico-port=${port}`, `--cortico-token=${bridge.token}`, `--cortico-peer-id=${options.id}`, `--cortico-peer-name=${options.name}`],
+      { cwd: dirname(options.executableFile), windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    this.game = game;
+    game.stdout?.pipe(log, { end: false }); game.stderr?.pipe(log, { end: false });
+    game.once('exit', () => { log.end(); void this.detach().then(() => options.onChange('closed')); });
+
+    host.on('net', this.fromHost);
+    host.on('roster', this.rosterFromHost);
+    bridge.on('net', this.fromPeer);
+    bridge.on('peer', this.lobbyRequest);
+    bridge.once('disconnected', () => { void this.detach(); });
+
+    try {
+      await this.until('游戏连接', (resolve, reject) => {
+        bridge.once('connected', (hello: { pid: number; version: string }) => hello.pid === game.pid && hello.version === 'v2.2.0.6' ? resolve() : reject(new Error('本地客户端的进程或版本与启动请求不匹配。')));
+        game.once('error', reject);
+        game.once('exit', () => reject(new Error('本地客户端在连接前退出。')));
+      });
+      await this.until('主菜单', (resolve) => {
+        const check = (snapshot: BuckshotSnapshot) => { if (snapshot.scene === 'menu') { bridge.off('snapshot', check); resolve(); } };
+        if (bridge.snapshot) check(bridge.snapshot);
+        bridge.on('snapshot', check);
+      });
+      const reply = await bridge.request('peer_enter', { lobby }, options.actionTimeoutMs);
+      if (!reply.ok) throw new Error(reply.detail);
+    } catch (error) {
+      await this.stop();
+      throw error;
+    }
+  }
+
+  async stop(): Promise<void> {
+    const game = this.game;
+    if (game?.exitCode === null) await this.bridge.request('quit', {}, this.options.actionTimeoutMs).catch(() => undefined);
+    await this.detach();
+    await this.bridge.stop();
+    if (game?.pid && game.exitCode === null) await new Promise<void>((resolve) => { game.once('close', () => resolve()); if (!game.kill()) resolve(); });
+  }
+
+  private until(what: string, wait: (resolve: () => void, reject: (error: Error) => void) => void): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error(`等待本地客户端${what}超时；检查 game-peer.log。`)), this.options.startupTimeoutMs);
+      wait(() => { clearTimeout(timer); resolve(); }, (error) => { clearTimeout(timer); reject(error); });
+    });
+  }
+
+  private readonly fromHost = (message: { to?: unknown; from?: unknown; data?: unknown }) => {
+    if (message.to === this.options.id) this.bridge.send('net', { from: message.from, data: message.data });
+  };
+
+  // The peer talks to the host only, whatever member it addresses.
+  private readonly fromPeer = (message: { data?: unknown }) => { this.host.send('net', { from: this.options.id, data: message.data }); };
+
+  private readonly rosterFromHost = (message: { peer?: unknown; roster?: unknown }) => { if (message.peer === this.options.id) this.bridge.send('roster', { roster: message.roster }); };
+
+  /** The peer's lobby scripts asked to join or leave; the host answers in order. */
+  private readonly lobbyRequest = (message: { event?: unknown; lobby?: unknown }) => {
+    this.requests = this.requests.then(async () => {
+      if (message.event === 'leave') { await this.leave(); return; }
+      if (message.event !== 'join') return;
+      const reply = await this.host.request('peer_attach', { peer: this.options.id, name: this.options.name, mock: this.options.mockSteamPlayer === true }, this.options.actionTimeoutMs).catch(() => null);
+      const roster = (reply as { roster?: { lobby?: string } } | null)?.roster;
+      const ok = reply?.ok === true && roster?.lobby === message.lobby;
+      if (reply?.ok && !ok) await this.leave();
+      this.bridge.send('peer_joined', { lobby: message.lobby, ok, roster: ok ? roster : {} });
+      if (ok && !this.joined) { this.joined = true; this.options.onChange('joined'); }
+    }).catch(() => undefined);
+  };
+
+  private async leave(): Promise<void> {
+    await this.host.request('peer_detach', { peer: this.options.id }, this.options.actionTimeoutMs).catch(() => undefined);
+    if (this.joined) { this.joined = false; this.options.onChange('left'); }
+  }
+
+  /** Takes the peer out of the host's lobby for good and stops relaying. */
+  private async detach(): Promise<void> {
+    if (this.detached) return;
+    this.detached = true;
+    this.host.off('net', this.fromHost);
+    this.host.off('roster', this.rosterFromHost);
+    await this.requests;
+    await this.leave();
+  }
+}

package/src/webui/client.ts

@@ -11,10 +11,12 @@ const game: WebUiPanel = {
     const start = ui.button('启动游戏', { variant: 'primary' });
     const stop = ui.button('关闭游戏', { variant: 'danger' });
     const capture = ui.button('查看画面');
+    const peerJoin = ui.button('本地加入');
+    const peerLeave = ui.button('退出本地');
     const preview = ui.h('img');
     preview.alt = '游戏当前画面';
     preview.style.cssText = 'display:none;width:100%;height:auto;margin-top:12px;';
-    actions.append(start, stop, capture);
+    actions.append(start, stop, capture, peerJoin, peerLeave);
     card.body.append(status, message, actions, preview);
     ctx.root.append(card.el);
     let busy = false;
@@ -26,21 +28,26 @@ const game: WebUiPanel = {
         { k: '场景', v: state.scene ?? '—' },
         { k: '模式', v: state.mode ?? '—' },
         { k: '轮次', v: state.round === undefined ? '—' : String(state.round) },
+        { k: '本地玩家', v: ui.pill({ offline: '未加入', starting: '启动中', menu: '未进房间', joined: '在房间里' }[state.peer], state.peer === 'joined' ? 'on' : 'off') },
       ]));
-      message.textContent = state.error;
+      message.textContent = state.error || state.peerError;
       start.disabled = busy || state.state === 'online' || state.state === 'loading';
       stop.disabled = busy || !state.stoppable;
       capture.disabled = busy || state.state !== 'online';
+      peerJoin.disabled = busy || state.state !== 'online' || state.peer !== 'offline';
+      peerLeave.disabled = busy || state.peer === 'offline';
     }
     async function refresh() { if (!ctx.signal.aborted) render(await ctx.invoke<BuckshotGameState>('state')); }
-    async function act(method: 'start' | 'stop') {
-      busy = true; start.disabled = stop.disabled = capture.disabled = true;
+    async function act(method: 'start' | 'stop' | 'peerJoin' | 'peerLeave') {
+      busy = true; start.disabled = stop.disabled = capture.disabled = peerJoin.disabled = peerLeave.disabled = true;
       try { render(await ctx.invoke<BuckshotGameState>(method)); await ctx.refresh(); }
       catch (error) { message.textContent = error instanceof Error ? error.message : String(error); }
       finally { busy = false; await refresh().catch(() => undefined); }
     }
     start.addEventListener('click', () => { void act('start'); }, { signal: ctx.signal });
     stop.addEventListener('click', () => { void act('stop'); }, { signal: ctx.signal });
+    peerJoin.addEventListener('click', () => { void act('peerJoin'); }, { signal: ctx.signal });
+    peerLeave.addEventListener('click', () => { void act('peerLeave'); }, { signal: ctx.signal });
     capture.addEventListener('click', () => {
       void ctx.invokeBinary('capture').then((blob) => {
         if (ctx.signal.aborted) return;

package/src/webui/types.ts

@@ -5,4 +5,7 @@ export interface BuckshotGameState {
   scene?: string;
   mode?: string;
   round?: number;
+  /** The local peer: not running, starting, at its menu, or in this game's lobby. */
+  peer: 'offline' | 'starting' | 'menu' | 'joined';
+  peerError: string;
 }

package/src/world.ts

@@ -16,6 +16,7 @@ import { BUCKSHOT_PANEL_DECLS } from './webui/panels.ts';
 import type { BuckshotGameState } from './webui/types.ts';
 import { describeObservation, frameKey } from './events.ts';
 import { Settlement } from './settle.ts';
+import { LOCAL_PEER_ID, LocalPeer } from './peer.ts';
 
 const ENV_PROMPT_FILE = fileURLToPath(new URL('./ENV_PROMPT.md', import.meta.url));
 
@@ -39,6 +40,10 @@ export class BuckshotWorld implements World {
   private readonly narrator = new StateNarrator();
   /** While an input waits for its settlement: the observations go into its receipt instead of events. */
   private settling: { observations: string[] } | null = null;
+  /** The second local game process that joins this game's multiplayer lobby; see LocalPeer. */
+  private peer: LocalPeer | null = null;
+  private peerStarting: Promise<void> | null = null;
+  private peerError = '';
 
   constructor(private readonly ctx: WorldContext<BuckshotConfigSection>) {}
 
@@ -83,6 +88,8 @@ export class BuckshotWorld implements World {
         if (panel !== 'game') throw new Error('未知面板。');
         if (method === 'start') await this.startGame();
         else if (method === 'stop') await this.stopGame();
+        else if (method === 'peerJoin') await this.startPeer();
+        else if (method === 'peerLeave') await this.stopPeer();
         else if (method === 'capture') {
           const reply = await this.request('capture', {});
           if (!reply.ok || !reply.png) throw new Error(reply.detail);
@@ -99,7 +106,8 @@ export class BuckshotWorld implements World {
 
   private gameState(): BuckshotGameState {
     const snapshot = this.bridge?.snapshot;
-    return { state: this.state, error: this.error, stoppable: this.game !== null || this.starting !== null, scene: snapshot?.scene, mode: snapshot?.mode, round: snapshot?.round };
+    const peer = this.peerStarting ? 'starting' : this.peer?.joined ? 'joined' : this.peer ? 'menu' : 'offline';
+    return { state: this.state, error: this.error, stoppable: this.game !== null || this.starting !== null, scene: snapshot?.scene, mode: snapshot?.mode, round: snapshot?.round, peer, peerError: this.peerError };
   }
 
   async start(host: WorldHost): Promise<void> {
@@ -112,6 +120,7 @@ export class BuckshotWorld implements World {
     if (this.frameTimer) clearTimeout(this.frameTimer);
     this.frameTimer = null;
     this.frameWanted = false;
+    await this.stopPeer();
     if (this.ctx.cfg.closeOnStop) await this.stopGame();
     else { await this.bridge?.stop(); this.bridge = null; this.game = null; this.state = 'offline'; }
     await this.eventTail;
@@ -205,7 +214,7 @@ export class BuckshotWorld implements World {
         if (['shot', 'reveal', 'revival', 'result', 'dialogue'].includes(event.kind)) this.scheduleFrame();
       });
       bridge.on('fault', (error: Error) => { this.state = 'error'; this.error = error.message; void this.emit('error', error.message); });
-      bridge.on('disconnected', () => { if (this.bridge === bridge) { this.state = 'offline'; void this.emit('disconnected', '游戏事件桥已断开。'); } });
+      bridge.on('disconnected', () => { void this.stopPeer(); if (this.bridge === bridge) { this.state = 'offline'; void this.emit('disconnected', '游戏事件桥已断开。'); } });
       const port = await bridge.start();
       const logDir = join(this.ctx.dataDir, 'buckshot');
       await mkdir(logDir, { recursive: true });
@@ -245,7 +254,51 @@ export class BuckshotWorld implements World {
     }
   }
 
+  /** Starts the local peer once this game hosts a lobby on its lobby screen; it joins that lobby on its own. */
+  async startPeer(): Promise<void> {
+    if (this.peerStarting) return this.peerStarting;
+    if (this.peer) throw new Error('本地客户端已在运行。');
+    const bridge = this.bridge;
+    if (!bridge || this.state !== 'online') throw new Error('先启动游戏并等它连接。');
+    this.peerError = '';
+    this.peerStarting = (async () => {
+      const lobby = await bridge.request('peer_lobby', { peer: LOCAL_PEER_ID }, this.ctx.cfg.actionTimeoutMs);
+      if (!lobby.ok) throw new Error(`${{ 'not hosting a lobby': '可缇还没有在多人模式里建房间。', 'not on the lobby screen': '房间已经离开大厅界面（对局进行中）。', 'the lobby is full': '房间已满。' }[lobby.detail] ?? lobby.detail}`);
+      const executableFile = normalizeExecutableFile(this.ctx.cfg.executableFile);
+      const runtimeDir = this.ctx.cfg.runtimeDir || join(this.ctx.botDir, 'runtimes', 'buckshot');
+      const packFile = await prepareImplant(executableFile, runtimeDir, 'local-peer');
+      const logDir = join(this.ctx.dataDir, 'buckshot');
+      await mkdir(logDir, { recursive: true });
+      const options = this.ctx.cfg.localPeer;
+      const name = options.name.trim() || 'Player 2';
+      const peer = new LocalPeer(bridge, {
+        id: LOCAL_PEER_ID, executableFile, packFile, logFile: join(logDir, 'game-peer.log'), name, screenIndex: options.screenIndex, muteAudio: options.muteAudio,
+        startupTimeoutMs: this.ctx.cfg.startupTimeoutMs, actionTimeoutMs: this.ctx.cfg.actionTimeoutMs,
+        onChange: (change) => {
+          if (change === 'joined') void this.emit('peer', `本地玩家 ${name} 加入了房间。`);
+          if (change === 'left') void this.emit('peer', `本地玩家 ${name} 离开了房间。`);
+          if (change === 'closed' && this.peer === peer) this.peer = null;
+        },
+      });
+      this.peer = peer;
+      await peer.start((lobby as { lobby?: string }).lobby ?? '');
+    })().catch((error) => {
+      this.peer = null;
+      this.peerError = error instanceof Error ? error.message : String(error);
+      throw error;
+    }).finally(() => { this.peerStarting = null; });
+    return this.peerStarting;
+  }
+
+  async stopPeer(): Promise<void> {
+    if (this.peerStarting) await this.peerStarting.catch(() => undefined);
+    const peer = this.peer;
+    this.peer = null;
+    await peer?.stop();
+  }
+
   async stopGame(): Promise<void> {
+    await this.stopPeer();
     if (this.frameTimer) clearTimeout(this.frameTimer);
     this.frameTimer = null;
     this.frameWanted = false;