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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat: add asset meta management and SDK reference to MCP server
esengine67e855a5df0e
diff --git a/desktop/src-tauri/src/bridge_server.rs b/desktop/src-tauri/src/bridge_server.rsindex d72024e78..bb4215204 100644--- a/desktop/src-tauri/src/bridge_server.rs+++ b/desktop/src-tauri/src/bridge_server.rs@@ -240,6 +240,56 @@ fn parse_request(let body = read_json_body(reader)?;Ok(("removeComponent".into(), body))}+ ("POST", "/scene/duplicate-entity") => {+ let body = read_json_body(reader)?;+ Ok(("duplicateEntity".into(), body))+ }+ ("POST", "/scene/instantiate-prefab") => {+ let body = read_json_body(reader)?;+ Ok(("instantiatePrefab".into(), body))+ }+ ("GET", "/assets/list") => {+ let asset_type = query_params.get("type").cloned();+ let mut p = json!({});+ if let Some(t) = asset_type { p["type"] = json!(t); }+ Ok(("listAssets".into(), p))+ }+ ("GET", "/assets/info") => {+ let uuid = query_params.get("uuid").cloned();+ let path = query_params.get("path").cloned();+ let mut p = json!({});+ if let Some(u) = uuid { p["uuid"] = json!(u); }+ if let Some(pa) = path { p["path"] = json!(pa); }+ Ok(("getAssetInfo".into(), p))+ }+ ("GET", "/components/list") => {+ Ok(("listComponents".into(), json!({})))+ }+ ("GET", "/components/schema") => {+ let name = query_params.get("name").cloned().unwrap_or_default();+ Ok(("getComponentSchema".into(), json!({ "name": name })))+ }+ ("GET", "/menus/list") => {+ Ok(("listMenus".into(), json!({})))+ }+ ("GET", "/scene/metadata") => {+ Ok(("getSceneMetadata".into(), json!({})))+ }+ ("POST", "/scene/toggle-visibility") => {+ let body = read_json_body(reader)?;+ Ok(("toggleVisibility".into(), body))+ }+ ("POST", "/scene/new") => {+ Ok(("newScene".into(), json!({})))+ }+ ("POST", "/scene/open") => {+ let body = read_json_body(reader)?;+ Ok(("openScene".into(), body))+ }+ ("POST", "/scripts/create") => {+ let body = read_json_body(reader)?;+ Ok(("createScript".into(), body))+ }("POST", "/action/select") => {let body = read_json_body(reader)?;Ok(("selectEntity".into(), body))@@ -261,6 +311,40 @@ fn parse_request(("POST", "/action/reload-scripts") => {Ok(("reloadScripts".into(), json!({})))}+ ("POST", "/action/undo") => {+ Ok(("undo".into(), json!({})))+ }+ ("POST", "/action/redo") => {+ Ok(("redo".into(), json!({})))+ }+ ("GET", "/assets/meta") => {+ let uuid = query_params.get("uuid").cloned();+ let path = query_params.get("path").cloned();+ let mut p = json!({});+ if let Some(u) = uuid { p["uuid"] = json!(u); }+ if let Some(pa) = path { p["path"] = json!(pa); }+ Ok(("getAssetMeta".into(), p))+ }+ ("POST", "/assets/meta/update") => {+ let body = read_json_body(reader)?;+ Ok(("updateAssetMeta".into(), body))+ }+ ("POST", "/assets/meta/ensure") => {+ let body = read_json_body(reader)?;+ Ok(("ensureAssetMeta".into(), body))+ }+ ("POST", "/assets/create") => {+ let body = read_json_body(reader)?;+ Ok(("createAsset".into(), body))+ }+ ("POST", "/assets/delete") => {+ let body = read_json_body(reader)?;+ Ok(("deleteAsset".into(), body))+ }+ ("POST", "/assets/rename") => {+ let body = read_json_body(reader)?;+ Ok(("renameAsset".into(), body))+ }_ => Err(format!("Unknown route: {} {}", method, path)),}}diff --git a/desktop/src/native-fs.ts b/desktop/src/native-fs.tsindex 6c914d6d0..4a7d57a0c 100644--- a/desktop/src/native-fs.ts+++ b/desktop/src/native-fs.ts@@ -15,6 +15,7 @@ import {stat,copyFile,remove,+ rename,watch as tauriWatch,} from '@tauri-apps/plugin-fs';import { invoke, convertFileSrc } from '@tauri-apps/api/core';@@ -69,6 +70,8 @@ export interface NativeFS {readFile(path: string): Promise<string | null>;readBinaryFile(path: string): Promise<Uint8Array | null>;copyFile(src: string, dest: string): Promise<boolean>;+ removeFile(path: string): Promise<boolean>;+ renameFile(oldPath: string, newPath: string): Promise<boolean>;getFileStats(path: string): Promise<FileStats | null>;openProject(): Promise<string | null>;listDirectory(path: string): Promise<string[]>;@@ -231,6 +234,26 @@ export const nativeFS: NativeFS = {}},+ async removeFile(path: string) {+ try {+ await remove(path);+ return true;+ } catch (err) {+ console.error('Failed to remove file:', err);+ return false;+ }+ },++ async renameFile(oldPath: string, newPath: string) {+ try {+ await rename(oldPath, newPath);+ return true;+ } catch (err) {+ console.error('Failed to rename file:', err);+ return false;+ }+ },+async getFileStats(path: string) {try {const stats = await stat(path);diff --git a/editor/src/bridge/McpBridge.ts b/editor/src/bridge/McpBridge.tsindex f15526c1f..dcbb43887 100644--- a/editor/src/bridge/McpBridge.ts+++ b/editor/src/bridge/McpBridge.ts@@ -10,7 +10,10 @@ 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 { getInitialComponentData, getAllComponentSchemas, getComponentsByCategory, getComponentSchema } from '../schemas/ComponentSchemas';+import { getAssetDatabase, type AssetEntry } from '../asset/AssetDatabase';+import { getSceneService, getClipboardService } from '../services';+import { getEditorContext } from '../context/EditorContext';import type { SceneData, EntityData } from '../types/SceneTypes';import { RingBuffer } from './RingBuffer';@@ -111,12 +114,32 @@ export class McpBridge {case 'reparentEntity': return this.reparentEntity_(params);case 'addComponent': return this.addComponent_(params);case 'removeComponent': return this.removeComponent_(params);+ case 'duplicateEntity': return this.duplicateEntity_(params);case 'selectEntity': return this.selectEntity_(params);case 'setProperty': return this.setProperty_(params);case 'executeMenu': return this.executeMenu_(params.id as string);case 'togglePlayMode': return this.togglePlayMode_();case 'saveScene': return this.saveScene_();case 'reloadScripts': return this.reloadScripts_();+ case 'undo': return this.undo_();+ case 'redo': return this.redo_();+ case 'listAssets': return this.listAssets_(params);+ case 'getAssetInfo': return this.getAssetInfo_(params);+ case 'listComponents': return this.listComponents_();+ case 'getComponentSchema': return this.getComponentSchema_(params.name as string);+ case 'listMenus': return this.listMenus_();+ case 'getSceneMetadata': return this.getSceneMetadata_();+ case 'toggleVisibility': return this.toggleVisibility_(params);+ case 'newScene': return this.newScene_();+ case 'openScene': return this.openScene_(params.path as string);+ case 'instantiatePrefab': return this.instantiatePrefab_(params);+ case 'createScript': return this.createScript_(params);+ case 'getAssetMeta': return this.getAssetMeta_(params);+ case 'updateAssetMeta': return this.updateAssetMeta_(params);+ case 'ensureAssetMeta': return this.ensureAssetMeta_(params);+ case 'createAsset': return this.createAsset_(params);+ case 'deleteAsset': return this.deleteAsset_(params);+ case 'renameAsset': return this.renameAsset_(params);default: throw new Error(`Unknown method: ${method}`);}}@@ -522,6 +545,380 @@ export class McpBridge {return { ok: true, success };}+ private duplicateEntity_(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.selectEntity(id);+ getClipboardService().duplicateSelected();+ getSharedRenderContext().requestRender();+ return { ok: true };+ }++ private undo_(): unknown {+ const store = getEditorStore();+ if (!store.canUndo) throw new Error('Nothing to undo');+ store.undo();+ getSharedRenderContext().requestRender();+ return { ok: true };+ }++ private redo_(): unknown {+ const store = getEditorStore();+ if (!store.canRedo) throw new Error('Nothing to redo');+ store.redo();+ getSharedRenderContext().requestRender();+ return { ok: true };+ }++ // =========================================================================+ // Assets & Components+ // =========================================================================++ private listAssets_(params: Record<string, unknown>): unknown {+ const db = getAssetDatabase();+ const typeFilter = params.type as string | undefined;+ const results: Array<{ uuid: string; path: string; type: string }> = [];+ for (const entry of db.getAllEntries()) {+ if (typeFilter && entry.type !== typeFilter) continue;+ results.push({ uuid: entry.uuid, path: entry.path, type: entry.type });+ }+ return results;+ }++ private getAssetInfo_(params: Record<string, unknown>): unknown {+ const db = getAssetDatabase();+ const uuid = params.uuid as string | undefined;+ const path = params.path as string | undefined;+ const entry = uuid ? db.getEntry(uuid) : path ? db.getEntryByPath(path) : undefined;+ if (!entry) throw new Error('Asset not found');+ return {+ uuid: entry.uuid,+ path: entry.path,+ type: entry.type,+ address: entry.address,+ group: entry.group,+ labels: [...entry.labels],+ fileSize: entry.fileSize,+ };+ }++ private listComponents_(): unknown {+ const byCategory = getComponentsByCategory();+ const result: Record<string, string[]> = {};+ for (const [category, schemas] of Object.entries(byCategory)) {+ result[category] = schemas.map((s: { name: string }) => s.name);+ }+ return result;+ }++ private getComponentSchema_(name: string): unknown {+ if (!name) throw new Error('name is required');+ const schema = getComponentSchema(name);+ if (!schema) throw new Error(`Component not found: ${name}`);+ const defaults = getInitialComponentData(name);+ return {+ name: schema.name,+ category: schema.category,+ displayName: schema.displayName ?? schema.name,+ description: schema.description ?? null,+ removable: schema.removable !== false,+ requires: schema.requires ?? [],+ conflicts: schema.conflicts ?? [],+ defaults,+ properties: schema.properties.map(p => ({+ name: p.name,+ type: p.type,+ displayName: p.displayName ?? p.name,+ tooltip: p.tooltip ?? null,+ readOnly: p.readOnly ?? false,+ min: p.min ?? null,+ max: p.max ?? null,+ step: p.step ?? null,+ options: p.options ?? null,+ })),+ };+ }++ private listMenus_(): unknown {+ const menus = getAllMenus();+ return menus.map(menu => ({+ id: menu.id,+ label: menu.label,+ items: getMenuItems(menu.id)+ .filter(i => !i.hidden)+ .map(i => ({+ id: i.id,+ label: i.label,+ shortcut: i.shortcut ?? null,+ separator: i.separator ?? false,+ enabled: i.enabled ? i.enabled() : true,+ })),+ }));+ }++ private getSceneMetadata_(): unknown {+ const store = getEditorStore();+ const scene = store.scene;+ const designWidth = getSettingsValue<number>('project.designWidth') ?? 1080;+ const designHeight = getSettingsValue<number>('project.designHeight') ?? 1920;+ return {+ name: scene.name,+ filePath: store.filePath,+ isDirty: store.isDirty,+ entityCount: scene.entities.length,+ designResolution: { width: designWidth, height: designHeight },+ canUndo: store.canUndo,+ canRedo: store.canRedo,+ undoDescription: store.undoDescription ?? null,+ redoDescription: store.redoDescription ?? null,+ };+ }++ private toggleVisibility_(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.toggleVisibility(id);+ getSharedRenderContext().requestRender();+ return { ok: true };+ }++ // =========================================================================+ // Scene+ // =========================================================================++ private async newScene_(): Promise<unknown> {+ const sceneService = getSceneService();+ await sceneService.newScene();+ getSharedRenderContext().requestRender();+ return { ok: true };+ }++ private async openScene_(path: string): Promise<unknown> {+ if (!path) throw new Error('path is required');+ const sceneService = getSceneService();+ await sceneService.openSceneFromPath(path);+ getSharedRenderContext().requestRender();+ return { ok: true };+ }++ private async instantiatePrefab_(params: Record<string, unknown>): Promise<unknown> {+ const store = getEditorStore();+ const prefabPath = params.path as string;+ if (!prefabPath) throw new Error('path is required');+ const parentRef = params.parent;+ const parent = parentRef == null ? null+ : typeof parentRef === 'string' ? this.resolveEntityByName_(parentRef)+ : parentRef as number;+ const entity = await store.instantiatePrefab(prefabPath, parent);+ if (entity == null) throw new Error('Failed to instantiate prefab');+ getSharedRenderContext().requestRender();+ return { ok: true, entityId: entity };+ }++ private async createScript_(params: Record<string, unknown>): Promise<unknown> {+ const name = params.name as string;+ if (!name) throw new Error('name is required');+ const content = params.content as string | undefined;+ const dir = params.dir as string | undefined;++ const fs = getEditorContext().fs;+ if (!fs) throw new Error('File system not available');+ if (!this.projectPath_) throw new Error('No project path');++ const projectDir = this.projectPath_.replace(/\/[^/]+$/, '');+ const scriptsDir = dir ? `${projectDir}/${dir}` : `${projectDir}/src`;+ const fileName = name.endsWith('.ts') ? name : `${name}.ts`;+ const filePath = `${scriptsDir}/${fileName}`;++ const scriptContent = content ?? [+ `import { defineComponent, defineSystem, PreUpdate, type World, type Entity } from 'esengine';`,+ ``,+ `export const ${name.replace(/\.ts$/, '')} = defineComponent('${name.replace(/\.ts$/, '')}', {`,+ `});`,+ ``,+ ].join('\n');++ await fs.writeFile(filePath, scriptContent);+ return { ok: true, path: filePath };+ }++ // =========================================================================+ // Asset Meta+ // =========================================================================++ private getAssetMeta_(params: Record<string, unknown>): unknown {+ const db = getAssetDatabase();+ const uuid = params.uuid as string | undefined;+ const path = params.path as string | undefined;+ const entry = uuid ? db.getEntry(uuid) : path ? db.getEntryByPath(path) : undefined;+ if (!entry) throw new Error('Asset not found');+ return {+ uuid: entry.uuid,+ path: entry.path,+ type: entry.type,+ labels: [...entry.labels],+ address: entry.address,+ group: entry.group,+ importer: entry.importer,+ platformOverrides: entry.platformOverrides,+ fileSize: entry.fileSize,+ lastModified: entry.lastModified,+ };+ }++ private async updateAssetMeta_(params: Record<string, unknown>): Promise<unknown> {+ const db = getAssetDatabase();+ const uuid = params.uuid as string;+ if (!uuid) throw new Error('uuid is required');+ const entry = db.getEntry(uuid);+ if (!entry) throw new Error(`Asset not found: ${uuid}`);++ const updates: Partial<Pick<AssetEntry, 'labels' | 'address' | 'group' | 'importer' | 'platformOverrides'>> = {};+ if (params.labels !== undefined) updates.labels = new Set(params.labels as string[]);+ if (params.address !== undefined) updates.address = params.address as string | null;+ if (params.group !== undefined) updates.group = params.group as string;+ if (params.importer !== undefined) updates.importer = params.importer as Record<string, unknown>;+ if (params.platformOverrides !== undefined) updates.platformOverrides = params.platformOverrides as Record<string, Record<string, unknown>>;++ await db.updateMeta(uuid, updates);+ return { ok: true };+ }++ private async ensureAssetMeta_(params: Record<string, unknown>): Promise<unknown> {+ const db = getAssetDatabase();+ const path = params.path as string;+ if (!path) throw new Error('path is required');+ const uuid = await db.ensureMeta(path);+ const entry = db.getEntry(uuid);+ return {+ uuid,+ path: entry?.path ?? path,+ type: entry?.type ?? 'unknown',+ created: !params.path || !db.getEntryByPath(path),+ };+ }++ private async createAsset_(params: Record<string, unknown>): Promise<unknown> {+ const fs = getEditorContext().fs;+ if (!fs) throw new Error('File system not available');+ if (!this.projectPath_) throw new Error('No project path');++ const projectDir = this.projectPath_.replace(/\/[^/]+$/, '');+ const assetType = params.type as string;+ const name = params.name as string;+ const dir = params.dir as string | undefined;+ if (!assetType || !name) throw new Error('type and name are required');++ const parentDir = dir ? `${projectDir}/${dir}` : `${projectDir}/assets`;+ let fileName: string;+ let content: string;++ switch (assetType) {+ case 'material':+ fileName = name.endsWith('.esmaterial') ? name : `${name}.esmaterial`;+ content = JSON.stringify({ shader: 'standard', properties: {} }, null, 2);+ break;+ case 'scene':+ fileName = name.endsWith('.esscene') ? name : `${name}.esscene`;+ content = JSON.stringify({+ version: '2.0', name: name.replace(/\.esscene$/, ''),+ entities: [],+ }, null, 2);+ break;+ case 'shader':+ fileName = name.endsWith('.esshader') ? name : `${name}.esshader`;+ content = [+ 'precision mediump float;',+ 'varying vec2 v_uv;',+ 'uniform sampler2D u_texture;',+ '',+ 'void main() {',+ ' gl_FragColor = texture2D(u_texture, v_uv);',+ '}',+ ].join('\n');+ break;+ case 'anim-clip':+ fileName = name.endsWith('.esanim') ? name : `${name}.esanim`;+ content = JSON.stringify({ version: '1.0', frames: [], fps: 12 }, null, 2);+ break;+ case 'timeline':+ fileName = name.endsWith('.estimeline') ? name : `${name}.estimeline`;+ content = JSON.stringify({ version: '1.0', duration: 1, tracks: [] }, null, 2);+ break;+ case 'bitmap-font':+ fileName = name.endsWith('.bmfont') ? name : `${name}.bmfont`;+ content = JSON.stringify({ chars: {}, kernings: {}, common: { lineHeight: 32 } }, null, 2);+ break;+ default:+ throw new Error(`Unknown asset type: ${assetType}. Supported: material, scene, shader, anim-clip, timeline, bitmap-font`);+ }++ const filePath = `${parentDir}/${fileName}`;+ await fs.writeFile(filePath, content);++ const relativePath = filePath.replace(`${projectDir}/`, '');+ const db = getAssetDatabase();+ const uuid = await db.ensureMeta(relativePath);++ return { ok: true, path: filePath, relativePath, uuid };+ }++ private async deleteAsset_(params: Record<string, unknown>): Promise<unknown> {+ const fs = getEditorContext().fs;+ if (!fs) throw new Error('File system not available');+ if (!this.projectPath_) throw new Error('No project path');++ const projectDir = this.projectPath_.replace(/\/[^/]+$/, '');+ const db = getAssetDatabase();++ const uuid = params.uuid as string | undefined;+ const path = params.path as string | undefined;+ const entry = uuid ? db.getEntry(uuid) : path ? db.getEntryByPath(path) : undefined;+ if (!entry) throw new Error('Asset not found');++ const fullPath = `${projectDir}/${entry.path}`;+ const metaPath = `${fullPath}.meta`;++ await fs.removeFile(fullPath);+ try { await fs.removeFile(metaPath); } catch { /* meta may not exist */ }+ db.unregister(entry.path);+ return { ok: true, deleted: entry.path };+ }++ private async renameAsset_(params: Record<string, unknown>): Promise<unknown> {+ const fs = getEditorContext().fs;+ if (!fs) throw new Error('File system not available');+ if (!this.projectPath_) throw new Error('No project path');++ const projectDir = this.projectPath_.replace(/\/[^/]+$/, '');+ const db = getAssetDatabase();++ const uuid = params.uuid as string | undefined;+ const path = params.path as string | undefined;+ const newName = params.newName as string;+ if (!newName) throw new Error('newName is required');++ const entry = uuid ? db.getEntry(uuid) : path ? db.getEntryByPath(path) : undefined;+ if (!entry) throw new Error('Asset not found');++ const oldFullPath = `${projectDir}/${entry.path}`;+ const dirPart = entry.path.replace(/\/[^/]+$/, '');+ const newRelativePath = `${dirPart}/${newName}`;+ const newFullPath = `${projectDir}/${newRelativePath}`;++ await fs.renameFile(oldFullPath, newFullPath);+ const oldMetaPath = `${oldFullPath}.meta`;+ const newMetaPath = `${newFullPath}.meta`;+ if (await fs.exists(oldMetaPath)) {+ await fs.renameFile(oldMetaPath, newMetaPath);+ }++ db.updatePath(entry.path, newRelativePath);+ return { ok: true, oldPath: entry.path, newPath: newRelativePath };+ }+// =========================================================================// Helpers// =========================================================================diff --git a/editor/src/types/NativeFS.ts b/editor/src/types/NativeFS.tsindex 249968701..50bc08ab9 100644--- a/editor/src/types/NativeFS.ts+++ b/editor/src/types/NativeFS.ts@@ -22,6 +22,8 @@ export interface NativeFS {readFile(path: string): Promise<string | null>;readBinaryFile(path: string): Promise<Uint8Array | null>;copyFile(src: string, dest: string): Promise<boolean>;+ removeFile(path: string): Promise<boolean>;+ renameFile(oldPath: string, newPath: string): Promise<boolean>;getFileStats(path: string): Promise<FileStats | null>;openProject(): Promise<string | null>;listDirectory(path: string): Promise<string[]>;diff --git a/tools/mcp-server/src/resources.ts b/tools/mcp-server/src/resources.tsindex 1e6eab7aa..58fcbadbb 100644--- a/tools/mcp-server/src/resources.ts+++ b/tools/mcp-server/src/resources.ts@@ -1,15 +1,29 @@import type { BridgeClient } from './bridge.js';+import { SDK_API_REFERENCE } from './sdk-reference.js';export function registerResources(server: { resource: Function; prompt: Function },bridge: BridgeClient,): void {+ server.resource(+ 'editor://sdk-api',+ 'editor://sdk-api',+ 'ESEngine SDK API reference: defineComponent, defineSystem, Query, Schedule, built-in components, script template',+ async () => ({+ contents: [{+ uri: 'editor://sdk-api',+ text: SDK_API_REFERENCE,+ mimeType: 'text/markdown',+ }],+ }),+ );+server.resource('editor://components','editor://components',- 'All registered component schemas and default values',+ 'All registered component types grouped by category',async () => {- const result = await bridge.get('/state/settings');+ const result = await bridge.get('/components/list');return {contents: [{uri: 'editor://components',@@ -23,9 +37,9 @@ export function registerResources(server.resource('editor://assets','editor://assets',- 'Asset inventory with UUIDs, paths, and types',+ 'All project assets with UUIDs, paths, and types',async () => {- const result = await bridge.get('/scene/tree');+ const result = await bridge.get('/assets/list');return {contents: [{uri: 'editor://assets',@@ -36,6 +50,28 @@ export function registerResources(},);+ server.prompt(+ 'create-game-object',+ 'Guide: create a game entity with components and script',+ [],+ async () => ({+ messages: [{+ role: 'user' as const,+ content: {+ type: 'text' as const,+ text: 'I want to create a new game object. Please:\n' ++ '1. Read editor://sdk-api resource to understand the API\n' ++ '2. Use list_components to see available component types\n' ++ '3. Use create_entity with the appropriate components\n' ++ '4. If custom behavior is needed, use create_script to write a script\n' ++ '5. Use reload_scripts after creating scripts\n' ++ '6. Use set_property to configure component values\n' ++ '7. Use save_scene to persist changes',+ },+ }],+ }),+ );+server.prompt('inspect-ui','Inspect UI: capture screenshot, get selection, entity data, and console logs',diff --git a/tools/mcp-server/src/sdk-reference.ts b/tools/mcp-server/src/sdk-reference.tsnew file mode 100644index 000000000..6b7df21bb--- /dev/null+++ b/tools/mcp-server/src/sdk-reference.ts@@ -0,0 +1,472 @@+export const SDK_API_REFERENCE = `+# ESEngine SDK API Reference++## Imports+\`\`\`typescript+import {+ // Component+ defineComponent, defineTag, getComponent,+ // System+ defineSystem, addSystem, addStartupSystem, addSystemToSchedule, Schedule,+ // Query+ Query, Removed,+ // Resources+ Res, ResMut, defineResource,+ // Commands+ Commands,+ // Events+ defineEvent, EventReader, EventWriter,+ // World access+ GetWorld,+ // Built-in components+ Transform, Sprite, Camera, Name, Parent, Children, Velocity,+ SpriteAnimator, SpineAnimation, Tilemap, TilemapLayer,+ AudioSource, AudioListener, ParticleEmitter, ShapeRenderer,+ PostProcessVolume, TimelinePlayer,+ // Types+ type Entity, type World, type ComponentDef,+} from 'esengine';++import {+ // Physics+ RigidBody, BoxCollider, CircleCollider, CapsuleCollider,+ PolygonCollider, ChainCollider, SegmentCollider,+ RevoluteJoint, DistanceJoint, PrismaticJoint, WeldJoint, WheelJoint,+ Physics,+} from 'esengine/physics';++import {+ // UI+ UIRect, Canvas, Image, Text, BitmapText, Button, Toggle, ToggleGroup,+ Slider, ProgressBar, ScrollView, Dropdown, TextInput, ListView,+ Interactable, Focusable, UIMask, FlexContainer, FlexItem,+ LayoutGroup, SafeArea, Draggable, DragState, UIRenderer,+} from 'esengine';+\`\`\`++## defineComponent+Define a custom component with default values. The editor auto-registers it.+\`\`\`typescript+export const Health = defineComponent('Health', {+ current: 100,+ max: 100,+ invincible: false,+});++// With nested objects+export const Movement = defineComponent('Movement', {+ speed: 5,+ direction: { x: 0, y: 0 },+ grounded: false,+});+\`\`\`++## defineTag+Define a tag component (no data, just marks entities).+\`\`\`typescript+export const Enemy = defineTag('Enemy');+export const Player = defineTag('Player');+\`\`\`++## defineSystem+Define a system with typed parameters. Parameters are injected automatically.+\`\`\`typescript+// Query entities with Transform and Velocity+const movementSystem = defineSystem(+ [Query(Transform, Velocity)],+ (query) => {+ for (const [transform, velocity] of query) {+ transform.position.x += velocity.linear.x;+ transform.position.y += velocity.linear.y;+ }+ },+);++// Access resources+const scoreSystem = defineSystem(+ [Query(Player), Res(ScoreResource)],+ (players, score) => {+ // score is read-only+ },+);++// Mutable resource access+const timerSystem = defineSystem(+ [ResMut(GameTimer)],+ (timer) => {+ timer.elapsed += timer.deltaTime;+ },+);++// Spawn/despawn entities+const spawnerSystem = defineSystem(+ [Commands(), Query(Spawner)],+ (commands, spawners) => {+ for (const [spawner] of spawners) {+ if (spawner.shouldSpawn) {+ const e = commands.spawn();+ commands.insert(e, Transform, { position: { x: 0, y: 0, z: 0 }, rotation: { x: 0, y: 0, z: 0, w: 1 }, scale: { x: 1, y: 1, z: 1 } });+ commands.insert(e, Sprite, { size: { x: 32, y: 32 } });+ }+ }+ },+);++// Events+const damageSystem = defineSystem(+ [EventReader(DamageEvent), Query(Health)],+ (events, healths) => {+ for (const event of events) {+ // handle damage+ }+ },+);++// Direct world access+const worldSystem = defineSystem(+ [GetWorld()],+ (world) => {+ const entity = world.spawn();+ world.insert(entity, Transform, { ... });+ if (world.valid(entity)) {+ const t = world.tryGet(entity, Transform);+ }+ world.despawn(entity);+ },+);++// Removed query (entities that just had a component removed)+const cleanupSystem = defineSystem(+ [Removed(Health)],+ (removed) => {+ for (const entity of removed) {+ console.log('Entity lost Health:', entity);+ }+ },+);+\`\`\`++## Schedule (execution order)+\`\`\`+Startup — runs once at app start+First — runs every frame, before everything+FixedPreUpdate — fixed timestep, before physics+FixedUpdate — fixed timestep, physics step+FixedPostUpdate— fixed timestep, after physics+PreUpdate — before main update+Update — main game logic (default)+PostUpdate — after main update (cleanup, camera follow)+Last — end of frame+\`\`\`++### Registering systems+\`\`\`typescript+addSystem(movementSystem); // Update schedule (default)+addStartupSystem(initSystem); // Startup (runs once)+addSystemToSchedule(Schedule.PostUpdate, cameraSystem); // Specific schedule+addSystemToSchedule(Schedule.FixedUpdate, physicsStep); // Fixed timestep+\`\`\`++## defineResource+\`\`\`typescript+export const GameState = defineResource('GameState', {+ score: 0,+ level: 1,+ paused: false,+});+\`\`\`++## defineEvent+\`\`\`typescript+export const DamageEvent = defineEvent<{ target: Entity; amount: number }>('DamageEvent');++// Write events+const attackSystem = defineSystem(+ [EventWriter(DamageEvent)],+ (writer) => {+ writer.send({ target: someEntity, amount: 10 });+ },+);+\`\`\`++## Query Filters+\`\`\`typescript+// With: entities that have both Transform AND Sprite+Query(Transform, Sprite)++// Optional component (may be undefined)+Query(Transform).optionally(Velocity)++// Without: exclude entities that have Enemy tag+Query(Transform).without(Enemy)++// Iteration+for (const [transform, sprite] of query) { ... }++// Get specific entity's components+const result = query.get(entity); // returns tuple or undefined+\`\`\`++## Built-in Component Defaults++### Transform+\`\`\`typescript+{+ position: { x: 0, y: 0, z: 0 },+ rotation: { x: 0, y: 0, z: 0, w: 1 }, // quaternion+ scale: { x: 1, y: 1, z: 1 },+}+\`\`\`++### Sprite+\`\`\`typescript+{+ texture: "", // asset UUID or relative path (empty = no texture)+ size: { x: 100, y: 100 },+ pivot: { x: 0.5, y: 0.5 },+ color: { r: 1, g: 1, b: 1, a: 1 },+ flipX: false,+ flipY: false,+ layer: 0,+ enabled: true,+}+\`\`\`++### Camera+\`\`\`typescript+{+ size: 5, // orthographic half-height+ near: -1000,+ far: 1000,+ clearColor: { r: 0.2, g: 0.2, b: 0.2, a: 1 },+ enabled: true,+}+\`\`\`++### RigidBody+\`\`\`typescript+{+ bodyType: 0, // 0=Dynamic, 1=Kinematic, 2=Static+ gravityScale: 1,+ linearDamping: 0,+ angularDamping: 0,+ fixedRotation: false,+ bullet: false,+ enabled: true,+}+\`\`\`++### UIRect+\`\`\`typescript+{+ anchorMin: { x: 0.5, y: 0.5 },+ anchorMax: { x: 0.5, y: 0.5 },+ offsetMin: { x: -50, y: -50 },+ offsetMax: { x: 50, y: 50 },+ pivot: { x: 0.5, y: 0.5 },+}+\`\`\`++## Script File Template+A typical user script file:+\`\`\`typescript+import {+ defineComponent, defineSystem, defineTag,+ Query, Commands, Res, addSystem, addSystemToSchedule, Schedule,+ Transform, Sprite,+ type Entity, type World,+} from 'esengine';++// 1. Define components+export const PlayerData = defineComponent('PlayerData', {+ speed: 200,+ jumpForce: 400,+ health: 100,+});++export const IsPlayer = defineTag('IsPlayer');++// 2. Define systems+const playerMovement = defineSystem(+ [Query(Transform, PlayerData)],+ (query) => {+ for (const [transform, player] of query) {+ // movement logic+ }+ },+ { name: 'PlayerMovement' },+);++// 3. Register systems+addSystem(playerMovement);+\`\`\`++## Property Value Types+When using \`set_property\`, values must match these formats:+\`\`\`+number → 42 or 3.14+string → "hello"+boolean → true / false+vec2 → { x: number, y: number }+vec3 → { x: number, y: number, z: number }+vec4 → { x: number, y: number, z: number, w: number }+color → { r: 0-1, g: 0-1, b: 0-1, a: 0-1 }+padding → { left: number, top: number, right: number, bottom: number }+vec2-array→ [{ x, y }, { x, y }, ...]+\`\`\`++## Asset Referencing+In the editor and scene files, asset fields (texture, clip, font, material, etc.) store **UUID strings** (preferred) or **relative paths**.+- **UUIDs** (stable, preferred): \`"a1b2c3d4-e5f6-7890-abcd-ef1234567890"\`+- **Relative paths** (fallback): \`"assets/textures/player.png"\`+- Use \`list_assets\` to find assets and get their UUIDs+- When setting asset fields via \`set_property\`, pass the UUID or relative path as a string+- To clear an asset field, set it to \`""\` (empty string)+- At runtime (C++/WASM), these are resolved to numeric handles internally — you don't need to deal with handles++## UI Components++### Canvas+Root container for UI elements. All UI entities must be children of a Canvas entity.+\`\`\`typescript+{ renderMode: 0, designResolution: { x: 1080, y: 1920 }, matchMode: 0 }+\`\`\`++### UIRect+Anchored rectangle layout (required on all UI elements under Canvas).+\`\`\`typescript+{+ anchorMin: { x: 0.5, y: 0.5 }, // 0-1, relative to parent+ anchorMax: { x: 0.5, y: 0.5 },+ offsetMin: { x: -50, y: -50 }, // pixels from anchor+ offsetMax: { x: 50, y: 50 },+ pivot: { x: 0.5, y: 0.5 },+}+\`\`\`++### Image+\`\`\`typescript+{ source: "", color: { r: 1, g: 1, b: 1, a: 1 }, type: 0, enabled: true }+// source: asset UUID or relative path (empty = no image)+// type: 0=Simple, 1=Sliced, 2=Tiled, 3=Filled+\`\`\`++### Text+\`\`\`typescript+{+ content: "Hello",+ fontSize: 24,+ color: { r: 1, g: 1, b: 1, a: 1 },+ align: 0, // 0=Left, 1=Center, 2=Right+ verticalAlign: 0, // 0=Top, 1=Middle, 2=Bottom+ lineSpacing: 0,+ overflow: 0, // 0=Overflow, 1=Truncate, 2=Wrap+}+\`\`\`++### Button+Requires: Interactable + Image on same entity. Use a child Text entity for the label.+\`\`\`typescript+{ normalColor: { r: 1, g: 1, b: 1, a: 1 }, pressedColor: ..., disabledColor: ... }+\`\`\`++### Toggle+\`\`\`typescript+{ isOn: false, toggleGroup: null }+\`\`\`++### Slider+\`\`\`typescript+{ value: 0, minValue: 0, maxValue: 1, wholeNumbers: false, direction: 0 }+\`\`\`++### ScrollView+\`\`\`typescript+{ horizontal: true, vertical: true, movementType: 0, elasticity: 0.1, inertia: true }+\`\`\`++### Interactable+Required for any interactive UI element (Button, Toggle, Slider, etc.).+\`\`\`typescript+{ interactable: true }+\`\`\`++## Query Advanced Patterns+\`\`\`typescript+// Optional component (may be undefined in tuple)+const q = Query(Transform).optionally(Velocity);+for (const [transform, velocity] of q) {+ if (velocity) { /* has velocity */ }+}++// Without filter (exclude entities)+Query(Transform, Sprite).without(Disabled)++// Combining+Query(Transform).with(Sprite).without(Enemy).optionally(Health)++// Removed query (entities that just lost a component this frame)+const cleanup = defineSystem(+ [Removed(Health)],+ (removed) => { for (const entity of removed) { ... } },+);+\`\`\`++## Draw API (Immediate Mode Drawing)+\`\`\`typescript+import { Draw } from 'esengine';++const debugDrawSystem = defineSystem(+ [Query(Transform)],+ (query) => {+ for (const [transform] of query) {+ Draw.circle(transform.position, 10, { r: 0, g: 1, b: 0, a: 0.5 });+ Draw.rect(transform.position, { x: 20, y: 20 }, { r: 1, g: 0, b: 0, a: 0.3 });+ Draw.line({ x: 0, y: 0 }, transform.position, { r: 1, g: 1, b: 1, a: 1 });+ }+ },+);+addSystemToSchedule(Schedule.PostUpdate, debugDrawSystem);+\`\`\`++## Audio+\`\`\`typescript+import { Audio } from 'esengine';++Audio.play('assets/audio/click.wav');+Audio.playMusic('assets/audio/bgm.mp3', { loop: true, volume: 0.5 });+Audio.stopAll();+Audio.setMasterVolume(0.8);+\`\`\`++## Common Entity Patterns++### Sprite Entity+\`\`\`+create_entity: { name, components: [+ { type: "Transform", data: { position: { x, y, z: 0 } } },+ { type: "Sprite", data: { texture: "<uuid-or-path>", size: { x, y } } }+]}+// Use list_assets to find the asset UUID, then pass it as the texture value+\`\`\`++### UI Button+\`\`\`+1. Create Canvas entity (if not exists): Canvas + UIRect + Transform+2. Create Button entity as child:+ - Transform + UIRect + Image + Interactable + Button+3. Create Label as child of Button:+ - Transform + UIRect + Text (content: "Click Me")+\`\`\`++### Physics Entity+\`\`\`+create_entity: { name, components: [+ { type: "Transform" },+ { type: "Sprite" },+ { type: "RigidBody", data: { bodyType: 0 } }, // 0=Dynamic+ { type: "BoxCollider", data: { size: { x: 1, y: 1 } } }+]}+\`\`\`+\`\`\`+`;diff --git a/tools/mcp-server/src/tools/actions.ts b/tools/mcp-server/src/tools/actions.tsindex 14cdfd592..540c21ab4 100644--- a/tools/mcp-server/src/tools/actions.ts+++ b/tools/mcp-server/src/tools/actions.ts@@ -73,4 +73,38 @@ export function registerActionTools(return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };},);++ server.tool(+ 'undo',+ 'Undo the last editor action',+ {},+ async () => {+ const result = await bridge.post('/action/undo', {});+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };+ },+ );++ server.tool(+ 'redo',+ 'Redo the last undone editor action',+ {},+ async () => {+ const result = await bridge.post('/action/redo', {});+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };+ },+ );++ server.tool(+ 'create_script',+ 'Create a new TypeScript script file in the project. Read editor://sdk-api resource first to understand the API.',+ {+ name: z.string().describe('Script name (e.g., "PlayerController")'),+ content: z.string().optional().describe('Script content (default: component template)'),+ dir: z.string().optional().describe('Directory relative to project root (default: "src")'),+ },+ async (args: { name: string; content?: string; dir?: string }) => {+ const result = await bridge.post('/scripts/create', args);+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };+ },+ );}diff --git a/tools/mcp-server/src/tools/scene.ts b/tools/mcp-server/src/tools/scene.tsindex 26e823622..15d4d6196 100644--- a/tools/mcp-server/src/tools/scene.ts+++ b/tools/mcp-server/src/tools/scene.ts@@ -144,4 +144,65 @@ export function registerSceneTools(return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };},);++ server.tool(+ 'duplicate_entity',+ 'Duplicate an entity with all its components',+ {+ entity: z.union([z.number(), z.string()]).describe('Entity ID or name to duplicate'),+ },+ async (args: { entity: number | string }) => {+ const body = typeof args.entity === 'number' ? { id: args.entity } : { name: args.entity };+ const result = await bridge.post('/scene/duplicate-entity', body);+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };+ },+ );++ server.tool(+ 'instantiate_prefab',+ 'Instantiate a prefab into the scene',+ {+ path: z.string().describe('Prefab asset path (relative or UUID)'),+ parent: z.union([z.number(), z.string()]).optional().describe('Parent entity ID or name'),+ },+ async (args: { path: string; parent?: number | string }) => {+ const result = await bridge.post('/scene/instantiate-prefab', args);+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };+ },+ );++ server.tool(+ 'new_scene',+ 'Create a new empty scene (discards current scene)',+ {},+ async () => {+ const result = await bridge.post('/scene/new', {});+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };+ },+ );++ server.tool(+ 'open_scene',+ 'Open a scene file by path',+ {+ path: z.string().describe('Scene file path (e.g., "assets/scenes/main.esscene")'),+ },+ async (args: { path: string }) => {+ const result = await bridge.post('/scene/open', { path: args.path });+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };+ },+ );++ server.tool(+ 'toggle_entity_visibility',+ 'Toggle an entity\'s visibility in the editor',+ {+ 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/toggle-visibility', body);+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };+ },+ );}diff --git a/tools/mcp-server/src/tools/state.ts b/tools/mcp-server/src/tools/state.tsindex b926c91d1..56f4709d0 100644--- a/tools/mcp-server/src/tools/state.ts+++ b/tools/mcp-server/src/tools/state.ts@@ -64,4 +64,157 @@ export function registerStateTools(return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };},);++ server.tool(+ 'list_assets',+ 'List all assets in the project, optionally filtered by type',+ {+ type: z.string().optional().describe('Filter by asset type (e.g., "texture", "scene", "script", "audio")'),+ },+ async (args: { type?: string }) => {+ const query = args.type ? `?type=${encodeURIComponent(args.type)}` : '';+ const result = await bridge.get(`/assets/list${query}`);+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };+ },+ );++ server.tool(+ 'get_asset_info',+ 'Get detailed information about a specific asset by UUID or path',+ {+ uuid: z.string().optional().describe('Asset UUID'),+ path: z.string().optional().describe('Asset relative path'),+ },+ async (args: { uuid?: string; path?: string }) => {+ const params = args.uuid ? `uuid=${args.uuid}` : `path=${encodeURIComponent(args.path!)}`;+ const result = await bridge.get(`/assets/info?${params}`);+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };+ },+ );++ server.tool(+ 'get_asset_meta',+ 'Get full asset meta: UUID, importer settings, labels, address, group, platform overrides',+ {+ uuid: z.string().optional().describe('Asset UUID'),+ path: z.string().optional().describe('Asset relative path'),+ },+ async (args: { uuid?: string; path?: string }) => {+ const params = args.uuid ? `uuid=${args.uuid}` : `path=${encodeURIComponent(args.path!)}`;+ const result = await bridge.get(`/assets/meta?${params}`);+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };+ },+ );++ server.tool(+ 'update_asset_meta',+ 'Update asset meta: labels, address, group, importer settings, platform overrides',+ {+ uuid: z.string().describe('Asset UUID'),+ labels: z.array(z.string()).optional().describe('Asset labels'),+ address: z.string().nullable().optional().describe('Addressable name (unique) or null to clear'),+ group: z.string().optional().describe('Asset group name'),+ importer: z.record(z.unknown()).optional().describe('Importer settings (type-specific)'),+ platformOverrides: z.record(z.record(z.unknown())).optional().describe('Platform-specific importer overrides'),+ },+ async (args: { uuid: string; labels?: string[]; address?: string | null; group?: string; importer?: Record<string, unknown>; platformOverrides?: Record<string, Record<string, unknown>> }) => {+ const result = await bridge.post('/assets/meta/update', args);+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };+ },+ );++ server.tool(+ 'ensure_asset_meta',+ 'Generate .meta file for an asset if it does not exist, returns the UUID',+ {+ path: z.string().describe('Asset relative path (e.g., "assets/textures/player.png")'),+ },+ async (args: { path: string }) => {+ const result = await bridge.post('/assets/meta/ensure', args);+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };+ },+ );++ server.tool(+ 'create_asset',+ 'Create a new asset file with default content and auto-generate .meta',+ {+ type: z.enum(['material', 'scene', 'shader', 'anim-clip', 'timeline', 'bitmap-font']).describe('Asset type'),+ name: z.string().describe('Asset file name (extension auto-added if missing)'),+ dir: z.string().optional().describe('Directory relative to project root (default: "assets")'),+ },+ async (args: { type: string; name: string; dir?: string }) => {+ const result = await bridge.post('/assets/create', args);+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };+ },+ );++ server.tool(+ 'delete_asset',+ 'Delete an asset file and its .meta file',+ {+ uuid: z.string().optional().describe('Asset UUID'),+ path: z.string().optional().describe('Asset relative path'),+ },+ async (args: { uuid?: string; path?: string }) => {+ const result = await bridge.post('/assets/delete', args);+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };+ },+ );++ server.tool(+ 'rename_asset',+ 'Rename an asset file and update its .meta file',+ {+ uuid: z.string().optional().describe('Asset UUID'),+ path: z.string().optional().describe('Asset relative path'),+ newName: z.string().describe('New file name (e.g., "player_idle.png")'),+ },+ async (args: { uuid?: string; path?: string; newName: string }) => {+ const result = await bridge.post('/assets/rename', args);+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };+ },+ );++ server.tool(+ 'list_components',+ 'List all available component types grouped by category (builtin, ui, physics, script, tag)',+ {},+ async () => {+ const result = await bridge.get('/components/list');+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };+ },+ );++ server.tool(+ 'get_component_schema',+ 'Get detailed schema for a component: fields, types, defaults, ranges, and constraints',+ {+ name: z.string().describe('Component type name (e.g., "Transform", "Sprite", "RigidBody")'),+ },+ async (args: { name: string }) => {+ const result = await bridge.get(`/components/schema?name=${encodeURIComponent(args.name)}`);+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };+ },+ );++ server.tool(+ 'list_menus',+ 'List all editor menu items with IDs, labels, shortcuts, and enabled state',+ {},+ async () => {+ const result = await bridge.get('/menus/list');+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };+ },+ );++ server.tool(+ 'get_scene_metadata',+ 'Get current scene info: name, file path, dirty state, design resolution, undo/redo status',+ {},+ async () => {+ const result = await bridge.get('/scene/metadata');+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };+ },+ );}