Skip to main content
Glama

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 用千星奇域 MCP 做的竞技场清怪游戏

AI 用千星奇域 MCP 做的机关逃脱游戏

AI 用千星奇域 MCP 做的躲避生存游戏

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

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

AI 通过 MCP 在原神千星奇域里自动试玩一局 Lua 写的翻牌配对游戏

它能做什么

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

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

    NPC 头顶的名字、血条、图标、进度条和对话气泡

    战斗里跟着掉的血条

  • 用积木捏东西:平台没有的角色、宠物、载具、雕像,用白盒形状(球、圆锥、长方体、圆柱、棱柱……)拼出来,每块单独上色,整个是一个元件,节点图一句话生成、跟随运动器带着走。拼的时候不用开游戏:工具一秒钟画出四个方向的预览图,看着改。下面是 39 块积木拼的派蒙,出场打招呼,然后一路跟在角色旁边(examples/paimon)。

    用 39 块白盒拼的派蒙:出场说话,然后跟在角色旁边

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

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

    工具做的客户端界面:静态图片、网格列表、运行时造的圆点

  • 写规则:节点图用 TypeScript 写,一次编译几十张图写进存档;自带节点文档、特效(3195 条)、音效(1997 条)、音乐(188 条)的中文目录。

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

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

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

Related MCP server: Hayba

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

千星奇域里的物件、特效、音效、图片,在存档和节点图里都是靠编号引用的。编号在编辑器里看得到,但本地数据里没有现成的表可查。这个仓库把它们整理成了图鉴,大部分是从编辑器里一样一样读出来、拍下来的,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_text_box

屏幕上的文本框:文字,或跟着自定义变量走的数字(“金币:{1:ps.coins}”)。要奇匠 Lv.2 以上的账号才显示

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_add_shape_prefab / scene_preview_shapes

用积木拼一个元件:一串零件,每块是白盒形状(长方体、球体、平面、三棱柱、五棱柱、三棱锥、五棱锥、圆柱、圆锥和两种线框)或任意物件模型,各有位置、旋转、尺寸(米)和颜色;写成“空模型加 N 个装饰物”,整个是一个实体。replace: true 换掉零件、保留编号和挂的图。scene_preview_shapes 不开游戏画出正面、侧面、顶面、斜视四张图(按零件清单,或读存档里的元件)。写法和编辑器手做的逐字节相同;跟随运动器带着走、生成时的朝向都上机验过(examples/paimon)

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_revive / 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/);总结见 千星奇域是怎么搭游戏的

scene_get_level_settings

读关卡设置:仇恨类型、仇恨转移倍率、关卡时钟的起始时刻和流速(改用 scene_set_level_settings,见下面“搭场景”)

scene_batch

一次调用里依次做一串 scene_* 改动,每一步用上一步返回的存档,后面的步骤能引用前面返回的编号;哪一步失败就停在哪一步并说明原因

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

注意:

  • 新建空存档的地面高度是 y=0。方块的位置是它的中心;树、房屋、围栏这类成品模型的位置是底部中心,填 y=0 就站在地面上。

  • 要特效先查 effect_catalog(按名字,如“烟花”“受击 火”“提示”),要声音查 sound_catalog,要音乐查 music_catalog;结果里有节点图里的写法。每个玩家动作都该有声音和画面的回应,做法见 knowledge/notes/feedback.zh-CN.md。

  • 先定镜头再摆景。scene_list_cameras 读出存档里镜头离角色多远、视角多大,scene_set_camera 可以改(写到存档副本),fixedView 把视角锁死(侧视、俯视的游戏都要锁,否则玩家一动鼠标镜头就转走)。画面在角色处的高度约为 2×距离×tan(视角/2):6 米、45° 只有 5 米高,房子都装不下;14 米约 11.6 米高,适合横版远景。镜头一开始在角色背后,横版游戏要在开局用 teleportPlayer 把角色传送成面朝 +z(朝向 [0,0,0]),镜头才会在 −z 一侧横着看;yawRange 定不住这个方向。王国样例的完整做法见 examples/kingdom/gen_kv3_scene.py 开头的说明。

  • 游戏过程中才出现的东西(金币、买下后出现的城墙、跟着玩家走的标记)用元件:scene_add_prefab 把任意物件按指定缩放做成元件,节点图用 f.createPrefab(元件编号, 位置, …) 在任意位置生成,大小就是设定的大小;scene_list_prefabs 列出存档里的元件。会被招募、会被生成的造物也用元件:先在场景里摆一只不创建的怪,再用 scene_add_prefab 的 fromEntity 把它做成元件。

  • 全新的空白地图也能直接开工:scene_add_graph 在存档里建一张空的服务器节点图并挂到关卡实体(新地图没有节点图,write_graphs 需要一张来写)。完整例子见 scripts/dev/fresh_map_round.mjs。各个范例都是整套从空白地图搭起的(见 examples)。

  • 谁打谁由阵营决定:scene_list_factions 看存档里的阵营和敌对关系,scene_set_faction_hostility 改。新地图里玩家、物件、造物三个阵营两两敌对,己方造物会去打节点图生成的物件;多数玩法应该改成只让玩家和造物敌对(hostilePairs: [[1,3]])。

  • 要指挥怪去打谁、往哪儿走:scene_set_level_settings 把关卡的仇恨类型改成自定义(aggroMode: "custom"),节点图里用 f.setTheAggroValueOfSpecifiedEntity(目标, 怪, 数值) 下指令,怪会从远处直接跑向目标(玩家角色、己方单位、物件都可以)。沿路径巡逻的做法在 2026-10-09 游戏更新后失效了(导入存档时巡逻模板被清空),对应的工具已经拿掉。

  • 物件图鉴里同名的很多(光“乔木”就有几十种)。scene_search_assets 的结果带 hasImage;选型前用 scene_asset_images 按编号取缩略图看一眼(一次最多 12 个,返回名字、分组、尺寸和图)。图里每个物件都缩放到差不多大,只用来看长相,真实大小看尺寸。少数物件没有图(拍不出来的),工具会明说,这时再把候选导进练手存档看。

  • 每次导入都是新增,同一个包导两次会多出一份。反复调整时先在一个练手存档里做。

  • 拉伸方块时贴图也跟着拉伸,很大的面近看会糊。

  • 实测过 100 个方块一次导入,更大的数量还没测。

场景和节点图怎么接起来

节点图要用到场景里的东西(夜里放出来的怪、付款后出现的墙)时,按这个顺序走,全程只用 MCP 工具:

  1. editor_open_map:把要用的存档导入并在编辑器里打开(已经开着目标存档就跳过)。

  2. scene_build_blocks + scene_import_assets:导入场景。要“之后再出现”的物件加 createAtStart:false。

  3. scene_list_entities:按名字读回实体编号。导入时编辑器会重新分配编号,包里写的不作数。返回的 mapPath 就是刚保存的那个存档。

  4. write_graphs(mapPath 用上一步的存档,graphs 里是每张图的编号和源码):类型检查、编译、写进存档副本,返回可以试玩的存档。

  5. playtest_start(mapPath 用 write_graphs 返回的存档)→ playtest_status。

节点图里:f.createEntity(new guid(编号), [] as bigint[]) 把没创建的物件创建出来。

scripts/dev/mcp_round.mjs 是照这个顺序把王国样例从头做一遍的客户端,可以当参考。

Windows 10 兼容截图

截图是可选功能,在核心 Python 环境之外还需要 Pillow。本机 Python 3.10 / Pillow 12.0.0 已验证;其他电脑可执行:

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

MCP 配置中的 MILIASTRA_PYTHON 可指定 Python 可执行文件的绝对路径;未指定时使用 PATH 中的 python。截图不使用 Windows.Graphics.Capture,不调用 Windows 10 Build 19045 缺失的 IsBorderRequired。

AI 调用顺序:

  1. list_editor_windows 取得新鲜的 windowId(窗口句柄与 PID 组合)。

  2. capture_editor_window({windowId, method: "window"}),收到标准 MCP image/png 内容和结构化元数据。

  3. 目视检查图像。背景窗口可尝试 window 模式;PrintWindow 对部分 GPU 程序可能返回旧帧或黑屏,不能只以返回成功判断画面正确。

  4. 必要时用 method: "screen"。此模式要求目标位于前台,且没有检测到其他应用窗口覆盖;工具不会自动抢焦点。

原图保存在 workspace/captures。返回的图片预览默认不超过 1600×1200,width/height 是原图尺寸,previewToImageScale 用于预览坐标到原图坐标的换算。imageOffsetInWindow 表示截图区域相对窗口左上角的物理像素偏移。

只允许截图及操作 YuanShen.exe、GenshinImpact.exe 和 BeyondEditor.exe。拒绝失效窗口、最小化窗口、不可访问或受保护的桌面;后台 screen 截图会返回具体错误码。截图工具本身不发送输入,也不改变窗口焦点。

实际 Windows 10 19045 上已经通过 MCP 拍到千星沙箱(3264×2160)和原神编辑场景(3840×2160),并检查到可辨认的节点图管理器、地形与石块。原有桌面插件自身的截图错误未被修改;现在使用的是独立兼容后端。

鼠标和键盘

先 list_editor_windows,再 focus_editor_window,检查返回的图片。取图片元数据中的 captureId,调用一次 editor_input:

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

坐标必须根据当前图片选取,示例数字不能直接当成你的界面坐标。其他动作示例(每行是独立请求):

{"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}
  • 每次动作后重新查看结果图片;用新返回的 captureId 执行下一步。凭据仅在同一个 MCP 服务进程有效,120 秒过期,输入或切焦点后旧凭据全部失效。

  • 输入检查窗口标题、位置、前台所属关系和点击位置遮挡。部分失败也会消耗凭据;不要重复使用。

  • 右键菜单可能是独立的无标题窗口。通过 list_editor_windows 发现,必要时 method: screen 拍摄;菜单和主窗口共享前台关系。菜单在操作后关闭时,工具尝试返回同进程前台编辑器的新截图。

  • inputSent: true 只证明发送过输入。检查图片或存档才能判断功能生效;POST_INPUT_CAPTURE_FAILED 表示已发送但截图失败,不能盲目重试。

  • 文本使用 Unicode SendInput,不改剪贴板。Enter/Tab 通过 key 发送。Windows 键、系统切换和关闭组合键不提供。

  • 若 FOCUS_FAILED,需要手动选择目标窗口。若 INPUT_FAILED,可能涉及目标进程完整性级别或部分输入未送达;工具不会更改系统安全设置。

npm run test:input-guards 检查截图凭据、缺失参数和越界坐标拒绝,不发送实际输入。tests/editor-session.mjs 是本地开发调试桥,使用随机口令,仅监听 loopback;不属于 MCP 发布服务。实际操作轨迹位于 workspace/editor-live-trace.json。

实验和验证

npm test
npm run test:local
  • npm test:使用明确标记的合成 GIL,启动独立 MCP 服务和 SDK 客户端,实际执行握手、工具调用、代码错误修复、编译、冲突拒绝、写入和逐字节恢复;检查未知 protobuf 字段保留。合成文件不代表能在游戏中加载。

  • npm run test:local:使用显式配置的真实存档及摘要,创建副本,通过 MCP 编译最小逻辑。无目标图时验证 MISSING_GRAPH,不修改原存档;不自动选择最新存档。

  • 本机测试证据写入 workspace/mcp-smoke-report.json 和 workspace/synthetic-smoke-report.json,包含工具参数和结果。

实现范围和限制

  • 只在 Windows、国服中文客户端、16:9 全屏下验证过;游戏更新后界面文字或存档格式变了,工具可能要跟着改。

  • 固定 Genshin-TS 版本并复用其编译/解析;自己写的存档读写只改对着编辑器存出来的样本确认过的字段,其余数据原样保留。来源见 THIRD_PARTY_NOTICES.md。

  • AI 提交的代码会经过上游编译执行流程;这是本地可信开发工具,不是不可信代码沙箱。不应直接暴露给公网或不可信调用方。

  • 哈希检查可以发现预览后的外部保存;与编辑器同时写文件仍存在极短竞争窗口。实时修改时应先切出目标地图,重载后再保存。单服务内部操作串行化;不要启动多个服务同时修改同一工作区。

  • 导入、烘焙、试玩都要开着编辑器。工具不会仅凭文件构建成功就说游戏可玩:编译通过、写进存档、在游戏里验证过是三件事,返回里分开报告。

  • 更多限制和还没做的事见 现状和限制。

和其他千星奇域工具的关系

社区里千星奇域的工具很多,游戏 7.1 加了客户端 Lua 以后,2D + Lua 这条线上尤其多。它们几乎都停在同一个地方:进真游戏验证这一步交给人(“模拟器通过不等于真机通过”“试玩按钮只能人点”“生成的文件没在真机验证过”,这些是它们自己写的)。本项目的位置就是这一步:让 AI 在真实的编辑器和游戏里把一整关做出来,自己点试玩、自己读日志和截图。

项目

侧重

和本项目

Genshin-TS

用 TypeScript 写节点图,编译并注入存档

本项目编译节点图用的就是它。只想自己手写代码、不需要 AI 操作编辑器的,直接用它

千星奇域节点图工具集

读写节点图文件、代码和节点图互转、节点数据

Genshin-TS 内含它的成果,本项目间接用到

Ayaya_Miliastra_Editor

用 Python 写节点图,离线校验、自动排版,有给人看的预览界面

想要 Python 工作流和节点图预览界面的选它;本项目没有给人看的界面

千星沙箱模拟器

游戏之外跑客户端 Lua 和界面,几秒一轮;五种画布、多人模拟、录制回放;有网页编辑器和七步制作流程

它的工程可以一步导进本项目上真机:scene_import_simulator 读它的完整存档,把脚本、模板、界面、信号、变量和服务端规则都写进存档,模板编号在 Lua 里自动对上,然后自动试玩。几秒一轮地调用它,上真机用这里

dsh-miliastra

DeepSeek Harness 插件:把脚本投进存档旁的活文件、读运行日志、截图、探针、界面规范检查

思路相近(都在真机的文件上干活),它面向 Harness、试玩由人点;本项目自己点试玩,也写存档本身

miliastra-ugc、MiliastraAgent、genshin-qianxing-2d-game

给 AI 的技能和提示词包:Lua 静态检查、离线 Lua 沙箱、像素画和图元拟合出图、分步流程

出图(像素画、帧动画、图元拟合)本项目没有,用它们的;流程类的可以和本项目的工具一起用

千星奇域工具箱

官方文档和社区经验的知识库问答,有在线 MCP

可以和本项目同时接:它回答“怎么做”,本项目动手做

WebMiliastraNodesEditor

网页版节点图编辑器,不开游戏就能画节点图

画节点图原型用

genshin-starcraft-mcp

查官方教程和节点文档的 MCP

本项目自带一份离线的官方指南,功能有重叠

qianxing-format-docs、genshin-miliastra-file-format

存档和导出文件格式的文档

本项目的物件名单和尺寸来自前者(CC BY 4.0)

只有本项目有的:

  • 真机上的自动试玩:导入存档、勾日志、点试玩、按键点鼠标、截图、读回打印,全程没有人。给出预期的打印,试玩自己回答通过没有。

  • 真机上一分钟一轮的 Lua:只改脚本时不重新导入存档,实测 74 秒一轮。

  • 写进去之前先对名字:脚本里的控件名、信号名、变量名、接口名、模板和图片音效编号,对着存档、节点图、图鉴和官方接口逐个查;信号带的参数,Lua 和节点图两边的个数、类型、顺序也对着定义查;界面写进去时直接说哪些控件在手机上出了屏幕。这个平台上名字对不上不报错、只是没反应。

  • 真编辑器画的多设备预览:电脑、手机、主机十种画布各截一张,是编辑器自己画的,不是近似。

  • 整关都在存档里:场景和 3D 玩法(摆景、复杂造物的战斗、投射物、机关)、节点图、普通界面、客户端界面,写出的记录和编辑器手配的逐字节相同。

  • 带缩略图的物件、特效、音效、界面图片编号图鉴。

本项目没有的:游戏之外的模拟器(最快也是一分钟一轮,模拟器是几秒)、多人模拟(所有范例都是单人)、出图工具、给人看的界面、一行命令安装(现在要克隆仓库)、Windows 以外的平台。

以上是按各项目 README 的自述整理的,如有不准确请提 issue。

常见问题

能让 AI 自动做千星奇域的地图 / 关卡吗? 能。这个仓库就是干这个的:AI 通过 MCP 调这里的工具,从一张空白存档搭出场景、写好节点图、自己进游戏试玩。三个没见过这个仓库的 AI 各自做出了一局能打通的游戏,记录在 盲测。好不好玩还是要人来判断和调。

支持哪些 AI 客户端? 任何支持 stdio MCP 的客户端:Claude Code、Claude Desktop、Cursor、Codex CLI、Cline 等。开发时用的是 Claude Code 和 Codex。服务自己不调用模型,不需要 API Key。

我不会写节点图 / 不会写代码,能用吗? 能。你用中文说想要什么玩法,AI 写节点图的 TypeScript 源码并编译进存档;你在编辑器里看到的是普通的节点图,可以接着手改。

千星奇域的节点图可以用代码写吗? 可以。本项目用 Genshin-TS 把 TypeScript 编译成节点图,并在它上面加了写进存档、挂到实体和元件、一次编译多张图这些步骤。

国际服(Miliastra Wonderland 英文客户端)能用吗? 没验证过。存档读写不分语言,但自动试玩靠识别屏幕上的中文按钮,英文界面下大概率要改。

会不会弄坏我的存档? 默认只写存档的副本,试玩时把副本导入成一份新存档;正式存档要显式打开开关才会写,写之前比对哈希并备份。

创作账号等级低有什么影响? 奇匠 Lv.1 的账号,自定义的文字不显示:文本框是空的,选项卡只有图标没有字。升到 Lv.2 以后都正常显示,头顶的气泡和铭牌也是在 Lv.2 上验证的(都是实测)。工具两种做法都有:用文字的,和不靠文字的(图片控件、进度条、图标、标记特效);工具说明会提醒 AI,不确定账号等级时先放一个文本框试玩看一眼。

游戏更新以后工具坏了怎么办? 提 issue,说明游戏版本和出错的工具。图鉴是从编辑器里抄出来的,重抄的办法在 scripts/dev/README.md。

许可和来源

代码按 MIT 许可。用到的第三方软件见 THIRD_PARTY_NOTICES.md。

《原神》、千星奇域以及仓库里出现的游戏画面、物件和图标的缩略图、官方指南和教学存档的内容,权利属于米哈游 / HoYoverse;放在这里只是为了让工具能按名字查到平台自带的东西、让测试有样本可比。本项目不隶属于也未获得米哈游的认可。权利方如认为其中内容不妥,请提 issue,会及时处理。

Available Tools

85 tools
capture_editor_windowA
Read-only

Capture a freshly discovered game/editor window and return an inline PNG plus original file and coordinate metadata. window mode uses PrintWindow; GPU content may be blank/stale. screen mode requires foreground; fully covered edges are cropped, interior other-app overlaps are rejected. Does not focus windows or send input. Inspect the image before assuming it is usable.

Inputs: windowId (required), method, maxWidth, maxHeight.

creature_animationsA
Read-only

The animations of the complex creatures (the assets of the group "怪物(AI版)"), by creature: id, name, length in seconds and whether it loops. A creature skill (scene_add_creature_skill) plays one or several of them, which is everything a complex creature does besides walking: swing, shoot, dig, look around, talk, laugh. The models come with empty hands, and an attack only looks right with the thing in the hand its animation was made for: inItsHands says what a creature can hold, and the animations that were looked at in play say what happens in them (what) and at which millisecond the blow lands or the hand opens (atMs: the graphAtMs of the skill). Without creature it lists the creatures whose animations are known (with query, those that have a matching one: 挖矿 digging, 攻击 attacks, 待机 standing, 交谈 talking). Names and ids were read from the editor on 2026-10-11. Read-only.

Inputs: query, creature.

editor_inputA
Destructive

Send ONE click, key chord, literal Unicode text, scroll or drag to the window from a fresh captureId, then return a new screenshot. Coordinates are pixels of the returned preview image, not the original PNG. Capture IDs are single-use and expire after 120 seconds. Requires target foreground, unchanged rect/title, unobscured click point. Check the fresh image to verify effects. Use positive scroll delta to scroll up, negative to scroll down.

Inputs: kind (required), captureId (required), x, y, +8 more.

editor_open_mapA
Destructive

Import a .gil as a new save and leave it open in the editor, without playing it. Do this before scene_import_assets when the scene should go into a particular map. Needs the game running (main world, Miliastra lobby, save list or editor) and takes over mouse and keyboard for about 80 seconds. Returns a runId; poll playtest_status until it succeeds (officialSave is the new save file).

Inputs: mapPath (required).

editor_preview_interfaceA
Destructive

Show what the interface of a save looks like on other devices, in the editor itself, and return a picture of each canvas: a computer (1600 x 900), a phone (1280 x 720, also 19.5:9 and 4:3), a console (1920 x 1080, also 21:9), a phone with a gamepad. Most players are on phones, and the same numbers put a control elsewhere on each canvas (what stands 700 to the side on a computer is off a phone's screen): this is the look to take before saying an interface is done. It is the editor's own interface manager that draws the pictures, with the platform's own controls of that device around yours (the touch buttons of a phone, the key hints of a computer), so a control that lies under one of them shows. With mapPath the save is imported and opened first (or, when it is the one the last playtest left open, used as it is); without, the save that is open is shown. Client controls are drawn as the save has them, before any script ran: what a script draws at run time is not there. Takes over mouse and keyboard for about 30 seconds (90 with an import). Returns a runId; playtest_status gives the pictures.

Inputs: mapPath, canvases.

effect_catalogA
Read-only

The special effects of the platform that a node graph can show, by name: 1986 one-off effects (限时特效: a flash, dust where something appears or vanishes, a hit, an explosion, a warning circle, fireworks) and 1209 looping ones (循环特效: glows, markers and arrows that point at something, auras, shields, flying projectiles, question and exclamation signs over a head). Feedback is what makes a level feel like a game: give every action of the player one (picked up, bought, refused, hit, built, lost). query: words of the Chinese name (烟花, 受击 火, 提示); kind: "timed" or "looping"; the first rows come with the small picture the editor shows for them. ids: look at those effects, one picture each. page: contact sheets of the first 84 looping effects photographed on a character in play. queries: several searches in one call, one list each and no pictures (then look at the ones you chose with ids). The result says how to play and clear an effect in graph code. The names and ids were read from the editor's own lists on 2026-10-11. Read-only.

Inputs: ids, kind, page, limit, +4 more.

focus_editor_windowA
Destructive

Bring an observed game/editor window to the foreground and return a fresh screenshot. Windows may deny focus; do not proceed if it fails.

Inputs: windowId (required).

get_capabilitiesA
Read-only

Discover supported operations, limitations, version, configured paths and recommended workflow.

Inputs: no named parameters.

image_catalogB
Read-only

The pictures a screen can show (图片资源库 of the image control): icons of what a player does (功能图标, 玩法图标: elements, flags, swords, shields, hearts of the platform), decorations in colour (stars, crowns, balloons, coins, fruit, animals, clouds), plates and frames to put things on, plain shapes, dividers, special characters, skill and talent icons, items (potions, keys, chests, books, weapons) and portraits of creatures. Without arguments it lists the categories with the range of ids each holds; with a category it returns photographs of the editor's own grid, four sheets to a page, each picture with its id under it. Look at the sheets and read the id of the picture that fits: it is the image of scene_add_image. There are no names to search by, so choose by eye. This is how a screen without words gets its meaning: a heart beside the health bar, a key that appears when the key is found, a sword on the attack button.

Inputs: page, category.

inspect_mapA
Read-only

Read GIL header and actual node graph IDs, names, types and counts (nodeCount, and editorCount: the size the editor counts against its limit of 3000).

Inputs: mapPath (required).

list_editor_windowsA
Read-only

List visible Genshin and Miliastra editor windows with current windowId, PID, physical rect, foreground and minimized state. Read-only Windows 10 compatible backend.

Inputs: no named parameters.

list_mapsA
Read-only

List the saves in the game's save list, newest first: the name the creator sees, id, path, size and when it was last written. Excludes temporary and downloaded runtime maps. Every import (editor_open_map, playtest_start with a mapPath) adds a save named after the imported file.

Inputs: no named parameters.

music_catalogA
Read-only

The background music of the platform: 188 pieces with id, title, length in seconds and category (探索音乐 calm, 战斗音乐 tense, 任务音乐 story, 其他需求 events). A graph sets the music of a player at any moment with f.modifyPlayerBackgroundMusic: one piece for the day and another for the night, a tense one for the last wave, and so on; the result shows the call. query: words of the title; category: one of the four. Read from the editor's music library on 2026-10-11. Read-only.

Inputs: limit, query, offset, category.

playtest_framesA
Read-only

Put the screenshots of a finished playtest side by side in one picture, each cut to the same part of the screen and labelled with its play second: the way to look at motion. Whether an attack is right does not show in prints: is the weapon in the hand, does the blow land when the number comes up, does the knife leave when the hand opens, does a creature stop where it should. Take screenshots a quarter or half a second apart over the seconds that matter (playtest_start screenshotsAt takes fractions of a second, up to 120 of them; screenshotWidth up to 3840 keeps more detail), bring the camera close (scene_set_camera) or cut the picture with crop, then look at the sheet: left to right, top to bottom. fromSeconds and toSeconds pick the span (play seconds, the clock of the screenshots), every takes each n-th, crop is [x0, y0, x1, y1] as fractions of the screen, columns and width (pixels of the whole sheet) set the size of a frame. Several sheets of one run are fine: a wide one to find the moment, a close one of two seconds around it. Read-only.

Inputs: runId (required), crop, every, width, +4 more.

playtest_startA
Destructive

Run one full playtest through the official UI without further calls: optionally import a candidate .gil as a new save, subscribe the debug log for graphName (or for every graph in graphNames when the level is several graphs: only ticked graphs show their prints, and the log window lets at most 10 be ticked, so leave out the graphs that print nothing), start the playtest, take screenshots and press keys at the given seconds, leave after durationSeconds and collect the official log. screenshotsAt takes fractions of a second (a screenshot costs about a third of a second, so a quarter second apart is as close as it gets): a run of them over an attack, put side by side by playtest_frames, shows the motion frame by frame; screenshotWidth (default 1600) keeps them larger for that. An input is a key ({at, key, holdMs}: a tap of 120 ms unless holdMs says otherwise; hold a movement key for as long as the walk takes, up to a minute; keys overlap, so a character walks with one key held while another strikes; repeat {every, until} presses the key again every so many seconds until that second, which is how a fight of three minutes is scripted: {at: 5, key: "e", repeat: {every: 1.2, until: 170}}; up to 400 inputs; keys that were sent more than 0.3 s after their moment are listed in inputsLate of playtest_status, which is where to look first when a scripted walk ended in the wrong place), a mouse click at a place of the game window ({at, click: [x, y]} as fractions from the top left), held down for holdMs when that is given above 150 (a screenshot taken in between shows what a button looks like while pressed) or a click on a word that is on the screen ({at, clickText: "购买"}; words not found are listed in inputsMissed): the clicks are for screens with a free cursor, such as a shop. A place can be reached without walking: {at, teleport: [x, y, z], yaw} puts the player there at that second of the play (no earlier than 2.5), which is how a script stands exactly at a stall or in a doorway instead of guessing how long to hold a key; {at, look: [right, down]} moves the mouse that many pixels with no button held, as a player turns the camera (the way to check that a locked view stays locked); walking is still what a real player does, so walk where the walk itself is being tested. The level itself does the teleports, on a timer, so none is lost and none takes the place of another; half a second after each the probe looks where the player is, and probe.teleports of playtest_status says for every one whether it arrived (a teleport does not take while the character is down). Two teleports are at least a second apart, and a playtest takes up to 200 of them. trackPlayer (seconds between samples, 0.5 is a good value) records where the player is: playerTrack in playtest_status lists [playSeconds, x, y, z], from which the speed of a walk and the place of every event can be read. Both add a small probe to a copy of the level (three graphs, a skill on skill slot 4, which is the Z key on a PC, the player variables PT_step, PT_tp, PT_t0 and PT_turn; two more graphs in the log window, so name at most eight of your own); with it playtest_status also dates every print in play seconds (playSeconds beside t), which is the clock of the screenshots and the inputs: the level clock t starts a few seconds earlier, a different few every run, and falls behind when the level is busy (two seconds in three minutes on a level of 585 nodes): the runner presses the key of the probe at second 1 and every half minute after, and each press ties the two clocks together anew; probe.levelClockFellBehind says by how much they parted. A timer of the platform also runs slow by itself, about 4.5 % at 60 frames a second (a moment set at 50 s came at 52): the teleports of a script are set earlier by that much and counted from the latest press, and probe.teleports gives the play second each really happened; leave a second of margin around them. A graph of your own that counts seconds with a timer is slow in the same way: a round of 180 timer seconds lasts about 188 on the wall. startValues gives custom variables other start values for this one run ([{prefab: "player", variables: [{name: "wave", value: 5}]}], or entity for the placed things of one name; the type is taken from the variable that is there): the way to try the last minute of a level of three minutes without playing the first two, when the level keeps its clock or its stage in a variable. The values go into a copy; playtest_status says startValues were used, and such a run shows how that part plays, not that the level as built can be won. The track shows where the player stands, not a jump: the height it records stays the same while the character is in the air for an ordinary jump (look at screenshots for that). The probe uses skill slot 4 (Z) and timers named PT_ on the character and the stage entity: a level with a skill of its own on slot 4 cannot be probed. A character that is in the middle of another skill does not hear the key of the probe: keep the keys of your script that use a skill (an attack on E, say) away from seconds 1, 31, 61, 91 and so on by a second on either side, or the teleports of the half minute that follows do not happen (probe.teleports then says so for each). readTextAt reads the text on the screen at those seconds (screenTexts in playtest_status), which tells what a shop or a dialog shows without looking at an image. recordVideo {from, to} records the game between two seconds of the play with the Xbox Game Bar of Windows (it has to be switched on: 设置 > 游戏 > Xbox Game Bar); playtest_status then has video.file, an .mp4 for the listing of a published level (the official advice is ten to thirty seconds of the best moment). recordAudio records what the machine plays during the level: playtest_status then has audio with the .wav, how loud each second was and the seconds at which a sound began, which is how a script learns that its sounds and music play (nobody is listening). bakeNavigation bakes the navigation mesh of the level in the editor before playing (关卡设置 > 地形导航 > 开始烘焙; a minute or two, more on a big scene): a level with complex creatures needs it, or the tactics that choose their own points (wandering, pursuit, fleeing) find none and the creature stands still. bursts photographs stretches of the play several times a second ({from, to, everyMs}, 125 ms apart unless said, at most 600 frames a run; a 4K screen cannot be read faster than about eight times a second, and a frame whose turn comes too late is left out so that keys stay on time): what is needed to see when a stroke lands, when a hand opens or how far an attack carries a creature, which two screenshots a second cannot show. The frames are not returned as images: playtest_status says how many there are and how far apart they really came (burstFrames), and playtest_frames {runId, fromSeconds, toSeconds, crop} puts a stretch of them side by side, each labelled with its play second to a hundredth. Needs the game running (main world, Miliastra lobby, save list or editor) and the monitor of the computer switched on (with no display attached nothing the game draws is shown: the run then fails at once and says so), and takes over mouse and keyboard until it finishes. A failure that says the game window does not answer means the game has to be closed and started again. A level that reaches its result screen before durationSeconds ends the run six seconds later (endedEarly), so durationSeconds can be generous. Returns at once with a runId; read the outcome with playtest_status. Omit mapPath to replay the save already open in the editor. The first playtest of a workspace imports the candidate as a new save into the save list of the game; later ones write the candidate over that same save and open it again (replaceSave, on unless switched off), so that a night of playtests leaves one save in the list and not thirty. The save editor_open_map opened (the one the scene was imported into) is never written over: the playtest after an editor_open_map imports a save of its own. A candidate that differs from the save still open only in the text of its client scripts (Lua) is not imported either: the scripts are written into the files the editor keeps beside the save, which are what the game runs, and the play starts (a round on the Lua is about 70 seconds instead of five minutes; playtest_status says shortWay). expect {prints: [...], absent: [...]} says what the run has to print, in order: playtest_status then answers with expectations {passed, firstNotMet}, and a round ends in a yes or in the one line that is missing. When the save holds client scripts, what they name is checked before anything is started (scene_check_client): a script that does not compile stops the call at once, the rest comes back as clientCheck. A playtest of the very same candidate as the last one (same file, same teleports and trackPlayer; other keys, screenshots or bursts) while the editor still has it open skips importing and opening altogether and starts about two minutes sooner (step same-save-still-open): the way to look at one moment again from closer. Read miliastra://platform-rules before designing a test: creatures far from every player do not act and report stale positions.

Inputs: bursts, expect, inputs, mapPath, +14 more.

playtest_statusA
Read-only

Progress or outcome of a playtest_start or scene_import_assets run: completed steps, log prints (t is the level clock in seconds) and the screenshots as images. At most 8 screenshots come as images, spread evenly over the run (imagesShown names their play seconds); screenshotsFrom and screenshotsTo (play seconds) pick a span to take the eight from instead. screenshots lists every one with its file and playSeconds, and playtest_frames shows any span of them side by side in one picture (the way to look at a stretch closely). Filter prints with prefix or graphId. Look at the screenshots yourself; a succeeded run only means the level was played, not that the gameplay is right. When the level reached its result screen before the planned time, levelEndedAt is the play second it was first seen; when the server ended the level for load, serverMessage holds the line it showed and warning explains the usual cause. waitSeconds (up to 45) holds the answer back until the run has ended or that many seconds have passed: call it again while state is still "running", which is four or five calls for a playtest instead of forty.

Inputs: runId (required), prefix, graphId, maxPrints, +4 more.

publish_kitA
Read-only

Put together what a level is published with, from playtests that were already run: a cover and four more pictures cut to 16:9 at 1600 x 900 (each is the screenshot nearest to a play second of a run: {runId, playSeconds}), the title, the description, the tags, an optional video file, and a checklist of what the official guide to publishing asks for (a title of at most ten Chinese characters or twenty Latin ones; five different pictures; what matters on the cover in the middle or on the right, because a tag may hide its left side on the home page; a description that says what you do, what is special and one hint; how many players the level takes; whether there is a respawn point). Everything goes into one folder, /publish/, with a listing.md to copy from; the cover comes back as an image to look at. Take the screenshots for it on purpose: a playtest with screenshotsAt at the best moments (a fight in full swing, the whole scene, the win), without debug markers on the screen. This tool does not publish: that is done by the creator in the game (我的奇域 > the save > 上传存档 > 预览信息), under their own name.

Inputs: name (required), cover (required), title (required), images (required), +4 more.

read_knowledgeA
Read-only

Read one knowledge-base page by the id that search_knowledge returned, optionally only the sections whose heading contains heading. Image links are stripped unless images is true (the official CDN screenshots of node graphs and editor panels are in them).

Inputs: id (required), images, heading.

scene_add_buttonA
Destructive

Put an interaction button (交互按钮) on the screen in a copy of a save: a round button the player clicks (or presses with its key), at any time and anywhere, unlike an option tab that needs the character next to something. Pressing it raises whenUiControlGroupIsTriggered in a graph on the player template (scene_add_graph attachToPrefab "player"); evt.eventSourceEntity is the player that pressed, and evt.uiControlGroupIndex is the controlGroupIndex this tool returns for the button. position is [x, y] from the screen centre on a 1600 x 900 canvas, y up; size [width, height]; key is the number key that presses it (1 by default: give each button its own). On a computer the button is pressed with its key, which is shown under it: the mouse cursor belongs to the camera during play. The button has the editor's default settings otherwise (no cooldown, no use limit, the default icon, a question mark); with key 1 the three records written are byte for byte those of the button in the official sample 界面控件. Verified in play on 2026-10-11 (examples/buttons): two buttons, keys 1 and 2, each raised the event with its own index, on an account of 奇匠 level 1. Writes a new .gil in the workspace; the official save is not touched.

Inputs: name (required), key, size, mapPath, +2 more.

scene_add_card_selectorA
Destructive

Add a card selector (卡牌选择器) to a copy of a save: the platform's own window in which a player picks one or more cards out of a few, each with an icon, a title and a description (three upgrades to choose from after a wave, a reward, a class at the start); in a level for one player the game stands still while it is open. cards is the library of cards the window can show, {title, description, icon, label} each, or {unknown: true, label} for a card that hides what it is. A graph opens the window for a player with f.invokeDeckSelector, saying which cards of the library to show this time and what value each gives back, and the choice comes to a graph on the player template as whenDeckSelectorIsComplete; the answer of this tool gives both lines. seconds is the time to choose in (the graph may give another). canGiveUp: false takes the button 放弃选择 away (the player has to choose), canFold: false the button that folds the window away, pauseWhenAlone: false lets the game run on behind it, showTime: false hides the countdown; all four are on unless said. The selector stands in no layout: it shows only when a graph opens it, and not in the first seconds of a level (opened at level second 3 it did not show and the choice came back as the default twenty seconds later; at second 14 it showed: open it some seconds in, or on something the player did). The window has a title, a countdown, the cards in a row, 放弃选择 and 确认选择; a playtest picks a card with an input {clickText: its label} and then {clickText: "确认选择"}. Icons seen in the official sample: 91001 a sword (the one a card has when none is given), 91011 a polearm, 91016 a catalyst, 92001 to 92003 dishes. The records are those of the official sample 卡牌选择器, byte for byte; seen in play 2026-10-14 (examples/cards). Its words show on an account of 奇匠 level 2 and up. Writes a new .gil in the workspace.

Inputs: name (required), cards (required), title, canFold, +8 more.

scene_add_client_templateB
Destructive

Add a template of client controls (客户端控件模板) to a copy of a save: one control, with children when it is a container, kept beside the screen. A script makes copies of it at run time (game.InstantiateClientUIControl(templateIndex, parent), game.DestroyClientUIControl(control)): bullets, cards, rows of a list, anything whose number is not known beforehand. A grid of scene_add_client_ui makes its items from one (itemTemplate), a reference shows one (template). template is a control as scene_add_client_ui takes one (its name is the name of the template; a container with children, an image, a preset button with its states, scripts of its own that start with every copy); the result gives its templateIndex for the script. Add the template before the interface that uses it. Writes a new .gil in the workspace. The records are byte for byte those of two templates saved in the editor; not yet seen in play.

Inputs: template (required), mapPath, replace, outputName.

scene_add_client_uiA
Destructive

Put a tree of client controls (客户端控件) on the screen, in a copy of a save: a container that fills the screen, with the controls given under it and the client script (scene_set_client_script, by name) on its root. A control is {name, kind, position, size, children}: kind "image" (a picture: give image, an id from image_catalog, and colour and opacity here, or let the script give it one with control:SetImage(Enum.ImageSource.StaticReference, id) and control.imageColor = Color(r, g, b, a); fill: {shape: horizontal | vertical | radial90 | radial180 | radial360, from, amount 0 to 1} shows a part of it, which is a bar or a cooldown ring with no script drawing it, feather softens its edge and invertMask shows the rest instead), "grid" (网格视窗: a scrolling list whose items are copies of a template, itemTemplate: its name; the script fills it), "reference" (模板引用控件: shows a template, template: its name), "presetButton" (预设按钮), "keyHint" (按键提示: the key of the device in use), "textWindow" (文本视窗: a text box that scrolls), "animation" and "fullscreenAnimation" (界面动效), "cursorArea" (an area that hears the mouse: area:AddCursorEventListener(Enum.CursorEventType.CursorClick, fn); the root needs showCursor = true for the cursor to be there), "container" (holds other controls in children, and moves them with it), "text" (a text box; shown on an account of 奇匠 level 2 and up, seen in play 2026-10-13, and nothing of it on level 1). position is [x, y] of the control's centre from the centre of what holds it, y up, in units of the canvas; size [width, height]. The canvas is 1600 x 900 on a computer, 1280 x 720 on a phone, 1920 x 1080 on a console: the same numbers are used on all of them unless devices says otherwise, so a control more than 640 to the side or 360 up or down is off a phone's screen; hang what belongs at an edge on that edge with anchor, or give devices {mobile: {position, size}, console, mobileGamepad} where the layout must differ. The answer names what would be off a phone as given (offPhoneCanvas: the control and by how much on which side). Beyond what is said here the controls are written the way the editor makes a new one: what each shows, and every change after, is the script's to make (SetAnchoredPosition, SetSizeDelta, SetVisible, SetActive). A control takes more than this when wanted (the schema lists it): scale, rotation, pivot and anchors; active false and visible false for a start out of sight; a script of its own, and values of its own for that script's public variables (script: {name, values: {variable: value}}; a variable of type controlId takes the name of a control); navigation {left, right, up, down} saying which control the stick of a gamepad goes to (by name, or "none"); text {content, fontSize, colour, align...} on a text box (scrollable and scrollbar on a text window); grid {columns or rows, itemSize, spacing, padding}; states {normal, hover, pressed, disabled} naming the children a preset button shows (give hover as well as normal, or the button shows nothing under the cursor); key for a key hint; effect for an interface effect; and on the interface itself showCursor, blockKeys, blockCursor, hidden (out of sight, its scripts not started, until a graph switches it on by containerId), scripts (several on the root). A script finds a control by its name, so the names of one holder must differ. Controls are drawn in the order given, later ones over earlier ones, and over the whole of the ordinary interface when they cover it. Client controls are destroyed and made anew when the player is teleported or reconnects: a script must be able to draw its state again from the custom variables. Writes a new .gil in the workspace. Byte for byte the official sample 客户端脚本 when given what that sample holds, and every kind and every setting byte for byte what the editor writes for it; seen in play on 2026-10-13 (examples clientui, clientgame, clientlist, clientmenu, clientcheck, clientvars), text and the text window on 2026-10-13 on an account of 奇匠 level 2 (example clienttext; level 1 shows no custom text), all but what only another device shows (devices, navigation: this was played on a computer with mouse and keyboard; editor_preview_interface shows the other canvases).

Inputs: name (required), hidden, script, mapPath, +8 more.

scene_add_componentsA
Destructive

Give a prefab (and every placed copy of it) or the placed entities of one name the platform's own components, in a copy of a save. This is how interaction is done on this platform, instead of comparing positions on a timer. collisionTriggers: zones that raise whenEnteringCollisionTrigger / whenExitingCollisionTrigger in a graph attached to the same prefab or entity when a character (or object, creature) walks in or out: pickups, pressure plates, shop areas, "inside the base". The enter event comes once for each entity, at the moment it walks in: a thing that has to act again while the entity stays inside (a tower that reloads, a shop with a cooldown) asks again itself when it is ready, with f.getAllEntitiesWithinTheCollisionTrigger(self, triggerIndex) (examples/kingdom5 does this for its archery range). A zone that lies on the ground has to stand at least 0.45 m high to catch a standing character: one of 0.3 m passed under a character that stood still, eight times out of eight (the shape of a character that triggers does not reach its feet). For a thing to be jumped over make it 0.45 to 0.6 m; from 0.8 m a jump does not clear it. Areas grow with the scale of the prefab. When a hazard is meant to be dodged, check both halves in play: that it hits a player who does nothing, and that it misses one who dodges. optionTab: the native "walk up and press F" prompt with one or several options; choosing one raises whenTabIsSelected with the option id: paying, opening, talking, switching. variables: custom variables (自定义变量) with a type and a start value, the place where an entity keeps its own state; any graph reads and writes them by name, and whenCustomVariableChanges fires on the entity that holds them. motions: basic motion devices (基础运动器) that a graph starts by name with f.activateBasicMotionDevice, or that run from the moment the piece appears (active true). Either a straight move, {name, move: [x, y, z] metres, seconds} (a gate that rises, a wall that comes up; the metres are those of the world, whatever the scale of the piece; a motion can be started again after it has run, so a gate with the motions open, [0, 4, 0], and close, [0, -4, 0], opens and closes as often as a graph starts them in turn: examples/doors, seen in play 2026-10-13), or a path, {name, path: [{position relative to the piece, rotation in degrees, seconds from the point before}...], loop}: loop "backAndForth" with one waypoint and active true is the moving platform of platform games (it goes there and back for ever), "restart" with waypoints that only turn ([0,180,0] then [0,360,0]) spins a thing on the spot, "once" stops at the end. Objects only, creatures move by themselves. follow: a follow motion device (跟随运动器), "attach" to stick to a target or "chase" to fly to it, for things carried by or drawn to a player; a graph names the target. minimapMarker: an icon for the entity on the minimap, with a name and a description (the icon shows where to go without any text on screen). textBubbles: what the thing says, words over it shown a line after another to a character who comes within radius: [{lines: [{text, seconds}], above, active, loop, endEvent, radius, fontSize}]; above is how many metres over the foot of the thing it hangs (before the scale of the prefab; give it: at the foot the thing itself hides the bubble); the first shows from the start when active is true, a graph switches to another with f.switchActiveTextBubble(entity, its number from 1); the lines are said again and again unless loop is false, and endEvent: true tells the graph of the thing when the last was said (whenTextBubbleIsCompleted). nameplates: what stands over the thing, [{items: [...], above, radius, active}], an item being {text} (a label; {1:s.NAME} in it is a custom variable of the thing, {2:HpCur} and {2:HpMax} its health), {icon: id}, {bar: {current, min, max}} (a bar that follows three custom variables of the thing) or {health: true} (the health bar of the thing: {numbers: true} writes the numbers on it, {colour: red} colours it), each with size and an offset in screen units from where the nameplate hangs (a second item 40 lower: offset [0, -40]); indicator: {text, icon, min, max} adds the navigation indicator, a mark that points to the thing from wherever the character looks while the thing is between min and max metres away, with words of its own ({2:PDist} in them is the distance) and an icon: where to go next; f.setEntityActiveNameplate(entity, f.assemblyList([1n], 'config_id')) says which show. attachPoints: [{name, offset: [x, y, z]}] names places on the thing, in metres from its foot, that a bubble or a nameplate hangs on by attach: the name (above makes such a point by itself). Both are the platform's own way to label an NPC or an enemy (the player's own character too: prefab "character"); seen in play 2026-10-14 (examples/talk), and their words show on an account of 奇匠 level 2 and up. hurtBox: the areas where the piece can be hit; an object has none of its own, so a wall, a target or a crate that enemies or players should be able to attack needs one. abilityUnits: ready-made abilities the piece owns, each with a name a graph uses it by: attack {coefficient, added} hits a target for coefficient x the attack of the piece plus the added damage (a thorn bush, a trap), heal restores an amount of health (a spring); this list replaces the units the piece had. What the target loses is less than that number: the attack of an ability unit is not absolute damage (是否是绝对伤害 is off), so the defence of the target takes its share: a creature or an object of level 1 with the attributes it comes with loses 0.45 of it (measured with coefficient 0: +80 takes 36, +55 takes 24 or 25, +40 takes 18). A hit box triggered from a skill graph with absoluteDamage true takes exactly its increment. The tool cannot switch absolute damage on for an ability unit yet (no official sample has one to copy the field from): give the unit 2.2 times the damage that is wanted, or use a hit box. solid false lets characters walk through the piece (pickups). motions (straight and path), follow, minimapMarker, the attack kind of abilityUnits and a trigger for creatures were verified in play on 2026-10-10; hurtBox was verified on 2026-10-11 (examples/strike: a crate with a hurt box is hit and broken by the hit box of a sword skill, which passes through objects without one); the heal kind of abilityUnits too (f.recoverHp(character, 1500, unitName, false, source): the health on the screen went from 8492 to 9992 and whenHpIsRecovered fired on the character with 1500; the attack unit of 1 x attack + 3000 before it took 1508, less the character's defence). projectile makes the thing fly from the moment it is created (a bullet, an arrow, a thrown stone): {type: "straight", velocity: [x, y, z] metres a second in its own axes with z forward and y up, acceleration, accelerationSeconds}, {type: "parabola", velocity, gravity (9.8)} or {type: "tracking", velocity, turnDegreesPerSecond (9999: it turns at once), targetAttachPoint (the point of the target it flies at: "GI_RootNode" its feet; creatures also have "GI_ChestMark"), snapRange and snapSeconds (within that many metres it closes in on the target in that time; 1 and 1)}: an arrow or a spell that follows whoever it was shot at, so that a target that walks is still hit; a graph launches one with f.createProjectile(prefabId, position, rotation, owner, target, false, 1n, [] as bigint[]), the fifth argument being the entity a tracking one follows. hitDetection tells when it touches something: {areas, trigger: "once" or "oncePerEntity", delaySeconds: how long after it appears it starts to detect, so that it does not hit whoever shot it, abilityUnit: the name of one of this prefab's abilityUnits, launched at what it hits, layers: what counts as a touch, of hurtBox, scene and objectCollision (all three when left out; ["hurtBox"] for a bullet that should only notice things that can be hurt), factions: "hostile" for one that only notices enemies of its own faction, so that it flies past friends (give the thing its shooter's faction with f.modifyEntityFaction), continuous: {speedAbove, radius} switches on continuous detection (连续碰撞检测) above that speed, for a fast thing that would otherwise be on one side of a target in one moment and on the other in the next}; whenOnHitDetectionIsTriggered fires in a graph on the prefab. Both records are byte for byte those of the official sample 投射运动器; verified in play on 2026-10-11 (examples/shoot: a bolt shot by a skill breaks a crate with two hits; do not remove the bolt in the very moment it hits, or that hit does no damage: remove it a third of a second later). loot is what the thing leaves behind when it is destroyed: {dropPrefab: a drop prefab from scene_add_prefab {drop}, items: [{item, amount}]} (the platform's way to have a defeated creature or a broken crate drop something; verified in play on 2026-10-11 with a chest that a graph destroys: the drop appears where it stood and gives the items listed here). An area is a box {size: metres or [x,y,z], offset} or a sphere {radius, offset}, relative to the entity. Called again on the same target, each kind that is given replaces what the target had of that kind (the whole collisionTriggers list, the option tab, the motions and so on: to change the size of one trigger give the whole list again), kinds that are not given stay as they are, and variables are merged by name (one given again gets the new start value). Target: prefab (name or id, or "player" / "character" for the built-in templates, which take variables only) or entity (a placed name). Static pieces carry no components. Writes a new .gil in the workspace; the official save is not touched. launcher {areas, speed, direction}: makes the thing fling the characters that touch it (the platform's 角色扰动装置, kind 弹射器): a character entering an area gets that many metres a second of extra speed in the direction ([0, 1, 0], straight up, when left out: a bounce pad; sideways: a bumper or a gust that pushes off a ledge). The official bounce mushroom is {areas: [{radius: 1.5, offset: [0, 0.5, 0]}], speed: 7}. It works by itself, without a graph, and only on characters that walk into the area (one teleported into it is not flung). Verified in play on 2026-10-12 (examples/walls): a flat pad of speed 14 threw the player 8.6 m up, again each time it came down on it. The direction of a launcher may also be "away": the character is pushed straight away from the piece, wherever it touched it, which is what a bumper, a swinging hammer or a blast does; holdSeconds is how long the push lasts at full strength (0.25) and fadeSeconds how long it then takes to fade (0) (verified in play on 2026-10-13, examples/hazards: a big coin with speed 10 threw a player who kept walking into it back two or three metres every time). extraCollision {areas}: shapes that stop characters and creatures whatever the model looks like (the platform's 额外碰撞). On a prefab of the empty model (asset 10005018, 空模型, which shows nothing) it is a wall nobody sees: {areas: [{size: [0.5, 4, 12]}]} is a pane four metres high and twelve long, the way to keep players inside an arena or on a path without building a visible wall. Verified in play on 2026-10-13 (examples/hazards): the player stopped 0.2 m before the pane with nothing to be seen there. A blind test walled an arena this way that night: with its top 2.0 m above the ground a wall was still climbed over, with 2.4 m and more it held (3.2 m where a bale of 0.8 m stood beside it). The camera of the game does not pass through it either: when such a wall comes between the camera and the character, the camera jumps close to the character (seen with a camera that looks down from the south at a player by the south wall), so keep the walls on the side the camera looks from further out than the play needs, or let that side be open ground with a visible edge. "toward" pulls the character to the piece instead. forceField {areas, direction, speed}: the same component in its other kind (力场器), which pushes for as long as a character is inside instead of once on entering: a wind across a bridge, a current, a conveyor; innerRadius and outerRadius with innerSpeed and outerSpeed make the push differ between the core of its sphere and beyond it. A piece carries a launcher or a force field, not both. Both were read from devices configured by hand on 2026-10-13. The force field was tried in play that night (examples/hazards, second lane): walking through a field of radius 2.5 that blows sideways at 6 m/s put the player three metres off its line. "toward" pulled in the same run: on entering the area the player was carried 2.3 m towards the piece (speed 8, holdSeconds 0.3), once, like every launcher. The areas of a component grow with the scale of the prefab: on a piece of scale 2.5 an area of radius 3 reached 7.5 m, so the pull came much earlier than where the area was thought to be.

Inputs: loot, solid, entity, follow, +18 more.

scene_add_creature_skillA
Destructive

Define a skill of a complex creature (造物技能) in a copy of a save: an animation of that creature and a client graph that runs at a chosen moment of it. A complex creature (an asset of the group "怪物(AI版)": scene_search_assets {group:"怪物(AI版)"}) does nothing by itself; what it can do beyond walking is its skills: swing and hit, shoot, dig, hammer at a wall, look around. creature is the asset id of the creature the skill is for (a skill plays the animations of one model and can only be given to that creature). animation is one of its animations, by id or by name ("近战攻击_01"): creature_animations {creature} lists them with their lengths; animations gives several, played one after another (a wind-up, a loop, a recovery). graphId is a graph made with scene_add_graph {kind:"creatureSkill"}; it runs graphAtMs milliseconds into the skill (the moment the weapon lands, the arrow leaves): there it triggers a hit box, fires a projectile or tells a server graph (f.notifyServerNodeGraph, heard as whenSkillNodeIsCalled by a server graph on the creature's own prefab). graphAtMs may be a list of moments, and the graph then runs at each of them: the three strokes of a triple stroke ([350, 900, 1700] for 单手武器_三连击) each trigger its hit box (seen in play; the graph cannot tell which of the moments it is). faceTarget (自动面向目标) turns the creature to its target while the skill plays; interrupts (可打断其他技能) lets the skill cut off another one. effect shows an effect on an attachment point of the creature for part of the animation: the thing the creature holds only while it does this (a pickaxe on GI_WeaponR while it digs, the knife in its hand until it is thrown; what is carried all the time is mounted by a server graph instead, f.mountLoopingSpecialEffect). animationPortion plays only the first part of the animation (0.62 leaves out the two seconds 盗宝团·斥候 just stands at the end of its throw). creature_animations says for the animations that were looked at in play which moment counts and what belongs in the hand; the result repeats it (hint) when graphAtMs is far from that moment. Give the skill to a creature with scene_set_creature_logic, which also sets its cooldown. Writes a new .gil in the workspace; the official save is not touched. A skill of one animation is byte for byte the skill of the official sample 复杂造物; several animations and the two switches are written as the editor saved them on 2026-10-11.

Inputs: name (required), graphId (required), creature (required), effect, +8 more.

scene_add_currencyA
Destructive

Define a currency (货币) in a copy of a save and give every character a backpack that can hold it, optionally with a starting amount. Currency is the platform's own money: a graph reads and changes it with f.getInventoryCurrencyQuantity(character, currencyId) and f.modifyInventoryCurrencyQuantity(character, currencyId, change), whenTheQuantityOfInventoryCurrencyChanges fires on the character, and shops, item prices and drops are all counted in it. The holder is the character entity (the backpack component is put on the character template), not the player entity. If the map has no backpack template, one of ten slots is made. icon is the number of a currency icon (100001 is the default one, 100007 the Mora coin). The records written are byte for byte those of the official sample 货币与商店. Writes a new .gil in the workspace; the official save is not touched. Verified in play on 2026-10-10: the starting amount is there, and the change event also fires once when the level starts, for the starting amount.

Inputs: name (required), icon, mapPath, outputName, +1 more.

scene_add_environmentA
Destructive

Add a second sky to a copy of a save: an environment configuration (环境配置) fixed at one hour, with stars, the milky way and clouds as asked. This is how night is done on this platform: changing the level clock alone does not darken the sky that is in force, a graph switches the players to another environment configuration with f.modifyEnvironmentSettings(environmentId, players, false, 0n), and back with the id of the map's own. The new configuration applies to nobody until a graph switches to it. hour is 0 to 23 (0 is midnight). Returns environmentId. Writes a new .gil in the workspace; the official save is not touched. Verified in play on 2026-10-10: a midnight configuration is dark with stars, and stars and clouds follow their switches. On a map of the current version the sky is written the way the editor fixes one at an hour (the 34 brightness and colour curves of the map's own sky, each taken at that hour), so a day sky looks like the sky of the map at that hour and not brighter (seen in play on 2026-10-13, examples/hazards/hazards_sky.json; until that day a day sky came out washed out). For day and night make two, one for the night and one for the day (hour 11, stars and milkyWay false), and switch between them: the map's own configuration follows a clock that stays at the hour of the last fixed one, so going back to it after a night stays dark.

Inputs: name (required), hour, stars, clouds, +3 more.

scene_add_global_timerA
Destructive

Define a global timer (全局计时器) in a copy of a save and give it to the player template (holder "player", one per player) or to the stage entity (holder "stage", one for the level): a countdown of some seconds, or a stopwatch with countdown false. A graph starts it with f.startGlobalTimer(holder entity, name); when a countdown ends, a graph on the holder hears whenGlobalTimerIsTriggered. Use it for the length of a round or of a day, instead of counting ticks in a graph: it can also be shown on the screen with scene_add_timer_display. Writes a new .gil in the workspace; the official save is not touched. Verified in play on 2026-10-10: a timer held by the stage starts counting by itself when the level loads (several seconds before the graphs start), whenGlobalTimerIsTriggered fires when it reaches zero, and f.startGlobalTimer starts it again after that.

Inputs: name (required), seconds (required), holder, mapPath, +2 more.

scene_add_graphA
Destructive

Add an empty node graph to a copy of a save and, for a server graph, attach it. The platform is event driven and its games are many small graphs, each on the entity it is about: attachToPrefab puts the graph on a prefab (元件) so that every copy of it, placed or created later, runs its own instance and receives its own events (a coin that is picked up, a pay station, a door); attachToPrefab "player" puts it on the player template (per-player state such as score) and "character" on the character template; attachTo names one placed entity (default 关卡实体, the stage entity: level-wide things such as the clock, and the only place that hears whenEntityIsDestroyed of objects and creatures). An entity can run several graphs, and one graph can sit on several prefabs that behave alike (attachToPrefab as a list: a wooden and a stone wall, three kinds of coin). kind makes another kind of graph instead, none of which is attached to an entity: boolFilter, a client graph with a yes/no test that an option of an option tab can name so that it shows only to players for whom it is true (scene_add_components filterGraphId; verified in play); characterSkill, the client graph a skill runs (scene_add_skill names it; verified in play); item, a server graph that hears the events of one item, such as its being used from the backpack (scene_add_item useGraphId names it; verified in play); creatureSkill, creatureStatus, creatureDecision, the client graphs of complex creatures: what a skill of the creature does, one of its behaviours (a list of tactics and skills), and the graph that picks the behaviour (scene_add_creature_skill and scene_set_creature_logic wire them to a creature; verified in play, read_knowledge {id:"example-brain"}). A new map has no node graph, and write_graphs needs one to write into: call this, then use the returned graphId as targetGraphId. The name gets the prefix GSTS if it lacks it (graphs with that prefix are the ones these tools may overwrite). Writes a new .gil in the workspace and returns its path; the official save is not touched.

Inputs: kind, name, mapPath, attachTo, +2 more.

scene_add_imageA
Destructive

Put an image (图片) on the screen, in a copy of a save: a plain rectangle in a colour (image 100001, the default: a panel behind bars, a coloured mark, a frame for the corner of the screen) or one of the pictures of the platform by its id. This is how a screen says something without words, which matters on an account of 奇匠 level 1, where custom text does not show. colour is "#rrggbb" (it tints a picture; white leaves it as it is), opacity 0 to 1 (0.5 with black is the dark panel the official samples put behind their controls). position is [x, y] from the screen centre on a 1600 x 900 canvas (y up), size [width, height]. image_catalog shows every picture of the platform with its id (about 1600, in fifteen categories): choose there. knownImages of scene_list_interface names 22 of them in words (plain discs, an arrow, a question mark, a sword and shield, fruit, gift boxes, round birds, a rank letter). Controls are drawn in the order they were added, so add the panel before what lies on it. A graph takes an image off the screen and puts it back with f.modifyUiControlStatusWithinTheInterfaceLayout(player, controlId, UIControlGroupStatus.Off or .On) (a row of discs as lives: examples/images/images_lives.json, seen in play); hidden true starts it off the screen. Verified in play on 2026-10-13 on an account of 奇匠 level 1 (examples/images): panel, pictures and coloured rectangles all show.

Inputs: name (required), size, image, colour, +5 more.

scene_add_itemA
Destructive

Define an item (道具) in a copy of a save: a thing a character holds in its backpack in numbers (fruit, wood, a key), which a shop can sell or buy. Define a currency first (scene_add_currency gives every character the backpack). value is what one of it is worth in a currency (the currency by name or id); icon is the number of an item icon (90001 an apple, 90015 fowl meat). A graph gives and takes it with f.modifyInventoryItemQuantity(character, itemId, change) and reads f.getInventoryItemQuantity(character, itemId). The events about an item (whenItemIsAddedToInventory, whenItemIsLostFromInventory, whenTheQuantityOfInventoryItemChanges, whenItemsInTheInventoryAreUsed) arrive only in the item's own item graph (useGraphId), not in a graph on the character or the player; only the currency event goes to the holder. The record written is byte for byte the item of the official sample 货币与商店. Verified in play on 2026-10-11 (bought and sold in a shop, counted by a graph). category "consumable" with useGraphId makes it an item the player uses from the backpack: useGraphId is an item graph (scene_add_graph {kind: "item"}, source g.server({id, name, type:'item'}).on('whenItemsInTheInventoryAreUsed', ...)), the record being that of the fowl meat of the official sample 掉落物、道具、背包; evt.itemOwnerEntity is the character that used it and evt.amountToUse how many. The player presses B for the backpack, clicks the item, 使用 and 确认; useCooldownSeconds is how long the item then waits before it can be used again (10 when left out). Verified in play on 2026-10-11 (examples/potion). Equipment is not made; the drop that lies on the ground is scene_add_prefab {drop}. Writes a new .gil in the workspace; the official save is not touched.

Inputs: name (required), icon, value, mapPath, +6 more.

scene_add_lightA
Destructive

Add a point light that belongs to one environment configuration (环境配置), in a copy of a save: a lamp that is lit at night. A light shines only while a player is under the environment configuration it belongs to, so lamps for the night go on the night configuration made with scene_add_environment. environment is that configuration's name or id; position is [x, y, z]; radius is how far the light reaches (metres), intensity its strength, range the distance it is drawn from. Writes a new .gil in the workspace; the official save is not touched. Verified in play on 2026-10-10: the lamp is lit under its own configuration and off under any other.

Inputs: name (required), position (required), environment (required), range, +4 more.

scene_add_prefabA
Destructive

Make a prefab (元件) in a copy of a save, so that a node graph can create that thing at run time wherever it wants and at the size you chose: small coins, a wall that appears when it is bought, markers that follow the player, units that are recruited. Two ways: asset (an object asset id or unique name from scene_search_assets) with a scale; or fromEntity (the name of something already placed in the save, from scene_list_entities) to make a prefab of that very thing, which is how creature prefabs are made: place one creature with createAtStart false, import, then make the prefab from it. scale is a number or [x, y, z], 1 = natural size; with fromEntity it defaults to the entity's own scale. (Created by its bare asset id with f.createPrefab a thing always has its natural size.) Mechanism assets (group 交互机关: chests, levers, doors, the bounce mushroom) have a preset status (预设状态), a built-in animation: the prefab is given the asset's status id, the result names it, and a graph plays it with f.setPresetStatus(entity, statusId, 1n): the chest opens, the lever goes down, the door swings. presetStatusValue is the value it starts at (default 0). presetStatusId registers an id of your own for an asset that is not in the table of verified ones (for most mechanisms of group 交互机关 the id is (asset id - 4000) x 10): an id the asset does not have fails the editor's check before a playtest, and the failure names the prefab (playtest_status gives the text), so a playtest that starts means the id exists. health is the base health of the thing (an object has 10 when it is left out, which one hit of a sword skill breaks; the target dummy of the official attack lesson has 300; on a creature it replaces the base health the placed creature has, which the game multiplies by several for the creature's level: a hilichurl of base 13.6 falls to two or three hits of 50, one of base 40 stood after three): it matters once something can hit the thing, which for an object needs a hurtBox (scene_add_components); verified in play on 2026-10-11 (examples/raid: a crate of 100 takes two hits of 50). drop makes the prefab a drop (掉落物): the thing that lies on the ground and gives the character that picks it up an item into its backpack, {item: name or id from scene_add_item, amount, pickupSize: the side of the box around it, in metres, within which the prompt to pick up shows (1 when left out, which asks the player to stand just beside it; 6 was comfortable in examples/raid)}; a graph creates it like any prefab, and a thing with the loot component (scene_add_components) leaves it behind when destroyed. Verified in play on 2026-10-11 (examples/drops): the prompt to pick up (F) shows when the character is about 0.6 m from the drop, not from further than a metre and not while standing on it. A creature created from such a prefab acts like a placed one (verified in play): to send it at something in custom aggro mode, the target has to be its enemy (a wall goes on the players' side with f.modifyEntityFaction first) and the order has to come a moment after it appears, not in its own whenEntityIsCreated. Returns the new prefabId and a new .gil in the workspace; the official save is not touched.

Inputs: drop, name, asset, scale, +6 more.

scene_add_preset_pointA
Destructive

Add a named preset point (预设点) to a copy of a save: a position and a rotation a graph reads by id with f.queryPresetPointPositionRotation(pointId), so that places (a waiting room, the arena, where the boss appears) live in the map and not as numbers inside graphs. Returns pointId. Writes a new .gil in the workspace; the official save is not touched. Verified in play on 2026-10-10.

Inputs: name (required), position (required), mapPath, rotation, +1 more.

scene_add_progress_barA
Destructive

Put a bar on the player's screen that follows one of the player's custom variables, in a copy of a save: a purse, a countdown, the health of the thing to defend, progress towards a goal. It is the way to show a number to the player on an account whose 奇匠 level is 1, where text boxes show nothing in play (measured) but bars do, with the fill and a percentage, or with the number itself (shows "value"). variable is an integer custom variable of the player (made with start value min if the player template does not have it); min and max are the ends of the bar. position is [x, y] from the screen centre on a 1600 x 900 canvas with y up (top centre is about [0, 380], top left [-600, 380]); size is [width, height]. A graph moves the bar with f.setCustomVariable(player, variable, value, true). How it looks: shape "horizontal" (as it comes), "vertical" or "ring" (a circle that fills clockwise from the top: a cooldown, a charge); shows "percent" (as it comes), "value" (the number itself: 7 coins read as 7, on an account of 奇匠 level 1 too, since the bar writes it, not a text box), "ratio" or "nothing" (a clean bar); colour of the fill and backColour behind it ("#rrggbb", backOpacity 0.5 unless said), textColour, fontSize. hidden true leaves the bar off the screen until a graph switches it on with f.modifyUiControlStatusWithinTheInterfaceLayout(player, controlId, UIControlGroupStatus.On). The style fields were read from three bars restyled by hand in the editor on 2026-10-13 and seen in play that morning (examples/images/images_lives.json): a red bar reading 6.0, a blue ring filled to six tenths, an upright bar reading 6.0 / 10.0, and a picture that came on when the graph switched it on. Writes a new .gil in the workspace; the official save is not touched.

Inputs: max (required), name (required), variable (required), min, +12 more.

scene_add_respawn_pointB
Destructive

Add a respawn point (复苏点) in a copy of a save: where a character that went down comes back. The platform has the whole of dying and coming back built in: when a character's health reaches 0 its player gets the revive screen (wait, then 复苏) and the character returns at a respawn point of that player; a character that falls out of the world is put back at once and loses part of its health. Without a respawn point there is nowhere to come back to. Give position (and rotation; a preset point is made there) or point (the id or name of a preset point that exists). The point is added to the level settings and to the list of the player template. A graph makes points usable or not while the game runs, which is how checkpoints are made: f.activateRevivePoint(player, respawnId) for the one just reached, f.deactivateRevivePoint(player, respawnId) for the one before. Lives are f.setPlayerRemainingRevives(player, n); f.setPlayerReviveTime(player, seconds) sets the wait; f.reviveCharacter(character) revives at once; f.allowForbidPlayerToRevive(player, false) ends it; whenTheCharacterIsDown, whenCharacterRevives and whenAllPlayerSCharactersAreDown tell a graph what happened. The records are those of the official samples (角色设置, 基础运动), byte for byte; verified in play on 2026-10-13 (examples/hazards).

Inputs: name, point, mapPath, position, +2 more.

scene_add_shopA
Destructive

Make a prefab a shop (商店) in a copy of a save: the platform's own buying and selling screen, which moves items and currency between the shop and the backpack of the character without any graph. sell lists what the shop sells to the player, buy what it buys from the player; each line is {item, currency, price} with the item and the currency by name or id (scene_add_item, scene_add_currency), and a line of sell may give stock (how many the shop has; 1 when left out, as in the official lesson). prefab is the stall, a prefab from scene_add_prefab. A graph opens the shop for a player with f.openShop(player, the stall entity, 1), in the official lesson when a character enters the stall's collision trigger, and f.closeShop(player) closes it; whenCustomShopItemIsSold (the shop sold something) and whenSellingItemsToTheShop (the player sold something) fire in a graph on the stall. The shop template and the shop component written are byte for byte those of the official sample 货币与商店 (which has one line in each list). Verified in play on 2026-10-11 (examples/shop): the screen shows the shelf on the left with each line's icon, stock and price, and the backpack on the right; a click on a line and on 购买 buys (the currency goes down, the item goes into the backpack, a sold-out line is marked 已售罄); 批量出售, a click on an item of the backpack and 出售 sells at the price of the buy list, not at the item's value. It works on an account of 奇匠 level 1. To play it by script, playtest_start takes click and clickText inputs. Writes a new .gil in the workspace; the official save is not touched.

Inputs: name (required), prefab (required), buy, sell, +2 more.

scene_add_signalA
Destructive

Define a signal (信号) in a copy of a save: a level-wide broadcast with a name. One graph sends it with f.sendSignal('name') and any number of graphs on any entities hear it with .onSignal('name', (evt, f) => {...}). It is the platform's way to let one thing tell many without knowing them: night falls and the lamps, the gates and the enemies each react in their own graph. parameter gives the signal one string to carry (its name; the sender passes the string as second argument of f.sendSignal, the listeners read it from the event): which lever, which team. parameters gives it several values of any of the eighteen types the editor offers, [{name, type}] with type one of integer, float, boolean, string, vector3, entity, guid, prefabId, configId or a list of one of them (integerList ...): a score as an integer, where something happened as a vector3, who did it as an entity. The answer says how graphs and client scripts send and read them (defineSignal in a graph, AddInt and the like in Lua). The same signal reaches the client scripts (Lua) of one player when a graph sends it as f.sendSignal('client:name', player) (and the string after the player when it carries one): that is the node 发送客户端脚本信号 of game 7.1, which the compiler does not know and this server puts in when it writes the graph; a script hears it with script:RegisterServerSignalHandler("name", function(name, params) ... end). A name cannot begin with "client:". Writes a new .gil in the workspace; the official save is not touched. Verified in play on 2026-10-10, without and with a parameter; to client scripts on 2026-10-13 (example clientsignal).

Inputs: name (required), mapPath, parameter, outputName, +1 more.

scene_add_skillA
Destructive

Define a skill (技能) in a copy of a save: the platform's way for a player to act beyond walking and the "press F" prompt. A key press runs the skill's client graph, which tells the server, and a server graph on the character does the work. Two types are made. "instant" (瞬发技能, the default): no animation, the graph runs the moment the key is pressed. "normal" (普通技能): the character plays one animation (animation = its id: 1001 one-handed sword attack, 1006 raking the ground, 1023 watering, 1025 reaching out a hand; these are the ones the official samples use) and the graph runs at the start of it or graphAtMs milliseconds in (a sword swing that hits when the blade comes down); animationPortion is the number the editor stores for the clip (1 in most samples; the three tools of the farming sample have 0.167, 0.96 and 0.25); effect shows an effect asset at an attach point of the character for some milliseconds of the animation (the official attack skills show the sword 10002152 at "GI_WeaponR" for 1833 ms). The long-press, combo and aiming types, cooldowns and use counts are not made. To make the skill hit things, its client graph triggers a hit box, f.triggerSectorHitboxAtSpecificLocation(...) at the character's own place and rotation: read_knowledge {id:"example-strike"} has the call with the values of the official attack (a sector 3 m long, 50 damage, once per target); it damages creatures, and objects that have a hurtBox (scene_add_components). graphId is a client skill graph made first with scene_add_graph {kind: "characterSkill"}; its source is g.characterSkill({id, name, prefix:false}).on('start',(evt,f)=>{f.notifyServerNodeGraph('word','','');}) (a client graph cannot create or change things). A server graph hands the skill to a character at run time, f.addCharacterSkill(character, skillId, CharacterSkillSlot.Skill1E, TopOfStackSkillDestructionType.Destroy): slots are NormalAttack (the attack button), Skill1E, Skill2Q, Skill3R, Skill4T and CustomSkillSlot1 to 15; f.deleteCharacterSkillBySlot takes it away. A server graph on the character template (scene_add_graph attachToPrefab "character") hears whenSkillNodeIsCalled with evt.callerEntity and evt.parameter1 to 3. The records written are byte for byte those of the official samples: the instant skill 放下工具 and the normal skill 耙子-开垦 of 耕种-采集流程, and the timed attack with a sword of 命中与受击. Writes a new .gil in the workspace; the official save is not touched. Verified in play: the instant type on 2026-10-10 (given on the E key, pressed, heard by the character graph); the normal type on 2026-10-11 (examples/skills: the three animations play, the sword shows in the hand, each graph reaches the server; the sword attack carries the character 0.65 m forward and the raking 0.55 m). A skill has no cooldown of its own here; a graph gives it one: when the skill has been used (whenSkillNodeIsCalled on the character's graph), f.setCharacterSkillCd(character, CharacterSkillSlot.Skill1E, seconds, false) makes the slot wait that long, and a press during the wait is refused (verified in play on 2026-10-12, examples/skills/skills_cd_test.json; with the last argument true nothing happens, because the skill has no longest cooldown to be held to). Slots on a PC: Skill1E the E key, Skill2Q Q, Skill3R R, Skill4T the Z key (not T).

Inputs: name (required), graphId (required), type, effect, +5 more.

scene_add_text_boxA
Destructive

Put a text box (文本框) on the screen, in a copy of a save: words, numbers that follow custom variables, or both. A variable is written into the text as {1:ps.name} for a custom variable of the player who sees it, {1:lv.name} for one of the stage entity, {1:p1.name} to {1:p8.name} for one of that player: "金币:{1:ps.coins}" shows the number as a graph changes it. position is [x, y] from the screen centre on a 1600 x 900 canvas (y up), size [width, height], fontSize the size of the letters. IMPORTANT: custom text is shown only on accounts whose 奇匠 level is 2 or higher (seen in play on level 2, 2026-10-13: the number follows the variable); on a level 1 account the box is there and shows nothing (measured with the official sample itself). Before a game relies on text, put one box in and look at a playtest screenshot; if nothing shows, say what has to be said without words (scene_add_progress_bar, markers, effects: read_knowledge {id: "feedback.zh-CN"}). The three records are byte for byte those of the official sample 界面控件.

Inputs: name (required), text (required), size, mapPath, +3 more.

scene_add_timer_displayA
Destructive

Put a clock on the player's screen that shows a global timer (made with scene_add_global_timer) running, in a copy of a save. It shows digits, not custom text, so it is a way to show time left on an account whose 奇匠 level is 1. position is [x, y] from the screen centre on a 1600 x 900 canvas with y up; size is [width, height]. Writes a new .gil in the workspace; the official save is not touched. Verified in play on 2026-10-10.

Inputs: name (required), timer (required), size, mapPath, +2 more.

scene_add_unit_statusA
Destructive

Define a unit status (单位状态) in a copy of a save: an effect that a graph puts on an entity and takes off again. outline draws a coloured edge around the entity, the platform's usual way to say "you can interact with this" or to mark a team, and it needs no text; seeThrough shows the entity through walls in a colour; maxHealth raises maximum health by a number per stack. Colours: green or white (or a colour code of the editor as a number; only those two are mapped). The status lasts until it is removed. Returns statusId for f.addUnitStatus / f.removeUnitStatus. Writes a new .gil in the workspace; the official save is not touched. Verified in play on 2026-10-10: a green outline on an object and a white one on a character, put on with f.addUnitStatus(character that walked in, target, statusId, 1n, dictionary) and taken off with f.removeUnitStatus (the applier, the first argument, is the character, as in the official sample). More effects, which may be combined in one status: speedPercent (movement speed of a character or a creature, a whole percentage up to +40, which is as far as the editor goes; negative slows), invincible true (takes no damage and does not hear attacks), superJump [horizontal, vertical] (the multipliers of a character's jump: [1.5, 2] jumps half again as far and twice as high), rooted true (the player's character cannot be moved with the keys: a stun, a trap). These are what pickups and hazards are made of: a boot that speeds up for some seconds, a star that makes invincible, tar that slows, a snare that holds. seconds makes the status end by itself after that long (left out it stays until a graph removes it). The effect ids were read from a status configured by hand in the editor on 2026-10-13. Verified in play that day (examples/hazards): after a pickup of speedPercent 40 the player covered 9.4 m in the next 1.2 s (5.2 m/s without), one of rooted with seconds 2 held the player on the spot for two seconds with the movement key down; with invincible on, an attack of 2000 that had taken a thousand health a moment before took none; with superJump [1, 2.5] a jump on the spot rose three metres (hazards_test2.json).

Inputs: name (required), rooted, mapPath, outline, +8 more.

scene_asset_imagesA
Read-only

Look at assets before placing them: returns a small photo of each asset id (from scene_search_assets), with its name, group and model size. Use it to choose between assets that share a name (there are dozens of different 乔木) or to check what an unfamiliar asset is. The photos show every asset scaled to a similar size, so judge the look from the photo and the real size from sizeMetres. Assets that could not be photographed are reported as having no image. Read-only.

Inputs: ids (required).

scene_batchA
Destructive

Run a list of scene_* tool calls in one call, each on the save the one before returned: steps is [{tool, args}], args as that tool takes them without mapPath. A value of an earlier step is named as "$.", counting from 0: {tool: "scene_add_skill", args: {name: "swing", graphId: "$3.graphId", type: "normal", animation: 1001}} takes the graphId step 3 returned. It stops at the first step that fails and says which and why; mapPath is then the save with the steps before it done, and the call can be repeated on it with the rest. Returns the last mapPath and, for every step, what it returned without the explanations (ids, names, sizes). For the tools that change a save: scene_add_*, scene_set_*, scene_update_prefab, scene_remove_entities. Not for the ones that drive the editor (scene_import_assets, editor_open_map), the ones that only read, or write_graphs (which already takes all graphs in one call).

Inputs: steps (required), mapPath.

scene_block_catalogA
Read-only

List the building blocks scene_build_blocks can place: name, template ID, approximate colour and native size. Read this before designing a scene.

Inputs: no named parameters.

scene_build_blocksA
Destructive

Turn a list of pieces into an official asset pack (.gia) and put it in the editor’s import folder. template is a block name from scene_block_catalog or any asset id from scene_search_assets. position is in metres; rotation in degrees per axis. Give size (metres per axis: the piece is stretched to exactly that; blocks default to 1,1,1) or scale (1 = the model’s own size, the default for non-block assets). For blocks position is the centre in x and z and the bottom in y (measured in play: a block at y 0.5 and 1 high has its top at 1.5); other models are anchored at their base. Monsters (group 怪物) are imported alive with their official AI parameters. createAtStart:false places a piece without creating it, so a node graph can create it later by GUID (the editor assigns new GUIDs on import; read them from the save). patrol (monsters only) makes the creature walk a path that already exists in the map while it has no target: templates:[{pathId,waypointIds}] with ids from inspect_level_paths; since the game update of 2026-10-09 the importer drops the template list, so a patrol written here does not reach the game: steer creatures with custom aggro instead. offset [x, y, z] is added to every position: the same list of pieces on ground of another height (a new empty save has its ground at y=0) or as a second copy elsewhere. Returns the pack’s bounds. Nothing changes in the game until scene_import_assets runs. solid false switches the native collision (原生碰撞) of a piece off, for a thing that is to be walked through; left out it is on. A character walks over low things by itself (a fence of 1.56 m, with jumping allowed and no key pressed, 2026-10-12): what keeps a player in is a wall of at least 2.4 m and a class that may not climb.

Inputs: name (required), blocks (required), offset, install, +1 more.

scene_check_clientA
Read-only

Check what the client scripts (Lua) of a save name against what there is, in a moment and without the game. On this platform a name that does not match is not an error: the control is not found, the signal is not heard, the variable reads nil, and nothing says so. This parses every script and looks up each name it writes as a literal: its syntax; the functions of game, the methods of script and every Enum value (the official API page); the controls it asks for (GetChild, FindChild) among the controls under the ones that carry it; the signals it sends and hears, among the signals of the save and the graphs that hear and send them, and the values it adds to a signal before sending it (AddInt, AddString ...) against what the signal carries, in order; the custom variables it reads, on the player and character templates; its own variables (GetParam); templates by index, pictures and sounds by id. Each problem comes with script, line, what is wrong and the nearest name there is. An error will not work; a warning may be on purpose (a signal no graph sends yet). scene_set_client_script, scene_add_client_ui and playtest_start run the same check on what they are given and report it; call this after the graphs are written, when everything is in the save. Read-only. It sees only literals: a name put together while the script runs is not checked, and neither is what the script does (the playtest is for that).

Inputs: mapPath, scripts.

scene_get_client_uiA
Read-only

Read a client interface (ui: its name) or a template of client controls (template: its name) back out of a save, whole: every control with its kind, rectangle (and where it differs on a phone or a console), switches, text, picture and colour, grid layout, button states, the scripts on it and the values it gives their variables, where the stick of a gamepad goes. What comes back under interface (or template) is exactly what scene_add_client_ui (scene_add_client_template) takes, so changing an interface is: read it, change what is to change, write it with replace: true. An interface made by hand in the editor is read the same way (the saves configured by hand that the tests keep are read and written back byte for byte). ids gives the id of every control by its path. Read-only.

Inputs: ui, mapPath, template.

scene_get_level_settingsA
Read-only

Read the level settings of a map that decide how creatures choose targets: aggroMode (default or custom), the aggro transfer multiplier, and the hour and speed of the level clock. Without mapPath it reads the newest official save. Read-only.

Inputs: mapPath.

scene_import_assetsA
Destructive

Import asset packs built by scene_build_blocks into the save that is open in the editor, through the official 资产导入导出管理 screen, then save. Takes over mouse and keyboard for about 45 seconds. Returns a runId; read the outcome and an overview screenshot with playtest_status. Every import adds new entities, so importing a pack twice duplicates it.

Inputs: packs (required), overview.

scene_import_simulatorA
Destructive

Bring a project of the 千星沙箱模拟器 (miliastra-beyond-simulator, the simulator outside the game for 2D + Lua levels) into a copy of a save, in one call, so that it can be played in the game itself: what passes in a simulator has not passed in the game. save is the simulator's full save (the .json it writes with 导出 → 完整存档; format "qxqy-simulator-save"). Everything it holds is written with the tools of this server: its Lua scripts (the text in the save, or the file beside it), its templates of client controls, its interface with the scripts on the controls that carried them, the rectangles of each device where they differ; the signals its scripts and its server rules name are defined, the variables its rules set are added to the player; and its server rules (when a signal comes from a script: set variables, send signals back) are written as the source of a node graph on the level entity and compiled. Template indices are the save's own after this, so every number in the Lua that was the index of a template in the simulator is put to the new index (only numbers of the Lua itself, never inside a string or a comment). The result says what was written, what could not be (notes: a look of a button the game has no state for, a parameter a rule reads and no script adds; the fill, soft edge and inverted mask of an image come over, and so do signals with several values, typed after what the scripts add), and what scene_check_client finds in the scripts against the finished save. Then playtest_start {mapPath} plays it. Reads the file format only; none of the simulator's code is used. Writes a new .gil in the workspace.

Inputs: save (required), mapPath, outputName.

scene_list_camerasA
Read-only

List the camera templates saved in a map (主镜头管理): name, distance from the character in metres, vertical field of view in degrees, the yaw and pitch ranges within which the player can turn the camera, and fixedView when the view is locked (scene_set_camera). Without mapPath it reads the newest official save. Read-only.

Inputs: mapPath.

scene_list_classesA
Read-only

List the classes (职业) of a save: for each, the camera template and screen layout it uses and whether its character may jump, sprint, climb and glide. Read-only.

Inputs: mapPath.

scene_list_client_scriptsB
Read-only

List the client scripts (Lua) of a save: name, file, number of lines, its variables (name, type, whether public), the controls each is on, and with includeSource the Lua itself. Read-only.

Inputs: mapPath, includeSource.

scene_list_componentsB
Read-only

Read what a prefab (and its placed copies) or the placed entities of one name carry: number of collision triggers, the options of the option tab, custom variables, and the ids of the node graphs they run. Read-only.

Inputs: entity, prefab, mapPath.

scene_list_creature_skillsB
Read-only

List the creature skills (造物技能) defined in a save: id, name, the creature they belong to, their animation and graph. Read-only.

Inputs: mapPath.

scene_list_currenciesB
Read-only

List the currencies defined in a save, its backpack templates, and what the character template's backpack holds at the start (null when characters carry no backpack).

Inputs: mapPath.

scene_list_entitiesA
Read-only

List entities placed in a save by name: GUID, asset id, position, whether it is created at level start, and kind (static, dynamic, creature). The editor assigns new GUIDs when it imports a pack, so after scene_import_assets read the GUIDs here before writing them into a node graph. Without mapPath it reads the save the editor wrote last (the one just imported into). Read-only.

Inputs: limit, mapPath, namePrefix.

scene_list_environmentsB
Read-only

List the environment configurations (环境配置, the skies) of a save: id, name, fixed hour, whether it follows the level clock, stars, milky way, clouds. Read-only.

Inputs: mapPath.

scene_list_factionsA
Read-only

List the factions (阵营) of a map and, for each, which factions it is hostile to and which it is friendly to. This decides who attacks whom: a creature attacks entities of a hostile faction that have combat attributes. A new map has three factions, players 1, objects 2 and creatures 3, each hostile to the other two, so allies of the player attack objects a graph creates (coins, walls, markers) and seem to swing at nothing. Without mapPath it reads the newest official save. Read-only.

Inputs: mapPath.

scene_list_global_timersB
Read-only

List the global timers (全局计时器) defined in a save: name, seconds, countdown or stopwatch. Read-only.

Inputs: mapPath.

scene_list_interfaceB
Read-only

List the screen layouts of a save and the controls on each: the built-in HUD pieces and the custom controls (progress bars, text boxes, timers, scoreboards, containers of client controls), and under clientInterfaces the trees of client controls with the Lua script each carries. Read-only.

Inputs: mapPath.

scene_list_itemsB
Read-only

List the items defined in a save (id, name, icon, value in a currency) and its shop templates (what each sells and buys, at what price).

Inputs: mapPath.

scene_list_prefabsA
Read-only

List the prefabs (元件) saved in a map: prefab id, name, the asset it is made of, object or creature, and its scale. A node graph creates prefabs at run time, anywhere, with f.createPrefab(prefabId, ...). Without mapPath it reads the newest official save. Read-only.

Inputs: mapPath.

scene_list_preset_pointsB
Read-only

List the preset points (预设点) of a save: id, name, position, rotation, and which one players start at. Read-only.

Inputs: mapPath.

scene_list_respawn_pointsC
Read-only

List the respawn points of a save (number, preset point, place) and how many players the level takes (the group of the level settings).

Inputs: mapPath.

scene_list_signalsB
Read-only

List the names of the signals (信号) defined in a save, and what each carries (parameters: name and type, in order). Read-only.

Inputs: mapPath.

scene_list_skillsA
Read-only

List the skills defined in a save: id, name, type (instant or animated), the client graph it runs and, for an animated one, the ids of its animation clips.

Inputs: mapPath.

scene_list_unit_statusesB
Read-only

List the unit statuses (单位状态) defined in a save: id, name and effects. Read-only.

Inputs: mapPath.

scene_remove_clientA
Destructive

Take a client interface (ui: the name given to scene_add_client_ui), a template of client controls (template) or a client script (script) out of a copy of a save; one of the three in a call. To change an interface or a template that is there, this is not needed: scene_get_client_ui reads it, and scene_add_client_ui (scene_add_client_template) with replace: true puts the changed one in its place under the same ids; a script alone is changed with scene_set_client_script. A script that controls still carry and a template a grid or a reference still names are refused, with the names of what holds them. Writes a new .gil in the workspace.

Inputs: ui, script, mapPath, template, +1 more.

scene_remove_entitiesA
Destructive

Take things that were placed in the scene out of a copy of a save: a floor piece that was laid in the wrong place, a row of fences that turned out not to be needed, the pieces of a version of the scene that is being replaced. names is a list of entity names (each exactly, as scene_list_entities gives them; every entity of that name goes), or namePrefix takes all whose names begin with it (at least two characters). Importing a scene can only add; this is how to take away without starting over from the base map. The entities every map has by itself (the stage entity, the player slots) are refused. A graph that looks a removed thing up by its GUID finds nothing afterwards. Returns a new .gil; the official save is not touched, so go on from the copy. Seen in the game on 2026-10-13: a level with three of its wall pieces removed opened in the editor and played, the walls gone and the rest as before.

Inputs: names, mapPath, namePrefix, outputName.

scene_search_assetsA
Read-only

Search the full catalog of 2468 official placeable assets (trees, houses, fences, tents, props, mechanisms, monsters) by words in the Chinese name or icon name, optionally by group and by longest side in metres. Returns id, name, group, icon, model size and hasImage, and presetStatus for mechanism assets whose built-in animation is known (chests that open, levers, doors: group 交互机关). Many assets share a name; look at them with scene_asset_images before choosing. Use the id as template in scene_build_blocks. The id of an asset as query finds that asset (its size, its group). queries: several searches in one call (queries: ["围栏", "拱门", "火盆", "石地板"]), one list each: the things of a whole scene are found in one or two calls instead of twenty. A query that finds nothing comes back with didYouMean, names of the catalog that share most of its characters.

Inputs: group, limit, query, offset, +3 more.

scene_set_cameraA
Destructive

Change how far the play camera stands from the character, its field of view, and whether the player can turn it, in a copy of a save. fixedView {yaw, pitch, ignoreCollision} locks the view (the 2.5D camera of the editor, 2.5D镜头): the camera looks from one horizontal angle (yaw 0 looks towards +z from the -z side, so that A and D walk along x; 90 turns it a quarter round) at one pitch (positive looks down: 20 to 25 for a side view, 50 to 60 for a view from above), the player cannot turn it with the mouse, the zoom is held at the distance, and with ignoreCollision (on unless switched off) the camera does not jump close when a wall or an invisible wall comes between it and the character. Every game that is built for one direction of view (a side-scroller, an arena seen from above, a lane) needs this: without it the first movement of the mouse turns the camera and D no longer walks along the lane. Read from a template switched to that mode by hand in the editor on 2026-10-13 and written the same way; seen in play that day (examples/hazards/hazards_fixed_view.json: the same mouse movements that swing the free camera right round leave the fixed view where it is; hazards_free_view.json is the comparison). Without fixedView: The picture shows about 2distancetan(fieldOfView/2) metres of height at the character and 16/9 of that across (at 45 degrees: 14 m shows about 20.6 m across, 18 m about 26.5 m; in a side-view game whatever stands further from the character than half of that is off the screen): 6 m at 45 degrees is a close shot (5 m tall, large buildings are cut off), 14 m shows about 11.6 m and whole buildings with sky above them. yawRange and pitchRange ([min, max] in degrees) limit how far the player can turn the camera; a new template allows everything (-180..180, -89..89). The camera starts behind the character, wherever the character faces: set the facing with scene_set_spawn (rotation [0,0,0] faces +z, so the camera looks from the -z side and A and D walk along x; turned 90 degrees, D no longer walks along x). yawRange did not fix the starting direction in playtests, and a yawRange of [0, 0] is dropped when the editor saves; pitchRange [55, 55] does give a top-down view. The camera template must already exist (create it once in the editor). Writes a new .gil in the workspace and returns its path; the official save is not touched.

Inputs: name, mapPath, distance, yawRange, +4 more.

scene_set_classA
Destructive

Change what a class (职业) lets the player's character do, in a copy of a save: allowJump, allowSprint, allowClimb, allowGlide, and cameraTemplateId (a camera from scene_list_cameras) so that this class plays with that camera. On this platform the character's abilities and its camera belong to the class, not to node graphs: a side-scroller or a top-down game gives its class the right camera and switches off what the game does not use. name picks the class when the save has several. Writes a new .gil in the workspace; the official save is not touched. allowJump false and allowClimb false were verified in play on 2026-10-11 (space pressed, the character stayed on the ground; pushed against a wall 2.4 m high it stopped, where with climbing on it climbed over); allowSprint too (with it off, two seconds of shift and D covered the 10.5 m that walking does; with it on, 17.4 m). allowGlide too (walking off a tower 12 m high and pressing space in the air: about a second to the ground with it off; with it on the character glides down at 2 m a second). health, attack, defence and stamina are the base combat attributes of the class and level the level a player starts it at (the character's real numbers are the base ones times the multiplier its level has on the growth curve of the class): a new map gives the character a base health of 10000, attack 500 and defence 500, which no ordinary enemy wears down, so a game in which the player can lose a fight sets a health to match its enemies. Read from the official samples (a class of health 1, a swordsman of health 100); health verified in play on 2026-10-12 (set to 300, the bar of a level 1 character reads 300 / 300).

Inputs: name, level, attack, health, +9 more.

scene_set_client_scriptA
Destructive

Put a client script (客户端脚本) into a copy of a save, or replace the one of that name: Lua 5.3 that runs on the player's own machine and drives client controls (scene_add_client_ui puts those on the screen and says which script their root carries). This is the way to an interface that moves and answers the mouse and any key, to a menu, to a whole 2D game on the screen; a node graph cannot do these. The game calls the functions OnInit(), OnStart(), OnEnable(), OnDisable(), OnDestroy() when the script defines them, and OnUpdate(dt) every frame once the script has called script:EnableUpdate(true) (not before: seen in play). variables gives the script values it reads with script:GetParam(name): any of the twenty types the editor offers (integer, float, boolean, string, vector3, the ids guid, configId, prefabId and controlId, entity, and a list of each); one marked public can be given another value by each control that carries the script (scene_add_client_ui, script: {name, values}), which is how one script serves several controls. script.object is the control the script is on; control:GetChild(name) finds a control under it. From the level a script reads custom variables (game.GetGlobalCustomVariableValue(Enum.CustomVariableEntityType.PlayerSelf | Level | AvatarSelf, name), and script:RegisterCustomVariableChangedHandler to hear a change), so a graph tells the screen something that lasts by setting a variable; a graph sends the scripts of one player a message of the moment with f.sendSignal('client:NAME', player) (a signal of scene_add_signal; the script hears it with script:RegisterServerSignalHandler("NAME", function(name, params) ... end)); to the level a script sends a signal (game.ServerSignal(name):SendSignal()). Not available in this Lua: coroutine, io, load, loadfile, dofile, package, most of os and debug (refused here). require is there: require("NAME") runs the script whose file is NAME.lua (another script of the save, put there with this tool and carried by no control) once and gives what it returns, so a level can be several files; the name is the file name without .lua, letter for letter. Color(r, g, b, a) takes 0 to 255 (fractions give black), and the fill of an image (a bar that grows, a cooldown ring: SetFillHorizontal, SetFillRadial360, fillAmount) shows only on an image whose mask is on (mask: true in scene_add_client_ui, or control.enableMask = true): the result says so when the script looks like either mistake, as it does for an OnUpdate that was never enabled and a tween that was never played. A script that does not compile is refused here at once, with line and column; names it gets wrong (a function game does not have, an Enum value, a signal or a variable the save lacks) come back as problems, each with the nearest name there is; a fault while it runs comes back in the prints of the playtest with a traceback. read_knowledge {id:"client-lua.zh-CN"} is the page on writing one, with a worked script; the whole API is the official page (search_knowledge "客户端控件API文档"). Replacing a script keeps its id: the controls that carry it need no change, so a round of work on the Lua is this call and a playtest, and that playtest takes about a minute: when the save the last playtest opened is still open and nothing but the text of the scripts differs, playtest_start writes the Lua into the files the editor keeps beside the save (the game runs those) and plays, without importing anything. Writes a new .gil in the workspace; the official save is not touched.

Inputs: name (required), file, source, mapPath, +3 more.

scene_set_creature_logicA
Destructive

Give a complex creature its behaviour, in a copy of a save: the decision graph it runs all the time, the skills it can use and how it notices enemies. This is how a unit is made to do things on this platform (walk to a place, wander, work, flee, fight): an ordinary creature only reacts to enemies the way its asset was built to, a complex creature (an asset of the group "怪物(AI版)") does what its graphs say. prefab is a creature prefab made from a placed complex creature (scene_add_prefab {fromEntity}); every placed copy is changed too; entity names placed creatures instead. decisionGraphId is a graph made with scene_add_graph {kind:"creatureDecision"}: it looks at the situation and switches to one of several status graphs (kind "creatureStatus"), each a short list of tactics and skills with a condition on each: move to a point or to an entity, wander, stand still, pursue, flee, patrol, turn, execute a skill. These graphs read custom variables, so a server graph steers the creature by writing variables on it (where to go, what its job is, whether it is night). skills lists creature skills (scene_add_creature_skill) by name or id; they get the numbers 1, 2, ... in this order, which a status graph passes to f.executeSkill. cooldownSeconds of a skill is the wait after one use before the next, a number or [from, to] for a random wait (the editor's default is [0, 3]); firstCooldownSeconds the wait before its first use in a fight; sharedCooldownSeconds the wait every skill of the creature shares. logic is how the creature comes to fight (自主逻辑参数): noticeRadius, metres around it within which it notices an enemy whichever way it looks (范围感知; off when left out); sightDistance, how far it sees in front of it (视锥距离, 10); leaveCombatDistance, the distance to its target beyond which it gives up (脱战距离; the editor's 5 is less than its sight, so with logic it defaults to the larger of the two distances plus 6); leaveCombatDelaySeconds; territoryRadius, metres around the place it was created that it does not leave (领地, 50); chainRadius, within which its fellows join the fight (连锁入战距离). An enemy it notices becomes its aggro target (TargetEntity.AggroTarget in its graphs; f.queryIfEntityIsOnTheField tells whether there is one). Without logic the creature keeps its templates; one without any gets the template the editor makes. Writes a new .gil in the workspace; the official save is not touched. Without cooldowns and logic, byte for byte the two creatures of the official sample 复杂造物; the cooldown and logic numbers were each changed in the editor and read back on 2026-10-11.

Inputs: decisionGraphId (required), logic, entity, prefab, +4 more.

scene_set_faction_hostilityA
Destructive

Set which factions fight each other, in a copy of a save. hostilePairs is the complete list of pairs that are hostile, e.g. [[1,3]] for "players and creatures fight, objects are left alone by everyone"; every pair not listed becomes friendly (友善), so neither side attacks the other. Use it when creatures attack things they should ignore (display objects, walls, scenery created at run time) or ignore things they should attack. Writes a new .gil in the workspace and returns its path; the official save is not touched.

Inputs: hostilePairs (required), mapPath, outputName.

scene_set_level_settingsA
Destructive

Change level settings in a copy of a save. aggroMode "custom" switches the level to 自定义仇恨: the aggro nodes (setTheAggroValueOfSpecifiedEntity, tauntTarget, removeTargetEntityFromAggroList, clearSpecifiedTargetSAggroList) then work, so a graph can tell each creature whom to go for; "default" leaves target choice to the creatures. loadTier is the 负载需求档位 of the level: "low" (a new map; 1000) or "high" (4000; the editor warns that phones and consoles may not run such a level). Writes a new .gil in the workspace and returns its path; the official save is not touched.

Inputs: mapPath, loadTier, aggroMode, outputName.

scene_set_player_countA
Destructive

Set how many players the level takes (关卡设置 > 人数设置) in a copy of a save: {min, max}, up to 8. A new map says 1 to 8, which is what the lobby and matchmaking go by once the level is published: a game made for one player says {min: 1, max: 1}. A playtest from the editor is one player whatever this says. Written as the official samples have it for 1 to 8 and 1 to 4.

Inputs: max (required), min, mapPath, outputName.

scene_set_reviveA
Destructive

Set how a player's character comes back after going down (the revive settings of the player template), in a copy of a save: seconds (the wait before reviving, 10 on a new map), auto (true: it revives by itself when the wait is over), showScreen (false: the platform's revive screen with its button does not come up), lives (how many times a player may revive, 10 on a new map), healthPercent (the health a revived character has, 40), fallLossPercent (the share of its greatest health a character loses when it falls out of the world and is put back, 10). An arcade respawn is {seconds: 2, auto: true, showScreen: false}; three lives is {lives: 3}, and a graph hears whenAllPlayerSCharactersAreDown when they are used up. The level needs a respawn point (scene_add_respawn_point). scene_list_respawn_points shows the settings. The fields were read by changing each in the editor on 2026-10-13. Verified in play that day (examples/hazards): with {seconds: 2, auto: true, showScreen: false} a player knocked down by f.defeatAllPlayerSCharacters got no revive screen and stood at the respawn point about five seconds later.

Inputs: auto, lives, mapPath, seconds, +4 more.

scene_set_spawnA
Destructive

Set where players start and which way they face, in a copy of a save: the position and rotation ([x, y, z], rotation in degrees, y is the heading) of the preset point the level's spawn point uses. This is the platform's way to place the player at the start; a graph does not have to teleport anyone when the level begins. Stay on the ground: the flat ground of a new empty map ends about 32 m from its middle (a player teleported to x=32 fell out of the world), so keep the start, everything a creature is to walk to and every place a graph creates something within 30 m, or bring floor pieces of your own. The camera starts behind the character, so the heading also decides the first view (for a side view along x, face across the lane). Writes a new .gil in the workspace; the official save is not touched. Verified in play on 2026-10-10.

Inputs: mapPath, position, rotation, outputName.

scene_update_prefabA
Destructive

Change a prefab that already exists, in a copy of a save: its scale, the asset it shows, or its health. The prefab keeps its id, its components (triggers, option tabs, variables, hurt boxes) and the graphs attached to it, so nothing has to be made or attached again and the graphs that create it stay as they are: the way to make a wall thicker, a coin smaller, or to give a station another look after seeing it in a playtest. prefab is its name or id (scene_list_prefabs). scale is a number or [x, y, z] (1 = the natural size of the asset; the result gives the size in metres). asset swaps the model of an object prefab for another object asset (id or unique name from scene_search_assets); mechanism assets, the ones with a preset status, and creatures cannot be swapped in or out. health is the base health, as in scene_add_prefab. The areas of the triggers and option tabs of a prefab grow with its scale, so look at them again after a change of scale. Entities that were placed in the editor from this prefab keep their own scale.

Inputs: prefab (required), asset, scale, health, +2 more.

search_knowledgeA
Read-only

Full-text search of the offline knowledge base: the official Miliastra guide (every component, level setting, UI control, class, item/currency/shop system and node, 219 pages), the official course (84 lessons with step-by-step editor configuration), the FAQ, dissections of 48 official sample saves (which graphs hang on which entities, which events they use) and transcripts of the official videos. Use it before inventing a mechanic: the platform usually already has a component for it (collision trigger, option tab, timer, custom variable, currency, shop, UI text). Chinese or English words separated by spaces; hits come back as the best matching sections. section limits to guide / course / faq / samples / transcripts / notes / examples. The examples section holds our own worked levels, each recorded from a real run made with these tools only: every tool call in order with its arguments, and the source of every node graph (read_knowledge {id: "example-events"} is the small one to copy, "example-kingdom4" a whole game with a day and night and enemies, "example-hop" a platform course with a moving platform, a lever and gate, a skill and a countdown, "example-farm" a grow-and-sell loop with plots that keep their own state, tools, a signal that carries a string and currency, "example-checks" one use of each newer tool, "example-skills" three animated skills on three keys, "example-shop" a stall with the platform's shop screen, bought from and sold to by a script that clicks, "example-drops" a drop picked up and a chest that leaves loot, "example-buttons" two buttons on the screen, "example-strike" a sword attack that hits a crate and a creature, which leave loot, "example-raid" a fourth game: fight, pick up the loot, sell it, buy a key, open the gate, "example-potion" an item used from the backpack, "example-shoot" a bolt shot by a skill).

Inputs: query (required), limit, section.

search_node_docsA
Read-only

Find what a server node graph can call and listen to. Each hit is a node method or an event with its signature, what it does and what every parameter (or event field) means, in English and Chinese. Search by words from the name or the description in either language: "createPrefab", "特效", "patrol", "hp loss", "when timer". query "*" lists every node and event name, which is the quickest way to see what the platform offers. Hits beyond limit are listed by name in otherMatches. scope "raw" greps all bundled definition files instead (client graphs, enum members). queries: [...] asks up to 30 searches in one call (a level needs thirty or forty nodes, and one call for each was the slowest part of writing a graph in a blind test): each gets its own results, limit then counts for each query (three or four is enough when you know the names).

Inputs: limit, query, scope, queries.

sound_catalogA
Read-only

The sound effects of the platform, by name and category (环境 surroundings, 生物敌人叫声 creature voices, 角色动作 character moves, 战斗 fighting, 物件 objects, 界面音效 interface sounds such as clicks, confirmations, errors and rewards, 操控对象 vehicles). A graph plays one for a player with f.playerPlaysOneShot2dSoundEffect, or gives an entity a looping one with f.addSoundEffectPlayer; the result shows both calls. A level without sound feels like a prototype: give every action of the player a sound (picked up, bought, refused, hit, built, night falls, lost, won). query: words of the Chinese name; queries: several searches in one call, one list each; category: one of the categories. Names and ids were read from the editor's sound library on 2026-10-11; names longer than its list is wide end in …. Read-only.

Inputs: limit, query, offset, queries, +1 more.

write_graphsA
Destructive

Write the source of node graphs into a copy of a save, one graph or many in one call: each {graphId, code} is type-checked, compiled and written in place of that graph, and the save with all of them is returned. graphId is a graph that exists in the save (scene_add_graph returned it; inspect_map lists them), code its whole Genshin-TS source. Returns the mapPath of the save with all of them written, and for each graph the size the editor will count (limits) and any warnings. If one does not compile it stops there: failed names the graph and carries the compiler's errors, mapPath is the save with the graphs written before it, and the call can be repeated with the corrected graph and the ones after it on that mapPath. A level of ten graphs is one call instead of fifty. The graphs of one call are type-checked and compiled together, which takes about as long as one graph alone (thirty-seven graphs: a quarter of a minute; one by one they took four and a half): send all the graphs of a level, or all that changed, in one call. After a change to a few graphs, send only those, on the mapPath that has the others. A defineSignal that does not agree with the signal in the save (other types, another order or count; for client:NAME the player first) is refused with the declaration to use (SIGNAL_PARAMETERS_DIFFER): the values travel by their place and the compiler would take any.

Inputs: graphs (required), mapPath (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 85 tools

    Disambiguation4/5

    The set is large but the scene_/editor_/playtest_ prefixes and add/list/set/remove verbs make nearly every tool target a distinct resource+action (e.g. scene_add_skill vs scene_add_creature_skill vs scene_list_skills). A few pairs blur: scene_add_image / scene_add_text_box / scene_add_client_ui all put things on screen, and scene_set_camera / scene_set_class both touch cameras, though the long descriptions spell out the boundaries.

    Naming Consistency4/5

    Most tools follow a consistent snake_case verb_noun pattern with a domain prefix (scene_add_*, scene_list_*, scene_set_*, playtest_*). Deviations are minor: catalog tools are noun-only (effect_catalog, sound_catalog, creature_animations) and a few top-level tools lack prefixes (list_maps, inspect_map, write_graphs).

    Tool Count2/5

    85 tools is far beyond a comfortable surface for an agent to reason over, even for a rich game-editor domain spanning scene building, UI, scripting, playtests and publishing. scene_batch and playtest_start consolidate some workflows, but selection overhead and description volume remain heavy.

    Completeness4/5

    Coverage is strong across the lifecycle: create/read/update for prefabs, components, skills, items, currencies, shops, signals, timers, UI and scripts, plus read-only listers for nearly every resource and a full playtest/publish loop. Gaps are minor but real: no deletion/update tools for items, currencies, skills or signals, and some skill/item features (combos, cooldowns on definitions, equipment) are explicitly not supported.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers