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(mcp): name a scene, address one member, hand over a program too big to say
yhh7dcc2cb7cd2d
diff --git a/desktop/scripts/editor-mcp-tools.mjs b/desktop/scripts/editor-mcp-tools.mjsindex 223d75141..2721f5fd7 100644--- a/desktop/scripts/editor-mcp-tools.mjs+++ b/desktop/scripts/editor-mcp-tools.mjs@@ -82,7 +82,9 @@ export const TOOLS = [schema: obj({ id: { type: 'number' }, name: { type: 'string' } }, ['id', 'name']),method: 'renameEntity', args: (i) => [i.id, i.name] },{ name: 'set_field', write: true,- description: 'Set a component field (undoable). The field\'s DECLARED inspector type wins (see get_inspector: number, bool, string, vec2, vec3, angle, color, enum, select, flags, gradient, curve, dimension, asset) — `type` is advisory. Vecs take [x, y(, z)] number arrays, colors "#rrggbbaa" hex or {r,g,b,a} 0..1, assets a project-relative path or @uuid ref. Unknown components/fields and malformed values are errors, never silent writes.',+ description: 'Set a component field (undoable). The field\'s DECLARED inspector type wins (see get_inspector: number, bool, string, vec2, vec3, angle, color, enum, select, flags, gradient, curve, dimension, asset) — `type` is advisory. Vecs take [x, y(, z)] number arrays, colors "#rrggbbaa" hex or {r,g,b,a} 0..1, assets a project-relative path or @uuid ref. '+ + '`key` may name one MEMBER of a structural field — "position.x" / "position.z" (vec2/vec3), "gap.y", "padding.left" (sides), "width.value" / "width.unit" (dimension) — which reads and writes back the rest, so one number does not cost a read-modify-write. '+ + 'Unknown components/fields and malformed values are errors, never silent writes.',schema: obj({entity: { type: 'number' }, component: { type: 'string' }, key: { type: 'string' },type: { type: 'string' },@@ -181,9 +183,10 @@ export const TOOLS = [description: 'Save the open scene to disk (the toolbar Save).',schema: obj({}), method: 'save', args: () => [], root: 'editor' },{ name: 'create_scene_file', write: true,- description: 'Create a blank scene FILE under a project-relative directory (does not switch to it); returns its path, immediately referenceable (the registry refresh happens before this resolves).',- schema: obj({ destDir: { type: 'string' } }, ['destDir']),- js: (i) => `window.__estellaEditor.createSceneFile(${JSON.stringify(i.destDir)})+ description: 'Create a blank scene FILE under a project-relative directory (does not switch to it); returns its path, immediately referenceable (the registry refresh happens before this resolves). '+ + '`name` names it (the `.esscene` extension is added if absent); without one it is `scene.esscene`, which collides the moment you make a second.',+ schema: obj({ destDir: { type: 'string' }, name: { type: 'string' } }, ['destDir']),+ js: (i) => `window.__estellaEditor.createSceneFile(${JSON.stringify(i.destDir)}, ${JSON.stringify(i.name ?? null)}).then((p) => window.__estellaEditor.refreshAssets().then(() => p))` },{ name: 'create_asset', write: true,description: 'Create a text asset file under a project-relative directory with the given content. `type` is the meta vocabulary: scene, prefab, shader, material, animclip (.esanim), animation (.estimeline), tileset, statemachine (.esfsm), behaviortree (.esbt), locale, inputmap, tilemap (.tmj). A bare baseName gets the type\'s canonical extension appended. Returns the project-relative path, immediately referenceable (the registry refresh happens before this resolves).',@@ -206,12 +209,20 @@ export const TOOLS = [+ 'or give `components` as ["Transform","UINode","UIVisual"] / [{type,data}]; '+ '{op:"set", entity, fields}; {op:"add_component"|"remove_component", entity, component}; {op:"rename", entity, name}; {op:"parent", entity, parent}; {op:"delete", entity}. '+ 'ENTITY ADDRESSING: an entity is a live numeric id, or "$name" naming an earlier create\'s `ref` — so a parent/child tree is one call with no round trip to learn ids. '- + 'FIELDS is a flat map of "Component.key" → value, e.g. {"Transform.position.x": 10, "UIVisual.color": "#ff0000ff", "Text.content": "Hi"} — same coercion and validation as set_field. '- + 'Returns { refs: {name: id}, created: [id], applied: n }. Check get_diagnostics afterwards.',+ + 'FIELDS is a flat map of "Component.key" → value, e.g. {"Transform.position.x": 10, "UIVisual.color": "#ff0000ff", "Text.content": "Hi"} — same coercion and validation as set_field, '+ + 'including one member of a structural field ("FlexContainer.gap.x", "UINode.marginLeft"). '+ + 'Give either `ops` inline or `opsPath` (a JSON file), never both. Returns { refs: {name: id}, created: [id], applied: n }. Check get_diagnostics afterwards.',schema: obj({ops: { type: 'array', description: 'the op program, executed in order as one undo step' },+ opsPath: { type: 'string', description: 'project-relative path to a JSON file holding the op array, INSTEAD of `ops` — a panel of a few hundred entities is a few hundred KB of program, which does not belong in a message. Write it with write_project_file, then name it here.' },label: { type: 'string', description: 'undo-stack label (default "Apply scene ops")' },- }, ['ops']),+ }),+ // Only the file form needs the escape hatch; an inline program goes through+ // the typed door like everything else.+ js: (i) => (i.opsPath+ ? `window.estella.fs.read(${JSON.stringify(i.opsPath)})+ .then((text) => window.__estellaEditor.applyOps(JSON.parse(text), ${JSON.stringify(i.label ?? null)}))`+ : null),method: 'applyOps', args: (i) => [i.ops, i.label], root: 'editor' },{ name: 'list_assets',description: 'Search the open project\'s asset registry. `match` is a case-insensitive SUBSTRING of the project-relative path (not a glob); `type` filters by asset type (texture, scene, prefab, audio, font, material, shader...). '@@ -357,8 +368,12 @@ export async function runTool(tool, driver, rawInput, allowWrites = true) {if (tool.image) return { content: [{ type: 'image', data, mimeType: 'image/png' }] };return { content: [{ type: 'text', text: data === undefined ? 'ok' : JSON.stringify(data) }] };}- if (tool.js) {- const data = await driver.js(tool.js(input));+ // A js template may DECLINE (return null) for inputs it has nothing special+ // to do with, leaving the tool's typed `method` door to handle them — which+ // is how a tool grows one alternate path without every call losing the door.+ const js = tool.js ? tool.js(input) : null;+ if (js) {+ const data = await driver.js(js);if (tool.image) return { content: [{ type: 'image', data, mimeType: 'image/png' }] };return { content: [{ type: 'text', text: data === undefined ? 'ok' : JSON.stringify(data) }] };}diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.tsindex 2da334fa3..beffa7934 100644--- a/desktop/src/engine/EditorControlSurface.ts+++ b/desktop/src/engine/EditorControlSurface.ts@@ -71,6 +71,63 @@ export function setAssetRefProblemResolver(fn: AssetRefProblemResolver | null):* the `{x, y}` object spelling get_inspector-style reads suggest. Anything that* doesn't coerce cleanly throws — the automation door must never write garbage.*/+/**+ * The members a structural field can be addressed by, and where each one sits+ * in the value the inspector holds.+ *+ * Automation writes field PATHS ("Transform.position.x"), which read as CSS-ish+ * and are what an agent reaches for first — the MCP tool even documented that+ * exact example while rejecting it, because the inspector's field is `position`,+ * a whole vec3. Rather than make callers read back a vector, patch a component+ * and send the vector, a member path resolves to the field plus an index into it.+ */+const FIELD_MEMBERS: Partial<Record<InspectorFieldType, Record<string, number | string>>> = {+ vec2: { x: 0, y: 1 },+ vec3: { x: 0, y: 1, z: 2 },+ sides: { left: 0, top: 1, right: 2, bottom: 3 },+ dimension: { value: 'value', unit: 'unit' },+};++/** Split "position.x" into the field key and the member, when the field has one. */+export function splitFieldMember(+ key: string,+ fieldTypeOf: (k: string) => InspectorFieldType | undefined,+): { key: string; member: string; type: InspectorFieldType } | null {+ const dot = key.lastIndexOf('.');+ if (dot <= 0) return null;+ const base = key.slice(0, dot);+ const member = key.slice(dot + 1);+ const type = fieldTypeOf(base);+ if (!type) return null;+ return FIELD_MEMBERS[type]?.[member] !== undefined ? { key: base, member, type } : null;+}++/** Write `value` into `member` of a structural field's current value. */+export function patchFieldMember(+ type: InspectorFieldType,+ current: InspectorFieldValue,+ member: string,+ value: unknown,+): InspectorFieldValue {+ const at = FIELD_MEMBERS[type]?.[member];+ if (at === undefined) throw new Error(`"${type}" has no member "${member}"`);+ const n = typeof value === 'string' ? Number(value) : value;+ if (typeof n !== 'number' || !Number.isFinite(n)) {+ throw new Error(`member "${member}" expects a number, got ${JSON.stringify(value)}`);+ }+ if (typeof at === 'number') {+ const arr = Array.isArray(current) ? [...(current as number[])] : [];+ while (arr.length <= at) arr.push(0);+ arr[at] = n;+ return arr as InspectorFieldValue;+ }+ const obj = current !== null && typeof current === 'object' && !Array.isArray(current)+ ? { ...(current as Record<string, unknown>) }+ : {};+ obj[at] = n;+ return obj as InspectorFieldValue;+}+export function coerceFieldValue(declared: InspectorFieldType,key: string,@@ -302,6 +359,16 @@ export class EditorControlSurfaceImpl {const declared: InspectorFieldType | undefined =field?.type ?? (comp.enable?.key === key ? 'bool' : undefined);if (!declared) {+ // "position.x" / "gap.y" / "padding.left": one member of a structural field.+ const nested = splitFieldMember(key, (k) => comp.fields.find((f) => f.key === k)?.type);+ if (nested) {+ const whole = comp.fields.find((f) => f.key === nested.key)!;+ this.s.commands.setField(+ entity, component, nested.key, nested.type,+ patchFieldMember(nested.type, whole.value, nested.member, value),+ );+ return;+ }const keys = [...comp.fields.map((f) => f.key), ...(comp.enable ? [comp.enable.key] : [])];throw new Error(`"${component}" has no field "${key}" (fields: ${keys.join(', ')})`);}diff --git a/desktop/src/main.tsx b/desktop/src/main.tsxindex 430c7c7e1..d9831b305 100644--- a/desktop/src/main.tsx+++ b/desktop/src/main.tsx@@ -148,7 +148,8 @@ if (new URLSearchParams(location.search).has('automation')) {/** Patch the project's physics feature (Project Settings → Physics). */setPhysics: (patch: Record<string, unknown>) => ProjectStore.setPhysics(patch),/** Create a blank scene FILE under `destDir` (Content Browser "New Scene"). */- createSceneFile: (destDir: string) => ProjectStore.createSceneFile(destDir),+ createSceneFile: (destDir: string, name?: string | null) =>+ ProjectStore.createSceneFile(destDir, name ?? undefined),/** The Create-popover catalog: every ready-made entity the editor can spawn. */listEntityTemplates: () => entitySources().map(({ id, label, category }) => ({ id, label, category })),/** Create a TilemapLayer from an .estileset with an optional grid layoutdiff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.tsindex 285b8a38d..023735443 100644--- a/desktop/src/project/ProjectStore.ts+++ b/desktop/src/project/ProjectStore.ts@@ -590,9 +590,14 @@ class ProjectStoreImpl {* Browser's "New Scene" — writes it to disk WITHOUT switching the editor to it* (unlike {@link newScene}). Returns its project-relative path.*/- async createSceneFile(destDir: string): Promise<string> {+ async createSceneFile(destDir: string, name?: string): Promise<string> {const content = JSON.stringify(this.blankScene(), null, 2) + '\n';- return window.estella.project.createAsset(destDir, 'scene.esscene', content, 'scene');+ // A bare name takes the extension, so a caller naming scenes in bulk does not+ // have to know it. Nameless keeps the Content Browser's "New Scene" default.+ const base = name?.trim()+ ? (name.trim().endsWith('.esscene') ? name.trim() : `${name.trim()}.esscene`)+ : 'scene.esscene';+ return window.estella.project.createAsset(destDir, base, content, 'scene');}/** Create a blank `.inputmap` asset (named input actions) under `destDir`. */diff --git a/desktop/tests/editor-control-surface.test.ts b/desktop/tests/editor-control-surface.test.tsindex 916d92e15..0b9f5f842 100644--- a/desktop/tests/editor-control-surface.test.ts+++ b/desktop/tests/editor-control-surface.test.ts@@ -130,10 +130,22 @@ describe.skipIf(!HAS_WASM)('EditorControlSurface (headless World)', () => {const id = S.surface.addEntity()!;S.surface.addComponent(id, 'Sprite');expect(() => S.surface.setField(id, 'Rigidbody2D', 'mass', 'number', 1)).toThrow(/not on entity/);- expect(() => S.surface.setField(id, 'Sprite', 'size.x', 'number', 16)).toThrow(/no field/);+ expect(() => S.surface.setField(id, 'Sprite', 'sizes', 'number', 16)).toThrow(/no field/);+ expect(() => S.surface.setField(id, 'Sprite', 'size.w', 'number', 16)).toThrow(/no field/);expect(() => S.surface.setField(id, 'Sprite', 'size', 'vec2', 'garbage')).toThrow(/expects/);});+ it('setField writes ONE member of a structural field, leaving the rest', () => {+ const id = S.surface.addEntity()!;+ S.surface.addComponent(id, 'Sprite');+ const e = S.model.runtimeFor(id)!;+ const before = { ...host.world.get(e, Sprite).size };++ S.surface.setField(id, 'Sprite', 'size.x', 'number', 16);+ expect(host.world.get(e, Sprite).size.x).toBe(16);+ expect(host.world.get(e, Sprite).size.y).toBe(before.y);+ });+it('getDiagnostics flags a required-empty field (Details parity) and clears when set', () => {const id = S.surface.addEntity()!;S.surface.addComponent(id, 'Sprite'); // Sprite.texture is required, defaults emptydiff --git a/desktop/tests/editor-mcp-tools.test.ts b/desktop/tests/editor-mcp-tools.test.tsindex 628e5c2d7..ade149628 100644--- a/desktop/tests/editor-mcp-tools.test.ts+++ b/desktop/tests/editor-mcp-tools.test.ts@@ -168,3 +168,29 @@ describe('editor MCP tool registry', () => {}});});++describe('apply_scene_ops program sources', () => {+ const apply = () => TOOLS.find((t) => t.name === 'apply_scene_ops');++ it('reads the program from a file when one is named, so a big panel need not fit in a message', async () => {+ const js = vi.fn().mockResolvedValue({ refs: {}, created: [], applied: 3 });+ const driver = Object.assign(vi.fn(), { js });+ await runTool(apply(), driver, { opsPath: 'assets/scenes/panel.ops.json', label: 'Panel' });++ expect(driver).not.toHaveBeenCalled(); // not the inline door+ const src = js.mock.calls[0][0];+ expect(src).toContain('assets/scenes/panel.ops.json');+ expect(src).toContain('JSON.parse');+ expect(src).toContain('applyOps');+ });++ it('still takes the typed door for an inline program', async () => {+ const js = vi.fn();+ const driver = Object.assign(vi.fn().mockResolvedValue({ refs: {}, created: [], applied: 1 }), { js });+ const ops = [{ op: 'create', ref: 'a' }];+ await runTool(apply(), driver, { ops, label: 'Inline' });++ expect(js).not.toHaveBeenCalled();+ expect(driver).toHaveBeenCalledWith('applyOps', [ops, 'Inline'], 'editor');+ });+});diff --git a/desktop/tests/inspector-write-values.test.ts b/desktop/tests/inspector-write-values.test.tsindex 140fbb679..935644818 100644--- a/desktop/tests/inspector-write-values.test.ts+++ b/desktop/tests/inspector-write-values.test.ts@@ -12,7 +12,7 @@// produced a PARTIAL value that nothing downstream could read.import { describe, it, expect } from 'vitest';import { toModelValue } from '@/engine/SceneCommands';-import { coerceFieldValue } from '@/engine/EditorControlSurface';+import { coerceFieldValue, splitFieldMember, patchFieldMember } from '@/engine/EditorControlSurface';describe('toModelValue', () => {it('keeps a name-valued enum as the name', () => {@@ -58,3 +58,48 @@ describe('coerceFieldValue (the automation door)', () => {expect(coerceFieldValue('enum', 'projectionType', 2)).toBe(2);});});++// A field path like "Transform.position.x" is what automation reaches for first —+// the MCP tool advertised that exact example while the surface rejected it,+// because the inspector's field is `position`, a whole vec3.+describe('structural field members (the "position.x" door)', () => {+ const typeOf = (k: string) => (({+ position: 'vec3', gap: 'vec2', padding: 'sides', width: 'dimension', content: 'string',+ } as Record<string, string>)[k]) as never;++ it('splits a path only when the base really is a structural field', () => {+ expect(splitFieldMember('position.x', typeOf)).toEqual({ key: 'position', member: 'x', type: 'vec3' });+ expect(splitFieldMember('gap.y', typeOf)).toEqual({ key: 'gap', member: 'y', type: 'vec2' });+ expect(splitFieldMember('padding.left', typeOf)).toEqual({ key: 'padding', member: 'left', type: 'sides' });+ expect(splitFieldMember('width.unit', typeOf)).toEqual({ key: 'width', member: 'unit', type: 'dimension' });+ });++ it('is not a path when the member does not exist, or the field has no members', () => {+ expect(splitFieldMember('position.w', typeOf)).toBeNull(); // vec3 has x/y/z+ expect(splitFieldMember('gap.z', typeOf)).toBeNull(); // vec2 has x/y+ expect(splitFieldMember('content.length', typeOf)).toBeNull(); // a string has none+ expect(splitFieldMember('unknown.x', typeOf)).toBeNull();+ expect(splitFieldMember('position', typeOf)).toBeNull();+ });++ it('writes one member and keeps the rest', () => {+ expect(patchFieldMember('vec3', [1, 2, 3], 'y', 9)).toEqual([1, 9, 3]);+ expect(patchFieldMember('vec2', [4, 5], 'x', 0)).toEqual([0, 5]);+ expect(patchFieldMember('sides', [1, 2, 3, 4], 'bottom', 8)).toEqual([1, 2, 3, 8]);+ expect(patchFieldMember('dimension', { value: 10, unit: 0 }, 'unit', 2)).toEqual({ value: 10, unit: 2 });+ });++ it('fills a short or missing value rather than writing past its end', () => {+ expect(patchFieldMember('vec3', [], 'z', 7)).toEqual([0, 0, 7]);+ expect(patchFieldMember('dimension', null as never, 'value', 3)).toEqual({ value: 3 });+ });++ it('refuses a member that is not a number, and one that does not exist', () => {+ expect(() => patchFieldMember('vec3', [0, 0, 0], 'x', 'left')).toThrow(/expects a number/);+ expect(() => patchFieldMember('vec3', [0, 0, 0], 'w', 1)).toThrow(/no member "w"/);+ });++ it('takes a numeric string, which is what a schema-loose client sends', () => {+ expect(patchFieldMember('vec2', [0, 0], 'y', '12.5')).toEqual([0, 12.5]);+ });+});diff --git a/docs/astro/src/content/docs/guides/mcp.mdx b/docs/astro/src/content/docs/guides/mcp.mdxindex 688869088..58f88a9bf 100644--- a/docs/astro/src/content/docs/guides/mcp.mdx+++ b/docs/astro/src/content/docs/guides/mcp.mdx@@ -124,8 +124,20 @@ they create by name, so a whole subtree lands in one call:```It is atomic: if any op fails, the error names the op that failed (`op[7] set: …`)-and the whole batch rolls back, so a bad program never leaves a half-built subtree-behind.+and the whole batch rolls back — entities it had already created included — so a+bad program never leaves a half-built subtree behind.++A field path may name **one member** of a structural field (`"Transform.position.x"`,+`"FlexContainer.gap.y"`, `"UINode.width.value"`), which reads and writes back the+rest, so moving a node one axis does not cost a read-modify-write.++Past a few hundred nodes the program itself is the problem — a real panel is+hundreds of KB of JSON, which does not belong in a chat message. Write it with+`write_project_file` and hand `apply_scene_ops` the path instead:++```json+{ "opsPath": "assets/scenes/shop.ops.json", "label": "Build the shop" }+```<Aside type="note">Some things live in **import settings**, not on a component — a texture's 9-slicediff --git a/docs/astro/src/content/docs/zh-cn/guides/mcp.mdx b/docs/astro/src/content/docs/zh-cn/guides/mcp.mdxindex 47570e660..45edd6fe6 100644--- a/docs/astro/src/content/docs/zh-cn/guides/mcp.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/mcp.mdx@@ -116,7 +116,18 @@ claude mcp add estella --env ESTELLA_MCP_ALLOW_WRITES=1 -- \```它是原子的:任何一步失败,报错会指名是哪一步挂的(`op[7] set: …`),整批回滚-——一段写错的程序不会留下一棵搭到一半的子树。+——**包括它已经创建出来的实体**——一段写错的程序不会留下一棵搭到一半的子树。++字段路径可以只点名结构字段里的**一个成员**(`"Transform.position.x"`、+`"FlexContainer.gap.y"`、`"UINode.width.value"`),其余部分会被读出来原样写回,+所以只挪一个轴不必先读再改再写。++节点数量上到几百之后,程序本身就成了负担——一个真实面板是几百 KB 的 JSON,+不该塞进对话里。用 `write_project_file` 写成文件,再把路径交给 `apply_scene_ops`:++```json+{ "opsPath": "assets/scenes/shop.ops.json", "label": "搭建商店" }+```<Aside type="note">有些东西在**导入设置**里,不在组件上——最容易踩的是纹理的九宫格边框: