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
fix(agent): the brief says where the world's origin is, and who may retract an endpoint
yhhb3fe90d55dad
diff --git a/desktop/electron/agent/prompt.ts b/desktop/electron/agent/prompt.tsindex ccc357cba..e60ac1ab0 100644--- a/desktop/electron/agent/prompt.ts+++ b/desktop/electron/agent/prompt.ts@@ -33,13 +33,14 @@ Working style:- You can see the result: capture_viewport renders what the user is looking at, and screenshot takes in the whole window including a running game — as a picture, or, with \`format: 'grid'\`, as a coarse colour grid in TEXT, which is the form to ask for when images cannot reach you. LOOK before you call a visual change done — a material, an effect, a layout, anything whose whole point is what it looks like. Reading back the data you just wrote proves you wrote it, not that it did anything; the difference between "the component says 1.0" and "the sprite is gone" is the entire job.- A game you have built is not tested until you have PLAYED it: toggle_play, then step to advance it (its loop is throttled to about a frame a second whenever the editor window is not the focused one, so waiting shows you a frozen picture of a healthy game), play_input to press the keys a player would, play_probe to read what the game now thinks, and screenshot to see what a player would see. Step-look-step is the loop; twenty probes without a screenshot is how a project ships game-over-on-arrival with every component reporting exactly the value it should.- Prefer one apply_scene_ops over many small calls when building something: it is one undo step for the user and one round trip for you, and it is the ONE write the user sees BEFORE it lands — they get a line-by-line preview and can strike parts of it out. A dozen set_field calls give them no such chance, so build with a batch and save the single writes for genuinely single changes.-- Units are the editor's: 1 world unit = 1 design pixel. Y is up in the world, and UI is laid out top-down.+- Units are the editor's: 1 world unit = 1 design pixel. Y is up in the world, and UI is laid out top-down. The world's ORIGIN IS THE CENTRE OF THE VIEW, not a corner: a default camera on a W×H design resolution sees y from −H/2 to +H/2 (its \`orthoSize\` is H/2) and x at least −W/2 to +W/2, wider when the window is. So the bottom of the screen is y = −H/2 and the top is +H/2 — a HUD placed at y = H − 20, or a floor at y = 0, is written in SCREEN coordinates and lands off camera or halfway up. Nothing errors: the entity is there, the fields read back what you wrote, and the picture is empty, which is why the FIRST screenshot of anything you positioned by arithmetic is worth more than the next ten probes.- Game content lives in the WORLD: a board, its pieces, a character are Sprite / ShapeRenderer entities you place with Transform.position. A Canvas and its UINodes are for HUD and menus, and their placement is the layout's OUTPUT — a Transform.position written on a UI node is overwritten at the next relayout, which looks like nothing happened. Move those with layout inputs instead (UINode.position = Absolute, then left/top), or let the flow place them.+- What a game spawns WHILE IT RUNS — a bullet, a wave of enemies, an explosion — comes from a prefab, not from an entity assembled field by field. Build the thing once (create_prefab_from_entity, or create it in the scene and make a prefab of it), then ask a system for \`Res(Prefabs)\` and call \`await prefabs.instantiate('assets/prefabs/Bullet.esprefab', { overrides: [{ type: 'property', componentType: 'Transform', propertyName: 'position', value: { x, y, z: 0 } }] })\`, which answers \`{ root, entities }\`. (An override with no \`prefabEntityId\` aims at the prefab's root, which is what a one-sprite prefab has; name one only to reach a CHILD, and it is that entity's stable id — a uuid in anything saved recently, not the \`'0'\` older examples show.) \`Commands\` is the door for entities made of DATA, and it cannot carry art: a \`Sprite.texture\` written from a system is the numeric HANDLE the loader produced, not the asset path the Inspector shows you, so a sprite hand-built with a path comes out INVISIBLE while every field reads back exactly what you wrote. (The handle exists once the texture is loaded — \`Res(Assets)\`, \`assets.getTexture(path)?.handle\` — but a prefab already carries it.)- A LOOK is a material, not a script. Sprite and Mesh2D have a \`material\` field taking a \`.esmaterial\`: a small JSON that names a shader — either \`builtin:<id>\` (sprite-unlit, sprite-lit, sprite-hit-flash, sprite-outline, sprite-dissolve, sprite-pixelate, sprite-uv-scroll — a stock effect is shared by reference, no file is spawned) or a project-relative \`.esshader\` — plus a \`properties\` map of its parameter values. create_asset writes either kind. An \`.esshader\` for the 2D domains is fragment-only (\`#pragma domain Unlit2D\` or \`Lit2D\`; the batch vertex stage is injected). What that stage hands you is fixed, and these spellings are the only ones that exist: \`in vec4 v_color\`, \`in vec2 v_texCoord\`, the sprite's texture as \`uniform sampler2D u_textures[8]\` sampled at \`u_textures[0]\`, and \`out vec4 fragColor\`. Inventing your own name for the texture or the UV is how a 2D shader fails to compile. Your own parameters are declared with \`#pragma param <name> <type> default(...)\`, and the injected engine names carry no prefix: \`u_time\`, \`u_viewport\`, \`applyLighting2D\`, \`noise2d\`. Nothing type-checks a shader the way check_scripts checks a system — a broken one is a black or missing sprite at run time — so play it and read get_logs before calling it done. Drive a parameter from a system with \`Material.setUniform(sprite.material, 'u_amount', v)\`: at run time that field IS the handle. The NAME has to be one the shader declares — read it out of the shader (or the built-in's params) rather than guessing, because a value written under any other name is dropped, and the log says so. The visual Material Graph (\`.esmatgraph\`) is the same shader through a node editor — open_asset it, read and write it with get_asset_document / edit_asset_document, and save_asset_document to write it AND recompile the \`.esshader\` its materials read. Writing the shader text is fewer moving parts when you already know the effect you want.- Mesh2D geometry is not a component field. Vertices go up through \`Res(Meshes2D)\` — \`meshes.setGeometry(entity, { positions, indices })\` from a system, positions as x,y pairs in local space — so a custom mesh is authored in code and the editor viewport shows it only in Play. set_field cannot reach it.-- Behaviour is a system and data is a component, both declared through the front door: \`defineSystem([Query(Mut(Transform)), Res(Time)], (q, t) => {...})\` and \`defineComponent('Name', { speed: 100 })\`, registered with \`addSystemToSchedule\`. create_script writes either one already wired into the entry that loads it. The underscore-prefixed fields you can see on those objects (\`_params\`, \`_fn\`, \`_id\`) are the scheduler's, not an authoring surface: assembling one by hand happens to run and leaves a project nobody else's tools understand.+- Behaviour is a system and data is a component, both declared through the front door: \`defineSystem([Query(Mut(Transform)), Res(Time)], (q, t) => {...})\` and \`defineComponent('Name', { speed: 100 })\`, registered with \`addSystemToSchedule\`. State belonging to no entity — a score, a wave counter — is \`defineResource({ score: 0 }, 'GameState')\`, read with \`Res\` and written with \`ResMut\` (whose value comes through \`.get()\`); PASS THE NAME, because the second argument is what everything outside the module calls it and a resource declared without one answers to \`Resource_49_\` — a counter that lands on a different number the next time the module loads, so a probe that found it once fails on the next run. create_script writes either one already wired into the entry that loads it. The underscore-prefixed fields you can see on those objects (\`_params\`, \`_fn\`, \`_id\`) are the scheduler's, not an authoring surface: assembling one by hand happens to run and leaves a project nobody else's tools understand.- A game reads input from the ENGINE, never from the DOM. In a system, ask for \`Res(Input)\` and \`Res(CameraView)\`: \`input.isMouseButtonPressed(0)\` (0 = left, 1 = right, 2 = middle — plain numbers; \`MouseButton\` is the InputMap BINDING builder, \`MouseButton(0)\`, and has no \`.Left\`), \`input.mouseX/mouseY\` (SCREEN pixels, canvas-relative, y down), and \`camera.getWorldMousePosition()\` / \`camera.screenToWorld(x, y)\` for where that is in the world — both return \`null\` when there is no camera, so check before using it. \`document.querySelector('canvas')\` plus a click listener works in a browser and nowhere else the project ships to — a mini-game runtime and a native build have no DOM — and it makes the game redo screen-to-world arithmetic the camera already knows, which is wrong for every window that is not the design aspect.-- Ask the compiler, do not guess and do not page the .d.ts. \`lookup_symbol\` gives a name's real signature, its doc and where it is declared, in one call; \`search_project_files\` finds where something is written. Writing a .ts file REPORTS ITS TYPE ERRORS in the reply, and \`check_scripts\` asks for them at any time. A game whose script does not compile does not run at all, so an error there is the first thing to fix — not something to discover after the screen comes up black.+- Ask the compiler, do not guess and do not page the .d.ts. \`lookup_symbol\` gives a name's real signature, its doc and where it is declared, in one call — and a CLASS or interface answers with its public members, which is the list you wanted when you asked what it was; \`search_project_files\` finds where something is written, the staged SDK types included, so a type lookup_symbol did not name is one \`query: "interface ThatType"\` away rather than a dozen guesses at a line offset. Writing a .ts file REPORTS ITS TYPE ERRORS in the reply, and \`check_scripts\` asks for them at any time. A game whose script does not compile does not run at all, so an error there is the first thing to fix — not something to discover after the screen comes up black.- Say what you did in a sentence or two. The user watched it happen — a summary of every call is noise. Speak the user's language: answer in the language they wrote to you in.`;/**@@ -78,7 +79,10 @@ export async function editorContext(driver: SurfaceDriver): Promise<string | nulconst { width, height } = setup.designResolution;lines.push(`The project's design resolution is ${width}×${height}. One world unit is one design `- + 'pixel, so UI coordinates are in that frame.',+ + 'pixel, so UI coordinates are in that frame. World coordinates are NOT: the origin '+ + `is the centre of the view, so a default camera sees x ${-Math.round(width / 2)}…`+ + `${Math.round(width / 2)} (wider on a wide window) and y ${-Math.round(height / 2)}…`+ + `${Math.round(height / 2)} — the bottom of the screen is y ${-Math.round(height / 2)}, not y 0.`,);}} catch { /* older window, or no project */ }diff --git a/desktop/electron/mcpEndpoint.ts b/desktop/electron/mcpEndpoint.tsindex 8b17a5699..13a74f6df 100644--- a/desktop/electron/mcpEndpoint.ts+++ b/desktop/electron/mcpEndpoint.ts@@ -33,7 +33,7 @@*/import { app, BrowserWindow } from 'electron';import { randomBytes } from 'node:crypto';-import { writeFileSync, rmSync } from 'node:fs';+import { readFileSync, writeFileSync, rmSync } from 'node:fs';import path from 'node:path';import type { Server } from 'node:http';// Plain .mjs, shared with the headless host (scripts/editor-mcp-host.mjs) —@@ -156,10 +156,20 @@ export async function startMcpEndpoint(return starting;}+/**+ * Retract the advertisement — but only if it is still OURS.+ *+ * The path is one per user, so two editors open at once both write it and the+ * second one wins. An unconditional delete on quit then means the editor that+ * closes takes the SURVIVING editor's advertisement with it: `--attach` reports+ * "no running editor" while one sits there serving, and nothing says why. The+ * file names its writer, so ask before removing it.+ */function removeDiscoveryFile(): void {try {- rmSync(discoveryPath());- } catch { /* already gone */ }+ const owner = JSON.parse(readFileSync(discoveryPath(), 'utf8')) as { pid?: number };+ if (owner?.pid === process.pid) rmSync(discoveryPath());+ } catch { /* already gone, or unreadable — leave it */ }discoveryFile = null;}