AI assistants / MCP

Epok exposes the open game project through the Model Context Protocol. An MCP client can inspect and edit scenes, components, assets and C++ scripts, control the editor and emulator, and receive PNG screenshots from the actual renderer.

editor_control also accepts serial_connection to open adapter setup and serial_prepare to install or repair Epok's managed serial components. Neither uploads a program. editor_state.serial reports the setup window, component directory, adapter and setup result; play uses the project's saved destination.

The server is off by default. No AI account or provider SDK is needed.

Connect

1. Open a game project.
2. Open Edit > Editor Preferences > AI / MCP.
3. Check Enable MCP Server, then Apply. Status should show Listening.
4. Copy either client configuration and add it to your AI application's MCP settings.

HTTP: the default endpoint is http://127.0.0.1:8765/mcp, with a bearer access key. Copy HTTP Client Config produces this shape with your actual key:

{
  "mcpServers": {
    "epok": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": { "Authorization": "Bearer YOUR_ACCESS_KEY" }
    }
  }
}

Stdio: Copy Stdio Client Config uses the current editor executable as a lightweight bridge to the running server. It does not open another editor or enable MCP automatically. The bridge reads the same user's saved preferences, so no key is embedded in this configuration:

{
  "mcpServers": {
    "epok": {
      "command": "D:/Applications/Epok/epok-editor.exe",
      "args": ["--mcp-stdio"]
    }
  }
}

Replace the example executable path with your installation, or use the copy button. Client configuration syntax can differ between applications; use their Streamable HTTP or stdio connection form as appropriate. Image-capable MCP clients can inspect the screenshot results directly.

Keep the editor open with the intended project selected. Closing that project stops its server; opening another project starts a server for the new project if the preference remains enabled. Clients should read editor_state after reconnecting. Only one editor can use a given port at a time; a conflict is shown in Status. Choose another port, or disable and re-enable after freeing it.

Tools

Tools publish their argument schemas and descriptions through tools/list.

editor_view takes view_mode with the value "3d", "2d" or "ui". The older scene_2d boolean still works and means the same thing it always did: true is the UI mode, false is 3D. When both are sent, view_mode wins. editor_state reports both, so a client written against either spelling keeps working. The 2D mode reports scene_2d: false, because a 2D world is not the Canvas editor: read view_mode when the distinction matters.

Read-only resources are also available at epok://guide, epok://editor/state, epok://scene/current, epok://scene/schema and epok://project/settings.

Editing workflow

Ask an assistant to inspect the project, create a blue cube next to the player, frame it, and show a Scene screenshot. A typical tool sequence is:

1. editor_state and scene_read establish the project and current revision.

2. scene_apply receives that revision and an operation such as:

   {
     "op": "create",
     "actor": {
       "name": "Blue Cube",
       "kind": "Mesh",
       "position": [0, 0.5, 0],
       "material": { "color": [0.2, 0.6, 1.0] }
     }
   }
   

3. actor_select uses the Actor UUID and current revision, with frame: true.

4. viewer_screenshot with target: "scene" returns the rendered image.

5. scene_save saves the accepted scene, or scene_history with action: "undo" restores the previous scene.

Entity indices refer to the scene array, not permanent IDs. Deleting a branch changes subsequent indices. Within a batch, each operation sees the result of the previous one. Patches merge objects recursively, replace arrays and use null to remove optional components. Invalid batches leave the scene untouched. Unknown component fields are rejected instead of silently ignored.

Scene changes remain unsaved until scene_save. Revisions prevent stale edits; Undo/Redo also rejects intervening changes from the user. MCP history covers scene batches only, not file changes, asset documents, lighting bakes or arbitrary GUI actions.

For source files, project_files returns a SHA256 revision. Supply it for replacement/deletion, or "absent" to create a new file. Prior contents are retained under .epok/mcp-backups/; the response identifies the backup path for manual recovery. Imported asset trash lives in UserSettings/AssetTrash/. The active scene and .epokasset packages use their dedicated tools.

Build, Play, import and lighting bake run asynchronously. Poll editor_state and read logs_read to distinguish completion from failure. Stop Play before authoring changes. The same scene, geometry and PSX budget validators used by the editor apply to MCP edits.

Scope and limits

• The HTTP server binds only to IPv4 loopback and checks the bearer key, Host and browser Origin. There is no LAN listener, shell execution or arbitrary computer filesystem access. Script edits can affect what runs during a game build; connect trusted clients.
• Preferences and the key are local to the OS user. They are not included in game exports. Regenerate > Apply rotates the key and restarts connections. Uncheck Enable MCP Server > Apply stops the listener, including while Play is running. A restart does not undo edits already applied.
• scene captures the full 960 x 600 render texture in 3D mode and the native HUD in 2D mode. The visible dock can crop this texture. hud always captures the native HUD; game requires a frame received from the emulator and returns its actual output resolution. editor captures the application surface, including open dialogs.
• File read/write payloads are limited to 2 MiB. Directory listing returns one level, up to 1,000 entries. Larger source files can be copied into the project normally and then imported by MCP.
• Requests use a bounded queue, with at most eight serviced per editor frame and a 20-second queue/response deadline. Cancelled or expired requests still waiting in the queue never edit the scene. If a client disconnects during an operation already underway, read the current state before retrying.
• This exposes current engine features; it does not add collision physics, texture import, animation blending or other unsupported runtime systems. MCP clients and transports are portable; the editor and emulator workflow supports Windows x64, macOS Apple Silicon and Linux x86_64. Linux editor and Play support remain experimental.

The transport uses the official Rust MCP SDK. Local tests cover protocol negotiation, resources, real HTTP and stdio clients, revisions, atomic scene edits, file conflicts, authentication and listener lifecycle. See Testing for the desktop/emulator integration command.

Actors

The actor tools author the Object/Actor/Component half of a scene (document version 5; see Actors and components and document formats). They are additive: the legacy entity tools are unchanged and still the way to author epok::Entity records.

Rules:

• class is validated against object_model::Model::placeable(), so an abstract class, a component class or a SceneScriptActor subclass is refused with the list of classes that are accepted. The whole scene is then checked with Scene::validate_with_model.
• Every mutation runs through the same scene transaction, so it goes through Editor::changed(): the build is marked stale and the edit is reversible with scene_history (undo/redo), together with other Actor edits, in one history.
• scene_actors lists the map's single collection of authored Actors. There is no derived Entity view or implicit migration.
• model_available is false in a project that has never compiled. scene_actors still lists the document; the mutating tools refuse until the class model exists.

Choosing a scene operation

The command-line equivalent of scene_add_actor is --project <folder> --add-actor <class>:<name> [--scene assets/scenes/Map.epokmap], which applies the same placeable() gate and the same validation before saving. It defaults to the project's startup scene.