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]}
]}

注意：

• La altura del suelo en un archivo nuevo vacío es y=0. La posición de un bloque es su centro; para modelos terminados como árboles, casas y cercas, la posición es el centro de la base; si pones y=0, quedan de pie sobre el suelo.
• Para efectos, consulta primero effect_catalog (por nombre, como "fuegos artificiales", "impacto fuego", "aviso"); para sonidos, consulta sound_catalog; para música, consulta music_catalog; los resultados incluyen la forma de escribirlos en el gráfico de nodos. Cada acción del jugador debe tener respuesta visual y sonora; el método está en knowledge/notes/feedback.zh-CN.md.
• Primero define la cámara y luego coloca el escenario. scene_list_cameras lee qué tan lejos está la cámara del personaje y el ángulo de visión en el archivo; scene_set_camera puede cambiarlo (escribe en una copia del archivo); fixedView fija el ángulo de visión (los juegos de vista lateral y cenital deben fijarlo, si no, la cámara se mueve al mover el mouse). La altura de la imagen a la altura del personaje es aproximadamente 2×distancia×tan(ángulo/2): a 6 metros y 45° solo hay 5 metros de alto, ni una casa cabe; a 14 metros hay unos 11.6 metros de alto, adecuado para vistas laterales amplias. La cámara empieza detrás del personaje; en juegos de desplazamiento lateral, al inicio usa teleportPlayer para teletransportar al personaje mirando hacia +z (orientación [0,0,0]), así la cámara queda en el lado −z mirando de lado; yawRange no puede fijar esa dirección. El método completo del ejemplo del reino está en la introducción de examples/kingdom/gen_kv3_scene.py.
• Las cosas que aparecen durante el juego (monedas, murallas que aparecen tras comprar, marcadores que siguen al jugador) se hacen con componentes: scene_add_prefab convierte cualquier objeto en un componente con la escala indicada; el gráfico de nodos usa f.createPrefab(元件编号, 位置, …) para generarlo en cualquier posición, con el tamaño definido; scene_list_prefabs lista los componentes del archivo. Las criaturas que serán reclutadas o generadas también usan componentes: primero coloca un monstruo sin crear en la escena y luego usa scene_add_prefab con fromEntity para convertirlo en componente.
• Un mapa vacío nuevo también se puede usar directamente: scene_add_graph crea un gráfico de nodos de servidor vacío en el archivo y lo enlaza a la entidad de nivel (los mapas nuevos no tienen gráfico de nodos; write_graphs necesita uno para escribir). Ejemplo completo en scripts/dev/fresh_map_round.mjs. Todos los ejemplos se construyen desde cero sobre un mapa vacío (ver examples).
• Quién ataca a quién lo decide la facción: scene_list_factions lee las facciones y relaciones hostiles del archivo; scene_set_faction_hostility las modifica. En mapas nuevos, las facciones jugador, objeto y criatura son hostiles entre sí por pares; las criaturas propias atacarán a los objetos generados por el gráfico de nodos; la mayoría de los modos deberían cambiar para que solo jugador y criatura sean hostiles (hostilePairs: [[1,3]]).
• Para ordenar a un monstruo a quién atacar o hacia dónde ir: scene_set_level_settings cambia el tipo de odio del nivel a personalizado (aggroMode: "custom"); en el gráfico de nodos usa f.setTheAggroValueOfSpecifiedEntity(目标, 怪, 数值) para dar órdenes; el monstruo correrá directamente hacia el objetivo desde lejos (personaje del jugador, unidades propias u objetos, todos sirven). El método de patrullar por una ruta dejó de funcionar tras la actualización del juego del 2026-10-09 (la plantilla de patrulla se borra al importar el archivo); la herramienta correspondiente ya se eliminó.
• En el catálogo de objetos hay muchos con el mismo nombre (solo "árbol" tiene decenas). El resultado de scene_search_assets incluye hasImage; antes de elegir, usa scene_asset_images para obtener una miniatura por número (máximo 12 a la vez; devuelve nombre, grupo, tamaño e imagen). En la imagen, todos los objetos están escalados a un tamaño similar; solo sirve para ver el aspecto; el tamaño real está en los datos. Pocos objetos no tienen imagen (no se pueden capturar); la herramienta lo indica explícitamente; en ese caso, importa los candidatos a un archivo de práctica para verlos.
• Cada importación es una adición; importar el mismo paquete dos veces duplica el contenido. Al ajustar repetidamente, hazlo primero en un archivo de práctica.
• Al estirar un bloque, la textura también se estira; las superficies muy grandes se ven borrosas de cerca.
• Se probó importar 100 bloques de una vez; cantidades mayores aún no se han probado.

Cómo conectar la escena y el gráfico de nodos

Cuando el gráfico de nodos necesite usar cosas de la escena (monstruos que salen de noche, murallas que aparecen tras el pago), sigue este orden, usando solo herramientas MCP:

1. editor_open_map: importa el archivo a usar y ábrelo en el editor (si el archivo de destino ya está abierto, omítelo).
2. scene_build_blocks + scene_import_assets: importa la escena. A los objetos que deben "aparecer después" añádeles createAtStart:false.
3. scene_list_entities: lee los números de entidad por nombre. Al importar, el editor reasigna los números; los escritos en el paquete no valen. El mapPath devuelto es el archivo recién guardado.
4. write_graphs (mapPath usa el archivo del paso anterior; graphs contiene los números y el código fuente de cada gráfico): verificación de tipos, compilación y escritura en una copia del archivo; devuelve un archivo listo para probar.
5. playtest_start (mapPath usa el archivo devuelto por write_graphs) → playtest_status.

En el gráfico de nodos: f.createEntity(new guid(编号), [] as bigint[]) crea los objetos no creados.

scripts/dev/mcp_round.mjs es un cliente que reproduce el ejemplo del reino desde cero siguiendo este orden; puede servir de referencia.

Capturas compatibles con Windows 10

Las capturas son una función opcional que, además del entorno Python principal, requiere Pillow. Se verificó con Python 3.10 / Pillow 12.0.0 en esta máquina; en otras computadoras se puede ejecutar:

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

En la configuración de MCP, MILIASTRA_PYTHON puede especificar la ruta absoluta del ejecutable de Python; si no se especifica, se usa python del PATH. Las capturas no usan Windows.Graphics.Capture ni llaman a IsBorderRequired, que falta en Windows 10 Build 19045.

Orden de llamadas para IA:

1. list_editor_windows obtiene un windowId fresco (combinación de identificador de ventana y PID).
2. capture_editor_window({windowId, method: "window"}); se recibe el contenido estándar de MCP image/png y metadatos estructurados.
3. Inspecciona visualmente la imagen. Para ventanas de fondo se puede probar el modo window; PrintWindow puede devolver fotogramas antiguos o pantalla negra con algunos programas GPU; no se debe juzgar solo por el éxito de la llamada.
4. Si es necesario, usa method: "screen". Este modo requiere que el objetivo esté en primer plano y que no se detecten otras ventanas cubriéndolo; la herramienta no roba el foco automáticamente.

La imagen original se guarda en workspace/captures. La vista previa devuelta no supera por defecto 1600×1200; width/height es el tamaño de la imagen original; previewToImageScale sirve para convertir coordenadas de la vista previa a las de la imagen original. imageOffsetInWindow indica el desplazamiento en píxeles físicos del área capturada respecto a la esquina superior izquierda de la ventana.

Solo se permite capturar y operar sobre YuanShen.exe, GenshinImpact.exe y BeyondEditor.exe. Se rechazan ventanas no válidas, minimizadas, escritorios inaccesibles o protegidos; las capturas de pantalla en segundo plano devuelven un código de error específico. La herramienta de captura no envía entradas ni cambia el foco de la ventana.

En Windows 10 19045 real ya se capturaron vía MCP el sandbox Qianxing (3264×2160) y la escena de edición de Genshin (3840×2160), y se verificaron el administrador de gráficos de nodos, el terreno y los bloques reconocibles. Los errores de captura del plugin de escritorio original no se modificaron; ahora se usa un backend compatible independiente.

Mouse y teclado

Primero list_editor_windows, luego focus_editor_window, y revisa la imagen devuelta. Toma el captureId de los metadatos de la imagen y llama una vez a editor_input:

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

Las coordenadas deben elegirse según la imagen actual; los números de ejemplo no deben usarse directamente como coordenadas de tu interfaz. Otros ejemplos de acciones (cada línea es una solicitud independiente):

{"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}

• Tras cada acción, vuelve a mirar la imagen resultante; usa el nuevo captureId devuelto para el siguiente paso. Las credenciales solo son válidas dentro del mismo proceso del servicio MCP y expiran en 120 segundos; tras una entrada o un cambio de foco, todas las credenciales antiguas quedan inválidas.
• Antes de la entrada, verifica el título de la ventana, la posición, la relación de primer plano y la oclusión del punto de clic. Un fallo parcial también consume credenciales; no las reutilices.
• El menú contextual puede ser una ventana independiente sin título. Descúbrelo con list_editor_windows; si es necesario, captúralo con method: screen; el menú y la ventana principal comparten la relación de primer plano. Cuando el menú se cierra tras una acción, la herramienta intenta devolver una nueva captura del editor en primer plano del mismo proceso.
• inputSent: true solo demuestra que se envió la entrada. Para saber si la función surtió efecto, revisa la imagen o el archivo; POST_INPUT_CAPTURE_FAILED indica que se envió pero la captura falló; no reintentes a ciegas.
• El texto usa SendInput Unicode y no modifica el portapapeles. Enter/Tab se envían mediante key. No se proporcionan la tecla Windows, ni combinaciones de cambio de sistema ni de cierre.
• Si FOCUS_FAILED, debes seleccionar la ventana de destino manualmente. Si INPUT_FAILED, puede deberse al nivel de integridad del proceso de destino o a que parte de la entrada no se entregó; la herramienta no cambia la configuración de seguridad del sistema.

npm run test:input-guards verifica credenciales de captura, parámetros faltantes y rechaza coordenadas fuera de rango; no envía entradas reales. tests/editor-session.mjs es un puente de depuración local para desarrollo, con contraseña aleatoria y solo escucha en loopback; no forma parte del servicio MCP publicado. La trayectoria real de operaciones está en workspace/editor-live-trace.json.

Experimentos y verificación

npm test
npm run test:local

• npm test: usa un GIL sintético claramente marcado, inicia un servicio MCP independiente y un cliente SDK, ejecuta realmente el apretón de manos, llamadas a herramientas, corrección de errores de código, compilación, rechazo de conflictos, escritura y restauración byte a byte; verifica la conservación de campos protobuf desconocidos. Los archivos sintéticos no representan que se puedan cargar en el juego.
• npm run test:local: usa un archivo real con configuración explícita y su resumen, crea una copia y compila una lógica mínima vía MCP. Sin gráfico de destino, verifica MISSING_GRAPH sin modificar el archivo original; no selecciona automáticamente el archivo más reciente.
• La evidencia de las pruebas locales se escribe en workspace/mcp-smoke-report.json y workspace/synthetic-smoke-report.json, con parámetros de herramientas y resultados.

Alcance de implementación y limitaciones

• Solo se verificó en Windows, cliente chino, pantalla completa 16:9; si el juego cambia los textos de la interfaz o el formato del archivo tras una actualización, las herramientas podrían necesitar ajustes.
• Se fija la versión de Genshin-TS y se reutiliza su compilación/análisis; la lectura/escritura propia del archivo solo modifica campos confirmados contra muestras guardadas por el editor; el resto de los datos se conserva tal cual. Fuente en THIRD_PARTY_NOTICES.md.
• El código enviado por la IA pasa por el flujo de compilación y ejecución ascendente; esta es una herramienta de desarrollo local de confianza, no una sandbox para código no confiable. No debe exponerse directamente a internet ni a llamadores no confiables.
• La verificación de hash puede detectar guardados externos tras la vista previa; escribir a la vez que el editor sigue teniendo una ventana de carrera muy corta. Al modificar en tiempo real, primero sal de la escena de destino y vuelve a cargarla antes de guardar. Las operaciones internas de un solo servicio están serializadas; no inicies varios servicios modificando el mismo espacio de trabajo a la vez.
• Importar, hornear y probar requieren que el editor esté abierto. La herramienta no dice que el juego sea jugable solo porque el archivo compile: compilar, escribir en el archivo y verificar en el juego son tres cosas distintas, y se reportan por separado en la respuesta.
• Más limitaciones y pendientes en Estado actual y limitaciones.

Relación con otras herramientas de Qianxing Qiyu

Hay muchas herramientas comunitarias para Qianxing Qiyu; desde que el juego 7.1 añadió Lua en el cliente, la línea 2D + Lua es especialmente numerosa. Casi todas se detienen en el mismo punto: la verificación en el juego real queda para la persona ("que pase el simulador no significa que pase en el dispositivo real", "el botón de probar solo lo puede pulsar una persona", "los archivos generados no se verificaron en el dispositivo real"; eso lo escriben ellas mismas). La posición de este proyecto es ese paso: que la IA construya un nivel completo en el editor y el juego reales, pulse probar ella misma, lea los registros y las capturas.

Proyecto	Enfoque	Relación con este proyecto
Genshin-TS	Escribir gráficos de nodos en TypeScript, compilar e inyectar en el archivo	Este proyecto lo usa para compilar gráficos de nodos. Si solo quieres escribir código a mano sin que la IA opere el editor, úsalo directamente
Conjunto de herramientas de gráficos de nodos de Qianxing Qiyu	Leer/escribir archivos de gráficos de nodos, convertir código y gráficos, datos de nodos	Genshin-TS incorpora sus resultados; este proyecto lo usa indirectamente
Ayaya_Miliastra_Editor	Escribir gráficos de nodos en Python, verificación offline, auto-maquetación, con interfaz de vista previa para personas	Si quieres un flujo Python y una interfaz de vista previa, elige ese; este proyecto no tiene interfaz para personas
Simulador de sandbox Qianxing	Ejecutar Lua de cliente e interfaz fuera del juego, rondas de unos segundos; cinco lienzos, simulación multijugador, grabación y reproducción; editor web y flujo de siete pasos	Su proyecto se puede importar en un paso a este proyecto para dispositivo real: scene_import_simulator lee su archivo completo, escribe scripts, plantillas, interfaces, señales, variables y reglas de servidor en el archivo; los números de plantilla se alinean automáticamente en Lua, y luego se prueba automáticamente. Úsalo para rondas rápidas; para dispositivo real, usa esto
dsh-miliastra	Plugin de DeepSeek Harness: inyectar scripts en archivos vivos junto al archivo, leer registros de ejecución, capturas, sondas, verificación de especificaciones de interfaz	Idea similar (trabaja sobre archivos del dispositivo real); está orientado a Harness y la prueba la pulsa una persona; este proyecto pulsa probar él mismo y también escribe el archivo
miliastra-ugc, MiliastraAgent, genshin-qianxing-2d-game	Paquetes de habilidades y prompts para IA: verificación estática de Lua, sandbox Lua offline, generación de imágenes por píxeles y formas, flujos paso a paso	Generación de imágenes (píxeles, animaciones de fotogramas, ajuste de formas) este proyecto no la tiene; usa las de ellos; los flujos de proceso se pueden combinar con las herramientas de este proyecto
Caja de herramientas de Qianxing Qiyu	Base de conocimiento de documentación oficial y experiencia comunitaria, con MCP en línea	Se puede conectar a la vez: responde "cómo se hace"; este proyecto lo hace
WebMiliastraNodesEditor	Editor web de gráficos de nodos, dibujar gráficos sin abrir el juego	Para prototipar gráficos de nodos
genshin-starcraft-mcp	MCP para consultar tutoriales oficiales y documentación de nodos	Este proyecto incluye una guía oficial offline propia; hay solapamiento de funciones
qianxing-format-docs, genshin-miliastra-file-format	Documentación de formatos de archivo y exportación	La lista de objetos y tamaños de este proyecto proviene del primero (CC BY 4.0)

Solo este proyecto tiene:

• Prueba automática en dispositivo real: importar archivo, marcar registros, pulsar probar, teclas y clics, capturas, leer impresiones; todo sin personas. Dada la impresión esperada, la prueba responde si pasó o no.
• Lua en dispositivo real en rondas de un minuto: al cambiar solo scripts no se reimporta el archivo; medido en 74 segundos por ronda.
• Verificar nombres antes de escribir: nombres de controles, señales, variables, interfaces, números de plantillas e imágenes/sonidos en scripts, verificados uno a uno contra el archivo, el gráfico de nodos, el catálogo y las interfaces oficiales; los parámetros de las señales, en cantidad, tipo y orden, también se verifican contra las definiciones en Lua y en el gráfico de nodos; al escribir la interfaz, se indica directamente qué controles salen de la pantalla en el teléfono. En esta plataforma, un nombre que no coincide no da error; simplemente no reacciona.
• Vista previa multidispositivo dibujada por el editor real: diez lienzos (PC, teléfono, consola), cada uno con una captura; la dibuja el editor, no es una aproximación.
• Todo el nivel está en el archivo: escena y jugabilidad 3D (decoración, combate con criaturas complejas, proyectiles, mecanismos), gráfico de nodos, interfaz normal, interfaz de cliente; los registros escritos son byte a byte idénticos a los que hace el editor a mano.
• Catálogo con miniaturas de objetos, efectos, sonidos y números de imágenes de interfaz.

Este proyecto no tiene: simulador fuera del juego (lo más rápido es un minuto por ronda; el simulador son segundos), simulación multijugador (todos los ejemplos son de un jugador), herramientas de generación de imágenes, interfaz para personas, instalación con un comando (ahora hay que clonar el repositorio), ni plataformas distintas de Windows.

Lo anterior se organizó según lo que dice cada README; si algo no es exacto, abre un issue.

Preguntas frecuentes

¿Puede la IA hacer mapas/niveles de Qianxing Qiyu automáticamente? Sí. Este repositorio es para eso: la IA llama a las herramientas vía MCP, construye la escena desde un archivo vacío, escribe el gráfico de nodos y entra al juego a probar ella misma. Tres IAs que no conocían este repositorio hicieron cada una un juego que se puede completar; el registro está en Prueba a ciegas. Que sea divertido o no, lo sigue decidiendo y ajustando una persona.

¿Qué clientes de IA se soportan? Cualquier cliente que soporte stdio MCP: Claude Code, Claude Desktop, Cursor, Codex CLI, Cline, etc. Para desarrollo se usaron Claude Code y Codex. El servicio no llama a modelos por sí mismo y no necesita API Key.

No sé escribir gráficos de nodos ni código, ¿puedo usarlo? Sí. Dices en chino qué jugabilidad quieres; la IA escribe el código TypeScript del gráfico de nodos y lo compila en el archivo; en el editor ves un gráfico de nodos normal que puedes seguir editando a mano.

¿Los gráficos de nodos de Qianxing Qiyu se pueden escribir con código? Sí. Este proyecto usa Genshin-TS para compilar TypeScript a gráfico de nodos, y le añade pasos como escribir en el archivo, enlazar a entidades y componentes, y compilar varios gráficos a la vez.

¿Funciona con el servidor internacional (cliente en inglés Miliastra Wonderland)? No se ha verificado. La lectura/escritura del archivo no depende del idioma, pero la prueba automática depende de reconocer botones en chino en pantalla; en interfaz en inglés probablemente haya que cambiarlo.

¿Puede dañar mi archivo? Por defecto solo escribe copias del archivo; al probar, importa la copia como un archivo nuevo; el archivo formal solo se escribe si activas explícitamente el interruptor, y antes de escribir compara el hash y hace una copia de seguridad.

¿Qué efecto tiene un nivel bajo de cuenta de creación? En cuentas de Artesano Lv.1, los cuadros de texto personalizados y el texto de opciones no se muestran. La herramienta tiene métodos que no dependen del texto: controles de imagen, barras de progreso, iconos y efectos de marcador.

¿Qué hago si la herramienta se rompe tras una actualización del juego? Abre un issue indicando la versión del juego y la herramienta que falla. El catálogo se copió del editor; el método para volver a copiarlo está en scripts/dev/README.md.

Licencia y fuentes

El código está bajo MIT. El software de terceros usado está en THIRD_PARTY_NOTICES.md.

Las imágenes del juego, las miniaturas de objetos e iconos, las guías oficiales y el contenido de los archivos de enseñanza de Genshin Impact, Qianxing Qiyu y este repositorio pertenecen a miHoYo / HoYoverse; se incluyen solo para que la herramienta pueda buscar por nombre lo que viene con la plataforma y para que las pruebas tengan muestras de comparación. Este proyecto no está afiliado ni respaldado por miHoYo. Si el titular de los derechos considera que algún contenido es inapropiado, abre un issue y se atenderá a tiempo.