内容
# 千星沙箱模拟器
面向千星奇域 **2D + Lua 脚本驱动的游戏开发**的独立模拟器：在游戏之外执行客户端 Lua 脚本、显示 UI、响应操作，并让 AI 直接试玩游戏。
提供 **Web 编辑器、MCP 服务和 DeepSeek Harness 插件**三种接入方式，共用同一套模拟器核心。可以独立在浏览器中使用，也可以通过 MCP 接入 OpenCode、WorkBuddy、Codex 等 AI 工具，配合 Web 查看和试玩。
你可以在浏览器中编辑界面、调试脚本，也可以让 AI 读取工程、修改控件、点击按钮、发送按键、查看截图与日志，完成“编写 → 试玩 → 检查 → 修改”的开发循环。日常调试无需反复打开游戏和官方编辑器，完成后再导出资产进行真机验证。
## 包含什么
| 能力 | 你可以做什么 |
|---|---|
| **可视化 UI 编辑器** | 查看控件树，调整位置、尺寸、锚点和属性；创建 11 类客户端控件，其中图片、文本框和预设按钮提供较完整的编辑能力。 |
| **Lua 脚本模拟运行** | 管理多个脚本并挂载到客户端控件或模板，检查脚本生命周期、UI 操作、输入响应和动画效果。 |
| **独立试玩窗口** | 启动、暂停、继续和单步运行，通过鼠标、触摸或按键测试交互，查看运行状态、日志和错误。 |
| **多设备与多玩家模拟** | 在 5 种 PC / 手机画布上检查布局；在本地模拟 1–8 名玩家，切换视角检查变量与信号交互。 |
| **AI 试玩与自动测试** | 通过工具直接编辑工程、驱动操作、获取截图；记录操作时间线，回放用例并检查控件、变量和日志。 |
| **七步游戏制作工作流** | 从策划案与测试用例出发，展示 HTML 效果、准备千星美术素材，再完成 Lua 编码、测试与真机反馈修复。 |
| **存档与资产交换** | 用完整 JSON 存档保存工程，导入导出 UI、Lua 脚本及已支持的 GIA 内容，衔接后续编辑与交付。 |
11 类控件的实际运行能力和缺口见 [客户端控件支持矩阵](studio/docs/control-support.md)。文本视窗、网格视窗现支持基础滚轮/拖拽/触摸与滚动条；编辑、字段存取与完整仿真程度分别说明。
## 集成方式
按你的开发环境选择接入方式。Web 可以独立使用；让 AI 直接编辑和测试工程时使用 MCP；需要边对话边看画面时组合 MCP + Web：
| 方式 | 适合谁 | 使用体验 |
|---|---|---|
| **[Web 编辑器](#web-部署)** | 在浏览器中编辑、调试，或配合外部 AI 工具查看结果 | 独立运行 UI/Lua 编辑器与试玩窗口，预览磁盘中的工程存档。 |
| **[MCP 服务](#mcp-接入)** | 使用 OpenCode、WorkBuddy、Codex 等支持本地 MCP stdio 的 AI 工具 | 向 AI 提供工程编辑、试玩、截图和保存工具，可独立使用或配合 Web。 |
| **[DeepSeek Harness 插件](#deepseek-harness-插件)** | 使用 DeepSeek Harness | 在 Harness 内嵌编辑器、注册模拟器工具，并提供 Skill 与 Agent 预设。 |
三个包已发布到 npm，也可从 GitHub 源码或本地构建的 `.tgz` 安装。Web 包名和启动命令均为 `beyond-simulator-web`。本地安装包路径以仓库根目录为基准；当前版本及文件名见 `release/manifest.json`。
### Web 部署
准备 **Node.js 22+**，从 npm 安装后即可启动完整前后端：
```sh
npm install -g beyond-simulator-web
mkdir ../my-game
beyond-simulator-web --workspace ../my-game --open
```
也可以从源码启动。准备 **pnpm 10.15.0**，在本仓库根目录执行：
```sh
pnpm install --frozen-lockfile
mkdir ../my-game
pnpm dev:web --workspace ../my-game
```
这里的 `my-game` 是保存游戏文件的工作区。已有项目时，跳过创建目录，将参数换成现有目录，例如 `--workspace E:/my-game`。
启动后打开：
- [编辑器](http://127.0.0.1:4173/editor)：编辑 UI、Lua 和服务端逻辑，保存存档并试玩。
- [存档预览](http://127.0.0.1:4173/)：查看工作区中已保存的存档，文件更新后自动刷新，适合配合 AI 或外部编辑器使用。
Web 也支持安装预构建包运行，仓库提供了 Docker 部署配置。对外部署时需配置访问口令和 HTTPS；当前面向单个可信操作者，不提供网站用户之间的项目权限隔离。安装包、Docker 和部署参数见 [Web 使用与部署指南](web/README.md)。
### MCP 接入
在 OpenCode、WorkBuddy、Codex 等支持本地 MCP stdio 服务的 AI 工具中配置模拟器，指定游戏工作区后，AI 即可打开、编辑和保存工程，控制试玩并获取画面。各客户端的配置入口和格式不同，共用以下服务命令与参数：
从 npm 安装：
```sh
npm install -g beyond-simulator-mcp
```
然后在客户端中添加本地 stdio 服务：
| 配置项 | 值 |
|---|---|
| 服务名（自定） | `qxqy-simulator` |
| 命令 | `beyond-simulator-mcp` |
| 参数 | `--workspace`、已有游戏目录的绝对路径，例如 `E:/my-game` |
客户端配置可参考 [OpenCode MCP 文档](https://opencode.ai/docs/mcp-servers/)、[WorkBuddy MCP 连接器文档](https://open.workbuddy.cn/docs/connector)及本仓库的 [Codex 配置示例](mcp/README.md#codex-接入)。接入后先检查 `qxqy_project_open`、`qxqy_studio_play` 等工具是否可见；安装 MCP 包不会自动安装游戏制作 Skill。
MCP 可以独立使用。组合 Web 时，让两者的 `--workspace` 指向同一个本地目录：AI 用 MCP 修改工程并显式保存 JSON，Web 的“存档预览”重新加载当前文件，用户在浏览器中查看和试玩。切换到另一份存档时可调用 `qxqy_preview_open`。Web 编辑器中的未保存草稿不会被自动覆盖。
只使用 Web 时，AI 也可以在工作区编辑 Lua 和工程文件，由用户在 Web 中加载检查；能否直接操作网页取决于 AI 客户端实际提供的浏览器工具。Web 服务本身不注册 MCP 工具。
安装方式、客户端配置和工具示例见 [MCP 接入指南](mcp/README.md)。
### DeepSeek Harness 插件
准备 Node.js 22+ 和 DeepSeek Harness，选择下面一种安装方式。GitHub 安装还需要 Git，会自动从源码构建；本地安装包路径以仓库根目录为基准，可按文末的[构建说明](#从源码构建)生成，文件名以 `release/manifest.json` 为准。
插件 2.0.7 起将 Harness **0.2 系列（含 `0.2.0-rc.1` 起的候选版本）**纳入安装范围，保留 0.1 系列支持；已验收 `0.2.0-rc.2`。版本检查、预设资源路径及验证范围见 [Harness 0.2 兼容说明](dsh-plugin/README.md#harness-02-兼容性)。
```sh
# 从 npm 安装
dsh plugin --profile web add dsh-plugin-beyond-simulator
# 或，从 GitHub 默认分支源码安装
dsh plugin --profile web add github:1475505/miliastra-beyond-simulator
# 或，从本地安装包安装
dsh plugin --profile web add ./release/dsh-plugin-beyond-simulator-2.0.8.tgz
dsh --profile web --dump-config
dsh web
```
为会话绑定游戏项目工作区，打开“模拟器”视图，即可编辑 UI 和 Lua 并启动试玩。插件同时提供模拟器操作 Skill，以及“千星 2D+Lua 游戏制作”Agent 预设；新建会话时可以选择该预设。
更新已有插件时，执行同一条安装命令，再重启 Harness。已有的用户 Agent 预设会保留，不会随插件升级自动覆盖。
安装配置与工具说明见 [Harness 插件指南](dsh-plugin/README.md)。
GitHub 安装使用仓库默认分支，安装时由 `prepare` 自动构建。首次安装若 pnpm 提示需要批准构建，请按提示允许该插件的构建脚本，再重新执行安装命令。安装入口是整个仓库，不需要指定子目录。详见 [分发说明](DISTRIBUTION.md#harness-安装入口)。
## 用 Agent 七步制作游戏
仓库提供可供 AI 按需读取的[七步制作 Skill](agent/wonderland-lua-builder/skills/qxqy-game-studio/SKILL.md)。提供游戏想法、参考图或已有工程后，AI 按当前步骤读取对应 Markdown，逐步完成制作。
在 OpenCode、WorkBuddy、Codex 等工具中，可让 AI 读取该 Skill 和随附的 `references/`，并通过 MCP 操作模拟器；在 Harness 中，可直接选择插件附带的“千星 2D+Lua 游戏制作”Agent 预设。工作流内容和 Harness 注册配置分开维护，接入方法见 [Agent / Skill 使用说明](agent/wonderland-lua-builder/README.md)。
启动制作时，AI 先检查工作区和当前 AI 工具配置中的 `miliastra-toolbox` 系列、其他知识库服务或本地资料，确认能否读取所需的官方 2D/Lua API 文档与使用指南。已有资料直接复用，只在缺项时提示补充；具体规则见[启动前知识库检查](agent/wonderland-lua-builder/skills/qxqy-game-studio/references/workflow.md#知识库发现与可用性核验)。模拟器安装包不捆绑官方知识库。
| 步骤 | Agent 会做什么 | 你会得到什么 |
|---|---|---|
| **1. 策划案** | 明确核心玩法、操作方式、计分与胜负规则，以及首版功能范围。 | 指导后续制作的游戏策划案。 |
| **2. TDD 制定测试用例** | 制定测试用例，测试驱动开发；先写清开局、成功、失败、重开及边界情况的操作与预期结果。 | 与策划规则对应、用于驱动实现的测试用例。 |
| **3. HTML 效果展示** | 制作可以打开试玩的 HTML 演示，与你确认画面、操作和节奏。 | 在正式编码前可以体验和调整的效果展示。 |
| **4. 准备千星美术参考图和素材** | 根据确认的效果整理或制作参考图，核对可用的千星图片资源与图元，规划素材的使用方式。 | 美术参考图、素材清单和 UI 还原方案。 |
| **5. Lua 编码实现** | 按策划案和测试用例编写 Lua，搭建 UI、接入素材，在模拟器中逐项实现功能并验证。 | 可以在模拟器运行的 Lua 游戏与完整存档。 |
| **6. 测试** | 执行测试用例，让 AI 实际操作游戏，检查画面、日志、交互和设备适配，修复问题并回归。 | 测试结果、问题记录与通过模拟器验证的游戏版本。 |
| **7. 真机试玩验证与 bug 修复** | 交接导入与脚本挂载，协助校准真实索引、绑定脚本更新目录，再根据真机回传修复和回归。 | 游戏资产、导入与后续更新说明、真机结果及待处理项。 |
先用策划案和测试用例明确目标，再用 HTML 展示确认体验，随后准备千星美术参考图和素材，进入 Lua 编码与测试。最终交付的是 Lua、完整存档和可导出的游戏资产；真机试玩发现的问题继续进入修复与回归。
可以这样开始：
> 我想做一个适合手机操作的 2D 小游戏：点击躲避障碍，连续成功会加分。请先写策划案并制定 TDD 测试用例，再做 HTML 效果展示。确认后准备千星美术参考图和素材，完成 Lua 编码与测试，最后配合我真机试玩并修复 bug。
已有工程可以从需要补齐的环节继续；玩法变化时同步更新策划案与测试用例，修复 bug 后重新执行相关测试。
## 使用指南
### 1. 准备工程
一个存档集中管理三类资产：**服务端 UI、客户端 UI 模板和 Lua 脚本**。它们共同组成试玩所需的界面与逻辑。
- 从零开始：在编辑器中添加控件、创建客户端模板，再编写 Lua 脚本。
- 继续已有工程：从顶栏“工作区存档”选择已保存的项目，或点击“导入”打开本地文件。
- 迁入现有资产：导入支持的 UI JSON、GIA 或 Lua，再检查布局和脚本挂载关系。
编写 Lua 时，AI 使用启动前已经核验的知识来源，按当前需求读取官方 API、指南和实战经验；“已配置知识库”还需核实当前会话能否读取所需资料。需要从参考图制作美术时，也可以配合工作区已有的像素画、图元拟合、UI 制作或帧动画 Skill。
### 2. 编辑并试玩
1. 在“UI 编辑”页添加控件，调整属性，并切换 PC / 手机画布检查适配。
2. 在“Lua 脚本”页创建或导入脚本，将入口脚本挂载到客户端控件或客户端模板；模板脚本在模板实例化时运行。
3. 如果玩法需要服务端响应，在“服务端逻辑”页配置监听信号、设置变量和向玩家发送信号。
4. 点击“试玩 ↗”，在独立窗口中操作游戏；Desktop 等宿主拒绝新窗口时自动进入应用内全屏试玩。遇到问题时暂停、单步推进，并查看“日志”页中的脚本输出与运行状态。内嵌时通过“返回编辑”“关闭试玩”或 Escape 停止并返回。
5. 返回编辑器修改，再次试玩；需要检查多人交互时，调整试玩人数并切换玩家视角。
### 3. 让 AI 帮你测试
通过 Harness 插件或 MCP 接入后，可以直接描述要检查的行为，例如：
> 打开我的游戏存档，在手机 16:9 画布上试玩。点击开始按钮，检查得分是否变化，截取操作后的画面，并告诉我日志里有没有报错。
也可以把操作整理成可重复执行的测试：
> 把“开始游戏 → 点击目标 → 得分增加”记录成测试用例。修改脚本后重新回放，检查得分和界面状态是否符合预期。
AI 可以直接获取工程状态、发送输入、读取日志和截图，无需你手动切换到试玩窗口。涉及玩法规则时，请提供预期结果，例如“每次点击加 1 分”“玩家 1 的操作不应改变玩家 2 的分数”。
### 4. 保存与导出
继续开发时，优先保存完整存档；需要与外部编辑链路交换资产时，再选择相应导出格式。
| 目的 | 推荐方式 |
|---|---|
| 保存进度、备份或交给 AI 继续修改 | 导出“资产包 JSON（三类合一）”，保留 UI、脚本和挂载关系。 |
| 保存到 Web 服务的工作区 | 点击“保存存档”，填写工作区内的相对路径，例如 `my-game.save.json`。 |
| 与官方编辑器交换已支持的资产 | 导出对应的 GIA，并检查导出提示及导入后的实际效果。 |
| 单独交换 UI 或脚本 | 导出当前界面 Authoring JSON、脚本包或单个 Lua 脚本。 |
编辑和试玩不会自动把完整存档写入磁盘。Web 用户请显式保存，Harness 用户可导出 JSON，MCP 用户可让 AI 调用保存工具；关闭服务前先保存未完成的工作。
### 5. 导入真机并持续更新
首次交付时，AI 会根据工程给出需要导入的文件、脚本映射与挂载位置，以及试玩步骤。你需要在千星沙箱完成导入，核对实际控件/模板索引；索引变化可通过对话告知 AI，或在模拟器中修改后让 AI 同步脚本。直接手改脚本时也应将最终修改同步回工程。
后续更新可以在 Web/DSH 的“Lua 脚本 → 实机脚本同步”绑定该关卡导入后的脚本目录。AI 准备修改并预览差异，你检查目标路径、选择文件并确认复制，然后在千星沙箱保存并重新试玩。目录绑定随完整存档保存，便于下次复用；新增脚本仍需建立映射和必要挂载。
如果模拟器服务无法访问游戏所在电脑的目录，可按交付说明手动更新。完整分工见 [真机交付与验证](agent/wonderland-lua-builder/skills/qxqy-game-studio/references/07-device-validation.md)，目录配置与复制说明见 [实机脚本同步](studio/docs/script-sync.md)。
## 当前支持边界
- **模拟器通过不等于真机通过。** 它用于提前发现脚本、布局和交互问题，最终仍需在千星奇域中验证。
- **服务端模拟覆盖变量与信号。** 1–8 人试玩是本地多客户端模拟，不包含完整官方服务端节点图或真实网络联机。
- **图片预览以基础图元为主。** 当前用代理图形显示图片 ID `100001–100006`，其他素材显示缺失提示；安装包不包含完整官方图片和动效资源。
- **GIA 支持已验证的内容子集。** 部分控件属性与脚本挂载关系无法完整交换，导出时请关注提示，并保留原始文件及完整 JSON 存档。
## 从源码构建
开发环境为 Node.js 22+、pnpm 10.15.0。首次安装依赖后，可以在仓库根目录构建和测试：
```sh
pnpm install --frozen-lockfile
pnpm build
pnpm test
```
生成可交付的 Web、Harness 和 MCP 安装包：
```sh
pnpm pack:release
pnpm test:packages
```
安装包生成在 `release/`，本次产物的名称、版本与校验值见 `release/manifest.json`。包中已包含模拟器核心及所需界面资源，使用者无需构建源码；安装时仍会下载第三方运行依赖。
测试套件完全自包含，只依赖仓库内源码与合成数据，独立检出即可运行。模块分工见 [开发入口](AGENTS.md)，构建、验收与发布设计见 [分发说明](DISTRIBUTION.md)。
自动发布通过 `npm-*` Git tag 触发；需要先在 npm 为三个包绑定同一份 GitHub Actions Trusted Publisher。配置项和版本规则见 [自动发布说明](DISTRIBUTION.md#自动发布到-npm)。
## 开源协议
本项目采用 [GNU GPL v3.0（GPL-3.0-only）](LICENSE)。源码仓库：[1475505/miliastra-beyond-simulator](https://github.com/1475505/miliastra-beyond-simulator)。
连接信息
猜你喜欢
暂无推荐服务器