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): 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.mdindex 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.mdxindex 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 thechain can be: they all run on scene values, before it. The **Display LUT** effect (`displayLut`) is the last pass's own stage: the picture iscurved, 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 thediff --git a/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdxindex 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.tsindex 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.tsnew file mode 100644index 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.mjsindex 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":