genshin-miliastra-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MILIASTRA_PYTHON | No | Absolute path to the Python interpreter, used when Python is not on PATH or you want to use a separate environment for screenshot capture. | |
| MILIASTRA_WORKSPACE | No | Folder where the tools put project copies, screenshots and logs. | |
| MILIASTRA_SAVE_ROOTS | No | JSON string of an array of absolute paths, set when the saves are not in the default location (default: current Windows user's AppData/LocalLow/miHoYo/原神/BeyondLocal and the international equivalent, scanning only Beyond_Local_Save_Level). | |
| MILIASTRA_STEP_TOOLS | No | Set to 1 to also list the earlier step-by-step graph tools (create project, edit source, build, preview, write), which are hidden by default. | |
| MILIASTRA_PLAYTEST_PYTHON | No | Absolute path to the Python interpreter used for automatic playtest, for a separate Python environment. | |
| MILIASTRA_ALLOW_LIVE_WRITE | No | When set to 0, only a copy of the save is written (imported as a new save during playtest), leaving your official save untouched. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_capabilitiesA | Discover supported operations, limitations, version, configured paths and recommended workflow. |
| list_mapsA | 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. |
| inspect_mapA | 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). |
| search_node_docsA | 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). |
| search_knowledgeA | 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). |
| read_knowledgeA | Read one knowledge-base page by the id that search_knowledge returned, optionally only the sections whose heading contains |
| write_graphsA | 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. |
| list_editor_windowsA | List visible Genshin and Miliastra editor windows with current windowId, PID, physical rect, foreground and minimized state. Read-only Windows 10 compatible backend. |
| capture_editor_windowA | 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. |
| focus_editor_windowA | Bring an observed game/editor window to the foreground and return a fresh screenshot. Windows may deny focus; do not proceed if it fails. |
| editor_inputA | 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. |
| playtest_startA | 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. |
| scene_block_catalogA | List the building blocks scene_build_blocks can place: name, template ID, approximate colour and native size. Read this before designing a scene. |
| scene_search_assetsA | 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. |
| scene_asset_imagesA | 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. |
| effect_catalogA | 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. |
| sound_catalogA | 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. |
| music_catalogA | 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. |
| creature_animationsA | 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. |
| scene_build_blocksA | 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. |
| scene_import_assetsA | 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. |
| editor_open_mapA | 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). |
| editor_preview_interfaceA | 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. |
| scene_list_entitiesA | 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. |
| scene_remove_entitiesA | 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. |
| scene_list_camerasA | 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. |
| scene_set_cameraA | 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. |
| scene_list_prefabsA | 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. |
| scene_add_prefabA | 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. |
| scene_update_prefabA | 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. |
| scene_list_factionsA | 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. |
| scene_set_faction_hostilityA | 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. |
| scene_get_level_settingsA | 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. |
| scene_set_level_settingsA | 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. |
| scene_add_graphA | 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. |
| scene_add_componentsA | 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. |
| scene_list_componentsB | 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. |
| scene_add_progress_barA | 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. |
| scene_add_text_boxA | 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 界面控件. |
| image_catalogB | 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. |
| scene_add_imageA | 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. |
| scene_add_global_timerA | 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. |
| scene_list_global_timersB | List the global timers (全局计时器) defined in a save: name, seconds, countdown or stopwatch. Read-only. |
| scene_add_timer_displayA | 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. |
| scene_list_interfaceB | 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. |
| scene_set_client_scriptA | 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. |
| scene_list_client_scriptsB | 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. |
| scene_import_simulatorA | 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. |
| scene_check_clientA | 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). |
| scene_add_client_uiA | 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). |
| scene_get_client_uiA | 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. |
| scene_add_client_templateB | 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. |
| scene_remove_clientA | 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. |
| scene_add_unit_statusA | 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). |
| scene_list_unit_statusesB | List the unit statuses (单位状态) defined in a save: id, name and effects. Read-only. |
| scene_add_environmentA | 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. |
| scene_add_lightA | 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. |
| scene_list_environmentsB | 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. |
| scene_list_classesA | 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. |
| scene_set_classA | 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). |
| scene_add_signalA | 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). |
| scene_list_signalsB | List the names of the signals (信号) defined in a save, and what each carries (parameters: name and type, in order). Read-only. |
| scene_list_preset_pointsB | List the preset points (预设点) of a save: id, name, position, rotation, and which one players start at. Read-only. |
| scene_set_spawnA | 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. |
| scene_add_respawn_pointB | 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). |
| scene_list_respawn_pointsC | List the respawn points of a save (number, preset point, place) and how many players the level takes (the group of the level settings). |
| scene_set_player_countA | 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. |
| scene_set_reviveA | 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. |
| scene_add_skillA | 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). |
| scene_list_skillsA | 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. |
| scene_add_creature_skillA | 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. |
| scene_list_creature_skillsB | List the creature skills (造物技能) defined in a save: id, name, the creature they belong to, their animation and graph. Read-only. |
| scene_set_creature_logicA | 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. |
| scene_add_currencyA | 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. |
| scene_list_currenciesB | 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). |
| scene_add_itemA | 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. |
| scene_add_shopA | 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. |
| scene_list_itemsB | 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). |
| scene_add_buttonA | 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. |
| scene_add_card_selectorA | 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. |
| scene_add_preset_pointA | 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. |
| playtest_statusA | 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. |
| playtest_framesA | 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. |
| publish_kitA | 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. |
| scene_batchA | 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). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| workflow | |
| knowledge | |
| platform-rules |
TDQS
Scored across 85 tools
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.
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).
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.
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.