Genshin Miliastra MCP

genshin-miliastra-mcp · 原神千星奇域游戏制作 MCP 服务器

让 AI 替你做千星奇域的关卡。 Miliastra Wonderland MCP Server for Genshin Impact UGC · English

给支持 MCP（Model Context Protocol）的 AI 用的《原神》千星奇域创作工具。你在自己的电脑上开着千星奇域的编辑器（千星沙箱），Claude、Cursor、Codex 这类 AI 接上这套工具替你搭关卡：搜物件摆场景、设关卡、写节点图（TypeScript，用 Genshin-TS 0.2.2 编译）、自动试玩并拿回日志和截图。

上面三局是三个没参与过开发的 AI 各自只拿到这套工具、从空白地图做出来并按脚本打通的（经过和它们卡在哪）。

AI 自己进游戏试玩。 下面这段是工具录的：一局用客户端 Lua 写的翻牌配对（examples/pairs），工具把它写进存档、打开游戏、照脚本点暂停、继续、翻完十二张牌，一直打到游戏自己的胜利画面，再把日志和画面拿回来对照。没有人碰鼠标。

它能做什么

• 搭场景：2468 种官方物件的图鉴，按名字搜、看缩略图，一次导入一百个物件；锁定视角、出生点、复苏点、昼夜和灯光。

• 做机关和怪：元件、碰撞触发器、按 F 交互、移动平台、弹跳垫、力场、隐形墙、投射物和命中检测、会自己找敌人打的复杂造物、技能、道具、商店、货币；NPC 头顶的对话气泡、名字、血条。

• 做界面：进度条（横条、竖条、圆环）、图片（约 1600 张平台自带的图）、计时器、按钮、卡牌选择器（三选一）。

  

• 写客户端 Lua（游戏 7.1 的新能力）：会动、能收鼠标和按键的界面，甚至整局 2D 小游戏；脚本的打印和节点图的打印一起从试玩里拿回来。

  

• 写规则：节点图用 TypeScript 写，一次编译几十张图写进存档；自带节点文档、特效（3195 条）、音效（1997 条）、音乐（188 条）的中文目录。

• 自己试玩：按脚本按键、点鼠标、把玩家放到指定位置，截图、连拍、录音、录像，读回日志；AI 靠这个知道做出来的东西在游戏里到底对不对。

• 发布前的准备：出封面、截图、标题和简介。发布本身由你在游戏里点。

• 离线知识库：官方综合指南、教程、48 份官方教学存档的拆解，加上一份实测出来的平台规则，AI 设计玩法前先查。

自带的图鉴：缩略图和编号

千星奇域里的物件、特效、音效、图片，在存档和节点图里都是靠编号引用的。编号在编辑器里看得到，但本地数据里没有现成的表可查。这个仓库把它们整理成了图鉴，大部分是从编辑器里一样一样读出来、拍下来的，AI 按中文名字就能查到编号、看到长相再挑：

图鉴	数量	内容	文件
物件	2468 种，其中 2398 种有缩略图	编号、名字、分组、尺寸（名单和尺寸来自 qianxing-format-docs，CC BY 4.0）；缩略图是摆进编辑器里逐个实拍的	src/scene/asset-catalog.json、src/scene/thumbs/<编号>.jpg
特效	3195 条（限时 1986、循环 1209）	编号、名字、每条在资产库里的小图；87 个循环特效另有挂在角色身上的实拍	src/scene/media/effects.json、fx-thumbs.*、src/scene/fx/
音效	1997 条	编号、名字、分类；其中 73 条录下来量过时长和响度	src/scene/media/sounds.json
背景音乐	188 首	编号、名字、分类	src/scene/media/music.json
界面图片	1590 张，15 类	图标、底板、分隔线、技能、道具、造物头像等；图库逐页的照片，每张图下面标着编号	src/scene/image-library/
复杂造物的动画	18 种造物 296 条	名字、编号、时长、是否循环；逐帧看过的动作写了手里拿什么、哪一毫秒出手	src/scene/media/creature-animations.json
机关的预设状态	45 个机关	宝箱开合、拉杆、活板门这些状态的编号和取值	src/scene/preset-status.json
官方教学存档	48 份	逐份拆成 JSON，加上做法的归纳	knowledge/samples/

这些都是普通的 JSON 和 JPG，不接 MCP 也可以直接拿去用（比如手写 Genshin-TS 时查编号）。游戏更新后重新抄一遍的办法在 scripts/dev/README.md。

说明和现状

这是爱好者做的非官方项目，和米哈游 / HoYoverse 没有关系。它只读写你本机的千星奇域存档、像人一样操作你自己打开的编辑器窗口，不修改游戏程序，不读写游戏内存，不拦截网络。游戏更新以后存档格式或界面可能变，工具要跟着改。用之前请自己确认符合游戏的用户协议和千星奇域的创作规范。

当前是 0.1.0 预览版：只在 Windows、国服中文客户端上验证过。

从哪看起：现状和限制 · 平台规则（实测出来的坑）· 千星奇域是怎么搭游戏的 · 范例。接上服务器以后，资源 miliastra://workflow 讲每一步用哪个工具，AI 会自己读。

需要什么

• Windows 10 或 11，装着原神（中文客户端），账号能进千星奇域的编辑器（千星沙箱）。
• Node.js 22.12 或更高。
• Python 3.10 或更高。自动试玩和截图还要 pip install -r requirements-capture.txt（Pillow 和 rapidocr-onnxruntime）。
• 一个支持 stdio MCP 的 AI 客户端（Claude Code、Claude Desktop、Cursor、Codex CLI 等）。本服务自己不调用大模型，不需要 API Key。
• 试玩时显示器要开着（没有显示器游戏出不了画面），窗口 16:9 全屏；工具会占用鼠标和键盘，这段时间别同时操作电脑。

安装

git clone https://github.com/8itlab/genshin-miliastra-mcp.git
cd genshin-miliastra-mcp
npm ci
npm run build:core
pip install -r requirements-capture.txt
npm run doctor

npm run doctor 检查 Node、Python 和可选的截图依赖是不是齐了。

接到 AI 客户端

在客户端的 MCP 配置里加一项（把路径换成你自己的；examples/mcp.example.json 是同一份）：

{
  "mcpServers": {
    "miliastra": {
      "command": "node",
      "args": ["C:/path/to/genshin-miliastra-mcp/src/server.mjs"],
      "env": {
        "MILIASTRA_WORKSPACE": "C:/path/to/genshin-miliastra-mcp/workspace",
        "MILIASTRA_ALLOW_LIVE_WRITE": "0"
      }
    }
  }
}

Claude Code 可以用一条命令加：

claude mcp add miliastra -e MILIASTRA_WORKSPACE=C:/path/to/genshin-miliastra-mcp/workspace -e MILIASTRA_ALLOW_LIVE_WRITE=0 -- node C:/path/to/genshin-miliastra-mcp/src/server.mjs

• MILIASTRA_WORKSPACE：工具放项目副本、截图和日志的文件夹。
• MILIASTRA_ALLOW_LIVE_WRITE：0 时只写存档的副本（试玩时再导入成一份新存档），不动你的正式存档。
• MILIASTRA_PYTHON / MILIASTRA_PLAYTEST_PYTHON：Python 不在 PATH 里，或者想用单独的环境时填解释器的绝对路径。
• MILIASTRA_SAVE_ROOTS：存档不在默认位置时填（绝对路径数组的 JSON 字符串）。默认从当前 Windows 用户的 AppData/LocalLow/miHoYo/原神/BeyondLocal 和国际服对应目录找，只扫账号下的 Beyond_Local_Save_Level。

服务用 stdio 说话，不是网页。多个客户端可以同时连同一个工作区（配置要一样）；它们共用一个后台进程，全部断开后自己退出。运行时的凭据在当前用户的 LocalAppData/MiliastraMCP/runtime/，不要把里面的 core.json 发给别人。

如果你是替用户安装的 AI：照上面“安装”的六条命令做，把 MCP 配置里的两处路径换成克隆下来的实际位置，让用户重启客户端；接上以后先读资源 miliastra://workflow 和 miliastra://platform-rules 再动手。仓库根目录的 llms.txt 是给你看的摘要。

第一次用

1. 在游戏里“我的奇域 → 新建存档”（超限模式），进编辑器存一次，记住存档名。
2. 对 AI 说类似这样的话：

使用 miliastra MCP。先读资源 miliastra://workflow 和 miliastra://platform-rules。在我的空白存档「XXX」上做一个一分钟的小游戏：捡齐五个金币就赢，倒计时走完就输。做完用 playtest_start 按脚本各打一遍赢和输，把结算画面的截图给我看；分别告诉我哪些是编译通过、哪些是在游戏里真的验证过的。

AI 做出来的东西写在存档的副本里；试玩时工具把副本导入成一份新存档并打开。发布由你自己在游戏里点，工具不点。

玩法代码是 Genshin-TS 支持的 TypeScript 子集；物件、特效、音效的编号都从工具自带的图鉴里查，不用自己找。

工具

工具	作用
get_capabilities	版本、功能、限制、路径、写入开关
list_maps / inspect_map	存档发现、真实图 ID、名称、类型、节点数；同名的存档会标出来
search_node_docs	搜索依赖自带的中英文节点定义（queries 一次查多个词）
effect_catalog / sound_catalog / music_catalog	平台自带的特效（限时 1986、循环 1209）、音效（1997）、背景音乐（188）：按中文名字查编号，特效带缩略图，结果里有节点图里的用法。名字和编号是从编辑器的资产库里抄下来的
scene_search_assets / scene_asset_images	2468 种官方物件的图鉴：按名字查（queries 一次查多个词，查不到会给相近的名字）、按编号看缩略图
scene_add_prefab / scene_update_prefab / scene_list_prefabs	做元件（图里 createPrefab 造出来的东西）：物件、由摆好的怪做成的造物、掉落物（drop）；机关物件带预设状态（宝箱开合、拉杆、活板门，45 个已对上），health 定生命值；scene_update_prefab 改已有元件的缩放、模型、生命值，编号、组件和挂的图都不变
scene_add_components / scene_list_components	给元件加平台自带的组件：碰撞触发器、选项卡（按 F 交互，可带布尔过滤器）、自定义变量、基础运动器（直线、路径）、跟随运动器、小地图标识、文本气泡（NPC 头顶一句接一句的话）、铭牌（头顶的名字、图标、跟着变量走的条、血条，以及离远了指路的导航指示器）、自定义挂接点、受击盒、能力单元、弹射器（launcher：碰到的角色被弹出去，弹跳垫、推人的机关）、战利品、投射运动器（直线、抛物线、追踪目标）和命中检测（子弹；可只碰敌对阵营、可开连续碰撞检测）。范例 examples/events
scene_add_graph	新建一张空图并挂好：关卡实体、元件（可一图挂多个元件）、玩家模板、角色模板；也能建客户端的技能图、过滤器图和道具图
scene_add_signal / scene_list_signals	信号（全关卡广播），可带好几个参数：整数、浮点数、布尔值、字符串、三维向量、实体、GUID、元件 ID、配置 ID 和它们的列表（编辑器给的十八种类型）；节点图之间、Lua 脚本发给节点图、节点图发给 Lua 脚本、客户端节点图发给服务器四条路都上机验过（examples/signalparams、examples/brain）
scene_add_global_timer / scene_list_global_timers / scene_add_timer_display	全局计时器（倒计时或正计时）和屏幕上显示它的计时器控件
scene_add_creature_skill / scene_list_creature_skills / scene_set_creature_logic	复杂造物（“怪物(AI版)”那 48 种）：定义造物技能（一段或几段动画加一张技能图，可设自动面向目标），给造物元件绑上决策图和技能表（每个技能的冷却），设它多远发现敌人、多远放弃、领地多大。配合三种造物图（scene_add_graph 的 creatureDecision / creatureStatus / creatureSkill），单位就能按图走位、闲逛、干活、自己发现敌人、追上去打。做法见 knowledge/notes/complex-creatures.zh-CN.md，范例 examples/brain、examples/skirmish，整个游戏见 examples/kingdom6
creature_animations	复杂造物的动画表：名字、编号、时长、是否循环（读了 18 种 296 条）。造物技能按名字或编号选动画。造物的模型都是空手的：表里还写了每种造物手里能拿什么、上机逐帧看过的那些动作是什么样、哪一毫秒算数（atMs，直接当技能的 graphAtMs）
scene_add_skill / scene_list_skills	技能：瞬发，或带一段角色动画的普通技能（可在某一毫秒触发技能图、手里挂武器）；技能图里打攻击盒就能打到怪和带受击盒的物件
scene_add_currency / scene_list_currencies	货币，以及角色身上的背包
scene_add_item / scene_add_shop / scene_list_items	道具（材料，或带道具节点图、能在背包里使用的消耗品）；把元件做成商店（平台自带的买卖界面）
scene_add_progress_bar / scene_add_button / scene_add_image / scene_list_interface	屏幕上的进度条（跟着玩家变量走；可以是横条、竖条、圆环，可以直接显示当前值的数字，颜色可改）、交互按钮（按数字键触发，玩家模板上的图收事件）和图片（平台自带的图，或一块纯色的底板：不靠文字也能把话说清楚）；控件可以一开始隐藏，由节点图开关
scene_add_card_selector	卡牌选择器：平台自带的“几选一”窗口（每张卡有图标、标题、描述；单人关卡里打开时游戏暂停），节点图用 f.invokeDeckSelector 唤起、玩家模板上的图收到选了哪张。记录和官方样例“卡牌选择器”逐字节相同
scene_add_unit_status / scene_list_unit_statuses	单位状态：描边、透视、加生命上限；图里加减
scene_add_environment / scene_list_environments / scene_add_light	固定时刻的环境配置（昼夜靠两套配置切换；按编辑器的写法写，白天不会过曝）和属于某套配置的点光源
scene_set_client_script / scene_add_client_ui / scene_add_client_template / scene_remove_client / scene_list_client_scripts	客户端界面（游戏 7.1）：把 Lua 5.3 脚本放进存档，在屏幕上摆一棵由它控制的客户端控件树（十一种：图片、光标检测区域、容器、网格视窗、模板引用、预设按钮、按键提示、文本框等），还能做脚本运行时照着造的控件模板。界面可以每帧在动、收鼠标和按键，整局 2D 玩法也能做；和节点图靠自定义变量和信号互通（节点图也能直接给脚本发信号：f.sendSignal('client:名字', 玩家)）。脚本变量二十种类型都能定，同一个脚本挂在几个控件上可以各给各的值；控件能按设备（电脑、手机、主机）给不同的位置，能指定手柄摇杆往哪走。图片能直接带填充（横、竖、四分之一圈、半圈、整圈）、边缘羽化和遮罩反转，进度条和冷却圈不用脚本画；scene_get_client_ui 把已有的界面读回成参数，改完 replace: true 原位换回去。做法见 knowledge/notes/client-lua.zh-CN.md，脚本写进存档时当场查：语法错直接拒绝并给出行列，写死的控件名、信号名、变量名、接口名、图片和音效编号逐个对存档、节点图和图鉴（scene_check_client），对不上的给出行号和最接近的名字；运行时的错带着调用栈从试玩日志里回来。只改 Lua 的一轮不重新导入存档，真机上大约一分钟一轮。editor_preview_interface 让编辑器把界面画在手机、主机的画布上各截一张；scene_import_simulator 把千星沙箱模拟器的工程整个写进存档上真机。范例 examples/clientui、examples/clientgame、examples/clientlist、examples/clientmenu、examples/clientcheck、examples/clientvars、examples/clientsignal、examples/clientapi、examples/clienttext，以及整局游戏 examples/pairs
image_catalog	界面图片控件能用的全部图片（约 1600 张，15 类：功能图标、玩法图标、装饰图案、底板、分隔线、特殊字符、技能、道具、造物头像）：按分类返回编辑器图库的照片，每张图下面是编号
scene_remove_entities	把已经导入场景的物件从存档副本里拿掉（按名字或名字前缀）：导入只能加，摆错的靠它减
scene_list_classes / scene_set_class	职业：角色能不能跳、冲刺、攀爬、滑翔，用哪个镜头模板；角色的等级和基础生命、攻击、防御、体力（新地图默认一万血，打不死）
scene_set_spawn / scene_add_preset_point / scene_list_preset_points	出生点和图里按编号读取的命名位置
scene_add_respawn_point / scene_list_respawn_points / scene_set_player_count	复苏点（角色倒下后回来的地方；配合图里的复苏次数、激活复苏点做命数和存档点）；关卡收几个人（发布单人游戏要设成 1 到 1）
playtest_start / playtest_status	一键试玩：导入存档、订阅日志、按脚本按键 / 点鼠标 / 点屏幕上的字、截图（可以隔零点几秒连拍，screenshotWidth 调大留细节）、读屏幕文字、收日志；recordAudio 把这一局的声音录下来，报告每秒的响度和每个声音开始的时刻；bakeNavigation 试玩前在编辑器里烘焙寻路网格（复杂造物的闲逛、追击需要）。电脑的显示器要开着，没有显示器时游戏出不了画面，工具会直接报出来。输入里的 teleport 把玩家放到指定位置（每次之后报人到没到）、trackPlayer 记录玩家的位置并把每条打印换算成试玩秒数（往存档副本里加一个小探针）；startValues 给自定义变量另设这一轮的初值（从关卡后半段开始验）；同一份存档接着玩会跳过导入；playtest_status 的 waitSeconds 等到这一轮结束再回话；recordVideo 用系统的 Xbox Game Bar 录一段视频
playtest_frames	把一次试玩里某一段的截图裁到同一块区域、标上秒数、拼成一张图：逐帧看动作（武器在不在手上、落刀和伤害数字对不对得上、飞刀是不是手松开时出去的）。打印看不出这些
publish_kit	发布前的准备：从试玩截图里出封面和四张图（1600×900）、标题、描述、标签和一张对照官方要求的检查表，放进一个文件夹。真正的发布由创作者自己在游戏里做
search_knowledge / read_knowledge	离线搜索官方综合指南、教程、常见问题、48 份官方教学存档的拆解和教学视频文字稿（knowledge/）；总结见 千星奇域是怎么搭游戏的
write_graphs	写节点图：一次调用把一张或多张图的源码类型检查、编译、写进存档副本（三十七张图约二十秒），返回可以试玩的存档和每张图的节点数；哪张编译不过就停在哪张并报出错误；只改了几张就只发那几张。早先分五步做的那组工具（建项目、改源码、构建、预览、写入）默认不再列出，要用时设环境变量 MILIASTRA_STEP_TOOLS=1
list_editor_windows	枚举原神与千星沙箱窗口、实际窗口 ID 和坐标
capture_editor_window	返回 MCP 内联 PNG、原图文件、缩放比例和质量提示
focus_editor_window	将指定编辑器窗口置于前台并返回新截图
editor_input	基于截图执行一次点击、按键、文字、滚动或拖拽，再返回新截图

资源 miliastra://workflow 提供面向 AI 的工作流与限制说明；miliastra://knowledge 是知识库的总结和索引。

上表里的工具哪些在游戏里走通过、还有哪些限制，见 现状和限制。用它们从零搭出并按脚本走通的游戏和一批单项验证关在 examples/。

一键试玩

写完代码、构建出候选存档后，用 playtest_start 让它自己玩一遍，再用 playtest_status 取结果。中间不需要 AI 一步步点界面。

{
  "mapPath": "D:\\\\work\\\\candidate.gil",
  "graphName": "_GSTS_MyGraph",
  "durationSeconds": 120,
  "screenshotsAt": [10, 60, 110],
  "inputs": [{"at": 30, "key": "D", "holdMs": 3000}]
}

它会依次做：导入这个存档（生成一个新的官方存档）、打开并保存、在沙箱日志窗口订阅 graphName、开始试玩、按时间点截图和按键、到时间后退出试玩、取回这一场的官方日志。playtest_status 返回每一步的进度、日志里的打印（t 是关卡时钟的秒数）和截图。不传 mapPath 就直接试玩编辑器里已经打开的存档。

使用条件：

• 原神开着就行：停在主世界、千星奇域大厅、存档列表或编辑器里都可以，工具会自己走到存档列表。运行期间它会占用鼠标和键盘，不要同时操作这台电脑。
• 中文客户端。按钮靠识别界面文字来找，不依赖分辨率；只有左上角菜单和左下角退出两个纯图标按钮按窗口比例定位，目前只在 16:9 全屏下测过。
• Python 需要 pip install -r requirements-capture.txt（Pillow 和 rapidocr-onnxruntime）。如果想用单独的 Python 环境，把解释器路径放进环境变量 MILIASTRA_PLAYTEST_PYTHON。
• 游戏如果以管理员身份运行，MCP 所在的程序也要以管理员身份运行，否则按键发不进去。

一轮的固定开销约两分钟（导入、打开、订阅、加载），加上试玩时长。

试玩跑完只代表关卡被玩了这么久。玩法对不对，要看返回的打印和截图自己判断。设计关卡和测试前先读 平台规则，里面是实测出来的坑，比如造物离玩家太远就不行动。

搭场景

场景可以写成一份方块清单，由工具生成官方资产包再导进编辑器。导进去的是能选中、能手调的真实物件。

1. scene_block_catalog：看有哪些方块可用（箱子、立方体、墙体等 21 种），各自的颜色和原始尺寸。
2. scene_build_blocks：给出每个物件的模板（方块名或物件编号）、位置和旋转（度），再给尺寸（米，拉伸到正好这么大）或缩放（1 是模型原大小）。方块能任意拉伸，一块就可以是一整面墙或一片地板。它会生成 .gia 并放进编辑器的导入目录。
3. scene_import_assets：在编辑器里打开目标存档后调用，它自己走完“资产导入导出管理”里的加载、选中、转存和保存，再拉远镜头拍一张总览。结果用 playtest_status 取。

{"name": "Camp", "blocks": [
  {"template": "积木立方体（木色）", "name": "Floor", "position": [0, 0.1, 0], "size": [12, 0.2, 8]},
  {"template": "石质墙体（灰）", "name": "Wall", "position": [6, 1.5, 0], "size": [1, 3, 8]},
  {"template": "火质立方体", "name": "Fire", "position": [0, 0.5, 0], "size": [0.6, 0.6, 0.6], "rotation": [0, 45, 0]}
]}

注意：

• A altura do piso de um novo arquivo vazio é y=0. A posição de um bloco é o seu centro; a posição de modelos prontos como árvores, casas e cercas é o centro da base, então preencher y=0 faz com que fiquem em pé no chão.
• Para efeitos, consulte primeiro effect_catalog (por nome, como "fogos de artifício", "impacto fogo", "aviso"); para sons, consulte sound_catalog; para música, consulte music_catalog; os resultados mostram como escrever no gráfico de nós. Cada ação do jogador deve ter resposta sonora e visual; veja knowledge/notes/feedback.zh-CN.md para saber como fazer.
• Defina a câmera antes de posicionar o cenário. scene_list_cameras lê a distância da câmera até o personagem e o ângulo de visão no arquivo salvo; scene_set_camera pode alterar (escrevendo em uma cópia do arquivo); fixedView trava a perspectiva (jogos de visão lateral e de cima devem travar, caso contrário a câmera gira quando o jogador mexe o mouse). A altura da imagem na posição do personagem é aproximadamente 2 × distância × tan(ângulo/2): com 6 metros e 45°, a altura é de apenas 5 metros, não cabendo nem uma casa; com 14 metros, cerca de 11,6 metros de altura, adequado para planos distantes em jogos de rolagem lateral. A câmera começa atrás do personagem; em jogos de rolagem lateral, use teleportPlayer no início para teleportar o personagem virado para +z (orientação [0,0,0]), assim a câmera fica no lado −z olhando de lado; yawRange não consegue fixar essa direção. O procedimento completo do exemplo do reino está na descrição no início de examples/kingdom/gen_kv3_scene.py.
• Coisas que só aparecem durante o jogo (moedas, muralhas que surgem após a compra, marcadores que seguem o jogador) usam componentes: scene_add_prefab transforma qualquer objeto em um componente com a escala especificada; no gráfico de nós, use f.createPrefab(元件编号, 位置, …) para gerar em qualquer posição, com o tamanho definido; scene_list_prefabs lista os componentes do arquivo salvo. Criaturas que serão recrutadas ou geradas também usam componentes: primeiro posicione um monstro não criado na cena e use scene_add_prefab com fromEntity para transformá-lo em componente.
• Um mapa totalmente novo e vazio também pode ser usado diretamente: scene_add_graph cria um gráfico de nós de servidor vazio no arquivo salvo e o anexa à entidade da fase (mapas novos não têm gráfico de nós, e write_graphs precisa de um para escrever). Veja scripts/dev/fresh_map_round.mjs para um exemplo completo. Todos os exemplos foram construídos do zero a partir de um mapa vazio (veja examples).
• Quem ataca quem é definido pelas facções: scene_list_factions lê as facções e relações hostis no arquivo salvo; scene_set_faction_hostility altera. Em mapas novos, as três facções — jogador, objetos e criaturas — são hostis entre si, e as criaturas aliadas atacam objetos gerados pelo gráfico de nós; a maioria dos modos de jogo deve ser alterada para que apenas jogador e criaturas sejam hostis (hostilePairs: [[1,3]]).
• Para ordenar que monstros ataquem alguém ou vão a algum lugar: scene_set_level_settings muda o tipo de hostilidade da fase para personalizado (aggroMode: "custom"); no gráfico de nós, use f.setTheAggroValueOfSpecifiedEntity(目标, 怪, 数值) para dar ordens, e os monstros correrão direto de longe até o alvo (personagem do jogador, unidades aliadas ou objetos). O método de patrulha ao longo de um caminho deixou de funcionar após a atualização do jogo de 2026-10-09 (o modelo de patrulha é limpo ao importar o arquivo salvo), e a ferramenta correspondente foi removida.
• Há muitos itens com o mesmo nome no catálogo (só "árvore alta" tem dezenas de variações). O resultado de scene_search_assets inclui hasImage; antes de escolher, use scene_asset_images para obter miniaturas pelo número (máximo 12 por vez; retorna nome, grupo, dimensões e imagem). No catálogo, todos os itens são dimensionados de forma semelhante — serve apenas para ver a aparência; o tamanho real está nas dimensões. Alguns itens não têm imagem (não podem ser fotografados); a ferramenta avisa claramente, e nesse caso importe os candidatos para um arquivo de teste.
• Cada importação é uma adição; importar o mesmo pacote duas vezes cria uma cópia extra. Ao ajustar repetidamente, faça primeiro em um arquivo de teste.
• Ao esticar um bloco, a textura também estica; superfícies muito grandes ficam borradas de perto.
• Já testamos a importação de 100 blocos de uma vez; quantidades maiores ainda não foram testadas.

Como conectar cena e gráfico de nós

Quando o gráfico de nós precisar de coisas da cena (monstros que aparecem à noite, muralhas que surgem após o pagamento), siga esta ordem, usando apenas ferramentas MCP:

1. editor_open_map: importe o arquivo salvo desejado e abra-o no editor (pule se o arquivo de destino já estiver aberto).
2. scene_build_blocks + scene_import_assets: importe a cena. Adicione createAtStart:false aos objetos que devem "aparecer depois".
3. scene_list_entities: leia de volta os IDs das entidades pelo nome. Ao importar, o editor redistribui os IDs; os escritos no pacote não valem. O mapPath retornado é o arquivo salvo recém-salvo.
4. write_graphs (mapPath usa o arquivo da etapa anterior; graphs contém os números e códigos-fonte de cada gráfico): verificação de tipos, compilação e escrita em uma cópia do arquivo salvo; retorna um arquivo jogável para teste.
5. playtest_start (mapPath usa o arquivo retornado por write_graphs) → playtest_status.

No gráfico de nós: f.createEntity(new guid(编号), [] as bigint[]) cria objetos ainda não criados.

scripts/dev/mcp_round.mjs é um cliente que refaz o exemplo do reino do zero seguindo essa ordem; pode ser usado como referência.

Capturas de tela compatíveis com Windows 10

A captura de tela é um recurso opcional que requer Pillow além do ambiente Python principal. Foi verificado com Python 3.10 / Pillow 12.0.0 nesta máquina; em outros computadores, execute:

python -m pip install -r requirements-capture.txt
npm run test:capture

O MILIASTRA_PYTHON na configuração do MCP pode especificar o caminho absoluto do executável Python; se não for especificado, usa python do PATH. A captura de tela não usa Windows.Graphics.Capture e não chama IsBorderRequired, que está ausente no Windows 10 Build 19045.

Ordem de chamada da IA:

1. list_editor_windows obtém um windowId novo (combinação de handle de janela e PID).
2. capture_editor_window({windowId, method: "window"}); recebe o conteúdo padrão do MCP image/png e metadados estruturados.
3. Inspecione visualmente a imagem. Para janelas em segundo plano, tente o modo window; o PrintWindow pode retornar quadros antigos ou tela preta para alguns programas com GPU — não considere apenas o retorno de sucesso como garantia de imagem correta.
4. Se necessário, use method: "screen". Esse modo exige que o alvo esteja em primeiro plano e que nenhuma outra janela de aplicativo esteja cobrindo; a ferramenta não rouba o foco automaticamente.

A imagem original é salva em workspace/captures. A pré-visualização retornada não excede 1600×1200 por padrão; width/height é o tamanho da imagem original, e previewToImageScale serve para converter coordenadas da pré-visualização para a imagem original. imageOffsetInWindow indica o deslocamento em pixels físicos da área capturada em relação ao canto superior esquerdo da janela.

Só é permitido capturar e operar YuanShen.exe, GenshinImpact.exe e BeyondEditor.exe. Janelas inválidas, minimizadas, áreas de trabalho inacessíveis ou protegidas são rejeitadas; capturas de tela em segundo plano retornam códigos de erro específicos. A ferramenta de captura não envia entrada nem altera o foco da janela.

No Windows 10 19045 real, já foram capturados via MCP o sandbox Qianxing (3264×2160) e a cena de edição de Genshin (3840×2160), com verificação de gerenciador de gráfico de nós, terreno e blocos reconhecíveis. Os erros de captura do plugin de desktop original não foram modificados; agora é usado um backend compatível independente.

Mouse e teclado

Primeiro list_editor_windows, depois focus_editor_window, e verifique a imagem retornada. Pegue o captureId dos metadados da imagem e chame editor_input uma vez:

{"captureId":"刚返回的 UUID","kind":"click","x":430,"y":190,"button":"left","clickCount":1}

As coordenadas devem ser escolhidas com base na imagem atual; os números de exemplo não devem ser usados diretamente como coordenadas da sua interface. Outros exemplos de ações (cada linha é uma solicitação independente):

{"captureId":"刚返回的 UUID","kind":"key","key":"Ctrl+A"}
{"captureId":"刚返回的 UUID","kind":"text","text":"_GSTS_MCP_Test"}
{"captureId":"刚返回的 UUID","kind":"scroll","x":500,"y":400,"delta":-120}
{"captureId":"刚返回的 UUID","kind":"drag","x":500,"y":400,"toX":700,"toY":500}

• Após cada ação, veja novamente a imagem resultante; use o novo captureId retornado para o próximo passo. As credenciais são válidas apenas no mesmo processo do serviço MCP, expiram em 120 segundos e todas ficam inválidas após entrada ou mudança de foco.
• Antes de enviar, verifique o título da janela, a posição, a relação de primeiro plano e a oclusão da posição do clique. Falhas parciais também consomem credenciais; não reutilize.
• O menu de contexto pode ser uma janela separada sem título. Descubra via list_editor_windows e, se necessário, capture com method: screen; o menu e a janela principal compartilham a relação de primeiro plano. Quando o menu fecha após a operação, a ferramenta tenta retornar uma nova captura do editor em primeiro plano no mesmo processo.
• inputSent: true apenas prova que a entrada foi enviada. Verifique a imagem ou o arquivo salvo para saber se a função funcionou; POST_INPUT_CAPTURE_FAILED indica que foi enviado, mas a captura falhou — não tente novamente às cegas.
• Texto usa Unicode SendInput, sem alterar a área de transferência. Enter/Tab são enviados via key. Combinações com a tecla Windows, alternância de sistema e fechamento não são fornecidas.
• Se FOCUS_FAILED, é necessário selecionar manualmente a janela de destino. Se INPUT_FAILED, pode envolver o nível de integridade do processo de destino ou parte da entrada não entregue; a ferramenta não altera configurações de segurança do sistema.

npm run test:input-guards verifica credenciais de captura, parâmetros ausentes e rejeição de coordenadas fora dos limites, sem enviar entrada real. tests/editor-session.mjs é uma ponte de depuração local para desenvolvimento, com senha aleatória e escuta apenas em loopback; não faz parte do serviço MCP publicado. Os rastros reais de operação estão em workspace/editor-live-trace.json.

Experimentos e validação

npm test
npm run test:local

• npm test: usa GIL sintético claramente marcado, inicia um serviço MCP independente e um cliente SDK, executa handshake, chamadas de ferramenta, correção de erros de código, compilação, rejeição de conflitos, escrita e restauração byte a byte; verifica a preservação de campos protobuf desconhecidos. Arquivos sintéticos não representam capacidade de carregamento no jogo.
• npm run test:local: usa um arquivo salvo real com configuração explícita e resumo, cria uma cópia e compila uma lógica mínima via MCP. Sem gráfico de destino, valida MISSING_GRAPH sem modificar o arquivo original; não seleciona automaticamente o arquivo mais recente.
• As evidências de teste local são gravadas em workspace/mcp-smoke-report.json e workspace/synthetic-smoke-report.json, incluindo parâmetros e resultados das ferramentas.

Escopo e limitações da implementação

• Verificado apenas em Windows, cliente chinês, tela cheia 16:9; se a interface ou o formato do arquivo mudar após atualizações do jogo, as ferramentas podem precisar de ajustes.
• Versão fixa do Genshin-TS com reutilização da compilação/análise; a leitura/escrita própria do arquivo salvo só altera campos confirmados em amostras salvas pelo editor; o restante é preservado como está. Fonte em THIRD_PARTY_NOTICES.md.
• O código enviado pela IA passa pelo fluxo de compilação e execução upstream; esta é uma ferramenta de desenvolvimento local confiável, não é um sandbox para código não confiável. Não deve ser exposta diretamente à internet ou a chamadores não confiáveis.
• A verificação de hash pode detectar salvamentos externos após a pré-visualização; ainda há uma janela de corrida muito curta ao escrever arquivos simultaneamente com o editor. Em modificações em tempo real, saia do mapa de destino primeiro, recarregue e depois salve. As operações internas do serviço são serializadas; não inicie vários serviços modificando o mesmo workspace ao mesmo tempo.
• Importar, assar e testar exigem o editor aberto. A ferramenta não considera o jogo jogável apenas porque o arquivo compilou: compilar, gravar no arquivo salvo e verificar no jogo são três coisas distintas, relatadas separadamente no retorno.
• Mais limitações e pendências em 现状和限制.

Relação com outras ferramentas de Qianxing Qiyu

Há muitas ferramentas comunitárias para Qianxing Qiyu; após o jogo 7.1 adicionar Lua no cliente, a linha 2D + Lua cresceu especialmente. Quase todas param no mesmo ponto: a etapa de validação no jogo real fica para humanos ("passar no simulador não é passar no dispositivo real", "o botão de teste só pode ser clicado por humanos", "os arquivos gerados não foram verificados no dispositivo real" — isso está escrito por elas mesmas). A posição deste projeto é exatamente essa etapa: fazer a IA construir uma fase inteira no editor e no jogo reais, clicar em testar sozinha, ler logs e capturas de tela sozinha.

Projeto	Foco	Relação com este projeto
Genshin-TS	Escrever gráficos de nós em TypeScript, compilar e injetar no arquivo salvo	É o que este projeto usa para compilar gráficos de nós. Se você quer apenas escrever código manualmente, sem IA operando o editor, use-o diretamente
千星奇域节点图工具集	Ler/escrever arquivos de gráfico de nós, converter código e gráfico, dados de nós	O Genshin-TS incorpora seus resultados; este projeto o usa indiretamente
Ayaya_Miliastra_Editor	Escrever gráficos de nós em Python, validação offline, layout automático, com interface de pré-visualização para humanos	Escolha-o se quiser fluxo de trabalho em Python e interface de pré-visualização; este projeto não tem interface para humanos
千星沙箱模拟器	Executar Lua do cliente e interface fora do jogo, ciclos de poucos segundos; cinco canvas, simulação multijogador, gravação/replay; editor web e fluxo de sete etapas	O projeto dele pode ser importado em uma etapa para o dispositivo real aqui: scene_import_simulator lê o arquivo salvo completo dele, grava scripts, modelos, interfaces, sinais, variáveis e regras de servidor no arquivo salvo; os números de modelo são alinhados automaticamente no Lua; depois, teste automático. Use-o para ciclos de poucos segundos; para dispositivo real, use aqui
dsh-miliastra	Plugin DeepSeek Harness: injeta scripts em arquivos vivos ao lado do arquivo salvo, lê logs de execução, capturas, sondas, verificação de conformidade de interface	Ideia semelhante (trabalha em arquivos do dispositivo real); voltado para Harness, com teste clicado por humanos; este projeto clica em testar sozinho e também escreve o arquivo salvo
miliastra-ugc、MiliastraAgent、genshin-qianxing-2d-game	Pacotes de habilidades e prompts para IA: verificação estática de Lua, sandbox Lua offline, geração de pixel art e formas primitivas, fluxos passo a passo	Geração de imagens (pixel art, animações de quadros, ajuste de formas) este projeto não tem — use as deles; fluxos podem ser combinados com as ferramentas deste projeto
千星奇域工具箱	Base de conhecimento com documentação oficial e experiência da comunidade, com MCP online	Pode ser conectado junto com este projeto: ele responde "como fazer", este projeto executa
WebMiliastraNodesEditor	Editor de gráfico de nós em web, sem abrir o jogo	Use para prototipar gráficos de nós
genshin-starcraft-mcp	MCP para consultar tutoriais oficiais e documentação de nós	Este projeto inclui um guia oficial offline próprio; há sobreposição de funcionalidades
qianxing-format-docs、genshin-miliastra-file-format	Documentação de formatos de arquivo salvo e exportação	As listas de objetos e dimensões deste projeto vêm do primeiro (CC BY 4.0)

Somente este projeto tem:

• Teste automático no dispositivo real: importar arquivo salvo, marcar logs, clicar em testar, teclar e clicar, capturar tela, ler impressões — tudo sem humanos. Dê a impressão esperada e o teste responde se passou.
• Lua em ciclos de um minuto no dispositivo real: ao alterar apenas scripts, sem reimportar o arquivo salvo; medido em 74 segundos por ciclo.
• Verificação de nomes antes de gravar: nomes de controles, sinais, variáveis, interfaces, números de modelos e imagens/sons em scripts são verificados contra o arquivo salvo, gráfico de nós, catálogo e interfaces oficiais; parâmetros de sinais são verificados em quantidade, tipo e ordem nos dois lados (Lua e gráfico de nós); ao gravar interfaces, informa diretamente quais controles saem da tela no celular. Nesta plataforma, nomes incorretos não geram erro — simplesmente não funcionam.
• Pré-visualização multi-dispositivo desenhada pelo editor real: uma captura para cada um dos dez canvas (PC, celular, console), desenhada pelo próprio editor, não aproximada.
• Fase inteira no arquivo salvo: cena e jogabilidade 3D (cenário, combate com criaturas complexas, projéteis, mecanismos), gráfico de nós, interface comum, interface de cliente — os registros gravados são byte a byte idênticos aos configurados manualmente no editor.
• Catálogo com miniaturas de objetos, efeitos, sons e números de imagens de interface.

Este projeto não tem: simulador fora do jogo (o mais rápido é um minuto por ciclo; simuladores são segundos), simulação multijogador (todos os exemplos são single-player), ferramentas de geração de imagem, interface para humanos, instalação em um comando (hoje é necessário clonar o repositório) e suporte a plataformas além de Windows.

O acima foi organizado com base nas descrições dos READMEs de cada projeto; se houver imprecisões, abra uma issue.

Perguntas frequentes

A IA consegue fazer mapas/fases de Qianxing Qiyu automaticamente? Consegue. Este repositório existe para isso: a IA chama as ferramentas daqui via MCP, constrói a cena a partir de um arquivo salvo vazio, escreve o gráfico de nós e entra no jogo para testar sozinha. Três IAs que nunca viram este repositório criaram cada uma um jogo jogável até o fim; os registros estão em 盲测. Se é divertido, ainda cabe a humanos julgar e ajustar.

Quais clientes de IA são suportados? Qualquer cliente com suporte a stdio MCP: Claude Code, Claude Desktop, Cursor, Codex CLI, Cline, entre outros. Durante o desenvolvimento, usamos Claude Code e Codex. O serviço não chama modelos e não precisa de API Key.

Não sei escrever gráfico de nós / não sei programar. Posso usar? Pode. Você descreve em português o que quer, a IA escreve o código-fonte TypeScript do gráfico de nós e compila para o arquivo salvo; no editor, você vê um gráfico de nós comum e pode editar manualmente.

O gráfico de nós de Qianxing Qiyu pode ser escrito com código? Pode. Este projeto usa Genshin-TS para compilar TypeScript em gráfico de nós e adiciona etapas de gravar no arquivo salvo, anexar a entidades e componentes e compilar vários gráficos de uma vez.

Funciona no servidor internacional (cliente em inglês Miliastra Wonderland)? Não foi verificado. A leitura/escrita do arquivo salvo não depende de idioma, mas o teste automático depende de reconhecer botões em chinês na tela; na interface em inglês, provavelmente precisará de ajustes.

Vai estragar meu arquivo salvo? Por padrão, apenas cópias do arquivo são gravadas; no teste, a cópia é importada como um novo arquivo salvo. O arquivo oficial só é gravado se você ativar explicitamente a opção; antes de gravar, há comparação de hash e backup.

O que acontece se minha conta de criação for de nível baixo? Em contas Qijiang Lv.1, caixas de texto personalizadas e textos de opções não aparecem. A ferramenta preparou alternativas sem texto: controles de imagem, barras de progresso, ícones e efeitos de marcador.

E se a ferramenta quebrar após uma atualização do jogo? Abra uma issue informando a versão do jogo e a ferramenta com erro. O catálogo foi copiado do editor; o método para recopiá-lo está em scripts/dev/README.md.

Licença e fontes

O código está sob licença MIT. O software de terceiros usado está em THIRD_PARTY_NOTICES.md.

《原神》, Qianxing Qiyu, e as imagens do jogo, miniaturas de objetos e ícones, guias oficiais e arquivos de ensino presentes no repositório pertencem à miHoYo / HoYoverse; estão aqui apenas para que a ferramenta possa consultar itens da plataforma por nome e para que os testes tenham amostras de comparação. Este projeto não é afiliado nem endossado pela miHoYo. Se os detentores de direitos considerarem algo inadequado, abra uma issue e trataremos prontamente.