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): look at the thing, and spell the fragment stage right
yhh2a0cb216fbec
diff --git a/desktop/electron/agent/prompt.ts b/desktop/electron/agent/prompt.tsindex a5f4b158c..886d8afe9 100644--- a/desktop/electron/agent/prompt.ts+++ b/desktop/electron/agent/prompt.ts@@ -30,11 +30,11 @@ How work lands here:Working style:- Look before you edit. get_scene_tree, get_inspector and get_document cost one round trip and are the difference between editing the right entity and editing a plausible one.-- You can see the result: capture_viewport renders what the user is looking at. Use it when the question is visual — layout, whether something is on screen, why the scene looks wrong.+- 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. 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.- 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.- 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.-- 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) and the injected 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 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.+- 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.- 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.diff --git a/desktop/tests/agent-brief-compiles.test.ts b/desktop/tests/agent-brief-compiles.test.tsindex 548f0bde6..519376911 100644--- a/desktop/tests/agent-brief-compiles.test.ts+++ b/desktop/tests/agent-brief-compiles.test.ts@@ -17,6 +17,7 @@ import ts from 'typescript';import path from 'node:path';import { fileURLToPath } from 'node:url';import { existsSync } from 'node:fs';+import { BUILTIN_SHADER_TEMPLATES } from 'esengine';import { SYSTEM_PROMPT } from '../electron/agent/prompt';const HERE = path.dirname(fileURLToPath(import.meta.url));@@ -72,4 +73,26 @@ describe("the agent's brief", () => {// The wrong form must not come back. Named, because this one shipped.expect(SYSTEM_PROMPT).not.toContain('MouseButton.Left');});++ it('names the fragment stage the engine actually injects', () => {+ // A shader is not TypeScript: the fixture cannot compile one, and the agent's+ // first hand-written `.esshader` reached for `texture(u_texture, v_uv)` — two+ // names that exist nowhere. The built-in templates ARE the contract, so they+ // are what the prose is checked against.+ for (const symbol of ['v_texCoord', 'u_textures[0]', 'fragColor', '#pragma param']) {+ expect([symbol, SYSTEM_PROMPT.includes(symbol)]).toEqual([symbol, true]);+ const used = BUILTIN_SHADER_TEMPLATES.some((t) => t.source.includes(symbol));+ expect([symbol, used]).toEqual([symbol, true]);+ }+ expect(SYSTEM_PROMPT).not.toContain('v_uv');+ });++ it('tells it to look at a visual change before calling it done', () => {+ // It built the material, wired the system, set the wrong param name, read the+ // component back at 1.0 and reported success — without ever taking a picture of+ // a sprite whose whole job was to disappear.+ expect(SYSTEM_PROMPT).toMatch(/LOOK before you call a visual change done/);+ expect(SYSTEM_PROMPT).toContain('capture_viewport');+ expect(SYSTEM_PROMPT).toContain('screenshot');+ });});