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(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.md
index 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 the
river; 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.esscene
index 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.mjs
index 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.md
index 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[] | undefined
factory: () => ShaderHandle
label: string
multiPass: 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: boolean
priority: number
shape: "box" | "sphere"
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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[] | undefined
factory: () => ShaderHandle
label: string
multiPass: 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: boolean
priority: number
shape: "box" | "sphere"
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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[] | undefined
factory: () => ShaderHandle
label: string
multiPass: 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: boolean
priority: number
shape: "box" | "sphere"
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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[] | undefined
factory: () => ShaderHandle
label: string
multiPass: 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: boolean
priority: number
shape: "box" | "sphere"
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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[] | undefined
factory: () => ShaderHandle
label: string
multiPass: 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: boolean
priority: number
shape: "box" | "sphere"
diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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);
+ });
+ });
});