千星沙箱模拟器

面向千星奇域 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。