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(agent): which names exist, and a search that admits it was mis-asked
yhh905908576860
diff --git a/desktop/electron/agent/prompt.ts b/desktop/electron/agent/prompt.tsindex c2d80cffa..4e1ec7752 100644--- a/desktop/electron/agent/prompt.ts+++ b/desktop/electron/agent/prompt.ts@@ -45,6 +45,7 @@ Working style:- 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.- A catalog is asked for, not searched for. What the editor offers you — entity templates, shader templates — exists as runtime VALUES, so there is no text of it anywhere in the project and repeated searches for a name you are guessing at will all come back empty while the thing itself is right there. \`list_entity_templates\` and \`list_shader_templates\` are those lists.+- Do not know the NAME yet? \`search_symbols\` lists what exists whose name looks like your fragment. Searching the files for it cannot work: the shipped types re-export under mangled aliases on one line, so a grep for \`UINode,\` or \`export * from\` finds nothing while the thing is right there.- 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.`;diff --git a/desktop/electron/projectFs.ts b/desktop/electron/projectFs.tsindex d42bfe7d6..de83cc616 100644--- a/desktop/electron/projectFs.ts+++ b/desktop/electron/projectFs.ts@@ -266,6 +266,12 @@ function isReExportBarrel(line: string): boolean {return line.length > 400 && /^export\s+(type\s+)?\{/.test(line);}+/**+ * Regex syntax nobody types by accident. A bare `.` is left out — `player.speed`+ * is a literal somebody means — so this fires on intent, not on punctuation.+ */+const REGEX_INTENT = /\.\*|\.\+|\\[wsdbWSDB]|\[[^\]]+\]|\([^)]*\)|\|\||^\^|\$$/;+export async function searchInRoot(root: string,opts: { query: string; regex?: boolean; glob?: string; maxResults?: number },@@ -297,6 +303,16 @@ export async function searchInRoot(if (out.length >= max) return out;}}+ // Nothing found, for a query that reads as a regular expression searched+ // literally. Answering `[]` says "it is not there", which is a different+ // thing and the caller acts on it — so say which of the two this was.+ if (out.length === 0 && !opts.regex && REGEX_INTENT.test(query)) {+ throw new Error(+ `no literal match for "${query}", and it reads as a regular expression — `+ + 'this search takes a literal substring unless you pass `regex: true`. '+ + 'Search again with regex: true, or with the plain text you meant.',+ );+ }return out;}diff --git a/desktop/electron/scriptService.ts b/desktop/electron/scriptService.tsindex 9de0c8da2..47d017a27 100644--- a/desktop/electron/scriptService.ts+++ b/desktop/electron/scriptService.ts@@ -33,6 +33,14 @@ export interface ScriptDiagnostic {}/** What the compiler knows about a name, for someone who cannot read the .d.ts. */+/** A name and what kind of thing it is — the answer to "what is there", which+ * comes before "what is this one". */+export interface SymbolBrief {+ name: string;+ kind: string;+ file: string;+}+export interface SymbolInfo {name: string;kind: string;@@ -269,6 +277,26 @@ class ProjectScripts {return `${head} { ${rendered.join('; ')}${tail} }`.slice(0, 2400);}+ /**+ * WHICH names exist, without rendering any of them. `lookup` answers what one+ * symbol is and costs a quickInfo per hit; this answers what there is to ask+ * about, which is the question you have when you do not know the name yet.+ */+ list(query: string, limit = 40): SymbolBrief[] {+ this.rescan();+ const items = this.service.getNavigateToItems(query, Math.min(limit * 4, 256), undefined, false, true);+ const seen = new Set<string>();+ const out: SymbolBrief[] = [];+ for (const item of items) {+ const key = `${item.name}:${item.kind}`;+ if (seen.has(key)) continue;+ seen.add(key);+ out.push({ name: item.name, kind: item.kind, file: path.relative(this.root, item.fileName) });+ if (out.length >= limit) break;+ }+ return out;+ }+lookup(name: string, limit = 8): SymbolInfo[] {this.rescan();const items = this.service.getNavigateToItems(name, 64, undefined, false, true);@@ -341,5 +369,10 @@ export function lookupScriptSymbol(name: string, limit?: number): SymbolInfo[] {return service().lookup(name, limit);}+/** Which symbols exist whose name looks like `query` — see {@link ScriptService.list}. */+export function searchScriptSymbols(query: string, limit?: number): SymbolBrief[] {+ return service().list(query, limit);+}+/** Whether a path is something the service has an opinion about. */export const isScriptPath = (relPath: string): boolean => SCRIPT_EXT.test(relPath);diff --git a/desktop/electron/surfaceDriver.ts b/desktop/electron/surfaceDriver.tsindex 58aacb64d..8aabb1e59 100644--- a/desktop/electron/surfaceDriver.ts+++ b/desktop/electron/surfaceDriver.ts@@ -17,7 +17,7 @@* so an in-process caller and a remote MCP client cannot drift apart.*/import type { BrowserWindow } from 'electron';-import { scriptDiagnostics, lookupScriptSymbol, isScriptPath } from './scriptService';+import { scriptDiagnostics, lookupScriptSymbol, searchScriptSymbols, isScriptPath } from './scriptService';import { searchInRoot, writeInRoot } from './projectFs';/** What the tool registry calls: a surface/editor method, plus the two escape@@ -377,6 +377,11 @@ export function createSurfaceDriver(for (const name of names) out[name] = lookupScriptSymbol(name, limit);return out;}+ case 'search_symbols':+ return searchScriptSymbols(+ String(input.query ?? ''),+ input.limit === undefined ? undefined : Number(input.limit),+ );case 'search_project_files':return searchInRoot(requireProjectRoot(), {query: String(input.query ?? ''),diff --git a/desktop/shared/toolCatalog.mjs b/desktop/shared/toolCatalog.mjsindex 500aa3717..36c1b46be 100644--- a/desktop/shared/toolCatalog.mjs+++ b/desktop/shared/toolCatalog.mjs@@ -534,6 +534,11 @@ const ATOMS = [+ '`name` also takes an ARRAY — ask about everything you are about to use in one call (["Query", "Res", "Mut", "Time"]) and the reply is keyed by name. Learning an API is a dozen symbols; a dozen calls is a dozen round trips. '+ 'Use this INSTEAD of paging the SDK .d.ts — that file is tens of thousands of lines and reading it a hundred at a time costs a context window to learn one method name.',schema: obj({ name: { type: ['string', 'array'] }, limit: { type: 'number' } }, ['name']), op: 'lookup_symbol' },+ { name: 'search_symbols',+ description: 'WHICH names exist, asked of the TypeScript compiler: `query` is a fragment of a name and the reply is `[{ name, kind, file }]` — the SDK, the project\'s own code and the staged types together, matched by prefix, substring and camelCase (`uinode`, `Scene`, `regAct`). '+ + 'This is the question that comes BEFORE lookup_symbol, and the one searching the files cannot answer: the shipped types re-export under mangled aliases on a single line (`export { jg as UINode, … }`), which no grep of a project turns into a list of what is available. '+ + 'Ask here when you do not know the name yet, then lookup_symbol the ones that look right.',+ schema: obj({ query: { type: 'string' }, limit: { type: 'number' } }, ['query']), op: 'search_symbols' },{ name: 'search_project_files',description: 'Lines matching `query` across the project (case-insensitive substring, or a regular expression with `regex: true`); `glob` filters paths — `*.ts`, `src/**`, `src/*.ts`, or a plain substring like ".ts". '+ 'Each hit is { file, line, text }. The door between list_project_files and reading a file whole. 'diff --git a/desktop/tests/project-fs.test.ts b/desktop/tests/project-fs.test.tsindex 606dc6829..013dfb92b 100644--- a/desktop/tests/project-fs.test.ts+++ b/desktop/tests/project-fs.test.ts@@ -119,6 +119,26 @@ describe('searchInRoot', () => {expect(hits[0].line).toBe(1);});+ // A regular expression searched literally matches nothing, and `[]` is what+ // "it is not there" looks like — so a run reads absence off a query that was+ // never asked. Seen four times in one dogfood turn (`export.*SceneManager`).+ it('refuses to pass off a mis-set regex as an absence', async () => {+ await expect(searchInRoot(root, { query: 'export.*SceneManager' }))+ .rejects.toThrow(/reads as a regular expression/);+ });++ it('says nothing about a plain query that genuinely is not there', async () => {+ expect(await searchInRoot(root, { query: 'nowhereAtAll' })).toEqual([]);+ // A dot is punctuation in code, not evidence of intent.+ expect(await searchInRoot(root, { query: 'player.speed' })).toEqual([]);+ });++ it('leaves a real regex search alone, found or not', async () => {+ expect(await searchInRoot(root, { query: 'define(System|Component)', regex: true }))+ .toHaveLength(1);+ expect(await searchInRoot(root, { query: 'zzz(a|b)', regex: true })).toEqual([]);+ });+// The SDK types are what this tool exists for, and the dot-dir rule that keeps// them out of the Content Browser was hiding them here too — so a search for a// declaration the compiler had just named came back empty, which reads as "nodiff --git a/desktop/tests/script-service.test.ts b/desktop/tests/script-service.test.tsindex a274a4cbe..92a81171b 100644--- a/desktop/tests/script-service.test.ts+++ b/desktop/tests/script-service.test.ts@@ -12,7 +12,7 @@ import { mkdtempSync, mkdirSync, writeFileSync, rmSync, cpSync, existsSync } froimport { tmpdir } from 'node:os';import path from 'node:path';import { fileURLToPath } from 'node:url';-import { adoptProjectScripts, scriptDiagnostics, lookupScriptSymbol, isScriptPath } from '../electron/scriptService';+import { adoptProjectScripts, scriptDiagnostics, lookupScriptSymbol, searchScriptSymbols, isScriptPath } from '../electron/scriptService';import { searchInRoot } from '../electron/projectFs';const HERE = path.dirname(fileURLToPath(import.meta.url));@@ -194,3 +194,34 @@ describe('project search', () => {expect(hits[0].text.length).toBeLessThanOrEqual(400);});});++/**+ * Which names exist — the question you have before you have a name, and the one+ * grep cannot answer: the shipped types re-export under mangled aliases on a+ * single line, which the file search skips as noise. The compiler has the list.+ */+describe('searchScriptSymbols', () => {+ it('finds an SDK export from a fragment of its name', () => {+ const names = searchScriptSymbols('UINod').map((s) => s.name);+ expect(names).toContain('UINode');+ });++ it('answers with a name and its kind, not a rendered signature', () => {+ const [hit] = searchScriptSymbols('defineComponent');+ expect(hit).toMatchObject({ name: 'defineComponent', kind: expect.any(String) });+ expect(hit).not.toHaveProperty('signature');+ });++ it('lists the project own symbols too', () => {+ writeFileSync(path.join(root, 'src', 'wellKnown.ts'), 'export const wellKnownThing = 1;\n');+ expect(searchScriptSymbols('wellKnownThing').map((s) => s.name)).toContain('wellKnownThing');+ });++ it('honours the limit, so a broad fragment is still one screen', () => {+ expect(searchScriptSymbols('e', 5).length).toBeLessThanOrEqual(5);+ });++ it('says nothing for a fragment nothing is named after', () => {+ expect(searchScriptSymbols('zzzNoSuchSymbolAnywhere')).toEqual([]);+ });+});