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(sdk): volume blend fades to each param's neutral, honors global weight

esengine6ce5880b18a6
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index ad6e3489b..556d8ca98 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -2366,6 +2366,7 @@ label: string
max: number
min: number
name: string
+neutralValue: number | undefined
step: number
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index b07bffcd2..042902e24 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -2361,6 +2361,7 @@ label: string
max: number
min: number
name: string
+neutralValue: number | undefined
step: number
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index d57cda710..8a7289f46 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -2361,6 +2361,7 @@ label: string
max: number
min: number
name: string
+neutralValue: number | undefined
step: number
```
diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.ts
index f863c502e..d9c02d633 100644
--- a/sdk/src/postprocess/effects.ts
+++ b/sdk/src/postprocess/effects.ts
@@ -10,6 +10,13 @@ export interface EffectUniformDef {
max: number;
step: number;
defaultValue: number;
+ /**
+ * The "effect does nothing" value a partial-weight volume blend fades toward.
+ * 0 for additive/intensity params (default); 1 for MULTIPLICATIVE params
+ * (contrast, saturation, zoom) — blending those from 0 crushes the image to
+ * black / extreme distortion at a volume's soft edge.
+ */
+ neutralValue?: number;
}
/** A texture parameter (LUT, mask): the sampler uniform it binds to. */
@@ -107,8 +114,8 @@ registerEffect({
factory: () => postProcessEffects.createColorGrade(),
uniforms: [
{ name: 'u_exposure', label: 'Exposure', min: -3, max: 3, step: 0.05, defaultValue: 0 },
- { name: 'u_contrast', label: 'Contrast', min: 0, max: 2, step: 0.01, defaultValue: 1 },
- { name: 'u_saturation', label: 'Saturation', min: 0, max: 2, step: 0.01, defaultValue: 1 },
+ { name: 'u_contrast', label: 'Contrast', min: 0, max: 2, step: 0.01, defaultValue: 1, neutralValue: 1 },
+ { name: 'u_saturation', label: 'Saturation', min: 0, max: 2, step: 0.01, defaultValue: 1, neutralValue: 1 },
{ name: 'u_temperature', label: 'Temperature', min: -1, max: 1, step: 0.01, defaultValue: 0 },
{ name: 'u_tint', label: 'Tint', min: -1, max: 1, step: 0.01, defaultValue: 0 },
],
@@ -147,7 +154,7 @@ registerEffect({
factory: () => postProcessEffects.createLensDistortion(),
uniforms: [
{ name: 'u_strength', label: 'Strength', min: -1, max: 1, step: 0.01, defaultValue: 0 },
- { name: 'u_zoom', label: 'Zoom', min: 0.5, max: 2, step: 0.01, defaultValue: 1 },
+ { name: 'u_zoom', label: 'Zoom', min: 0.5, max: 2, step: 0.01, defaultValue: 1, neutralValue: 1 },
],
});
diff --git a/sdk/src/postprocess/volumeBlending.ts b/sdk/src/postprocess/volumeBlending.ts
index 876c74dea..c8de21743 100644
--- a/sdk/src/postprocess/volumeBlending.ts
+++ b/sdk/src/postprocess/volumeBlending.ts
@@ -1,6 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { PostProcessVolumeData } from '../component';
+import { getEffectDef } from './effects';
export interface VolumeTransform {
x: number;
@@ -48,7 +49,7 @@ export function computeVolumeFactor(
px: number, py: number
): number {
if (volume.isGlobal) {
- return 1;
+ return volume.weight; // honor the global's weight, like local volumes below
}
let dist: number;
@@ -88,9 +89,14 @@ export function blendVolumeEffects(
const existing = result.get(effect.type);
if (!existing) {
+ // Blend from each param's neutral ("effect does nothing") value, not
+ // from 0 — else a multiplicative param (contrast/saturation/zoom,
+ // neutral 1) fades to 0 (black / extreme distortion) at the edge.
+ const def = getEffectDef(effect.type);
const uniforms = new Map<string, number>();
for (const [key, value] of Object.entries(effect.uniforms)) {
- uniforms.set(key, value * factor);
+ const neutral = def?.uniforms.find((u) => u.name === key)?.neutralValue ?? 0;
+ uniforms.set(key, neutral + (value - neutral) * factor);
}
const textures = new Map<string, string>();
if (effect.textures) {
diff --git a/sdk/tests/volumeBlending.test.ts b/sdk/tests/volumeBlending.test.ts
index a712960a3..3d728f273 100644
--- a/sdk/tests/volumeBlending.test.ts
+++ b/sdk/tests/volumeBlending.test.ts
@@ -75,6 +75,14 @@ describe('volumeBlending', () => {
expect(factor).toBe(1);
});
+ it('honors a global volume\'s weight (not always 1)', () => {
+ const volume = {
+ effects: [], isGlobal: true, shape: 'box' as const,
+ size: { x: 5, y: 5 }, priority: 0, weight: 0.5, blendDistance: 0,
+ };
+ expect(computeVolumeFactor(volume, baseTransform, 100, 100)).toBeCloseTo(0.5, 5);
+ });
+
it('returns weight when point is inside box volume', () => {
const volume = {
effects: [],
@@ -189,6 +197,26 @@ describe('volumeBlending', () => {
expect(blur.uniforms.get('u_intensity')).toBe(5);
});
+ it('blends a multiplicative param from its neutral (1), an intensity param from 0', () => {
+ const result = blendVolumeEffects([
+ {
+ data: {
+ effects: [
+ { type: 'colorGrade', enabled: true, uniforms: { u_contrast: 2 } },
+ { type: 'blur', enabled: true, uniforms: { u_intensity: 4 } },
+ ],
+ isGlobal: true, shape: 'box', size: { x: 5, y: 5 },
+ priority: 0, weight: 1, blendDistance: 0,
+ },
+ factor: 0.25, // partially active (a soft volume edge)
+ },
+ ]);
+ // contrast neutral is 1: 1 + (2-1)*0.25 = 1.25 (NOT 2*0.25 = 0.5, which crushes to grey).
+ expect(result.get('colorGrade')!.uniforms.get('u_contrast')).toBeCloseTo(1.25, 5);
+ // intensity neutral is 0: 0 + (4-0)*0.25 = 1 (unchanged fade-from-off behavior).
+ expect(result.get('blur')!.uniforms.get('u_intensity')).toBeCloseTo(1, 5);
+ });
+
it('higher priority volume overrides lower priority', () => {
const result = blendVolumeEffects([
{