Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat: add entity CRUD endpoints to MCP bridge (create, delete, rename, reparent, add/remove component)

esengine665fa163e9e2
diff --git a/desktop/src-tauri/src/bridge_server.rs b/desktop/src-tauri/src/bridge_server.rs
index 05bf858e6..d72024e78 100644
--- a/desktop/src-tauri/src/bridge_server.rs
+++ b/desktop/src-tauri/src/bridge_server.rs
@@ -216,6 +216,30 @@ fn parse_request(
let selector = query_params.get("selector").cloned().unwrap_or_default();
Ok(("getElementBounds".into(), json!({ "selector": selector })))
}
+ ("POST", "/scene/create-entity") => {
+ let body = read_json_body(reader)?;
+ Ok(("createEntity".into(), body))
+ }
+ ("POST", "/scene/delete-entity") => {
+ let body = read_json_body(reader)?;
+ Ok(("deleteEntity".into(), body))
+ }
+ ("POST", "/scene/rename-entity") => {
+ let body = read_json_body(reader)?;
+ Ok(("renameEntity".into(), body))
+ }
+ ("POST", "/scene/reparent-entity") => {
+ let body = read_json_body(reader)?;
+ Ok(("reparentEntity".into(), body))
+ }
+ ("POST", "/scene/add-component") => {
+ let body = read_json_body(reader)?;
+ Ok(("addComponent".into(), body))
+ }
+ ("POST", "/scene/remove-component") => {
+ let body = read_json_body(reader)?;
+ Ok(("removeComponent".into(), body))
+ }
("POST", "/action/select") => {
let body = read_json_body(reader)?;
Ok(("selectEntity".into(), body))
diff --git a/editor/src/bridge/McpBridge.ts b/editor/src/bridge/McpBridge.ts
index 7073d7187..f15526c1f 100644
--- a/editor/src/bridge/McpBridge.ts
+++ b/editor/src/bridge/McpBridge.ts
@@ -10,6 +10,7 @@ import { getAllMenus, getMenuItems } from '../menus/MenuRegistry';
import { getAllPanels } from '../panels/PanelRegistry';
import { exportSettings, getSettingsValue } from '../settings/SettingsRegistry';
import { PropertyCommand } from '../commands/PropertyCommand';
+import { getInitialComponentData } from '../schemas/ComponentSchemas';
import type { SceneData, EntityData } from '../types/SceneTypes';
import { RingBuffer } from './RingBuffer';
@@ -104,6 +105,12 @@ export class McpBridge {
case 'getRenderStats': return this.getRenderStats_();
case 'getElementBounds': return this.getElementBounds_(params.selector as string);
case 'capture': return this.capture_(params);
+ case 'createEntity': return this.createEntity_(params);
+ case 'deleteEntity': return this.deleteEntity_(params);
+ case 'renameEntity': return this.renameEntity_(params);
+ case 'reparentEntity': return this.reparentEntity_(params);
+ case 'addComponent': return this.addComponent_(params);
+ case 'removeComponent': return this.removeComponent_(params);
case 'selectEntity': return this.selectEntity_(params);
case 'setProperty': return this.setProperty_(params);
case 'executeMenu': return this.executeMenu_(params.id as string);
@@ -339,6 +346,88 @@ export class McpBridge {
}
}
+ // =========================================================================
+ // Entity CRUD
+ // =========================================================================
+
+ private createEntity_(params: Record<string, unknown>): unknown {
+ const store = getEditorStore();
+ const name = (params.name as string) ?? 'Entity';
+ const parentRef = params.parent;
+ const parent = parentRef == null ? null
+ : typeof parentRef === 'string' ? this.resolveEntityByName_(parentRef)
+ : parentRef as number;
+ const entity = store.createEntity(name, parent);
+
+ const components = params.components as Array<{ type: string; data?: Record<string, unknown> }> | undefined;
+ if (components) {
+ for (const comp of components) {
+ const defaults = getInitialComponentData(comp.type);
+ store.addComponent(entity, comp.type, { ...defaults, ...comp.data });
+ }
+ }
+
+ getSharedRenderContext().requestRender();
+ return { ok: true, entityId: entity };
+ }
+
+ private deleteEntity_(params: Record<string, unknown>): unknown {
+ const store = getEditorStore();
+ const id = this.resolveEntity_(params.id as number | undefined, params.name as string | undefined);
+ if (id == null) throw new Error('Entity not found');
+ store.deleteEntity(id);
+ getSharedRenderContext().requestRender();
+ return { ok: true };
+ }
+
+ private renameEntity_(params: Record<string, unknown>): unknown {
+ const store = getEditorStore();
+ const id = this.resolveEntity_(params.id as number | undefined, params.name as string | undefined);
+ if (id == null) throw new Error('Entity not found');
+ const newName = params.newName as string;
+ if (!newName) throw new Error('newName is required');
+ store.renameEntity(id, newName);
+ getSharedRenderContext().requestRender();
+ return { ok: true };
+ }
+
+ private reparentEntity_(params: Record<string, unknown>): unknown {
+ const store = getEditorStore();
+ const id = this.resolveEntity_(params.id as number | undefined, params.name as string | undefined);
+ if (id == null) throw new Error('Entity not found');
+ const parentRef = params.newParent;
+ const newParent = parentRef == null ? null
+ : typeof parentRef === 'string' ? this.resolveEntityByName_(parentRef)
+ : parentRef as number;
+ store.reparentEntity(id, newParent);
+ getSharedRenderContext().requestRender();
+ return { ok: true };
+ }
+
+ private addComponent_(params: Record<string, unknown>): unknown {
+ const store = getEditorStore();
+ const id = this.resolveEntity_(params.id as number | undefined, params.name as string | undefined);
+ if (id == null) throw new Error('Entity not found');
+ const componentType = params.component as string;
+ if (!componentType) throw new Error('component type is required');
+ const defaults = getInitialComponentData(componentType);
+ const data = params.data as Record<string, unknown> | undefined;
+ store.addComponent(id, componentType, { ...defaults, ...data });
+ getSharedRenderContext().requestRender();
+ return { ok: true };
+ }
+
+ private removeComponent_(params: Record<string, unknown>): unknown {
+ const store = getEditorStore();
+ const id = this.resolveEntity_(params.id as number | undefined, params.name as string | undefined);
+ if (id == null) throw new Error('Entity not found');
+ const componentType = params.component as string;
+ if (!componentType) throw new Error('component type is required');
+ store.removeComponent(id, componentType);
+ getSharedRenderContext().requestRender();
+ return { ok: true };
+ }
+
// =========================================================================
// Actions
// =========================================================================
diff --git a/tools/mcp-server/src/tools/scene.ts b/tools/mcp-server/src/tools/scene.ts
index 3597395dd..26e823622 100644
--- a/tools/mcp-server/src/tools/scene.ts
+++ b/tools/mcp-server/src/tools/scene.ts
@@ -48,4 +48,100 @@ export function registerSceneTools(
return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
},
);
+
+ server.tool(
+ 'create_entity',
+ 'Create a new entity in the scene, optionally with components',
+ {
+ name: z.string().optional().describe('Entity name (default: "Entity")'),
+ parent: z.union([z.number(), z.string()]).optional().describe('Parent entity ID or name'),
+ components: z.array(z.object({
+ type: z.string().describe('Component type (e.g., "Transform", "Sprite")'),
+ data: z.record(z.unknown()).optional().describe('Component data overrides'),
+ })).optional().describe('Components to add (defaults are auto-filled)'),
+ },
+ async (args: { name?: string; parent?: number | string; components?: Array<{ type: string; data?: Record<string, unknown> }> }) => {
+ const result = await bridge.post('/scene/create-entity', args);
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+ },
+ );
+
+ server.tool(
+ 'delete_entity',
+ 'Delete an entity from the scene',
+ {
+ entity: z.union([z.number(), z.string()]).describe('Entity ID or name'),
+ },
+ async (args: { entity: number | string }) => {
+ const body = typeof args.entity === 'number' ? { id: args.entity } : { name: args.entity };
+ const result = await bridge.post('/scene/delete-entity', body);
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };
+ },
+ );
+
+ server.tool(
+ 'rename_entity',
+ 'Rename an entity',
+ {
+ entity: z.union([z.number(), z.string()]).describe('Entity ID or current name'),
+ newName: z.string().describe('New name for the entity'),
+ },
+ async (args: { entity: number | string; newName: string }) => {
+ const body = typeof args.entity === 'number'
+ ? { id: args.entity, newName: args.newName }
+ : { name: args.entity, newName: args.newName };
+ const result = await bridge.post('/scene/rename-entity', body);
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };
+ },
+ );
+
+ server.tool(
+ 'reparent_entity',
+ 'Move an entity under a new parent (or to root if newParent is null)',
+ {
+ entity: z.union([z.number(), z.string()]).describe('Entity ID or name'),
+ newParent: z.union([z.number(), z.string()]).nullable().describe('New parent entity ID/name, or null for root'),
+ },
+ async (args: { entity: number | string; newParent: number | string | null }) => {
+ const body: Record<string, unknown> = { newParent: args.newParent };
+ if (typeof args.entity === 'number') body.id = args.entity;
+ else body.name = args.entity;
+ const result = await bridge.post('/scene/reparent-entity', body);
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };
+ },
+ );
+
+ server.tool(
+ 'add_component',
+ 'Add a component to an entity (defaults are auto-filled)',
+ {
+ entity: z.union([z.number(), z.string()]).describe('Entity ID or name'),
+ component: z.string().describe('Component type (e.g., "Transform", "Sprite", "RigidBody")'),
+ data: z.record(z.unknown()).optional().describe('Component data overrides'),
+ },
+ async (args: { entity: number | string; component: string; data?: Record<string, unknown> }) => {
+ const body: Record<string, unknown> = { component: args.component };
+ if (typeof args.entity === 'number') body.id = args.entity;
+ else body.name = args.entity;
+ if (args.data) body.data = args.data;
+ const result = await bridge.post('/scene/add-component', body);
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };
+ },
+ );
+
+ server.tool(
+ 'remove_component',
+ 'Remove a component from an entity',
+ {
+ entity: z.union([z.number(), z.string()]).describe('Entity ID or name'),
+ component: z.string().describe('Component type to remove'),
+ },
+ async (args: { entity: number | string; component: string }) => {
+ const body: Record<string, unknown> = { component: args.component };
+ if (typeof args.entity === 'number') body.id = args.entity;
+ else body.name = args.entity;
+ const result = await bridge.post('/scene/remove-component', body);
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };
+ },
+ );
}