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(postprocess): a volume can name an effect's colour params, so fog takes a night colour
yhh77b9bcd4adab
diff --git a/examples/neon-ascension/README.md b/examples/neon-ascension/README.mdindex 88a106071..3d9c4a9ea 100644--- a/examples/neon-ascension/README.md+++ b/examples/neon-ascension/README.md@@ -18,9 +18,8 @@ scene is derived from numbers in the two scripts.## Known gaps (measured on 2026-10-15)-- `distanceFog`'s colour cannot be set from a `PostProcessVolume`: the effect- definition surfaces floats and textures only, and a colour written there- blanks the frame once bloom follows. The fog keeps its bright default.+- Fog colour is set per volume with `colors: { u_fogColor: {r,g,b,a} }` (added with this+ example; the editor inspector does not edit colour params yet).- The wet floor reflects the baked panorama only, not nearby geometry or theriver; planar reflection would be an engine addition.- At most 16 point lights are drawn per frame.diff --git a/examples/neon-ascension/assets/scenes/main.esscene b/examples/neon-ascension/assets/scenes/main.essceneindex 5759b8efc..10d3993db 100644--- a/examples/neon-ascension/assets/scenes/main.esscene+++ b/examples/neon-ascension/assets/scenes/main.esscene@@ -57,6 +57,14 @@"u_fogNear": 900,"u_fogFar": 16000,"u_intensity": 0.55+ },+ "colors": {+ "u_fogColor": {+ "r": 0.035,+ "g": 0.05,+ "b": 0.085,+ "a": 1+ }}},{diff --git a/examples/neon-ascension/tools/make-greybox.mjs b/examples/neon-ascension/tools/make-greybox.mjsindex 942619725..6b9f1c734 100644--- a/examples/neon-ascension/tools/make-greybox.mjs+++ b/examples/neon-ascension/tools/make-greybox.mjs@@ -97,7 +97,8 @@ add('Camera', [isGlobal: true, priority: 0, weight: 1,effects: [{ type: 'distanceFog', enabled: true,- uniforms: { u_fogNear: 900, u_fogFar: 16000, u_intensity: 0.55 } },+ uniforms: { u_fogNear: 900, u_fogFar: 16000, u_intensity: 0.55 },+ colors: { u_fogColor: rgba(0.035, 0.05, 0.085) } },{ type: 'ssao', enabled: true, uniforms: {} },{ type: 'bloom', enabled: true, uniforms: { u_threshold: 0.8, u_intensity: 1.6, u_radius: 1.4 } },{ type: 'colorGrade', enabled: true, uniforms: { u_contrast: 1.12, u_saturation: 1.05, u_temperature: -0.08 } },diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex a32212c2d..e0b60760d 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -3451,6 +3451,7 @@ v: WorldAxis## EffectDef — interface @experimental```+colors: EffectColorDef[] | undefinedfactory: () => ShaderHandlelabel: stringmultiPass: EffectSubPass[] | undefined@@ -6420,7 +6421,7 @@ ComponentDef<PostProcessVolumeData>## PostProcessVolumeData — interface @experimental```blendDistance: number-effects: { type: string; enabled: boolean; uniforms: Record<string, number>; textures?: Record<string, string>; }[]+effects: { type: string; enabled: boolean; uniforms: Record<string, number>; textures?: Record<string, string>; colors?: Record<string, { r: number; g: number; b: number; a: number; }>; }[]isGlobal: booleanpriority: numbershape: "box" | "sphere"diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex e6a8a1a6f..8843c34c0 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -3459,6 +3459,7 @@ v: WorldAxis## EffectDef — interface @experimental```+colors: EffectColorDef[] | undefinedfactory: () => ShaderHandlelabel: stringmultiPass: EffectSubPass[] | undefined@@ -6623,7 +6624,7 @@ ComponentDef<PostProcessVolumeData>## PostProcessVolumeData — interface @experimental```blendDistance: number-effects: { type: string; enabled: boolean; uniforms: Record<string, number>; textures?: Record<string, string>; }[]+effects: { type: string; enabled: boolean; uniforms: Record<string, number>; textures?: Record<string, string>; colors?: Record<string, { r: number; g: number; b: number; a: number; }>; }[]isGlobal: booleanpriority: numbershape: "box" | "sphere"diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex a0fa0a665..5bed73613 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -3446,6 +3446,7 @@ v: WorldAxis## EffectDef — interface @experimental```+colors: EffectColorDef[] | undefinedfactory: () => ShaderHandlelabel: stringmultiPass: EffectSubPass[] | undefined@@ -6415,7 +6416,7 @@ ComponentDef<PostProcessVolumeData>## PostProcessVolumeData — interface @experimental```blendDistance: number-effects: { type: string; enabled: boolean; uniforms: Record<string, number>; textures?: Record<string, string>; }[]+effects: { type: string; enabled: boolean; uniforms: Record<string, number>; textures?: Record<string, string>; colors?: Record<string, { r: number; g: number; b: number; a: number; }>; }[]isGlobal: booleanpriority: numbershape: "box" | "sphere"diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex d912b6ee8..1362e7b6b 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -3446,6 +3446,7 @@ v: WorldAxis## EffectDef — interface @experimental```+colors: EffectColorDef[] | undefinedfactory: () => ShaderHandlelabel: stringmultiPass: EffectSubPass[] | undefined@@ -6708,7 +6709,7 @@ ComponentDef<PostProcessVolumeData>## PostProcessVolumeData — interface @experimental```blendDistance: number-effects: { type: string; enabled: boolean; uniforms: Record<string, number>; textures?: Record<string, string>; }[]+effects: { type: string; enabled: boolean; uniforms: Record<string, number>; textures?: Record<string, string>; colors?: Record<string, { r: number; g: number; b: number; a: number; }>; }[]isGlobal: booleanpriority: numbershape: "box" | "sphere"diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 1c1534b77..f9293d4d0 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -3446,6 +3446,7 @@ v: WorldAxis## EffectDef — interface @experimental```+colors: EffectColorDef[] | undefinedfactory: () => ShaderHandlelabel: stringmultiPass: EffectSubPass[] | undefined@@ -6422,7 +6423,7 @@ ComponentDef<PostProcessVolumeData>## PostProcessVolumeData — interface @experimental```blendDistance: number-effects: { type: string; enabled: boolean; uniforms: Record<string, number>; textures?: Record<string, string>; }[]+effects: { type: string; enabled: boolean; uniforms: Record<string, number>; textures?: Record<string, string>; colors?: Record<string, { r: number; g: number; b: number; a: number; }>; }[]isGlobal: booleanpriority: numbershape: "box" | "sphere"diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.tsindex 6076b7c77..51b544d7d 100644--- a/sdk/src/ecs/component.ts+++ b/sdk/src/ecs/component.ts@@ -1279,6 +1279,9 @@ export interface PostProcessVolumeData {uniforms: Record<string, number>;/** Texture params (LUTs, masks): sampler uniform -> serialized texture ref. */textures?: Record<string, string>;+ /** Colour params (a fog colour): uniform -> RGBA. Blends like a float does,+ * toward the effect's declared default at a volume's soft edge. */+ colors?: Record<string, { r: number; g: number; b: number; a: number }>;}[];isGlobal: boolean;shape: 'box' | 'sphere';diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.tsindex 6cda0a0c0..7ea4b5eca 100644--- a/sdk/src/postprocess/effects.ts+++ b/sdk/src/postprocess/effects.ts@@ -25,6 +25,13 @@ export interface EffectTextureDef {label: string;}+/** A colour parameter (fog colour): the vec4 uniform it feeds and its default. */+export interface EffectColorDef {+ name: string;+ label: string;+ defaultValue: { r: number; g: number; b: number; a: number };+}+export interface EffectSubPass {name: string;factory: () => ShaderHandle;@@ -43,6 +50,8 @@ export interface EffectDef {uniforms: EffectUniformDef[];/** Texture params, carried on the volume as serialized refs (`textures`). */textures?: EffectTextureDef[];+ /** Colour params, carried on the volume as `colors`. */+ colors?: EffectColorDef[];multiPass?: EffectSubPass[];}@@ -204,8 +213,11 @@ registerEffect({{ name: 'u_fogFar', label: 'Far', min: 0, max: 500, step: 0.5, defaultValue: 60 },{ name: 'u_intensity', label: 'Intensity', min: 0, max: 1, step: 0.01, defaultValue: 1 },],- // u_fogColor keeps its shader default: EffectDef surfaces floats and textures,- // and a colour row is an editor surface of its own rather than part of this.+ // The default is the shader's own `#pragma param u_fogColor` default, so a+ // volume that never names the colour fogs exactly as it always did.+ colors: [+ { name: 'u_fogColor', label: 'Colour', defaultValue: { r: 0.6, g: 0.68, b: 0.78, a: 1 } },+ ],});registerEffect({diff --git a/sdk/src/postprocess/volumeBlending.ts b/sdk/src/postprocess/volumeBlending.tsindex a36620968..cb81e6c3b 100644--- a/sdk/src/postprocess/volumeBlending.ts+++ b/sdk/src/postprocess/volumeBlending.ts@@ -21,8 +21,20 @@ export interface BlendedEffect {/** Texture params (sampler uniform -> serialized texture ref). Textures don't* interpolate: the last volume in priority order that sets one wins. */textures: Map<string, string>;+ /** Colour params (uniform -> RGBA), blended like the floats are. */+ colors: Map<string, Rgba>;}+export interface Rgba { r: number; g: number; b: number; a: number }++// `from*(1-t)+to*t`, not `from+(to-from)*t`: at t=1 this is exactly `to`.+const lerpRgba = (from: Rgba, to: Rgba, t: number): Rgba => ({+ r: from.r * (1 - t) + to.r * t,+ g: from.g * (1 - t) + to.g * t,+ b: from.b * (1 - t) + to.b * t,+ a: from.a * (1 - t) + to.a * t,+});+/*** Signed distance to a box, in three dimensions. `halfD` of **0 is unbounded*** depth — what a flat scene's box has always been, and the only reading that@@ -118,7 +130,16 @@ export function blendVolumeEffects(if (ref) textures.set(key, ref);}}- result.set(effect.type, { enabled: true, uniforms, textures });+ // A colour fades from the effect's declared default, as a float fades+ // from its neutral: a half-weight volume is half the way to its colour.+ const colors = new Map<string, Rgba>();+ if (effect.colors) {+ for (const [key, value] of Object.entries(effect.colors)) {+ const base = def?.colors?.find((c) => c.name === key)?.defaultValue ?? value;+ colors.set(key, lerpRgba(base, value, factor));+ }+ }+ result.set(effect.type, { enabled: true, uniforms, textures, colors });} else {if (effect.textures) {for (const [key, ref] of Object.entries(effect.textures)) {@@ -129,6 +150,14 @@ export function blendVolumeEffects(const prev = existing.uniforms.get(key) ?? 0;existing.uniforms.set(key, prev + (value - prev) * factor);}+ if (effect.colors) {+ const def = getEffectDef(effect.type);+ for (const [key, value] of Object.entries(effect.colors)) {+ const prev = existing.colors.get(key)+ ?? def?.colors?.find((c) => c.name === key)?.defaultValue ?? value;+ existing.colors.set(key, lerpRgba(prev, value, factor));+ }+ }}}}diff --git a/sdk/src/postprocess/volumeSystem.ts b/sdk/src/postprocess/volumeSystem.tsindex 5d163a736..5649c5b53 100644--- a/sdk/src/postprocess/volumeSystem.ts+++ b/sdk/src/postprocess/volumeSystem.ts@@ -7,7 +7,7 @@ import type { Entity } from '../types';import { PostProcessVolume, Transform, Camera, type PostProcessVolumeData, type TransformData, type CameraData } from '../ecs/component';import { PostProcess, type PostProcessAPI } from './PostProcessAPI';import { getEffectDef } from './effects';-import { blendVolumeEffects, computeVolumeFactor, type ActiveVolume, type VolumeTransform } from './volumeBlending';+import { blendVolumeEffects, computeVolumeFactor, type ActiveVolume, type BlendedEffect, type VolumeTransform } from './volumeBlending';import type { ShaderHandle } from '../render/material';import { Material } from '../render/material';@@ -49,7 +49,17 @@ function applyTextures(}}-type ResolvedEffects = Map<string, { enabled: boolean; uniforms: Map<string, number>; textures: Map<string, string> }>;+type ResolvedEffects = Map<string, BlendedEffect>;++function applyColors(+ stack: ReturnType<PostProcessAPI['createStack']>,+ passName: string,+ colors: BlendedEffect['colors'],+): void {+ for (const [uniformName, c] of colors) {+ stack.setUniformVec4(passName, uniformName, { x: c.r, y: c.g, z: c.b, w: c.a });+ }+}// Per-stack signature of the last-applied effect set, so an unchanged frame can// skip the whole wasm-boundary rebuild. Keyed by the stack object (auto-cleared@@ -65,6 +75,8 @@ function effectsSignature(effects: ResolvedEffects): string {for (const [k, v] of data.uniforms) sig += k + '=' + v + ';';sig += '|';for (const [k, ref] of data.textures) sig += k + '=' + ref + ';';+ sig += '|';+ for (const [k, c] of data.colors) sig += k + '=' + c.r + ',' + c.g + ',' + c.b + ',' + c.a + ';';sig += '#';}return sig;@@ -114,6 +126,7 @@ function applyBlendedEffects(stack.setUniform(subPass.name, uniformName, uniformValue);}applyTextures(stack, subPass.name, effectData.textures);+ applyColors(stack, subPass.name, effectData.colors);}} else {const shader = getOrCreateShader(api, effectType, def.factory);@@ -122,6 +135,7 @@ function applyBlendedEffects(stack.setUniform(effectType, uniformName, uniformValue);}applyTextures(stack, effectType, effectData.textures);+ applyColors(stack, effectType, effectData.colors);}}@@ -163,7 +177,7 @@ export const postProcessVolumeSystem = defineSystem(const blended = activeVolumes.length > 0? blendVolumeEffects(activeVolumes)- : new Map<string, { enabled: boolean; uniforms: Map<string, number>; textures: Map<string, string> }>();+ : new Map() as ResolvedEffects;applyBlendedEffects(api, cameraEntity, blended);}diff --git a/sdk/tests/volumeBlending.test.ts b/sdk/tests/volumeBlending.test.tsindex 23ae09167..6ee19c31a 100644--- a/sdk/tests/volumeBlending.test.ts+++ b/sdk/tests/volumeBlending.test.ts@@ -424,4 +424,42 @@ describe('volumeBlending', () => {expect(blended.get('blur')?.uniforms.get('u_intensity')).toBeCloseTo(2.5, 5);});});++ describe('colour params', () => {+ const volume = (colors: Record<string, { r: number; g: number; b: number; a: number }> | undefined) => ({+ effects: [{ type: 'distanceFog', enabled: true, uniforms: {}, ...(colors ? { colors } : {}) }],+ isGlobal: true, shape: 'box' as const, size: { x: 5, y: 5 }, priority: 0, weight: 1, blendDistance: 0,+ });+ const night = { r: 0.05, g: 0.07, b: 0.1, a: 1 };++ it('carries the volume colour through at full weight', () => {+ const fog = blendVolumeEffects([{ data: volume({ u_fogColor: night }), factor: 1 }]).get('distanceFog')!;+ expect(fog.colors.get('u_fogColor')).toEqual(night);+ });++ it('fades from the effect default, not from black, at partial weight', () => {+ const fog = blendVolumeEffects([{ data: volume({ u_fogColor: night }), factor: 0.5 }]).get('distanceFog')!;+ const c = fog.colors.get('u_fogColor')!;+ expect(c.r).toBeCloseTo((0.6 + 0.05) / 2, 5);+ expect(c.g).toBeCloseTo((0.68 + 0.07) / 2, 5);+ expect(c.b).toBeCloseTo((0.78 + 0.1) / 2, 5);+ });++ it('lets a later volume pull the colour toward its own by its factor', () => {+ const warm = { r: 1, g: 0.5, b: 0, a: 1 };+ const later = { ...volume({ u_fogColor: warm }), priority: 1 };+ const fog = blendVolumeEffects([+ { data: volume({ u_fogColor: night }), factor: 1 },+ { data: later, factor: 0.5 },+ ]).get('distanceFog')!;+ const c = fog.colors.get('u_fogColor')!;+ expect(c.r).toBeCloseTo((0.05 + 1) / 2, 5);+ expect(c.g).toBeCloseTo((0.07 + 0.5) / 2, 5);+ });++ it('leaves a volume that names no colour with none to apply', () => {+ const fog = blendVolumeEffects([{ data: volume(undefined), factor: 1 }]).get('distanceFog')!;+ expect(fog.colors.size).toBe(0);+ });+ });});