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): effect lengths follow the project's units

yhh7cc88adb1c4e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2c10a83ca..fddc006d8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,7 +25,7 @@ published separately; it ships inside the editor.
- **The sky lights the scene.** Sky Atmosphere's **Light the Scene** makes the sky the scene's environment: every Ambient light that names no environment of its own lights with it, its diffuse light from the dome and the clouds and its reflection on metal and wet ground, scaled by the light's colour and intensity as an imported one is. The sky is worked out again as it changes (the sun moving, a weather coming in, clouds drifting), at most once a second; with clouds that takes about 20 ms on a desktop. The sun's disc is left out, since the directional light the sky follows is its direct light. Off by default, so a scene already lit by hand looks as it did.
- **Rooms stay dark under a sky that changes (sky occlusion).** With **Sky occlusion** on in the Lighting settings (`BakedLighting.skyOcclusion`), a probe bake keeps how much of the sky each probe sees instead of the sky itself: the probes hold the lights and their bounces, and the sky the frame has now (a live Sky Atmosphere, a weather, an environment) is added through what each probe sees of it, to the diffuse light and to the sky's reflection. A ball inside a roofed room measured 119 where the baked sky gave it 150, and a ball outside kept its light. A `.esprobes` baked this way carries `skyVisibility`; one without it lights as before. Probes are read per object, as Unity's light probes are: one large mesh spanning indoors and out takes one value.
-- **Defaults follow the project's units.** Every default that is a length, a speed or an acceleration — a character's capsule, a first-person walk and jump, a view model's near plane, a nav volume's cells, a perceiver's range, a particle's size and speed — is written at 100 units a metre and scaled by the project's units per metre (Project Settings → Physics → 3D). A centimetre project gets exactly the defaults it had; a metre project (an imported glTF scene) now gets metres instead of values 100 times too big. A value a scene states is never scaled. A component declares its own with `worldUnitFields`.
+- **Defaults follow the project's units.** Every default that is a length, a speed or an acceleration — a character's capsule, a first-person walk and jump, a view model's near plane, a nav volume's cells, a perceiver's range, a particle's size and speed — is written at 100 units a metre and scaled by the project's units per metre (Project Settings → Physics → 3D). A centimetre project gets exactly the defaults it had; a metre project (an imported glTF scene) now gets metres instead of values 100 times too big. A value a scene states is never scaled. A component declares its own with `worldUnitFields`. Post-process effects follow too: a length a volume leaves unset (rain and snow shelter range and puddle size, SSR distance and thickness, GTAO / SSAO / SSGI radius, contact-shadow length, depth-of-field focus, voxel GI cell, height-fog start and range) takes its default in the project's units, and fog density and height falloff — rates per length — by the inverse; the inspector offers ranges in those units and writes an added effect's defaults in them. A metre project's rain used to shelter within 3 km.
- **`Particle.emitAt(emitter, count, position, { normal, velocity })` spawns a burst where something happened, now** — an impact's sparks, a muzzle's flash — from the emitter's own settings, its shape turned onto the normal, without moving the emitter or replaying it (Unity's `ParticleSystem.Emit`). CPU-simulated emitters.
- **A first-person player has its own jump feel.** `FirstPersonController.gravityScale` (the player's gravity as a share of the world's), `coyoteTime` (a jump just after walking off an edge still takes off) and `jumpBuffer` (a jump pressed just before landing takes off as it lands).
- **A UI node can stand over a point in the 3D world.** `UIWorldAnchor` puts its UINode at the screen position of an entity (plus an offset) or a world point every frame: an objective marker, a name over a head, a health bar. `clampToEdges` keeps an off-screen or behind-the-camera marker on the screen's edge in its true direction; `onScreen`, `behind` and `distance` read back. It is placed from the camera's pose at the end of Update, so a marker does not trail a first-person view that turned this frame. Saltline's relay and boat markers are four of them.
diff --git a/desktop b/desktop
index c2f4330f0..b71ce90fa 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit c2f4330f0360018c4e4fa456a6f5d3a672314315
+Subproject commit b71ce90fa6e4888cb5a4c1a2c465faa96d106fe6
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 19b7544c4..2d1c62ca9 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -174,6 +174,7 @@ export {
type EffectUniformDef,
registerEffect,
getEffectDef,
+ uniformInUnits,
getEffectTypes,
getAllEffectDefs,
registerWeatherPreset,
diff --git a/sdk/src/postprocess.ts b/sdk/src/postprocess.ts
index 473ae2093..db260904c 100644
--- a/sdk/src/postprocess.ts
+++ b/sdk/src/postprocess.ts
@@ -18,6 +18,7 @@ export {
type EffectUniformDef,
registerEffect,
getEffectDef,
+ uniformInUnits,
getEffectTypes,
getAllEffectDefs,
PostProcessPlugin,
diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.ts
index dd6b653d5..c9a01b45e 100644
--- a/sdk/src/postprocess/effects.ts
+++ b/sdk/src/postprocess/effects.ts
@@ -1,6 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { ShaderHandle } from '../render/material';
+import { worldUnitScale } from '../ecs/worldUnits';
import { FOG_UNIFORMS, FOG_EXPLORED_TEXTURE, FOG_VISIBLE_TEXTURE } from './fogOfWarMask';
import { RAIN_SHELTER_UNIFORMS, RAIN_SHELTER_MASK_TEXTURE, RAIN_SHELTER_MASK_SIZE, RAIN_SHELTER_MASK_MIN, RAIN_SHELTER_MASK_MAX } from './rainShelterMask';
import { effectSourcesOf, computeSourceOf } from './effectSources';
@@ -37,6 +38,25 @@ export interface EffectUniformDef {
neutralValue?: number;
/** Set by the engine from another effect, not by a scene: an inspector does not list it. */
internal?: boolean;
+ /**
+ * A world length (1) or a world rate per length (-1): its default is written at 100 units a metre and follows the
+ * project's units per metre when a volume leaves it unset (ecs/worldUnits.ts). A value a volume states is never scaled.
+ */
+ worldUnits?: 1 | -1;
+}
+
+/**
+ * A uniform as it reads in this project: a world-unit one's default and range scaled to the project's units per metre
+ * (a length by the scale, a rate per length by its inverse), any other as declared. What the volume system fills an
+ * unset uniform with, and what an inspector offers.
+ */
+export function uniformInUnits(u: EffectUniformDef): EffectUniformDef {
+ if (!u.worldUnits) return u;
+ const s = worldUnitScale();
+ if (s === 1) return u;
+ const k = u.worldUnits === 1 ? s : 1 / s;
+ const lo = u.min * k, hi = u.max * k;
+ return { ...u, defaultValue: u.defaultValue * k, min: Math.min(lo, hi), max: Math.max(lo, hi), step: u.step * k };
}
/** A texture parameter (LUT, mask): the sampler uniform it binds to. */
@@ -488,7 +508,7 @@ registerEffect({
// Rays per surface point: more is smoother and costs in proportion.
{ name: 'u_rays', label: 'Rays', min: 1, max: 32, step: 1, defaultValue: 8 },
// The world size of a voxel: the cache is 128 x 64 x 128 of them around the camera, so this sets how far it reaches and how finely.
- { name: 'u_voxelSize', label: 'Voxel Size', min: 0.01, max: 400, step: 0.01, defaultValue: 40 },
+ { name: 'u_voxelSize', label: 'Voxel Size', min: 0.01, max: 400, step: 0.01, defaultValue: 40, worldUnits: 1 },
// How far a ray looks, in voxels.
{ name: 'u_range', label: 'Range', min: 4, max: 90, step: 1, defaultValue: 48 },
// Brighter than this a surface does not give out, so one lamp does not light the street from a single pixel.
@@ -538,16 +558,16 @@ registerEffect({
],
uniforms: [
// Per WORLD unit at the base height: the share of light a unit of fog takes out.
- { name: 'u_density', label: 'Density', min: 0, max: 0.05, step: 0.0001, defaultValue: 0.0015, neutralValue: 0 },
+ { name: 'u_density', label: 'Density', min: 0, max: 0.05, step: 0.0001, defaultValue: 0.0015, neutralValue: 0, worldUnits: -1 },
// How fast the fog thins with height; 0 is a fog of one density at every height.
- { name: 'u_heightFalloff', label: 'Height Falloff', min: 0, max: 0.1, step: 0.0005, defaultValue: 0.003 },
- { name: 'u_baseHeight', label: 'Base Height', min: -1000, max: 5000, step: 10, defaultValue: 0 },
+ { name: 'u_heightFalloff', label: 'Height Falloff', min: 0, max: 0.1, step: 0.0005, defaultValue: 0.003, worldUnits: -1 },
+ { name: 'u_baseHeight', label: 'Base Height', min: -1000, max: 5000, step: 10, defaultValue: 0, worldUnits: 1 },
// On a planet the fog's height is the height above the ground's sphere, not world Y: the radius, above 0, turns that on, and the centre is where the planet stands.
{ name: 'u_planetRadius', label: 'Planet Radius', min: 0, max: 100000000, step: 100, defaultValue: 0, neutralValue: 0 },
{ name: 'u_planetX', label: 'Planet Centre X', min: -100000000, max: 100000000, step: 100, defaultValue: 0 },
{ name: 'u_planetY', label: 'Planet Centre Y', min: -100000000, max: 100000000, step: 100, defaultValue: 0 },
{ name: 'u_planetZ', label: 'Planet Centre Z', min: -100000000, max: 100000000, step: 100, defaultValue: 0 },
- { name: 'u_startDistance', label: 'Start Distance', min: 0, max: 3000, step: 10, defaultValue: 0 },
+ { name: 'u_startDistance', label: 'Start Distance', min: 0, max: 3000, step: 10, defaultValue: 0, worldUnits: 1 },
{ name: 'u_maxOpacity', label: 'Max Opacity', min: 0, max: 1, step: 0.01, defaultValue: 1 },
// 1: the sun is the scene's own directional light — its direction and colour — and the two angles below are
// only what a scene with no sun falls back to. 0: the angles are the sun.
@@ -564,7 +584,7 @@ registerEffect({
// directional light that casts a shadow, and costs 24 taps a pixel.
{ name: 'u_volumetric', label: 'Volumetric Light', min: 0, max: 1, step: 0.01, defaultValue: 0, neutralValue: 0 },
// How far from the camera the air is walked: past it the fog still dims, but takes no shafts.
- { name: 'u_volumeRange', label: 'Volumetric Range', min: 100, max: 1000000, step: 100, defaultValue: 3000 },
+ { name: 'u_volumeRange', label: 'Volumetric Range', min: 100, max: 1000000, step: 100, defaultValue: 3000, worldUnits: 1 },
// How much the sky's clouds cut the beams: a gap in them is a shaft, and what they cover is dark air. It follows the clouds
// of a skyAtmosphere that has Cloud Shadows above 0 (the clouds are then fixed to the world, so the shafts stand where they do).
{ name: 'u_cloudShade', label: 'Cloud Shafts', min: 0, max: 1, step: 0.01, defaultValue: 0, neutralValue: 0 },
@@ -601,9 +621,9 @@ registerEffect({
// How much of the bounced light is added: 1 is what the surfaces gave out, scaled by the receiver's colour.
{ name: 'u_intensity', label: 'Intensity', min: 0, max: 4, step: 0.01, defaultValue: 1, neutralValue: 0 },
// A WORLD length: how far from a surface the rays look for something to bounce light from.
- { name: 'u_radius', label: 'Radius', min: 0.05, max: 1500, step: 0.05, defaultValue: 150 },
+ { name: 'u_radius', label: 'Radius', min: 0.05, max: 1500, step: 0.05, defaultValue: 150, worldUnits: 1 },
// A WORLD length: how thick a thing the rays can land on, so a far wall is not taken for the one beside it.
- { name: 'u_thickness', label: 'Thickness', min: 0.01, max: 300, step: 0.01, defaultValue: 30 },
+ { name: 'u_thickness', label: 'Thickness', min: 0.01, max: 300, step: 0.01, defaultValue: 30, worldUnits: 1 },
// Brighter than this a surface does not bounce, so one lamp does not light the street from a single pixel.
{ name: 'u_maxBounce', label: 'Max Bounce', min: 0.5, max: 16, step: 0.5, defaultValue: 3 },
],
@@ -622,9 +642,9 @@ registerEffect({
// How dark a contact shadow is.
{ name: 'u_intensity', label: 'Intensity', min: 0, max: 1, step: 0.01, defaultValue: 0.6, neutralValue: 0 },
// A WORLD length: how far from a surface the ray looks for something standing in the light's way.
- { name: 'u_length', label: 'Length', min: 5, max: 600, step: 1, defaultValue: 60 },
+ { name: 'u_length', label: 'Length', min: 5, max: 600, step: 1, defaultValue: 60, worldUnits: 1 },
// A WORLD length: how thick a thing can be and still shadow, so a far wall does not shadow what is in front of it.
- { name: 'u_thickness', label: 'Thickness', min: 0.5, max: 80, step: 0.5, defaultValue: 8 },
+ { name: 'u_thickness', label: 'Thickness', min: 0.5, max: 80, step: 0.5, defaultValue: 8, worldUnits: 1 },
{ name: 'u_followSun', label: 'Follow Scene Sun', min: 0, max: 1, step: 1, defaultValue: 1, neutralValue: 1 },
{ name: 'u_sunAzimuth', label: 'Sun Azimuth', min: 0, max: 360, step: 1, defaultValue: 40 },
{ name: 'u_sunElevation', label: 'Sun Elevation', min: -90, max: 90, step: 1, defaultValue: 35 },
@@ -684,7 +704,7 @@ registerEffect({
factory: () => postProcessEffects.createDofGather(),
uniforms: [
// A WORLD length from the camera to what is in focus (what the lens rests on when Auto Focus is off).
- { name: 'u_focusDistance', label: 'Focus Distance', min: 1, max: 5000, step: 1, defaultValue: 600 },
+ { name: 'u_focusDistance', label: 'Focus Distance', min: 1, max: 5000, step: 1, defaultValue: 600, worldUnits: 1 },
// 1: the lens focuses on the surface under the focus point, and glides there at Focus Speed.
{ name: 'u_autoFocus', label: 'Auto Focus', min: 0, max: 1, step: 1, defaultValue: 0, neutralValue: 0 },
// Where on the screen the auto-focus looks, as a share of its width from the left and of its height from the top.
@@ -692,7 +712,7 @@ registerEffect({
{ name: 'u_focusY', label: 'Focus Point Y', min: 0, max: 1, step: 0.01, defaultValue: 0.5 },
{ name: 'u_focusSpeed', label: 'Focus Speed', min: 0.1, max: 40, step: 0.1, defaultValue: 5 },
// How deep a slab around it stays sharp, before the blur starts.
- { name: 'u_focusRange', label: 'Focus Range', min: 0, max: 2000, step: 1, defaultValue: 100 },
+ { name: 'u_focusRange', label: 'Focus Range', min: 0, max: 2000, step: 1, defaultValue: 100, worldUnits: 1 },
// The blur, in pixels, of something infinitely far: a bigger lens blurs sooner and harder.
{ name: 'u_aperture', label: 'Aperture (px)', min: 0, max: 64, step: 0.5, defaultValue: 24, neutralValue: 0 },
{ name: 'u_maxBlur', label: 'Max Blur (px)', min: 1, max: 32, step: 0.5, defaultValue: 14 },
@@ -725,14 +745,14 @@ registerEffect({
{ name: 'u_speed', label: 'Speed', min: 0.2, max: 6, step: 0.1, defaultValue: 1.6 },
{ name: 'u_streakLength', label: 'Streak Length', min: 0.05, max: 0.9, step: 0.01, defaultValue: 0.3 },
// A WORLD length: the size of the grid cell each ring lives in.
- { name: 'u_rippleScale', label: 'Ripple Scale', min: 5, max: 400, step: 1, defaultValue: 60 },
+ { name: 'u_rippleScale', label: 'Ripple Scale', min: 5, max: 400, step: 1, defaultValue: 60, worldUnits: 1 },
// How far from the camera, in world units, the map of what stands over each place reaches: ground under an awning
// inside it stays dry. The map is the scene drawn from straight above, so this is also how much of it costs.
- { name: 'u_shelterRange', label: 'Shelter Range', min: 100, max: 30000, step: 100, defaultValue: 3000 },
+ { name: 'u_shelterRange', label: 'Shelter Range', min: 100, max: 30000, step: 100, defaultValue: 3000, worldUnits: 1 },
// How much of the flat ground is standing water, and how big the pools are (a WORLD length).
// The reflections effect draws the same pools when it is given the same two numbers.
{ name: 'u_puddles', label: 'Puddles', min: 0, max: 1, step: 0.01, defaultValue: 0.3, neutralValue: 0 },
- { name: 'u_puddleScale', label: 'Puddle Size', min: 40, max: 2000, step: 10, defaultValue: 350 },
+ { name: 'u_puddleScale', label: 'Puddle Size', min: 40, max: 2000, step: 10, defaultValue: 350, worldUnits: 1 },
],
colors: [
{ name: 'u_streakColor', label: 'Streak Colour', defaultValue: { r: 0.78, g: 0.82, b: 0.9, a: 1 } },
@@ -747,14 +767,14 @@ registerEffect({
// How much lies: a dusting in the low places at a little, everything closed over at 1.
{ name: 'u_amount', label: 'Amount', min: 0, max: 1, step: 0.01, defaultValue: 1, neutralValue: 0 },
// The height it stops at, in world units, and how far it thins out above that.
- { name: 'u_snowLine', label: 'Snow Line', min: -100000, max: 100000, step: 1, defaultValue: -100000 },
- { name: 'u_snowLineBand', label: 'Snow Line Band', min: 0, max: 100000, step: 1, defaultValue: 100 },
+ { name: 'u_snowLine', label: 'Snow Line', min: -100000, max: 100000, step: 1, defaultValue: -100000, worldUnits: 1 },
+ { name: 'u_snowLineBand', label: 'Snow Line Band', min: 0, max: 100000, step: 1, defaultValue: 100, worldUnits: 1 },
// How much a surface must face up to hold it: 1 only the flat, 0 almost a wall.
{ name: 'u_slopeLimit', label: 'Slope Limit', min: 0, max: 1, step: 0.01, defaultValue: 0.55 },
// The world size of the drifts.
- { name: 'u_grainScale', label: 'Drift Size', min: 1, max: 100000, step: 1, defaultValue: 120 },
+ { name: 'u_grainScale', label: 'Drift Size', min: 1, max: 100000, step: 1, defaultValue: 120, worldUnits: 1 },
// The same map of what stands over each place as the rain's: no snow under an awning.
- { name: 'u_shelterRange', label: 'Shelter Range', min: 100, max: 30000, step: 100, defaultValue: 3000 },
+ { name: 'u_shelterRange', label: 'Shelter Range', min: 100, max: 30000, step: 100, defaultValue: 3000, worldUnits: 1 },
],
colors: [
{ name: 'u_snowColor', label: 'Snow Colour', defaultValue: { r: 0.92, g: 0.95, b: 1, a: 1 } },
@@ -771,7 +791,7 @@ registerEffect({
uniforms: [
// A WORLD length: positions come back in world space, so this is "how far
// around a point counts as its neighbourhood", not a pixel count.
- { name: 'u_radius', label: 'Radius', min: 0.01, max: 400, step: 0.01, defaultValue: 60 },
+ { name: 'u_radius', label: 'Radius', min: 0.01, max: 400, step: 0.01, defaultValue: 60, worldUnits: 1 },
{ name: 'u_intensity', label: 'Intensity', min: 0, max: 2, step: 0.01, defaultValue: 1 },
// How far above the tangent plane a sample must sit to count. This is
// what keeps a flat floor from occluding itself into grey.
@@ -819,7 +839,7 @@ registerEffect({
// The horizon-based estimator in place of the ring of samples: no bias to tune against a surface occluding itself,
// so a flat floor stays white and a crease darkens by how closed it really is. The blur and the composite are SSAO's.
uniforms: [
- { name: 'u_radius', label: 'Radius', min: 0.01, max: 500, step: 0.01, defaultValue: 80 },
+ { name: 'u_radius', label: 'Radius', min: 0.01, max: 500, step: 0.01, defaultValue: 80, worldUnits: 1 },
{ name: 'u_intensity', label: 'Intensity', min: 0, max: 2, step: 0.01, defaultValue: 1 },
{ name: 'u_power', label: 'Power', min: 0.5, max: 4, step: 0.05, defaultValue: 1.4, neutralValue: 1 },
// 0 trusts every occluder to be as tall as it looks; 1 lets a thin one (a railing, a leaf) be seen past.
@@ -841,16 +861,16 @@ registerEffect({
{ name: 'u_intensity', label: 'Intensity', min: 0, max: 2, step: 0.01, defaultValue: 1, neutralValue: 0 },
// A WORLD length, like SSAO's radius: how far a reflected ray may travel before the
// search gives up. Step count is a constant, so a longer reach is a coarser step.
- { name: 'u_maxDistance', label: 'Max Distance', min: 10, max: 3000, step: 10, defaultValue: 400 },
+ { name: 'u_maxDistance', label: 'Max Distance', min: 10, max: 3000, step: 10, defaultValue: 400, worldUnits: 1 },
// How far behind a visible surface a ray may pass and still count as having hit it.
- { name: 'u_thickness', label: 'Thickness', min: 1, max: 200, step: 1, defaultValue: 12 },
+ { name: 'u_thickness', label: 'Thickness', min: 1, max: 200, step: 1, defaultValue: 12, worldUnits: 1 },
// 1 = only surfaces that face up reflect (wet ground, polished floors, and not the walls beside them);
// 0 = any surface smooth enough to show a reflection does.
{ name: 'u_floorBias', label: 'Floor Bias', min: 0, max: 1, step: 0.01, defaultValue: 0 },
// Standing water: flat, and a mirror. Give it the same two numbers as the Rain effect's puddles
// and the pools it darkens are the pools that reflect.
{ name: 'u_puddles', label: 'Puddles', min: 0, max: 1, step: 0.01, defaultValue: 0, neutralValue: 0 },
- { name: 'u_puddleScale', label: 'Puddle Size', min: 40, max: 2000, step: 10, defaultValue: 350 },
+ { name: 'u_puddleScale', label: 'Puddle Size', min: 40, max: 2000, step: 10, defaultValue: 350, worldUnits: 1 },
// Surfaces rougher than this reflect nothing and cost nothing: the ray is never marched for them.
{ name: 'u_maxRoughness', label: 'Max Roughness', min: 0.05, max: 1, step: 0.01, defaultValue: 0.75 },
// How wet the ground is: wet is smoother, so it reflects. Give it the Rain effect's wetness.
diff --git a/sdk/src/postprocess/index.ts b/sdk/src/postprocess/index.ts
index 3637806c8..f0606450c 100644
--- a/sdk/src/postprocess/index.ts
+++ b/sdk/src/postprocess/index.ts
@@ -13,6 +13,7 @@ export {
type EffectUniformDef,
registerEffect,
getEffectDef,
+ uniformInUnits,
getEffectTypes,
getAllEffectDefs,
} from './effects';
diff --git a/sdk/src/postprocess/volumeBlending.ts b/sdk/src/postprocess/volumeBlending.ts
index 169390b7a..eed4548c2 100644
--- a/sdk/src/postprocess/volumeBlending.ts
+++ b/sdk/src/postprocess/volumeBlending.ts
@@ -1,7 +1,8 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { PostProcessVolumeData } from '../ecs/component';
-import { getEffectDef } from './effects';
+import { getEffectDef, uniformInUnits } from './effects';
+import { worldUnitScale } from '../ecs/worldUnits';
import { log } from '../util/logger';
export interface VolumeTransform {
@@ -190,5 +191,14 @@ export function blendVolumeEffects(
}
}
+ // A world-unit uniform no volume stated takes its default in the project's units (a metre project's rain shelters
+ // within 30 m, not 3000). Unblended, as the shader's own default would have been; nothing to do at the reference scale.
+ if (worldUnitScale() !== 1) {
+ for (const [type, blended] of result) {
+ for (const u of getEffectDef(type)?.uniforms ?? []) {
+ if (u.worldUnits && !blended.uniforms.has(u.name)) blended.uniforms.set(u.name, uniformInUnits(u).defaultValue);
+ }
+ }
+ }
return result;
}
diff --git a/sdk/src/postprocess/volumeSystem.ts b/sdk/src/postprocess/volumeSystem.ts
index 1240d44fe..9bf296998 100644
--- a/sdk/src/postprocess/volumeSystem.ts
+++ b/sdk/src/postprocess/volumeSystem.ts
@@ -9,7 +9,7 @@ import { Query } from '../ecs/query';
import type { Entity } from '../types';
import { PostProcessVolume, Transform, Camera, ProjectionType, ClearFlags, type PostProcessVolumeData, type TransformData, type CameraData } from '../ecs/component';
import { PostProcess, deviceHasCompute, type PostProcessAPI } from './PostProcessAPI';
-import { getEffectDef } from './effects';
+import { getEffectDef, uniformInUnits } from './effects';
import { blendVolumeEffects, computeVolumeFactor, type ActiveVolume, type BlendedEffect, type VolumeTransform } from './volumeBlending';
import type { ShaderHandle } from '../render/material';
import { Material } from '../render/material';
@@ -267,12 +267,12 @@ function applyBlendedEffects(
for (const [index, subPass] of def.fallback.entries()) {
const shader = getOrCreateShader(api, subPass.name, subPass.factory);
stack.addPass(subPass.name, shader, subPass.scale ?? 1, index > 0);
- for (const u of def.uniforms) stack.setUniform(subPass.name, u.name, effectData.uniforms.get(u.name) ?? u.defaultValue);
+ for (const u of def.uniforms) stack.setUniform(subPass.name, u.name, effectData.uniforms.get(u.name) ?? uniformInUnits(u).defaultValue);
for (const [name, value] of Object.entries(subPass.uniforms ?? {})) stack.setUniform(subPass.name, name, value);
}
} else if (def.native) {
stack.addNativePass(effectType, def.native);
- for (const u of def.uniforms) stack.setUniform(effectType, u.name, effectData.uniforms.get(u.name) ?? u.defaultValue);
+ for (const u of def.uniforms) stack.setUniform(effectType, u.name, effectData.uniforms.get(u.name) ?? uniformInUnits(u).defaultValue);
} else if (def.compute) {
// The params block is the effect's uniforms in their listed order, each at the volume's value or the effect's own default.
stack.addComputePass(effectType, {
@@ -280,7 +280,7 @@ function applyBlendedEffects(
params: def.uniforms.map((u) => u.name),
workgroupSize: def.compute.workgroupSize ?? [8, 8],
});
- for (const u of def.uniforms) stack.setUniform(effectType, u.name, effectData.uniforms.get(u.name) ?? u.defaultValue);
+ for (const u of def.uniforms) stack.setUniform(effectType, u.name, effectData.uniforms.get(u.name) ?? uniformInUnits(u).defaultValue);
} else if (def.factory) {
const shader = getOrCreateShader(api, effectType, def.factory);
stack.addPass(effectType, shader);
diff --git a/sdk/src/postprocess/weather.ts b/sdk/src/postprocess/weather.ts
index c491045f0..59bd42a4e 100644
--- a/sdk/src/postprocess/weather.ts
+++ b/sdk/src/postprocess/weather.ts
@@ -14,7 +14,7 @@
* effects that result.
*/
import type { BlendedEffect, Rgba } from './volumeBlending';
-import { getEffectDef } from './effects';
+import { getEffectDef, uniformInUnits } from './effects';
export interface WeatherState {
/** × the directional lights' strength. */
@@ -213,7 +213,9 @@ export function currentWeatherDrive(): number {
function value(effect: BlendedEffect, type: string, name: string, fallback = 0): number {
const set = effect.uniforms.get(name);
if (set !== undefined) return set;
- return getEffectDef(type)?.uniforms.find((u) => u.name === name)?.defaultValue ?? fallback;
+ // In the project's units: a fog the weather makes from nothing is as thick per metre as one a volume left unset.
+ const u = getEffectDef(type)?.uniforms.find((d) => d.name === name);
+ return u ? uniformInUnits(u).defaultValue : fallback;
}
function entry(effects: Map<string, BlendedEffect>, type: string): BlendedEffect {
diff --git a/sdk/tests/effect-world-units.test.ts b/sdk/tests/effect-world-units.test.ts
new file mode 100644
index 000000000..820676ba0
--- /dev/null
+++ b/sdk/tests/effect-world-units.test.ts
@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Post-process effects follow the project's units: a length a volume leaves unset takes its default in the
+ * project's units, so a metre project's rain shelters within 30 m and its SSR reaches 4 m, not 3000 and 400.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import { blendVolumeEffects } from '../src/postprocess/volumeBlending';
+import { getEffectDef, uniformInUnits } from '../src/postprocess/effects';
+import { setWorldUnitsPerMeter, REFERENCE_UNITS_PER_METER } from '../src/ecs/worldUnits';
+
+afterEach(() => setWorldUnitsPerMeter(REFERENCE_UNITS_PER_METER));
+
+const uniform = (type: string, name: string) => getEffectDef(type)!.uniforms.find((u) => u.name === name)!;
+const volume = (type: string, uniforms: Record<string, number>) => ({
+ data: { effects: [{ type, enabled: true, uniforms }], isGlobal: true, shape: 'box', size: { x: 5, y: 5 }, priority: 0, weight: 1, blendDistance: 0 } as never,
+ factor: 1,
+});
+
+describe('a world-unit effect parameter', () => {
+ it('is as declared at the reference scale — the very definition', () => {
+ const u = uniform('rain', 'u_shelterRange');
+ expect(uniformInUnits(u)).toBe(u);
+ expect(u.defaultValue).toBe(3000);
+ });
+
+ it('in a metre project: a length scaled with its range, a rate per length by the inverse', () => {
+ setWorldUnitsPerMeter(1);
+ const shelter = uniformInUnits(uniform('rain', 'u_shelterRange'));
+ expect(shelter.defaultValue).toBeCloseTo(30);
+ expect(shelter.min).toBeCloseTo(1);
+ expect(shelter.max).toBeCloseTo(300);
+ expect(uniformInUnits(uniform('ssr', 'u_maxDistance')).defaultValue).toBeCloseTo(4);
+ expect(uniformInUnits(uniform('heightFog', 'u_density')).defaultValue).toBeCloseTo(0.15);
+ expect(uniformInUnits(uniform('rain', 'u_intensity')).defaultValue).toBe(1); // not a length
+ });
+
+ it('is filled in, in the project\'s units, where a volume leaves it unset — and a stated one is left alone', () => {
+ setWorldUnitsPerMeter(1);
+ const rain = blendVolumeEffects([volume('rain', { u_intensity: 0.4, u_shelterRange: 12 })]).get('rain')!;
+ expect(rain.uniforms.get('u_shelterRange')).toBe(12);
+ expect(rain.uniforms.get('u_puddleScale')).toBeCloseTo(3.5);
+ expect(rain.uniforms.get('u_intensity')).toBeCloseTo(0.4);
+ expect(rain.uniforms.has('u_wind')).toBe(false); // not a length: the shader's own default, as before
+ });
+
+ it('is not touched at the reference scale: a centimetre project renders as it did', () => {
+ const rain = blendVolumeEffects([volume('rain', { u_intensity: 0.4 })]).get('rain')!;
+ expect(rain.uniforms.has('u_shelterRange')).toBe(false);
+ expect([...rain.uniforms.keys()]).toEqual(['u_intensity']);
+ });
+});