AGENT SKILL

ez-mcp

Drive a running ezEditor or ezPlayer/game from an agent over MCP - launch one with a port, then call tools to inspect and change a live project. Use for ezEngine tasks that need the running app rather than files on disk. Triggers - ezEditor, ezPlayer, ezEditorProcessor, MCP server, editor-mcpport, mcpport, transform asset, asset dependencies, asset browser, open document, edit scene, build a scene, game object, component, prefab, property grid, selection, reflected types, RTTI, CVar, editor action, play the game, screenshot, inject input, press key, step frames, export project, create project, build the C++ plugin.

License 许可
MIT
所属仓库
ezEngine/ezEngine
最近更新
2026-11-13
Stars
★ 2.0k
Forks
268

01 前言 Front Matter

name
ez-mcp
description
Drive a running ezEditor or ezPlayer/game from an agent over MCP - launch one with a port, then call tools to inspect and change a live project. Use for ezEngine tasks that need the running app rather than files on disk. Triggers - ezEditor, ezPlayer, ezEditorProcessor, MCP server, editor-mcpport, mcpport, transform asset, asset dependencies, asset browser, open document, edit scene, build a scene, game object, component, prefab, property grid, selection, reflected types, RTTI, CVar, editor action, play the game, screenshot, inject input, press key, step frames, export project, create project, build the C++ plugin.

03 SKILL.md 正文

Driving ezEditor and the game over MCP

Two hosts, same protocol, separate ports and separate tool lists:

Host Started with Answers about
Editor (ezEditor.exe) -editor-mcpport <n> assets, documents, scene contents, reflected types, editor actions, the C++ plugin
Game (ezPlayer.exe, or the engine process the editor plays in) -mcpport <n> what is rendered and simulated: screenshots, input, frames, the clock

Neither is a registered project MCP server: neither runs most of the time and the port is per run. Start one, then talk to it. For anything the file system already answers, read the files instead.

Launching

# editor
ezEditor.exe -project "Data/Samples/PacMan" -unattended -editor-mcpport 7399
# game, standalone - no editor needed
ezPlayer.exe -project <project-folder> -scene <path/to/Scene.ezBinScene> -profile Default -unattended -mcpport 7401

Binaries are in Workspace/<workspace>-output/Bin/WinVs2026Dev64/.

  • -unattended is required for the editor, and should be passed to games as well. Otherwise a modal dialog during startup (e.g. "compile the C++ plugin?") hangs it before it serves anything. Tool calls suppress dialogs themselves; startup does not.
  • Launch detached (start "" / Start-Process); it runs until told to quit.
  • Startup takes seconds - poll the port, do not sleep a fixed time.
  • Pick a port other than the default 7391 so a user's own editor keeps working.
  • Without -mcpport the game starts no server at all.
  • -editor-mcpport and -mcpport are separate names on purpose: the editor forwards its whole command line to its engine process, which takes -editor-mcpport + 1. Read that port from the editor's app_info as engineMcpPort rather than computing it.
  • -project or -createProject keeps the dashboard away.

Calling tools

curl -s -X POST http://127.0.0.1:7399/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"project_info","arguments":{}}}'

{"jsonrpc":"2.0","id":1,"method":"tools/list"} returns every tool with its full description and input schema. Read that list before guessing - the descriptions carry the argument semantics and the warnings, plugins can add tools, and the two hosts do not have the same list. Results are JSON in content[0].text; failures carry "isError":true and a sentence saying what to do instead.

To register a running host for the session: claude mcp add --transport http ez-editor http://127.0.0.1:7399/mcp.

What is there

Both hosts: app_info, app_ping, app_quit, app_command_line_options, log_read, log_write, cvar_list, cvar_set, rtti_find_types, rtti_type_info, rtti_type_properties, rtti_derived_types - each answering for its own process.

Editor only
Project project_info, project_export
C++ plugin cpp_status, cpp_generate, cpp_build
Assets asset_types, asset_find, asset_info, asset_uses, asset_thumbnail, asset_transform, asset_health, asset_history, asset_processor, asset_importers, asset_import
Documents document_types, document_list, document_open, document_create, document_save, document_close, document_focus, document_delete
Contents object_tree, object_properties, object_modify, object_undo, object_drop_asset
Scene layers scene_layers
Node graphs graph_info, graph_node_templates, graph_add_node, graph_move_nodes, graph_connect, graph_disconnect
Selection selection_get, selection_set
Actions action_list, action_state, action_execute
Game only
Rendering app_screenshot
Time game_info, game_wait, game_pause, game_speed
Input input_slots, input_set, input_sequence

Start with project_info on the editor (paths and asset states are relative to what it reports), and with game_info on the game.

Editing a document

Nothing works on a closed document, and nothing opens implicitly:

  1. asset_find → path or guid. Its paths start with the data directory name (Testing Chambers/Scenes/DynamicFog.ezScene) - that is the form other tools want.
  2. document_open with path (not document - see below) and focus false, unless the user is meant to look at it.
  3. object_tree → guids. Asset documents have one top level object, so object_properties with only document already reads an asset's whole configuration. Scenes have many.
  4. object_properties / object_modify.
  5. document_save - nothing saves on its own, and the asset system sees nothing until it is saved.

Which argument names a tool takes, because guessing costs a round trip and they follow a rule:

Argument Tools Why
path document_open, document_create, document_delete act on a file that need not be open yet
document object_*, selection_*, document_save/_close/_focus, and the document argument of the action tools act on an already open document
asset asset_info, asset_transform, asset_thumbnail, asset_uses act on the asset database, open or not
name action_execute, action_state, rtti_*, cvar_set the thing named is not a document at all

So it is document_open path, action_execute name, rtti_derived_types name. When in doubt read the schema from tools/list rather than guessing - and note that a wrong name fails with a message that says the right one.

A scene's game objects and components live in the same hierarchy, told apart by the parent property they sit in. Building one is all object_modify:

addObject   property "Children",   type "ezGameObject"          -> child object ('object' "root": top level object)
addObject   property "Components", type "ezPointLightComponent"  -> component on it
set         property "Name" / "LocalPosition" / any component property
moveObject  newParent <guid>|"root" | duplicateObject | deleteObject  (each takes everything below it)

To place an asset, object_drop_asset runs the editor's own drag & drop handler: a mesh becomes an object with an ezMeshComponent, a prefab one with an ezPrefabReferenceComponent (prefabInstance true: an editable, linked prefab instance, like Shift+drag), and so on, at position and under parent. attachTo adds the component to an existing object instead, targetComponent assigns a material to a mesh component.

Scenes can have layers, separate .ezSceneLayer documents in <Scene>_data, listed by scene_layers. Only the active layer is editable, and while a layer is active the scene's objects are that layer's. The object tools therefore refuse a scene or layer that is not active, and say which one is. scene_layers setActive switches (the user sees it), after which the scene and the layer document both reach the layer's objects. Switch back to Scene to edit the scene's own objects.

rtti_derived_types of ezComponent lists component types; rtti_type_properties gives property names, value types and enum values before writing any. Vectors and colours go in as they come out ({"x":1,"y":2,"z":3} or [1,2,3]). selection_set is worth calling even when it changes nothing - it is how the user sees which object is meant, and selection_get answers "this object".

Editing a node graph

Visual scripts, materials using a visual shader, render pipelines, state machines, animation graphs and ProcGen graphs are node graphs. Nodes and connections are ordinary top level objects in object_tree, but pins, node positions and connecting only exist in the graph_* tools:

  1. graph_info - nodes with position and pins (name, dataType, description, connection count), connections as source node + output pin -> target node + input pin, and otherObjects (the asset's own settings). graphInUse false: the document ignores its graph (a material only uses it with ShaderMode Custom), and adding nodes or connections is refused until that is changed.
  2. graph_node_templates with contains - the node creation menu. Visual scripts have thousands of entries, many sharing one node type and differing only in pre-filled properties, so add by path, not by type.
  3. graph_add_node (template, position) returns the node with its pins. Node properties are set with object_modify as usual; a property can change the pins (e.g. a pin count), so re-read them afterwards.
  4. graph_connect goes from an output (source) to an input (target). Pins that take one connection get it replaced, reported under removedConnections. Pin names can be empty strings.
  5. graph_disconnect, graph_move_nodes. object_modify deleteObject on a node also removes its connections.

Connection objects cannot be created with addObject and their Source/Target/SourcePin/TargetPin cannot be set - use connect/disconnect. Other properties of a connection (a state machine transition) are set with object_modify. Lay out left to right, ~300 units apart, y pointing down.

Driving the game

gameStateActive false in game_info means nothing is being played - normal for the editor's engine process until play-the-game runs, and why input does nothing and screenshots time out.

  • Start it from the editor port: action_execute Scene.GameMode.Play with the scene document; Scene.GameMode.Stop ends it. Both are asynchronous (the editor asks the engine process), so Stop reads as disabled for a moment and game_info on the game port is the better confirmation.

  • app_screenshot returns a path, not the image. Read that file. A rendered frame is the evidence a change works; "did not crash" is not.

  • input_set then game_wait - input is consumed one frame at a time, so setting a slot alone does nothing. input_sequence does a whole set/wait/text/clear chain in one call. Injected values merge with the real keyboard, larger wins, so a human is never locked out.

  • game_wait takes frames or seconds (game time on the global clock). For "let the game play for a while" use seconds - a frame count lasts however long the frame rate makes it.

  • Launch games with -unattended. It prevents assert message boxes and the user's mouse and keyboard are ignored and the window doesn't take the focus or capture the cursor. Only input_set/input_sequence drive the game.

  • game_pause stops the engine clock, not necessarily the game's own simulation.

  • cvar_list is worth far more here than in the editor: render passes, physics and AI visualisation are mostly CVars.

Editor actions

action_execute runs global actions by name. Actions of scope Document or Window need a document argument (guid or path, already open); so do action_list and action_state, and that is the only way to read their per-document enabled state. Passing document to action_list also flips globalOnly off, so {"contains":"GameMode","document":"…","includeState":true} is the usual way to find them. Window actions additionally need a window (document_open with focus true).

C++ plugin

cpp_status first: hasCppProject false means no C++ code at all and cpp_generate creates it; compilerUsable false means CMake will refuse and cpp_generate with useSdkCompiler is the fix. After editing sources call cpp_build, with force when files were added, removed or renamed (CMake collects them at generation time). Both return the full build log - on failure it is the only place the compiler errors are. Then check pluginBinary / pluginBinaryExists: a build that reports success without producing the library means the plugin is not in use. Headless equivalent: ezEditorProcessor.exe -project <path> -compile (-recompile forces CMake too).

Creating a project

No tool for it - a different set of plugins is loaded, so it happens at launch:

ezEditor.exe -createProject "C:/Projects/MyGame" -projectTemplate "Basic FPS" -unattended -editor-mcpport 7399

The directory must be empty or absent; the project opens right away. Without -projectTemplate the project is blank, using -pluginTemplate (default General3D). -listTemplates logs the valid names. ezEditorProcessor.exe takes the same options and quits when done - better when no editor is wanted afterwards.

Rules that are not obvious

  • Every call blocks its host. One at a time, on the main thread. No progress, no cancel.
  • Some calls run for minutes: asset_transform over a project, project_export, cpp_build, cpp_generate. Give curl a timeout in tens of minutes.
  • app_ping tells "busy" from "hung". It answers only when the main thread is free, so silence during a long call is expected and silence afterwards is not. Take the process id from app_info up front - a hung host must be killed by pid, and app_quit will not get through either.
  • log_read only sees its own process. The editor cannot see what the engine logged, or vice versa. app_info reports engineLogFilePattern for when that process has died.
  • A failed assert comes back as a tool error with file, line and expression. That is an engine bug, not bad arguments - retrying will not help. The host keeps answering but has continued past a check meant to stop it, so restart it before trusting anything further, and report the text.
  • Check app_info's buildTimestamp before concluding a tool is missing. A binary built before a feature returns the same tools/list as one that never had it.
  • cvar_set on a requiresRestart CVar does not change what the engine reads. The response returns pendingValue separately; re-reading keeps showing the old value, and that is not a failed write.
  • Quit before rebuilding: app_quit (with discardChanges if documents are modified), or the plugin DLLs stay locked and the build fails.
  • Nothing saves implicitly. object_modify only marks the document modified; object_undo reverts.

04 同仓库更多 Skills