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.

fix(render): a shipped game samples data textures as data

esengineace1d671f1a7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4ace6c02b..0bb28dd10 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,10 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Fixed
+
+- **A shipped game samples normal maps and roughness maps as data.** The engine's own upload — a web export, a mini-game, a native build, the editor's Play — made every image an sRGB colour texture in a linear project whatever its import settings said, so every normal map was bent (a flat one by about fifty degrees) and every packed occlusion, roughness and metal map gamma-darkened, while the editor's viewport, which uploads through its own path, looked right. ORCA Bistro's Vespa came out as dark chrome in an exported game and blue in the editor. Khronos's NormalTangentTest now draws each normal-mapped bump as its geometric twin does.
+
## [0.75.0] - 2026-09-27
### Added
diff --git a/fixtures/scenes/corpus-normal-tangent.esscene b/fixtures/scenes/corpus-normal-tangent.esscene
new file mode 100644
index 000000000..4a72b9424
--- /dev/null
+++ b/fixtures/scenes/corpus-normal-tangent.esscene
@@ -0,0 +1,102 @@
+{
+ "version": 4,
+ "name": "CorpusNormalTangent",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": -0.125,
+ "z": 4
+ },
+ "rotation": {
+ "x": 0,
+ "y": 0,
+ "z": 0,
+ "w": 1
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 0,
+ "fov": 40,
+ "nearPlane": 0.1,
+ "farPlane": 50,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Sun",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "rotation": {
+ "x": -0.33409089130725245,
+ "y": -0.27840907608937704,
+ "z": -0.0,
+ "w": 0.9004841268432137
+ }
+ }
+ },
+ {
+ "type": "Light",
+ "data": {
+ "type": 1,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "intensity": 2.5
+ }
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Sky",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Light",
+ "data": {
+ "type": 2,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "intensity": 0.3
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.ts
index c85a5d5ea..dad8fad9a 100644
--- a/sdk/src/asset/loaders/TextureLoader.ts
+++ b/sdk/src/asset/loaders/TextureLoader.ts
@@ -156,10 +156,12 @@ export class TextureLoader implements AssetLoader<TextureResult> {
width: number, height: number, pixels: Uint8Array, flipY: boolean, content: TextureContent,
): Promise<TextureResult> {
const rm = requireResourceManager();
+ // A collage of colour images, so colour: the engine takes the code as said.
+ const format = samplesAsSrgb(true) ? 2 : 1;
// Native (no wasm heap): upload the bytes directly. Web embind lacks this
// method, so it takes the heap path below unchanged.
if (rm.createTextureFromBytes) {
- const handle = rm.createTextureFromBytes(width, height, pixels, 1, flipY, content);
+ const handle = rm.createTextureFromBytes(width, height, pixels, format, flipY, content);
return { handle, width, height };
}
if (!this.module_) {
@@ -168,7 +170,7 @@ export class TextureLoader implements AssetLoader<TextureResult> {
const module = this.module_;
const handle = withMalloc(module, pixels.length, ptr => {
module.HEAPU8.set(pixels, ptr);
- return rm.createTexture(width, height, ptr, pixels.length, 1, flipY, content);
+ return rm.createTexture(width, height, ptr, pixels.length, format, flipY, content);
});
return { handle, width, height };
}
diff --git a/src/esengine/bindings/ResourceManagerBindings.cpp b/src/esengine/bindings/ResourceManagerBindings.cpp
index b6bbb55a5..3444a3240 100644
--- a/src/esengine/bindings/ResourceManagerBindings.cpp
+++ b/src/esengine/bindings/ResourceManagerBindings.cpp
@@ -3,7 +3,6 @@
#include "ResourceManagerBindings.hpp"
#include "BoundarySpan.hpp"
-#include "../resource/ShaderParser.hpp"
#include "../resource/TextureMetadata.hpp"
#include "../text/BitmapFont.hpp"
#include "../core/Types.hpp"
@@ -23,15 +22,14 @@ namespace esengine {
namespace {
/**
- * Pixel uploads crossing the JS boundary are color images (decoded PNGs, spine
- * atlases, glyph atlases, tileset collages) — the same "all image textures are
- * color" contract the SDK's raw-GL upload path applies. Linear mode stores them
- * sRGB-encoded so the sampler linearizes in hardware, on both backends.
+ * The caller decides: 2 is sRGB-encoded colour, which it only asks for in a
+ * linear pipeline, and 1 is plain bytes. Promoting 1 as well gamma-decoded every
+ * normal map and roughness map a shipped game uploaded, while the editor's own
+ * upload honoured the asset's setting and looked right.
*/
TextureFormat boundaryTextureFormat(i32 format) {
if (format == 0) return TextureFormat::RGB8;
- if (resource::ShaderParser::linearColorSpace()) return TextureFormat::SRGB8A8;
- return TextureFormat::RGBA8;
+ return format == 2 ? TextureFormat::SRGB8A8 : TextureFormat::RGBA8;
}
} // namespace
diff --git a/tools/check-render-scenes.mjs b/tools/check-render-scenes.mjs
index cd7c827c4..4b0d43e54 100644
--- a/tools/check-render-scenes.mjs
+++ b/tools/check-render-scenes.mjs
@@ -46,7 +46,7 @@ for (const s of SCENES) {
|| s.env.ESTELLA_VERIFY_SEAM
|| s.env.ESTELLA_VERIFY_GRID || s.env.ESTELLA_VERIFY_PREVIEW
|| s.env.ESTELLA_VERIFY_MESH_PREVIEW || s.env.ESTELLA_VERIFY_DEPTH_LAYERS
- || s.env.ESTELLA_VERIFY_COUNTERS || s.env.ESTELLA_VERIFY_COUNTERS_MAX || s.env.ESTELLA_VERIFY_FRAME_DEBUG || s.env.ESTELLA_VERIFY_EDGE || s.env.ESTELLA_VERIFY_CUTOUT_EDGE || s.env.ESTELLA_VERIFY_MINIFIED
+ || s.env.ESTELLA_VERIFY_COUNTERS || s.env.ESTELLA_VERIFY_COUNTERS_MAX || s.env.ESTELLA_VERIFY_FRAME_DEBUG || s.env.ESTELLA_VERIFY_EDGE || s.env.ESTELLA_VERIFY_CUTOUT_EDGE || s.env.ESTELLA_VERIFY_MINIFIED || s.env.ESTELLA_VERIFY_TWINS
|| s.env.ESTELLA_VERIFY_DRAW_CALLS
|| s.env.ESTELLA_VERIFY_YSORT || s.id === 'sprite-default';
if (!asserts && !s.rendersOnly) {
diff --git a/tools/corpora.mjs b/tools/corpora.mjs
index 934458e01..59ebb3296 100644
--- a/tools/corpora.mjs
+++ b/tools/corpora.mjs
@@ -44,6 +44,20 @@ export const CORPORA = {
'MatBed_occlusionRoughnessMetallic.jpg': 'e1472454ad6be574c3a418985f06a8ba36877108a94f61590f01e118804379b4',
},
},
+ 'khronos-normal-tangent-test': {
+ what: 'Khronos glTF sample: normal-mapped bumps beside the same bumps built as geometry, in every UV orientation, with no tangents supplied',
+ license: 'CC-BY-4.0 (© 2017 Analytical Graphics, Inc.; Khronos glTF-Sample-Assets)',
+ source: 'https://github.com/KhronosGroup/glTF-Sample-Assets/tree/7d4ba189827916452eeadc82d4b712dbc6280a6f/Models/NormalTangentTest',
+ base: `${KHRONOS_SAMPLES}/Models/NormalTangentTest/glTF`,
+ models: ['NormalTangentTest.gltf'],
+ files: {
+ 'NormalTangentTest.gltf': 'ef2b152063304ebb0314646d3d1610cdc680e131d2cbfef10972dc6120d4dd18',
+ 'NormalTangentTest0.bin': '2d0fc6d43cb11b61a746bc80218b5e9e6c60dcc40f86d4a3f4fdbf11909cd990',
+ 'NormalTangentTest_BaseColor.png': '4182902c6dc833b48c0325568c2c5bd3e2d5fc04e27a8dc1917ced2818e1fac1',
+ 'NormalTangentTest_OcclusionRoughnessMetallic.png': '3fff511720bea1fd8590ddb7b62090700e812e39ca71dd3200493093ad704399',
+ 'NormalTangentTest_Normal.png': '9cebea6c513ddfb1f5f5c761c08bca1468d2283a3cd9772bba3a57e484862ead',
+ },
+ },
'khronos-water-bottle': {
what: 'Khronos glTF sample: a PBR bottle with base colour, normal, packed occlusion/roughness/metal and emissive maps',
license: 'CC0-1.0',
diff --git a/tools/render-host/host.ts b/tools/render-host/host.ts
index 50c4a468c..4b799341c 100644
--- a/tools/render-host/host.ts
+++ b/tools/render-host/host.ts
@@ -24,6 +24,7 @@ import {
RenderTexture, Camera, Sprite,
EditorView, EditorGrid, installEditorGrid, editorViewHalfHeight, setEditorViewHalfHeight,
ProfileRecorder, AnimatorController, Timeline, onDeviceRestored, Schedule, defineSystem,
+ textureImportSettingsFrom,
} from 'esengine';
import type { App, SceneData, SceneEntityData, PrefabData, RenderSurfaceSource } from 'esengine';
import type { ESEngineModule } from 'esengine/wasm';
@@ -278,6 +279,7 @@ async function loadScene(
assets.setAssetRefResolver((ref: string) =>
ref.startsWith(UUID_PREFIX) ? (uuidToUrl.get(ref.slice(UUID_PREFIX.length)) ?? null) : ref,
);
+ assets.setTextureImportSettingsResolver(importSettingsFromMeta(uuidToUrl));
const result = await assets.preloadSceneAssets(raw);
missing = result.missing.map((m) => m.ref);
resolved = JSON.parse(JSON.stringify(raw)) as SceneData; // resolveSceneAssetPaths mutates
@@ -311,6 +313,33 @@ interface SceneLoadReport {
missing: string[];
}
+/**
+ * A texture's import settings, read from the `.meta` beside it as the editor and an
+ * export read them; without it every texture loaded as sRGB colour. Synchronous
+ * because the loader asks synchronously, and this is a test host.
+ */
+function importSettingsFromMeta(uuidToUrl: Map<string, string>) {
+ const cache = new Map<string, ReturnType<typeof textureImportSettingsFrom>>();
+ return (ref: string) => {
+ const url = ref.startsWith(UUID_PREFIX) ? uuidToUrl.get(ref.slice(UUID_PREFIX.length)) : ref;
+ if (!url) return undefined;
+ if (!cache.has(url)) {
+ let settings: ReturnType<typeof textureImportSettingsFrom>;
+ try {
+ const xhr = new XMLHttpRequest();
+ xhr.open('GET', `${url}.meta`, false);
+ xhr.send();
+ if (xhr.status === 200) {
+ settings = textureImportSettingsFrom(
+ (JSON.parse(xhr.responseText) as { importer?: Record<string, unknown> }).importer);
+ }
+ } catch { /* no meta: the loader's defaults */ }
+ cache.set(url, settings);
+ }
+ return cache.get(url);
+ };
+}
+
async function fetchManifest(manifestUrl?: string): Promise<Map<string, string>> {
const out = new Map<string, string>();
if (!manifestUrl) return out;
diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjs
index 1463fd57f..d6d7e80ed 100644
--- a/tools/render-host/run.mjs
+++ b/tools/render-host/run.mjs
@@ -36,6 +36,7 @@
* ESTELLA_VERIFY_UNIFORM the frame is one colour on purpose; ESTELLA_VERIFY_COUNT says which
* ESTELLA_VERIFY_EDGE how straight a straight edge is drawn (JSON: box, lit, dark, maxJag)
* ESTELLA_VERIFY_CUTOUT_EDGE how often a cutout's edge pixel is a blend (JSON: box, lit, run, partial, minShare)
+ * ESTELLA_VERIFY_TWINS pairs of points that must match (JSON: pairs [[x1,y1,x2,y2]], tol)
* ESTELLA_VERIFY_MINIFIED how much a far-off texture shimmers pixel to pixel (JSON: box, maxRipple, minMean)
* ESTELLA_VERIFY_SCALE copy the scene's content onto a grid (JSON), for a cost gate
* ESTELLA_VERIFY_OUTPUT_TRANSFORM the frame's output curve ("aces")
@@ -217,7 +218,7 @@ function finish(result, server) {
// A scene that could not load an asset it names draws a frame nobody declared, so
// its pixels answer a different question — say which asset instead.
const assetsOk = (result.missingAssets?.length ?? 0) === 0;
- const ok = result.ok && renderedOk && assetsOk && (result.expect?.ok ?? true) && (result.count?.ok ?? true) &&
+ const ok = result.ok && renderedOk && assetsOk && (result.expect?.ok ?? true) && (result.twins?.ok ?? true) && (result.count?.ok ?? true) &&
(result.seam?.ok ?? true) &&
(result.resize?.ok ?? true) && (result.preview?.ok ?? true) &&
(result.meshPreview?.ok ?? true) && (result.grid?.ok ?? true) &&
@@ -751,6 +752,25 @@ app.whenReady().then(async () => {
return { points: out, ok: out.every((o) => o.ok) };
`);
}
+ // ESTELLA_VERIFY_TWINS = { pairs: [[x1, y1, x2, y2], ...], tol }: points that must match —
+ // one surface drawn two ways, as a conformance model pairs a normal-mapped bump with the
+ // same bump built as geometry. Pins only that the two agree, not the lighting.
+ let twins = null;
+ if (process.env.ESTELLA_VERIFY_TWINS) {
+ twins = await readFrame(`
+ const t = ${JSON.stringify(JSON.parse(process.env.ESTELLA_VERIFY_TWINS))};
+ const at = (x, y) => {
+ const i = (((h - 1) - Math.round(y * (h - 1))) * w + Math.round(x * (w - 1))) * 4;
+ return [px[i], px[i + 1], px[i + 2]];
+ };
+ const pairs = t.pairs.map(([x1, y1, x2, y2]) => {
+ const a = at(x1, y1), b = at(x2, y2);
+ return { a, b, d: Math.max(...a.map((v, k) => Math.abs(v - b[k]))) };
+ });
+ const worst = Math.max(...pairs.map((p) => p.d));
+ return { pairs, worst, tol: t.tol, ok: worst <= t.tol };
+ `);
+ }
// ESTELLA_VERIFY_EDGE = { box (0..1, top-left), lit, dark, maxJag }: how far each
// row's crossing of a straight edge, found from the right to sub-pixel, strays from
// a line through its neighbours — a sampling grid drawn into the edge shows as that.
@@ -1026,7 +1046,7 @@ app.whenReady().then(async () => {
`);
if (respaced != null) grid = { ...grid, respacedPixels: respaced, ok: grid.ok && respaced > 300 };
}
- finish({ ok: true, entityCount, missingAssets, drawCalls, draws, counters, frameDebug, edge, cutoutEdge, minified, profile, capture, expect, count, seam, resize, preview, meshPreview, grid, deviceLoss, roundtrip, meshResident, meshAsset, meshMaterial, meshPrefab, setField, animator, pick, cameraTarget }, server);
+ finish({ ok: true, entityCount, missingAssets, drawCalls, draws, counters, frameDebug, edge, cutoutEdge, minified, profile, capture, expect, twins, count, seam, resize, preview, meshPreview, grid, deviceLoss, roundtrip, meshResident, meshAsset, meshMaterial, meshPrefab, setField, animator, pick, cameraTarget }, server);
} catch (e) {
finish({ ok: false, error: String((e && e.stack) || e) }, server);
}
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 9a1a52763..fa5f8ddd9 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -717,6 +717,10 @@ export const SCENES = [
// with a mip chain the stripes average to a flat tint (ripple 7.8), sampling the top
// level they shimmer (17.5); 7.9 on WebGPU, 13.7 before it built a chain.
{ id: "corpus-distant-texture", tier: "pr", webgpu: true, corpora: ["khronos-alpha-blend-mode-test"], env: { ESTELLA_VERIFY_PREFAB: "/corpora/khronos-alpha-blend-mode-test/imported/AlphaBlendModeTest.esprefab", ESTELLA_VERIFY_SCENE: "/scenes/corpus-distant-texture.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/corpus-alpha-modes.textures.json", ESTELLA_VERIFY_COLORSPACE: "linear", ESTELLA_VERIFY_TEXTURES: "runtime", ESTELLA_VERIFY_W: "640", ESTELLA_VERIFY_H: "640", ESTELLA_VERIFY_STEPS: "8", ESTELLA_VERIFY_MINIFIED: "{\"box\":[0.469,0.461,0.688,0.516],\"maxRipple\":11,\"minMean\":100}" } },
+ // Khronos's NormalTangentTest: each bump as geometry and as a normal map, no tangents
+ // supplied. Off the bump's peak (where parallax parts them) the twins must agree, through
+ // the upload a shipped game uses, which gamma-decoded every normal map.
+ { id: "corpus-normal-tangent", tier: "pr", webgpu: true, corpora: ["khronos-normal-tangent-test"], env: { ESTELLA_VERIFY_PREFAB: "/corpora/khronos-normal-tangent-test/imported/NormalTangentTest.esprefab", ESTELLA_VERIFY_SCENE: "/scenes/corpus-normal-tangent.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/corpus-alpha-modes.textures.json", ESTELLA_VERIFY_COLORSPACE: "linear", ESTELLA_VERIFY_TEXTURES: "runtime", ESTELLA_VERIFY_W: "640", ESTELLA_VERIFY_H: "640", ESTELLA_VERIFY_STEPS: "8", ESTELLA_VERIFY_TWINS: "{\"pairs\": [[0.1531, 0.1652, 0.263, 0.1652], [0.1875, 0.1995, 0.2974, 0.1995], [0.2115, 0.1411, 0.3214, 0.1411], [0.1531, 0.3025, 0.263, 0.3025], [0.1875, 0.3369, 0.2974, 0.3369], [0.2115, 0.2785, 0.3214, 0.2785], [0.1531, 0.4399, 0.263, 0.4399], [0.1875, 0.4742, 0.2974, 0.4742], [0.2115, 0.4159, 0.3214, 0.4159], [0.1531, 0.5773, 0.263, 0.5773], [0.1875, 0.6116, 0.2974, 0.6116], [0.2115, 0.5532, 0.3214, 0.5532], [0.1531, 0.7146, 0.263, 0.7146], [0.1875, 0.749, 0.2974, 0.749], [0.2115, 0.6906, 0.3214, 0.6906], [0.4279, 0.1652, 0.5378, 0.1652], [0.4622, 0.1995, 0.5721, 0.1995], [0.4863, 0.1411, 0.5962, 0.1411], [0.4279, 0.3025, 0.5378, 0.3025], [0.4622, 0.3369, 0.5721, 0.3369], [0.4863, 0.2785, 0.5962, 0.2785], [0.4279, 0.4399, 0.5378, 0.4399], [0.4622, 0.4742, 0.5721, 0.4742], [0.4863, 0.4159, 0.5962, 0.4159], [0.4279, 0.5773, 0.5378, 0.5773], [0.4622, 0.6116, 0.5721, 0.6116], [0.4863, 0.5532, 0.5962, 0.5532], [0.4279, 0.7146, 0.5378, 0.7146], [0.4622, 0.749, 0.5721, 0.749], [0.4863, 0.6906, 0.5962, 0.6906]], \"tol\": 8}" } },
// Khronos's AlphaBlendModeTest (tools/corpora.mjs): the opaque box ignores its alpha, and
// each cutout box is cut exactly at its own threshold — wall above the mark, stripes below.
{ id: "corpus-alpha-modes", tier: "pr", webgpu: true, corpora: ["khronos-alpha-blend-mode-test"], env: { ESTELLA_VERIFY_PREFAB: "/corpora/khronos-alpha-blend-mode-test/imported/AlphaBlendModeTest.esprefab", ESTELLA_VERIFY_SCENE: "/scenes/corpus-alpha-modes.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/corpus-alpha-modes.textures.json", ESTELLA_VERIFY_W: "960", ESTELLA_VERIFY_H: "540", ESTELLA_VERIFY_STEPS: "8", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.2344,\"y\":0.3185,\"rgb\":[255,255,107],\"tol\":40},{\"x\":0.5135,\"y\":0.3167,\"rgb\":[255,255,255],\"tol\":40},{\"x\":0.5125,\"y\":0.4444,\"rgb\":[255,255,108],\"tol\":40},{\"x\":0.651,\"y\":0.3704,\"rgb\":[255,255,255],\"tol\":40},{\"x\":0.651,\"y\":0.487,\"rgb\":[255,255,108],\"tol\":40},{\"x\":0.7896,\"y\":0.4444,\"rgb\":[255,255,255],\"tol\":40},{\"x\":0.7875,\"y\":0.5185,\"rgb\":[107,255,255],\"tol\":40}]" } },