千星沙箱模拟器

面向千星奇域 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 内容，衔接后续编辑与交付。

集成方式

按你的开发环境选择接入方式。Web 可以独立使用；让 AI 直接编辑和测试工程时使用 MCP；需要边对话边看画面时组合 MCP + Web：

方式	适合谁	使用体验
Web 编辑器	在浏览器中编辑、调试，或配合外部 AI 工具查看结果	独立运行 UI/Lua 编辑器与试玩窗口，预览磁盘中的工程存档。
MCP 服务	使用 OpenCode、WorkBuddy、Codex 等支持本地 MCP stdio 的 AI 工具	向 AI 提供工程编辑、试玩、截图和保存工具，可独立使用或配合 Web。
DeepSeek Harness 插件	使用 DeepSeek Harness	在 Harness 内嵌编辑器、注册模拟器工具，并提供 Skill 与 Agent 预设。

三个包已发布到 npm，也可从 GitHub 源码或本地构建的 .tgz 安装。Web 包名和启动命令均为 beyond-simulator-web。本地安装包路径以仓库根目录为基准；当前版本及文件名见 release/manifest.json。

Web 部署

准备 Node.js 22+，从 npm 安装后即可启动完整前后端：

npm install -g beyond-simulator-web
mkdir ../my-game
beyond-simulator-web --workspace ../my-game --open

也可以从源码启动。准备 pnpm 10.15.0，在本仓库根目录执行：

pnpm install --frozen-lockfile
mkdir ../my-game
pnpm dev:web --workspace ../my-game

这里的 my-game 是保存游戏文件的工作区。已有项目时，跳过创建目录，将参数换成现有目录，例如 --workspace E:/my-game。

启动后打开：

• 编辑器：编辑 UI、Lua 和服务端逻辑，保存存档并试玩。
• 存档预览：查看工作区中已保存的存档，文件更新后自动刷新，适合配合 AI 或外部编辑器使用。

Web 也支持安装预构建包运行，仓库提供了 Docker 部署配置。对外部署时需配置访问口令和 HTTPS；当前面向单个可信操作者，不提供网站用户之间的项目权限隔离。安装包、Docker 和部署参数见 Web 使用与部署指南。

MCP 接入

在 OpenCode、WorkBuddy、Codex 等支持本地 MCP stdio 服务的 AI 工具中配置模拟器，指定游戏工作区后，AI 即可打开、编辑和保存工程，控制试玩并获取画面。各客户端的配置入口和格式不同，共用以下服务命令与参数：

从 npm 安装：

npm install -g beyond-simulator-mcp

然后在客户端中添加本地 stdio 服务：

配置项	值
服务名（自定）	qxqy-simulator
命令	beyond-simulator-mcp
参数	--workspace、已有游戏目录的绝对路径，例如 E:/my-game

客户端配置可参考 OpenCode MCP 文档、WorkBuddy MCP 连接器文档及本仓库的 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 接入指南。

DeepSeek Harness 插件

准备 Node.js 22+ 和 DeepSeek Harness，选择下面一种安装方式。GitHub 安装还需要 Git，会自动从源码构建；本地安装包路径以仓库根目录为基准，可按文末的构建说明生成，文件名以 release/manifest.json 为准。

# 从 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-1.0.10.tgz

dsh --profile web --dump-config
dsh web

…