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): the catalog hands over a whole material, not just the shader's name

yhh1ea5e1631ced
diff --git a/desktop/shared/toolCatalog.mjs b/desktop/shared/toolCatalog.mjs
index 11702606e..aed63d361 100644
--- a/desktop/shared/toolCatalog.mjs
+++ b/desktop/shared/toolCatalog.mjs
@@ -546,7 +546,7 @@ const ATOMS = [
schema: obj({}), method: 'listEntityTemplates', args: () => [], root: 'editor' },
{ name: 'list_shader_templates',
description: "The material picker's catalog: every shader a material can name, and what each one takes. "
- + 'Answers `[{ ref, label, description, source, params: [{ name, type, default, range? }] }]` — `ref` is EXACTLY what goes in a material\'s `shader` field (`builtin:sprite-outline` for a stock one, the file path for a project `.esshader`), and `params` are the uniforms you then set in its `properties`. '
+ + 'Answers `[{ ref, label, description, source, params: [{ name, type, default, range? }], material }]` — `ref` is EXACTLY what goes in a material\'s `shader` field (`builtin:sprite-outline` for a stock one, the file path for a project `.esshader`), `params` are the uniforms you then set in its `properties`, and `material` is a WHOLE `.esmaterial` already bound to it: pass it to create_asset as the content and change the properties you care about, rather than working the file format out. '
+ 'ASK THIS RATHER THAN GUESSING: the stock templates exist only as runtime values and shader source, so their ids and their parameters are in NEITHER the staged types nor anything search_project_files can reach — a project has no text of them to find. '
+ 'Outline, hit-flash, dissolve, pixelate and UV-scroll are among the ones already here; reaching for a hand-written shader before reading this list is writing one that exists.',
schema: obj({}), method: 'listShaderTemplates', args: () => [], root: 'editor' },
diff --git a/desktop/src/material/openMaterial.ts b/desktop/src/material/openMaterial.ts
index 409c198dc..8d53ab32b 100644
--- a/desktop/src/material/openMaterial.ts
+++ b/desktop/src/material/openMaterial.ts
@@ -8,6 +8,7 @@
* parent ref (UE MIC).
*/
import { builtinShaderTemplate, type MaterialAssetData } from 'esengine';
+import { newMaterialDocument } from './shaderCatalog';
import { ProjectStore } from '@/project/ProjectStore';
import { AssetRegistry } from '@/project/AssetRegistry';
import { dockApi } from '@/layout/dockApi';
@@ -49,24 +50,14 @@ async function writeMeta(rel: string): Promise<void> {
*/
export async function createMaterial(dir: string, templateId = 'sprite-unlit'): Promise<void> {
const template = builtinShaderTemplate(templateId);
- if (!template) {
+ const asset = newMaterialDocument(templateId);
+ if (!template || !asset) {
Toasts.push(t('mat.unknownTemplate', { id: templateId }), 'error');
return;
}
const folder = dir ? (dir.endsWith('/') ? dir : `${dir}/`) : '';
const matRel = uniqueMaterialPath(folder, `New${template.label}Material`);
- const asset: MaterialAssetData = {
- version: '1.0',
- type: 'material',
- shader: `builtin:${templateId}`,
- blendMode: 0,
- depthTest: false,
- depthWrite: true,
- cull: 0,
- properties: structuredClone(template.defaults) as MaterialAssetData['properties'],
- };
-
try {
await window.estella.fs.write(matRel, JSON.stringify(asset, null, 2) + '\n');
await writeMeta(matRel);
diff --git a/desktop/src/material/shaderCatalog.ts b/desktop/src/material/shaderCatalog.ts
index 789283a54..4ed863206 100644
--- a/desktop/src/material/shaderCatalog.ts
+++ b/desktop/src/material/shaderCatalog.ts
@@ -10,9 +10,33 @@
* param` declarations cannot be found by reading types or grepping the project.
* Reflection is the SAME call the inspector makes, so there is no second list.
*/
-import { BUILTIN_SHADER_TEMPLATES, reflectEsshader, type ShaderParam } from 'esengine';
+import {
+ BUILTIN_SHADER_TEMPLATES, builtinShaderTemplate, reflectEsshader,
+ type MaterialAssetData, type ShaderParam,
+} from 'esengine';
import { BUILTIN_SHADER_PREFIX } from './materialInspectorModel';
+/**
+ * A new material bound to a stock template, as the file would be written. Null
+ * for an id no template answers to. The New-Material flow and the catalog an
+ * agent reads both come through here, so what it is told to write is what the
+ * menu would have written.
+ */
+export function newMaterialDocument(templateId: string): MaterialAssetData | null {
+ const template = builtinShaderTemplate(templateId);
+ if (!template) return null;
+ return {
+ version: '1.0',
+ type: 'material',
+ shader: `${BUILTIN_SHADER_PREFIX}${templateId}`,
+ blendMode: 0,
+ depthTest: false,
+ depthWrite: true,
+ cull: 0,
+ properties: structuredClone(template.defaults) as MaterialAssetData['properties'],
+ };
+}
+
/** One parameter of a shader, as a caller needs it to write a material. */
export interface ShaderParamInfo {
name: string;
@@ -32,6 +56,9 @@ export interface ShaderCatalogEntry {
description: string;
source: 'builtin' | 'project';
params: ShaderParamInfo[];
+ /** A whole `.esmaterial` bound to it, ready to write. Absent for a project
+ * shader, whose defaults are its own file's to declare. */
+ material?: MaterialAssetData;
}
const info = (p: ShaderParam): ShaderParamInfo => ({
@@ -51,6 +78,7 @@ export function builtinShaderCatalog(): ShaderCatalogEntry[] {
description: t.description,
source: 'builtin' as const,
params: reflectEsshader(t.source).params.map(info),
+ material: newMaterialDocument(t.id) ?? undefined,
}));
}
diff --git a/desktop/tests/shader-catalog.test.ts b/desktop/tests/shader-catalog.test.ts
index ee8e79794..a1c0d2b02 100644
--- a/desktop/tests/shader-catalog.test.ts
+++ b/desktop/tests/shader-catalog.test.ts
@@ -48,6 +48,30 @@ describe('the stock templates', () => {
});
});
+// The other half of what the run went looking for: `interface MaterialAsset`,
+// `type: 'material'`, `"version":`, `properties` — the file format, guessed at
+// from types because nothing hands over a whole one.
+describe('the material each template comes with', () => {
+ it('is a document that can be written as it stands', () => {
+ expect(byRef('builtin:sprite-outline')!.material).toMatchObject({
+ version: '1.0',
+ type: 'material',
+ shader: 'builtin:sprite-outline',
+ properties: expect.any(Object),
+ });
+ });
+
+ it('starts from the template own defaults, so it renders before anything is set', () => {
+ const material = byRef('builtin:sprite-outline')!.material!;
+ const params = byRef('builtin:sprite-outline')!.params.map((p) => p.name);
+ for (const key of Object.keys(material.properties ?? {})) expect(params).toContain(key);
+ });
+
+ it('is absent for a project shader, whose own file declares them', () => {
+ expect(projectShaderEntry('a.esshader', '#pragma param u_x float default(1)').material).toBeUndefined();
+ });
+});
+
describe("a project's own shader", () => {
it('is named by its path and reflected the same way', () => {
const entry = projectShaderEntry('assets/shaders/wave.esshader', [