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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect } from 'vitest';
import {
signedDistanceBox,
signedDistanceSphere,
computeVolumeFactor,
blendVolumeEffects,
} from '../src/postprocess/volumeBlending';
describe('volumeBlending', () => {
describe('signedDistanceBox', () => {
it('returns negative distance when point is inside box', () => {
const dist = signedDistanceBox(0, 0, 0, 0, 0, 0, 5, 5, 0);
expect(dist).toBeLessThan(0);
});
it('returns 0 when point is on box edge', () => {
const dist = signedDistanceBox(5, 0, 0, 0, 0, 0, 5, 5, 0);
expect(dist).toBeCloseTo(0, 5);
});
it('returns positive distance when point is outside box', () => {
const dist = signedDistanceBox(8, 0, 0, 0, 0, 0, 5, 5, 0);
expect(dist).toBeCloseTo(3, 5);
});
it('handles offset center', () => {
const dist = signedDistanceBox(15, 10, 0, 10, 10, 0, 5, 5, 0);
expect(dist).toBeCloseTo(0, 5);
});
it('handles point at corner outside', () => {
const dist = signedDistanceBox(8, 8, 0, 0, 0, 0, 5, 5, 0);
expect(dist).toBeCloseTo(Math.sqrt(9 + 9), 5);
});
});
// A volume is a volume of world, not a column through it. The cases above are
// these functions with a shared depth; a `0` half-depth is what keeps a flat
// scene's box reaching through every depth, as it always did.
describe('depth', () => {
it('a box with a half-depth excludes what is outside it', () => {
expect(signedDistanceBox(0, 0, 0, 0, 0, 0, 5, 5, 5)).toBeLessThan(0);
expect(signedDistanceBox(0, 0, 9, 0, 0, 0, 5, 5, 5)).toBeCloseTo(4);
});
it('a box with no half-depth reaches through every depth', () => {
expect(signedDistanceBox(0, 0, 900, 0, 0, 0, 5, 5, 0)).toBeLessThan(0);
});
it('a sphere is a sphere, not a cylinder', () => {
expect(signedDistanceSphere(0, 0, 9, 0, 0, 0, 5)).toBeCloseTo(4);
expect(signedDistanceSphere(0, 0, 3, 0, 0, 0, 5)).toBeCloseTo(-2);
});
it('a camera two floors up is outside a volume on this one', () => {
const volume = {
effects: [], isGlobal: false, shape: 'sphere' as const,
size: { x: 50, y: 50 }, priority: 0, weight: 1, blendDistance: 0,
};
const here = computeVolumeFactor(volume, { x: 0, y: 0, z: 0 }, 0, 0, 0);
const upstairs = computeVolumeFactor(volume, { x: 0, y: 0, z: 0 }, 0, 0, 400);
expect(here).toBe(1);
expect(upstairs).toBe(0);
});
});
describe('signedDistanceSphere', () => {
it('returns negative distance when point is inside sphere', () => {
const dist = signedDistanceSphere(1, 0, 0, 0, 0, 0, 5);
expect(dist).toBeCloseTo(-4, 5);
});
it('returns 0 when point is on sphere edge', () => {
const dist = signedDistanceSphere(5, 0, 0, 0, 0, 0, 5);
expect(dist).toBeCloseTo(0, 5);
});
it('returns positive distance when point is outside sphere', () => {
const dist = signedDistanceSphere(8, 0, 0, 0, 0, 0, 5);
expect(dist).toBeCloseTo(3, 5);
});
it('handles offset center', () => {
const dist = signedDistanceSphere(15, 10, 0, 10, 10, 0, 5);
expect(dist).toBeCloseTo(0, 5);
});
});
describe('computeVolumeFactor', () => {
const baseTransform = { x: 0, y: 0 };
it('returns 1 for global volumes', () => {
const volume = {
effects: [],
isGlobal: true,
shape: 'box' as const,
size: { x: 5, y: 5 },
priority: 0,
weight: 1,
blendDistance: 0,
};
const factor = computeVolumeFactor(volume, baseTransform, 100, 100);
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: [],
isGlobal: false,
shape: 'box' as const,
size: { x: 5, y: 5 },
priority: 0,
weight: 0.8,
blendDistance: 0,
};
const factor = computeVolumeFactor(volume, baseTransform, 0, 0);
expect(factor).toBeCloseTo(0.8, 5);
});
it('returns 0 when point is outside box volume with no blend distance', () => {
const volume = {
effects: [],
isGlobal: false,
shape: 'box' as const,
size: { x: 5, y: 5 },
priority: 0,
weight: 1,
blendDistance: 0,
};
const factor = computeVolumeFactor(volume, baseTransform, 10, 0);
expect(factor).toBe(0);
});
it('returns interpolated factor within blend distance', () => {
const volume = {
effects: [],
isGlobal: false,
shape: 'box' as const,
size: { x: 5, y: 5 },
priority: 0,
weight: 1,
blendDistance: 4,
};
const factor = computeVolumeFactor(volume, baseTransform, 7, 0);
expect(factor).toBeCloseTo(0.5, 5);
});
it('returns 0 when point is beyond blend distance', () => {
const volume = {
effects: [],
isGlobal: false,
shape: 'box' as const,
size: { x: 5, y: 5 },
priority: 0,
weight: 1,
blendDistance: 2,
};
const factor = computeVolumeFactor(volume, baseTransform, 10, 0);
expect(factor).toBe(0);
});
it('works with sphere shape', () => {
const volume = {
effects: [],
isGlobal: false,
shape: 'sphere' as const,
size: { x: 5, y: 5 },
priority: 0,
weight: 1,
blendDistance: 0,
};
const factor = computeVolumeFactor(volume, baseTransform, 3, 0);
expect(factor).toBeCloseTo(1, 5);
});
it('returns 0 for sphere when outside', () => {
const volume = {
effects: [],
isGlobal: false,
shape: 'sphere' as const,
size: { x: 5, y: 5 },
priority: 0,
weight: 1,
blendDistance: 0,
};
const factor = computeVolumeFactor(volume, baseTransform, 10, 0);
expect(factor).toBe(0);
});
});
describe('blendVolumeEffects', () => {
const volumeOf = (uniforms: Record<string, unknown>, colors?: Record<string, unknown>) => ({
data: {
effects: [{ type: 'heightFog', enabled: true, uniforms, ...(colors ? { colors } : {}) }],
isGlobal: true, shape: 'box', size: { x: 5, y: 5 }, priority: 0, weight: 1, blendDistance: 0,
} as never,
factor: 1,
});
it('reads a colour written among the uniforms as the colour it is, not as NaN', () => {
const fog = blendVolumeEffects([volumeOf({ u_density: 0.01, u_fogColor: { r: 0.5, g: 0.6, b: 0.7, a: 1 } })]).get('heightFog')!;
expect(fog.uniforms.has('u_fogColor')).toBe(false);
expect(fog.colors.get('u_fogColor')).toEqual({ r: 0.5, g: 0.6, b: 0.7, a: 1 });
expect([...fog.uniforms.values()].every(Number.isFinite)).toBe(true);
});
it('lets the colours block win over the same colour among the uniforms', () => {
const fog = blendVolumeEffects([volumeOf({ u_fogColor: { r: 1, g: 0, b: 0, a: 1 } }, { u_fogColor: { r: 0, g: 0, b: 1, a: 1 } })]).get('heightFog')!;
expect(fog.colors.get('u_fogColor')).toEqual({ r: 0, g: 0, b: 1, a: 1 });
});
it('leaves out a uniform that is not a number', () => {
const fog = blendVolumeEffects([volumeOf({ u_density: 'thick', u_startDistance: 2 })]).get('heightFog')!;
expect(fog.uniforms.has('u_density')).toBe(false);
expect(fog.uniforms.get('u_startDistance')).toBe(2);
});
it('returns empty map when no active volumes', () => {
const result = blendVolumeEffects([]);
expect(result.size).toBe(0);
});
it('returns single volume effects when only one active', () => {
const result = blendVolumeEffects([
{
data: {
effects: [
{ type: 'blur', enabled: true, uniforms: { u_intensity: 5 } },
],
isGlobal: true,
shape: 'box',
size: { x: 5, y: 5 },
priority: 0,
weight: 1,
blendDistance: 0,
},
factor: 1,
},
]);
expect(result.size).toBe(1);
const blur = result.get('blur')!;
expect(blur.enabled).toBe(true);
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([
{
data: {
effects: [
{ type: 'blur', enabled: true, uniforms: { u_intensity: 2 } },
],
isGlobal: true,
shape: 'box',
size: { x: 5, y: 5 },
priority: 0,
weight: 1,
blendDistance: 0,
},
factor: 1,
},
{
data: {
effects: [
{ type: 'blur', enabled: true, uniforms: { u_intensity: 10 } },
],
isGlobal: true,
shape: 'box',
size: { x: 5, y: 5 },
priority: 1,
weight: 1,
blendDistance: 0,
},
factor: 1,
},
]);
const blur = result.get('blur')!;
expect(blur.uniforms.get('u_intensity')).toBe(10);
});
it('lerps uniforms based on factor', () => {
const result = blendVolumeEffects([
{
data: {
effects: [
{ type: 'blur', enabled: true, uniforms: { u_intensity: 0 } },
],
isGlobal: true,
shape: 'box',
size: { x: 5, y: 5 },
priority: 0,
weight: 1,
blendDistance: 0,
},
factor: 1,
},
{
data: {
effects: [
{ type: 'blur', enabled: true, uniforms: { u_intensity: 10 } },
],
isGlobal: true,
shape: 'box',
size: { x: 5, y: 5 },
priority: 1,
weight: 1,
blendDistance: 0,
},
factor: 0.5,
},
]);
const blur = result.get('blur')!;
expect(blur.uniforms.get('u_intensity')).toBeCloseTo(5, 5);
});
it('combines different effect types from multiple volumes', () => {
const result = blendVolumeEffects([
{
data: {
effects: [
{ type: 'blur', enabled: true, uniforms: { u_intensity: 5 } },
],
isGlobal: true,
shape: 'box',
size: { x: 5, y: 5 },
priority: 0,
weight: 1,
blendDistance: 0,
},
factor: 1,
},
{
data: {
effects: [
{ type: 'vignette', enabled: true, uniforms: { u_intensity: 0.8 } },
],
isGlobal: true,
shape: 'box',
size: { x: 5, y: 5 },
priority: 1,
weight: 1,
blendDistance: 0,
},
factor: 1,
},
]);
expect(result.size).toBe(2);
expect(result.has('blur')).toBe(true);
expect(result.has('vignette')).toBe(true);
});
it('disabled effects are not included', () => {
const result = blendVolumeEffects([
{
data: {
effects: [
{ type: 'blur', enabled: false, uniforms: { u_intensity: 5 } },
],
isGlobal: true,
shape: 'box',
size: { x: 5, y: 5 },
priority: 0,
weight: 1,
blendDistance: 0,
},
factor: 1,
},
]);
expect(result.size).toBe(0);
});
it('zero factor volume does not contribute', () => {
const result = blendVolumeEffects([
{
data: {
effects: [
{ type: 'blur', enabled: true, uniforms: { u_intensity: 10 } },
],
isGlobal: true,
shape: 'box',
size: { x: 5, y: 5 },
priority: 0,
weight: 1,
blendDistance: 0,
},
factor: 0,
},
]);
expect(result.size).toBe(0);
});
});
describe('local volume gating (per-camera integration shape)', () => {
const localBlur = {
effects: [{ type: 'blur', enabled: true, uniforms: { u_intensity: 5 } }],
isGlobal: false,
shape: 'box' as const,
size: { x: 100, y: 100 },
priority: 0,
weight: 1,
blendDistance: 0,
};
it('camera inside the volume applies its effect', () => {
const factor = computeVolumeFactor(localBlur, { x: 0, y: 0 }, 0, 0);
const blended = blendVolumeEffects([{ data: localBlur, factor }]);
expect(blended.get('blur')?.uniforms.get('u_intensity')).toBeCloseTo(5, 5);
});
it('camera outside the volume applies nothing', () => {
const factor = computeVolumeFactor(localBlur, { x: 0, y: 0 }, 500, 0);
const active = factor > 0 ? [{ data: localBlur, factor }] : [];
expect(blendVolumeEffects(active).size).toBe(0);
});
it('camera in the blend band applies a partial effect', () => {
const feathered = { ...localBlur, blendDistance: 50 };
const factor = computeVolumeFactor(feathered, { x: 0, y: 0 }, 125, 0);
const blended = blendVolumeEffects([{ data: feathered, factor }]);
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);
});
});
});
describe('the effects the scene resolves for an eye that is not a camera entity', () => {
it('are the global volume\'s anywhere, and a local volume\'s only where the eye is inside it', async () => {
const { effectsAt } = await import('../src/postprocess/volumeSystem');
const volume = (isGlobal: boolean, type: string) => ({
isGlobal, priority: 0, weight: 1, blendDistance: 0, shape: 'box', size: { x: 10, y: 10, z: 10 },
effects: [{ type, enabled: true, uniforms: {}, colors: {}, textures: {} }],
}) as never;
const tx = { x: 0, y: 0, z: 0 };
const volumes = [{ data: volume(true, 'skyAtmosphere'), tx }, { data: volume(false, 'bloom'), tx: { x: 500, y: 0, z: 0 } }];
expect([...effectsAt(volumes, 4000, 20, 4000).keys()]).toEqual(['skyAtmosphere']);
expect([...effectsAt(volumes, 500, 0, 0).keys()].sort()).toEqual(['bloom', 'skyAtmosphere']);
});
});