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
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.mdindex ad6e3489b..556d8ca98 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -2366,6 +2366,7 @@ label: stringmax: numbermin: numbername: string+neutralValue: number | undefinedstep: number```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex b07bffcd2..042902e24 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -2361,6 +2361,7 @@ label: stringmax: numbermin: numbername: string+neutralValue: number | undefinedstep: number```diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex d57cda710..8a7289f46 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -2361,6 +2361,7 @@ label: stringmax: numbermin: numbername: string+neutralValue: number | undefinedstep: number```diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.tsindex 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.tsindex 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 Teamimport 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.tsindex 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([{