Skip to content

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.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.mjs
index 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.ts
index 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 "no
diff --git a/desktop/tests/script-service.test.ts b/desktop/tests/script-service.test.ts
index 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 } fro
import { 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([]);
+ });
+});