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(assets): an image shaped like a colour lookup table is adopted as data, uncompressed, unmipped and not sRGB

yhhc78706473482
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 288d0aa93..a55fa14b2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ published separately; it ships inside the editor.
### Added
+- **A lookup table is adopted as data.** A PNG shaped like a colour lookup table (N slices of N by N: 1024 by 32, 256 by 16, 4096 by 64) is given no compression, no mips, no sRGB decode and clamped edges when it is added to a project, where it used to take the picture defaults and answer wrongly until someone found why.
- **An Outdoor Environment to create.** **Create → Rendering → Outdoor Environment** makes a sun, a sky light, a clock, a weather and a global volume with the sky (clouds that cast shadows), the haze (beams in their gaps) and a plain grade, already pointing at one another. It is the arrangement the Terrain & Water example uses, for the engine's scale of a hundred units to the metre.
- **An Online 3D starter.** A template for a networked 3D game: a lit ground, a pawn per player predicted on its owner's screen and replicated to the others, a camera that follows your own, and a `server/` that runs the same project headless. The rules both ends agree on are one module, `src/shared/rules.ts`. `tools/check-arena-server.mjs` now takes `--project`, and runs against this template too.
- **Start a project from the command line.** `estella create <template> <dir> [--name]` makes a project from any starter or example, and `estella templates` lists them. The editor's New project gallery and the command line now share one implementation (`pipeline/src/project/scaffold.ts`), so both copy the same files and write the same `package.json` and `.gitignore`.
diff --git a/docs/astro/src/content/docs/graphics/post-processing.mdx b/docs/astro/src/content/docs/graphics/post-processing.mdx
index 93c372bbc..47350d61d 100644
--- a/docs/astro/src/content/docs/graphics/post-processing.mdx
+++ b/docs/astro/src/content/docs/graphics/post-processing.mdx
@@ -407,8 +407,7 @@ needs no reload. In code: `outputTransform: 'none' | 'aces' | 'neutral'`.
A look authored against the finished picture (a warm LUT from a colourist, a film emulation) belongs after the curve, and no effect in the
chain can be: they all run on scene values, before it. The **Display LUT** effect (`displayLut`) is the last pass's own stage: the picture is
curved, encoded for the display, and then read off a 1024x32 table by the colour it will show: 32 slices along x, blue the slice, red along a slice and green up the picture (an image is read from its bottom).
-It adds a texture read to the pass that was running anyway, not a pass, whatever the output transform. Give the table's texture no compression,
-no mips and no sRGB: it is data. In code, `stack.setDisplayLut(textureHandle, amount)`.
+It adds a texture read to the pass that was running anyway, not a pass, whatever the output transform. A table's texture is data: no compression, no mips and no sRGB. An image of that shape (N slices of N by N, so 1024 by 32 for 32) is adopted with those settings on its own, in the editor and from the command line. In code, `stack.setDisplayLut(textureHandle, amount)`.
<Aside>
The `tonemap` *effect* in the list above is a separate, optional ACES pass inside the
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx
index 121b35257..8b48e09b2 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx
@@ -300,7 +300,7 @@ registerEffect({
对着成品画面做的调色(调色师给的暖色 LUT、胶片模拟)应该排在曲线之后,而效果链里的任何效果都做不到:它们都跑在
场景值上,在曲线之前。**显示 LUT**(`displayLut`)是最后一个通道自己的阶段:画面先过曲线,再为显示器编码,然后按它将要
显示的颜色从一张 1024x32 的表里取值:沿 x 排 32 片,蓝是片号,红沿片内 x 增大,绿沿图像向上增大(图像从最下面一行读起)。它是在本来就要跑的那个通道里多读一次纹理,不是多一个通道,
-和输出变换是哪个无关。表的纹理不要压缩、不要 mip、不要 sRGB:它是数据。代码里是 `stack.setDisplayLut(textureHandle, amount)`。
+和输出变换是哪个无关。表的纹理是数据:不压缩、不要 mip、不要 sRGB。符合这个形状的图(N 片 N×N,32 片就是 1024×32)被加入项目时会自动按这些设置建立,编辑器里和命令行里都一样。代码里是 `stack.setDisplayLut(textureHandle, amount)`。
<Aside>
上面列表里的 `tonemap` *效果*是效果链里一个单独的、可选的 ACES 通道。设了输出变换之后,通常既不需要它,也不需要第二条曲线:
diff --git a/pipeline/src/assets/assetMeta.ts b/pipeline/src/assets/assetMeta.ts
index 50a9e5e51..db136ed59 100644
--- a/pipeline/src/assets/assetMeta.ts
+++ b/pipeline/src/assets/assetMeta.ts
@@ -67,6 +67,30 @@ export function mintMeta(type: string, importer?: Record<string, unknown>): Reco
};
}
+/**
+ * What a colour lookup table's image needs, or null for any other image: a strip of N slices of N by N, so N squared wide and N high
+ * (1024 by 32 for 32, the size the LUT effects read). It is data and not a picture: compressing it, mipping it or decoding it as
+ * sRGB colour changes what it answers, and nothing about the image says so. A stranger's 1024 by 32 sprite strip is the price of knowing.
+ */
+export async function lutStripImporter(absFile: string): Promise<Record<string, unknown> | null> {
+ if (!absFile.toLowerCase().endsWith('.png')) return null;
+ let handle: Awaited<ReturnType<typeof open>> | undefined;
+ try {
+ handle = await open(absFile, 'r');
+ const head = Buffer.alloc(24);
+ const { bytesRead } = await handle.read(head, 0, 24, 0);
+ // The IHDR chunk: the signature, then the width and the height as big-endian words at 16 and 20.
+ if (bytesRead < 24 || head.readUInt32BE(0) !== 0x89504e47) return null;
+ const width = head.readUInt32BE(16), height = head.readUInt32BE(20);
+ if (![16, 32, 64].includes(height) || width !== height * height) return null;
+ return { compress: 'off', mipmaps: false, sRGB: false, filterMode: 'linear', wrapMode: 'clamp', maxSize: width };
+ } catch {
+ return null;
+ } finally {
+ await handle?.close();
+ }
+}
+
/**
* Adopt an orphan: mint `<absFile>.meta` iff the file has none and it resolves
* to a known asset type. Returns what happened, so callers can count adoptions /
@@ -77,6 +101,8 @@ export async function adoptOrphan(absFile: string,
if (existsSync(absFile + META_EXT)) return 'has-meta';
const type = await metaTypeForFile(absFile);
if (!type) return 'unknown-type';
+ // What the file's own shape says comes first, and what an importing source asked for over it.
+ if (type === 'texture') importer = { ...(await lutStripImporter(absFile) ?? {}), ...importer };
// Exclusive: the file's creator may have written its sidecar since the check, and
// the uuid it handed out is the one refs point at.
try {
diff --git a/pipeline/tests/asset-meta-lut.test.ts b/pipeline/tests/asset-meta-lut.test.ts
new file mode 100644
index 000000000..4aaa6e79f
--- /dev/null
+++ b/pipeline/tests/asset-meta-lut.test.ts
@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A colour lookup table dropped into a project is adopted as the data it is: no compression, no mips, no sRGB decode.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { adoptOrphan, lutStripImporter } from '../src/assets/assetMeta';
+import { solidPng } from './fixtures/solidPng.mjs';
+
+let dir = '';
+beforeEach(() => { dir = mkdtempSync(path.join(tmpdir(), 'estella-lut-')); });
+afterEach(() => { rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); });
+
+const write = (name: string, w: number, h: number): string => {
+ const file = path.join(dir, name);
+ writeFileSync(file, solidPng(w, h, [128, 128, 128, 255]));
+ return file;
+};
+const importerOf = (file: string) => JSON.parse(readFileSync(`${file}.meta`, 'utf8')).importer as Record<string, unknown>;
+
+describe('a lookup-table strip', () => {
+ it('is recognised by its shape: N slices of N by N, N squared wide and N high', async () => {
+ for (const n of [16, 32, 64]) expect(await lutStripImporter(write(`lut${n}.png`, n * n, n))).not.toBeNull();
+ for (const [w, h] of [[512, 512], [1024, 64], [1024, 31], [32, 1024]]) expect(await lutStripImporter(write(`other-${w}x${h}.png`, w, h))).toBeNull();
+ });
+
+ it('is adopted as data, and any other image keeps the defaults', async () => {
+ const lut = write('warm.png', 1024, 32);
+ expect(await adoptOrphan(lut)).toBe('adopted');
+ expect(importerOf(lut)).toMatchObject({ compress: 'off', mipmaps: false, sRGB: false, wrapMode: 'clamp', filterMode: 'linear' });
+ const picture = write('picture.png', 512, 512);
+ await adoptOrphan(picture);
+ expect(importerOf(picture)).toMatchObject({ mipmaps: true, sRGB: true, wrapMode: 'repeat' });
+ });
+
+ it('gives way to what an importing source asked for, and to a file that already has a meta', async () => {
+ const lut = write('asked.png', 1024, 32);
+ await adoptOrphan(lut, { wrapMode: 'repeat' });
+ expect(importerOf(lut)).toMatchObject({ wrapMode: 'repeat', mipmaps: false });
+ expect(await adoptOrphan(lut)).toBe('has-meta');
+ });
+
+ it('is not a PNG, or not a readable file: nothing', async () => {
+ const notPng = path.join(dir, 'x.jpg');
+ writeFileSync(notPng, Buffer.alloc(40));
+ expect(await lutStripImporter(notPng)).toBeNull();
+ expect(await lutStripImporter(path.join(dir, 'missing.png'))).toBeNull();
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 4bad0457c..f6b4ee508 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2882,6 +2882,8 @@ export const NOTED = {
{"internal":"Gate and test follow the code they check."},
"feat(editor): Create offers an Outdoor Environment, the sky, haze, clock and weather already pointing at one another":
{"note":"An Outdoor Environment to create."},
+ "feat(assets): an image shaped like a colour lookup table is adopted as data, uncompressed, unmipped and not sRGB":
+ {"note":"A lookup table is adopted as data."},
"feat(water): two tiled, scrolling detail normal maps give the surface its sparkle":
{"note":"Sparkle on the water."},
"fix(lod): a LODGroup with only a cull size is no longer ignored":