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(assets): a material says what it left out - a texture that would not load, a property nothing reads
yhhb52490260ea3
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 06e42dd8e..aff0c32ac 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,7 @@ published separately; it ships inside the editor.### Fixed+- **A material that loaded with part of it missing no longer fails in silence.** A texture that would not load, or a property of a shape nothing reads (a tiling written `[12, 12]` instead of `{ "x": 12, "y": 12 }`), left the material loaded and drawing with the default look where that part was, and said so only in one log line. The loader now reports what it left out; `get_diagnostics` lists it as `asset-degraded` against every entity that uses the material, naming the property and what to write instead, and Project Health shows it as a warning.- **A terrain brush stroke no longer makes the ground vanish for a moment.** An edited page of the ground used to be thrown away at once and rebuilt over the next frames, so the touched area had no ground to draw until it was done; it now goes on being drawn as it was, and changes in place.- **Voxel Ground compiles on WebGPU again.** The Model shader's new wet-ground map left the voxel ground one texture past what a shader has units for, so its last texture was dropped and the whole shader was refused (`unresolved value 'u_wetMask'`). Voxel ground takes no wet map.- **Several editors open at once can be told apart by an agent, and each grants on its own.** An editor advertises itself in a file of its own (its process id, its project, its port, its permission) instead of the one file the last editor to start overwrote. An agent attached to more than one gets `list_editors` and `select_editor` (or `--instance` / `ESTELLA_MCP_INSTANCE`), and until it chooses it is refused with the list rather than sent to whichever window won. It then drives the editor it chose and no other. The Read only / Can edit permission belongs to the editor window it is switched in and every editor starts read-only; it is no longer a saved setting that a second editor inherited. The Connect AI Tools dialog shows which editor it is.diff --git a/desktop b/desktopindex 9f859635a..788b413e8 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 9f859635a6e8f9bc167940969aaeb57ed3123ce8+Subproject commit 788b413e88e92dcac544f3b676b683de0792f557diff --git a/sdk/src/asset/AssetLoader.ts b/sdk/src/asset/AssetLoader.tsindex 54f52c2e2..bf3b41aaf 100644--- a/sdk/src/asset/AssetLoader.ts+++ b/sdk/src/asset/AssetLoader.ts@@ -127,6 +127,12 @@ export interface LoadContext {acquireTexture(path: string, flipY?: boolean): Promise<AssetLease<TextureResult>>;/** Say that material @p material binds texture @p texture, before it is acquired: a mesh material's textures may start small. */noteMaterialTexture?(material: string, texture: string): void;+ /**+ * Say what is wrong with an asset that LOADED anyway: a part of it was left out (a texture that would not load, a value of a shape nothing+ * reads) and what draws is the rest. Replaces the list this asset had; an empty list says it is whole. Without this a half-loaded material+ * looks exactly like a good one: a log line, and then a default-looking surface nobody can attribute.+ */+ noteAssetProblems?(asset: string, problems: readonly string[]): void;/*** The same for an asset of ANY type — a material instance acquiring the* parent it diffs against. The general door; {@link acquireTexture} is thediff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex 8ff2bf34b..8d20b0937 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -2552,6 +2552,23 @@ export class Assets {this.assetRefResolver_ = resolver;}+ private readonly assetProblems_ = new Map<string, readonly string[]>();+ private assetProblemListener_: ((asset: string, problems: readonly string[]) => void) | null = null;++ /**+ * What is wrong with an asset that loaded: the parts of it that were left out, each said once. Empty when it is whole (or was never+ * loaded). A material whose texture would not load, or whose value has a shape nothing reads, is here and not in a failed load.+ * @experimental+ */+ getAssetProblems(asset: string): readonly string[] {+ return this.assetProblems_.get(asset) ?? [];+ }++ /** Hear every change to an asset's problems (the editor's diagnostics). One listener; null removes it. @experimental */+ setAssetProblemListener(listener: ((asset: string, problems: readonly string[]) => void) | null): void {+ this.assetProblemListener_ = listener;+ }+getAssetRefResolver(): AssetRefResolver | null {return this.assetRefResolver_;}@@ -3018,6 +3035,13 @@ export class Assets {const { result, lease } = await self.acquireTextureVariant_(path, flipY !== false);return self.textureLease_(lease, result);},+ noteAssetProblems(asset: string, problems: readonly string[]): void {+ const path = self.resolveLoadPath_(asset);+ const same = (self.assetProblems_.get(path) ?? []).join('\n') === problems.join('\n');+ if (problems.length === 0) self.assetProblems_.delete(path);+ else self.assetProblems_.set(path, [...problems]);+ if (!same) self.assetProblemListener_?.(path, problems);+ },noteMaterialTexture(material: string, texture: string): void {if (self.meshMaterials_.has(self.resolveLoadPath_(material)) || self.meshMaterials_.has(material)) {self.meshTextures_.add(self.resolveLoadPath_(texture));diff --git a/sdk/src/asset/loaders/MaterialAssetLoader.ts b/sdk/src/asset/loaders/MaterialAssetLoader.tsindex 4c06e4f27..1ed152fb5 100644--- a/sdk/src/asset/loaders/MaterialAssetLoader.ts+++ b/sdk/src/asset/loaders/MaterialAssetLoader.ts@@ -4,6 +4,7 @@ import type { AssetLoader, LoadContext, MaterialResult } from '../AssetLoader';import { isBuiltinAssetRef, resolveDocumentRef } from '../documentRef';import type { MaterialAssetData } from '../../render/material';import { Material } from '../../render/material';+import { assetPropertyProblems } from '../../render/materialProblems';import type { MaterialShaderSource } from './MaterialShaderAssetLoader';import { log } from '../../util/logger';@@ -27,7 +28,8 @@ export class MaterialAssetLoader implements AssetLoader<MaterialResult> {const parentPath = resolveDocumentRef(path, data.instanceOf);const parent = await ctx.acquireAsset<MaterialResult>('material', parentPath);const handle = Material.createFromAsset(data, 0, parent.value.handle);- await this.applyTextureProps(handle, data, path, ctx);+ const missing = await this.applyTextureProps(handle, data, path, ctx);+ ctx.noteAssetProblems?.(path, [...assetPropertyProblems(data.properties), ...missing]);return { handle, shaderHandle: parent.value.shaderHandle };}@@ -37,7 +39,10 @@ export class MaterialAssetLoader implements AssetLoader<MaterialResult> {const source = await ctx.acquireAsset<MaterialShaderSource>('material-shader', shaderPath);const shaderHandle = source.value.compile(features);const handle = Material.createFromAsset(data, shaderHandle);- await this.applyTextureProps(handle, data, path, ctx);+ const missing = await this.applyTextureProps(handle, data, path, ctx);+ // The material loaded, and draws with what could be read. Said once, where the editor's diagnostics and an agent can find it: a surface+ // that quietly falls back to the default look is otherwise indistinguishable from one that is meant to look that way.+ ctx.noteAssetProblems?.(path, [...assetPropertyProblems(data.properties), ...missing]);return { handle, shaderHandle };}@@ -51,7 +56,8 @@ export class MaterialAssetLoader implements AssetLoader<MaterialResult> {data: MaterialAssetData,matPath: string,ctx: LoadContext,- ): Promise<void> {+ ): Promise<string[]> {+ const problems: string[] = [];for (const [name, value] of Object.entries(data.properties)) {if (typeof value !== 'string') continue;const texPath = resolveDocumentRef(matPath, value);@@ -62,8 +68,10 @@ export class MaterialAssetLoader implements AssetLoader<MaterialResult> {} catch (e) {// Missing texture: leave the param unbound (it samples whatever is at the unit).log.warn('asset', `Material ${matPath}: failed to load texture '${texPath}' for param '${name}'`, e);+ problems.push(`${name}: the texture "${texPath}" did not load (${e instanceof Error ? e.message : String(e)}), so the surface draws without it`);}}+ return problems;}unload(asset: MaterialResult): void {diff --git a/sdk/src/render/materialProblems.ts b/sdk/src/render/materialProblems.tsnew file mode 100644index 000000000..34abf8981--- /dev/null+++ b/sdk/src/render/materialProblems.ts@@ -0,0 +1,31 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file materialProblems.ts+ * @brief What a material asset says that nothing reads. Pure, and apart from material.ts so a loader can name it without the material system.+ */++/**+ * The properties of a material asset that `parseAssetProperties` (material.ts) would drop, each with what to write instead. A dropped value is the quietest+ * way a material goes wrong: it loads, draws, and simply ignores what was written (a tiling of `[12, 12]` leaves the surface untiled).+ * Strings are texture refs and are the loader's own business.+ */+export function assetPropertyProblems(properties: Record<string, unknown>): string[] {+ const problems: string[] = [];+ for (const [key, value] of Object.entries(properties)) {+ if (typeof value === 'number' || typeof value === 'string') continue;+ if (Array.isArray(value)) {+ const names = ['x', 'y', 'z', 'w'].slice(0, Math.min(Math.max(value.length, 2), 4));+ const colour = value.length === 3 || value.length === 4;+ problems.push(`${key} is an array and no material reads one: write ${colour ? '{ "r": .., "g": .., "b": .., "a": .. } for a colour or ' : ''}{ ${names.map((n) => `"${n}": ..`).join(', ')} } for a vector`);+ } else if (typeof value === 'object' && value !== null) {+ const obj = value as Record<string, unknown>;+ if (!('r' in obj) && !('w' in obj) && !('z' in obj) && !('y' in obj)) {+ problems.push(`${key} is an object with none of the keys a colour (r, g, b, a) or a vector (x, y, z, w) has`);+ }+ } else {+ problems.push(`${key} is ${value === null ? 'null' : typeof value}: a material property is a number, a texture path, a colour or a vector`);+ }+ }+ return problems;+}diff --git a/sdk/tests/material-asset-loader.test.ts b/sdk/tests/material-asset-loader.test.tsindex 17e0ce2dd..02477a75d 100644--- a/sdk/tests/material-asset-loader.test.ts+++ b/sdk/tests/material-asset-loader.test.ts@@ -75,6 +75,31 @@ describe('MaterialAssetLoader texture failure', () => {});});+describe('MaterialAssetLoader says what a half-loaded material is missing', () => {+ beforeEach(() => {+ vi.clearAllMocks();+ (Material.createFromAsset as ReturnType<typeof vi.fn>).mockReturnValue(11);+ (Material.compileShader as ReturnType<typeof vi.fn>).mockReturnValue(7);+ });++ it('reports a texture that would not load, against the material, by param name', async () => {+ const loader = new MaterialAssetLoader();+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const ctx = makeCtx();+ const noted = vi.fn();+ ctx.noteAssetProblems = noted;++ await loader.load(MAT_PATH, ctx);++ expect(noted).toHaveBeenCalledTimes(1);+ const [asset, problems] = noted.mock.calls[0] as [string, string[]];+ expect(asset).toBe(MAT_PATH);+ expect(problems).toHaveLength(1);+ expect(problems[0]).toMatch(/^mainTex: the texture "assets\/materials\/missing\.png" did not load \(404 not found\)/);+ warnSpy.mockRestore();+ });+});+describe('MaterialAssetLoader ownership on unload', () => {beforeEach(() => {vi.clearAllMocks();diff --git a/sdk/tests/material-asset-problems.test.ts b/sdk/tests/material-asset-problems.test.tsnew file mode 100644index 000000000..51f964bb9--- /dev/null+++ b/sdk/tests/material-asset-problems.test.ts@@ -0,0 +1,36 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it } from 'vitest';+import { assetPropertyProblems } from '../src/render/materialProblems';++describe('the properties of a material asset that nothing reads', () => {+ it('accepts what a material is written with', () => {+ expect(assetPropertyProblems({+ u_roughness: 0.4,+ u_tiling: { x: 12, y: 12 },+ u_tint: { r: 1, g: 0.5, b: 0.2 },+ u_range: { x: 1, y: 2, z: 3 },+ mainTex: 'textures/wall.png',+ })).toEqual([]);+ });++ it('names an array, which is what an author writes first, and says what to write instead', () => {+ const [problem] = assetPropertyProblems({ u_tiling: [12, 12] });+ expect(problem).toMatch(/^u_tiling is an array/);+ expect(problem).toContain('"x": ..');+ expect(problem).toContain('"y": ..');+ });++ it('offers a colour for an array of three or four', () => {+ expect(assetPropertyProblems({ u_tint: [1, 0.5, 0.2, 1] })[0]).toContain('"r"');+ expect(assetPropertyProblems({ u_tiling: [12, 12] })[0]).not.toContain('"r"');+ });++ it('names an object of no known shape, a boolean and a null', () => {+ const problems = assetPropertyProblems({ a: { foo: 1 }, b: true, c: null });+ expect(problems).toHaveLength(3);+ expect(problems[0]).toMatch(/^a is an object with none of the keys/);+ expect(problems[1]).toMatch(/^b is boolean/);+ expect(problems[2]).toMatch(/^c is null/);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex a78b621a6..9855539a0 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -4400,4 +4400,8 @@ export const NOTED = {{"note": "Voxel Ground compiles on WebGPU again."},"fix: the docs build parses the GripSurface summary; dusk-fort keeps its fog colour in colors":{"internal": "A docs build error and an example scene's fog colour moved to where the loader reads it; no creator's project changes."},+ "feat(assets): a material says what it left out - a texture that would not load, a property nothing reads":+ {"note": "A material that loaded with part of it missing no longer fails in silence."},+ "feat(editor): an asset that loaded with part of it missing is a diagnostic and a project warning, not a log line":+ {"note": "A material that loaded with part of it missing no longer fails in silence."},};