1475505/miliastra-beyond-simulator

千星沙箱模拟器

面向千星奇域 2D + Lua 脚本驱动的游戏开发，提供一套在游戏之外运行的模拟工具：执行客户端 Lua 脚本、显示 UI、响应操作，并让 AI 直接试玩游戏。

你可以在浏览器中编辑界面、调试脚本，也可以让 AI 读取工程、修改控件、点击按钮、发送按键、查看截图与日志，完成“编写 → 试玩 → 检查 → 修改”的开发循环。日常调试无需反复打开游戏和官方编辑器，完成后再导出资产进行真机验证。

用 Agent 七步制作游戏

Harness 插件附带“千星 2D+Lua 游戏制作”Agent 预设。新建会话时选择它，提供游戏想法、参考图或已有工程，按下面七步与 Agent 协作完成游戏。

| 步骤 | Agent 会做什么 | 你会得到什么 |
|---|---|---|
| 1. 策划案 | 明确核心玩法、操作方式、计分与胜负规则，以及首版功能范围。 | 指导后续制作的游戏策划案。 |
| 2. TDD 制定测试用例 | 制定测试用例，测试驱动开发；先写清开局、成功、失败、重开及边界情况的操作与预期结果。 | 与策划规则对应、用于驱动实现的测试用例。 |
| 3. HTML 效果展示 | 制作可以打开试玩的 HTML 演示，与你确认画面、操作和节奏。 | 在正式编码前可以体验和调整的效果展示。 |
| 4. 准备千星美术参考图和素材 | 根据确认的效果整理或制作参考图，核对可用的千星图片资源与图元，规划素材的使用方式。 | 美术参考图、素材清单和 UI 还原方案。 |
| 5. Lua 编码实现 | 按策划案和测试用例编写 Lua，搭建 UI、接入素材，在模拟器中逐项实现功能并验证。 | 可以在模拟器运行的 Lua 游戏与完整存档。 |
| 6. 测试 | 执行测试用例，让 AI 实际操作游戏，检查画面、日志、交互和设备适配，修复问题并回归。 | 测试结果、问题记录与通过模拟器验证的游戏版本。 |
| 7. 真机试玩验证与 bug 修复 | 导出资产供你在千星奇域中试玩，根据真机回传复现并修复 bug，再验证修复结果。 | 经真机验证的游戏资产、修复记录及尚待处理的问题说明。 |

先用策划案和测试用例明确目标，再用 HTML 展示确认体验，随后准备千星美术参考图和素材，进入 Lua 编码与测试。最终交付的是 Lua、完整存档和可导出的游戏资产；真机试玩发现的问题继续进入修复与回归。

可以这样开始：

我想做一个适合手机操作的 2D 小游戏：点击躲避障碍，连续成功会加分。请先写策划案并制定 TDD 测试用例，再做 HTML 效果展示。确认后准备千星美术参考图和素材，完成 Lua 编码与测试，最后配合我真机试玩并修复 bug。

已有工程可以从需要补齐的环节继续；玩法变化时同步更新策划案与测试用例，修复 bug 后重新执行相关测试。

包含什么

| 能力 | 你可以做什么 |
|---|---|
| 可视化 UI 编辑器 | 查看控件树，调整位置、尺寸、锚点和属性；创建 11 类客户端控件，其中图片、文本框和预设按钮提供较完整的编辑能力。 |
| Lua 脚本模拟运行 | 管理多个脚本并挂载到客户端控件或模板，检查脚本生命周期、UI 操作、输入响应和动画效果。 |
| 独立试玩窗口 | 启动、暂停、继续和单步运行，通过鼠标、触摸或按键测试交互，查看运行状态、日志和错误。 |
| 多设备与多玩家模拟 | 在 5 种 PC / 手机画布上检查布局；在本地模拟 1–8 名玩家，切换视角检查变量与信号交互。 |
| AI 试玩与自动测试 | 通过工具直接编辑工程、驱动操作、获取截图；记录操作时间线，回放用例并检查控件、变量和日志。 |
| 游戏制作 Agent | 从策划案与测试用例出发，展示 HTML 效果、准备千星美术素材，再完成 Lua 编码、测试与真机反馈修复。 |
| 存档与资产交换 | 用完整 JSON 存档保存工程，导入导出 UI、Lua 脚本及已支持的 GIA 内容，衔接后续编辑与交付。 |

集成方式

按你的开发环境选择一种接入方式，也可以组合使用：

| 方式 | 适合谁 | 使用体验 |
|---|---|---|
| DeepSeek Harness 插件 | 希望在 AI 对话中完成游戏开发的人 | 在 Harness 内打开编辑器，让 Agent 操作同一份工程并试玩。 |
| Web 部署 | 希望直接在浏览器中编辑、调试的人 | 启动一个包含前后端的服务，通过浏览器编辑和试玩，无需 Harness。 |
| MCP 接入 | 使用其他支持 MCP 的 AI 客户端的人 | 向 AI 提供工程编辑、试玩、截图和保存工具，可配合 Web 查看结果。 |

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

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

为会话绑定游戏项目工作区，打开“模拟器”视图，即可编辑 UI 和 Lua 并启动试玩。插件同时提供模拟器操作 Skill，以及“千星 2D+Lua 游戏制作”Agent 预设；新建会话时可以选择该预设。

更新已有插件时，执行同一条安装命令，再重启 Harness。已有的用户 Agent 预设会保留，不会随插件升级自动覆盖。

安装配置与工具说明见 Harness 插件指南。
GitHub 安装使用仓库默认分支，安装时由 prepare 自动构建。首次安装若 pnpm 提示需要批准构建，请按提示允许该插件的构建脚本，再重新执行安装命令。安装入口是整个仓库，不需要指定子目录。详见 分发说明。

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 接入

在支持本地 MCP stdio 服务的 AI 客户端中配置模拟器，指定游戏工作区后，AI 即可打开、编辑和保存工程，控制试玩并获取画面。

从 npm 安装：

npm install -g beyond-simulator-mcp

然后在客户端中将服务命令设为 beyond-simulator-mcp，参数设为 --workspace 和已有游戏目录的绝对路径。

MCP 可以独立使用。需要同时看画面时，让 Web 指向同一个工作区，打开“存档预览”；AI 保存 JSON 后，预览会自动更新。Web 编辑器中的未保存草稿不会被自动覆盖。

安装方式、客户端配置和工具示例见 MCP 接入指南。

使用指南

1. 准备工程

一个存档集中管理三类资产：服务端 UI、客户端 UI 模板和 Lua 脚本。它们共同组成试玩所需的界面与逻辑。

- 从零开始：在编辑器中添加控件、创建客户端模板，再编写 Lua 脚本。
- 继续已有工程：从顶栏“工作区存档”选择已保存的项目，或点击“导入”打开本地文件。
- 迁入现有资产：导入支持的 UI JSON、GIA 或 Lua，再检查布局和脚本挂载关系。

编写 Lua 时，请让 AI 同时参考工作区中的千星 2D/Lua API 文档；模拟器安装包不包含官方知识库。需要从参考图制作美术时，也可以配合工作区已有的像素画、图元拟合、UI 制作或帧动画 Skill。

2. 编辑并试玩

1. 在“UI 编辑”页添加控件，调整属性，并切换 PC / 手机画布检查适配。
2. 在“Lua 脚本”页创建或导入脚本，将入口脚本挂载到客户端控件或客户端模板；模板脚本在模板实例化时运行。
3. 如果玩法需要服务端响应，在“服务端逻辑”页配置监听信号、设置变量和向玩家发送信号。
4. 点击“试玩 ↗”，在独立窗口中操作游戏。遇到问题时暂停、单步推进，并查看“日志”页中的脚本输出与运行状态。
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 调用保存工具；关闭服务前先保存未完成的工作。

当前支持边界

- 模拟器通过不等于真机通过。 它用于提前发现脚本、布局和交互问题，最终仍需在千星奇域中验证。
- 服务端模拟覆盖变量与信号。 1–8 人试玩是本地多客户端模拟，不包含完整官方服务端节点图或真实网络联机。
- 图片预览以基础图元为主。 当前用代理图形显示图片 ID 100001–100006，其他素材显示缺失提示；安装包不包含完整官方图片和动效资源。
- GIA 支持已验证的内容子集。 部分控件属性与脚本挂载关系无法完整交换，导出时请关注提示，并保留原始文件及完整 JSON 存档。

从源码构建

开发环境为 Node.js 22+、pnpm 10.15.0。首次安装依赖后，可以在仓库根目录构建和测试：

pnpm install --frozen-lockfile
pnpm build
pnpm test

生成可交付的 Web、Harness 和 MCP 安装包：

pnpm pack:release
pnpm test:packages

安装包生成在 release/，本次产物的名称、版本与校验值见 release/manifest.json。包中已包含模拟器核心及所需界面资源，使用者无需构建源码；安装时仍会下载第三方运行依赖。
测试套件完全自包含，只依赖仓库内源码与合成数据，独立检出即可运行。模块分工见 开发入口，构建、验收与发布设计见 分发说明。

自动发布通过 npm-* Git tag 触发；需要先在 npm 为三个包绑定同一份 GitHub Actions Trusted Publisher。配置项和版本规则见 自动发布说明。

开源协议

本项目采用 GNU GPL v3.0（GPL-3.0-only）。源码仓库：1475505/miliastra-beyond-simulator。