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(postprocess): a volume is a volume, and the gate now sees one

esenginec251b8c392c2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a05d42bda..44786cbb7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -54,15 +54,25 @@ published separately; it ships inside the editor.
### Fixed
-- **A component that describes a space is drawn, and a gate says so.** `NavAgent`'s
- routing width and `ParticleForceField`'s reach were authorable numbers with
- nothing on screen to show what they covered — the same gap the light gizmos had.
- Both now draw a world radius ring, from one table rather than a gizmo path each:
- a radius is a circle wherever it comes from, and what differs is what it means,
- which is its colour. New gate `check-gizmo-coverage`: a component declaring a
- spatial field (`halfExtents`, `radius`, `shapeRadius`, `halfHeight`, `extents`)
- must be named in the viewport, because `gizmo-chrome`'s list is written by hand
- and cannot notice a component nobody added to it.
+- **A component that describes a region of world is drawn, and a gate says so.**
+ `NavAgent`'s routing width, `ParticleForceField`'s reach, `ShadowCaster2D`'s
+ occluder box and `PostProcessVolume`'s graded region were all authorable numbers
+ with nothing on screen to show what they covered — the same gap the light gizmos
+ had. All four now draw their extent, from one table rather than a gizmo path
+ each: an extent is a ball or a box wherever it comes from, and what differs is
+ what it MEANS, which is its colour. New gate `check-gizmo-coverage`: a component
+ declaring a spatial field must be named in the viewport, because `gizmo-chrome`'s
+ list is written by hand and cannot notice a component nobody added to it.
+ `size` counts, with the components that ARE their own picture (a sprite, a shape)
+ listed rather than the field name dropped — dropping it to spare the sprite is
+ what hid the volume.
+
+- **A post-process volume is a volume.** `signedDistanceBox` and
+ `signedDistanceSphere` measured in x and y, so a "sphere" was a column: a camera
+ two floors above a graded room was inside it. Both take three axes now, and
+ `PostProcessVolume.size` gains an optional `z` half-depth whose **0 means
+ unbounded** — a box of no thickness contains nothing, so the value is free to
+ mean what every flat scene's volume already was.
- **A navigation volume is visible while it is being placed.** Nothing renders a
`NavVolume` and nothing collides with it, so the box that decides where agents
diff --git a/desktop b/desktop
index 8bb5fd75b..bec0d367d 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 8bb5fd75bdeaa4c2ef73a001d5e0e0d3955f3527
+Subproject commit bec0d367d4dc627bba586c0ed7a085d313ed6dae
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 83245a098..84013dfa1 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5698,7 +5698,7 @@ effects: { type: string; enabled: boolean; uniforms: Record<string, number>; tex
isGlobal: boolean
priority: number
shape: "box" | "sphere"
-size: { x: number; y: number; }
+size: { x: number; y: number; z?: number; }
weight: number
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index cbbb19ba5..9c87ce245 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5881,7 +5881,7 @@ effects: { type: string; enabled: boolean; uniforms: Record<string, number>; tex
isGlobal: boolean
priority: number
shape: "box" | "sphere"
-size: { x: number; y: number; }
+size: { x: number; y: number; z?: number; }
weight: number
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 73562cb06..85748a7c2 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -5693,7 +5693,7 @@ effects: { type: string; enabled: boolean; uniforms: Record<string, number>; tex
isGlobal: boolean
priority: number
shape: "box" | "sphere"
-size: { x: number; y: number; }
+size: { x: number; y: number; z?: number; }
weight: number
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 8d2bc1db5..47065d2c2 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -5938,7 +5938,7 @@ effects: { type: string; enabled: boolean; uniforms: Record<string, number>; tex
isGlobal: boolean
priority: number
shape: "box" | "sphere"
-size: { x: number; y: number; }
+size: { x: number; y: number; z?: number; }
weight: number
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index e0a2f2e3b..3798b6c40 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -5700,7 +5700,7 @@ effects: { type: string; enabled: boolean; uniforms: Record<string, number>; tex
isGlobal: boolean
priority: number
shape: "box" | "sphere"
-size: { x: number; y: number; }
+size: { x: number; y: number; z?: number; }
weight: number
```
diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.ts
index fff421cb3..3d7edcc90 100644
--- a/sdk/src/ecs/component.ts
+++ b/sdk/src/ecs/component.ts
@@ -1146,7 +1146,11 @@ export interface PostProcessVolumeData {
}[];
isGlobal: boolean;
shape: 'box' | 'sphere';
- size: { x: number; y: number };
+ /** Half-extents of the shape (a sphere uses `x` as its radius). `z` is the
+ * half-DEPTH of a box, where **0 means unbounded** — a flat scene's volume
+ * reaches through every depth, and a box of no thickness would contain
+ * nothing at all. */
+ size: { x: number; y: number; z?: number };
priority: number;
weight: number;
blendDistance: number;
diff --git a/sdk/src/postprocess/volumeBlending.ts b/sdk/src/postprocess/volumeBlending.ts
index a0492954a..a36620968 100644
--- a/sdk/src/postprocess/volumeBlending.ts
+++ b/sdk/src/postprocess/volumeBlending.ts
@@ -6,6 +6,8 @@ import { getEffectDef } from './effects';
export interface VolumeTransform {
x: number;
y: number;
+ /** Where the volume sits in depth. Absent = the plane a flat scene draws on. */
+ z?: number;
}
export interface ActiveVolume {
@@ -21,42 +23,54 @@ export interface BlendedEffect {
textures: Map<string, string>;
}
+/**
+ * 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
+ * leaves one unchanged. A box of no thickness contains nothing, so the value is
+ * free to mean that.
+ */
export function signedDistanceBox(
- px: number, py: number,
- cx: number, cy: number,
- halfW: number, halfH: number
+ px: number, py: number, pz: number,
+ cx: number, cy: number, cz: number,
+ halfW: number, halfH: number, halfD: number
): number {
const dx = Math.abs(px - cx) - halfW;
const dy = Math.abs(py - cy) - halfH;
- const outsideDist = Math.sqrt(Math.max(dx, 0) ** 2 + Math.max(dy, 0) ** 2);
- const insideDist = Math.min(Math.max(dx, dy), 0);
- return outsideDist + insideDist;
+ const dz = halfD > 0 ? Math.abs(pz - cz) - halfD : -Infinity;
+ const out = Math.sqrt(Math.max(dx, 0) ** 2 + Math.max(dy, 0) ** 2
+ + (halfD > 0 ? Math.max(dz, 0) ** 2 : 0));
+ const inside = Math.min(Math.max(dx, dy, halfD > 0 ? dz : -Infinity), 0);
+ return out + inside;
}
+/** Signed distance to a sphere. A flat scene hands in equal z and gets a circle. */
export function signedDistanceSphere(
- px: number, py: number,
- cx: number, cy: number,
+ px: number, py: number, pz: number,
+ cx: number, cy: number, cz: number,
radius: number
): number {
const dx = px - cx;
const dy = py - cy;
- return Math.sqrt(dx * dx + dy * dy) - radius;
+ const dz = pz - cz;
+ return Math.sqrt(dx * dx + dy * dy + dz * dz) - radius;
}
export function computeVolumeFactor(
volume: PostProcessVolumeData,
transform: VolumeTransform,
- px: number, py: number
+ px: number, py: number, pz = 0
): number {
if (volume.isGlobal) {
return volume.weight; // honor the global's weight, like local volumes below
}
+ const cz = transform.z ?? 0;
let dist: number;
if (volume.shape === 'sphere') {
- dist = signedDistanceSphere(px, py, transform.x, transform.y, volume.size.x);
+ dist = signedDistanceSphere(px, py, pz, transform.x, transform.y, cz, volume.size.x);
} else {
- dist = signedDistanceBox(px, py, transform.x, transform.y, volume.size.x, volume.size.y);
+ dist = signedDistanceBox(px, py, pz, transform.x, transform.y, cz,
+ volume.size.x, volume.size.y, volume.size.z ?? 0);
}
if (dist <= 0) {
diff --git a/sdk/src/postprocess/volumeSystem.ts b/sdk/src/postprocess/volumeSystem.ts
index 0ce04187a..8bcb586fc 100644
--- a/sdk/src/postprocess/volumeSystem.ts
+++ b/sdk/src/postprocess/volumeSystem.ts
@@ -141,7 +141,10 @@ export const postProcessVolumeSystem = defineSystem(
) => {
const volumes: { data: PostProcessVolumeData; tx: VolumeTransform }[] = [];
for (const [_entity, volumeData, transform] of volumeQuery) {
- volumes.push({ data: volumeData, tx: { x: transform.position.x, y: transform.position.y } });
+ volumes.push({
+ data: volumeData,
+ tx: { x: transform.position.x, y: transform.position.y, z: transform.position.z },
+ });
}
// Recomputed per camera: a local volume's weight depends on the camera position.
@@ -150,10 +153,11 @@ export const postProcessVolumeSystem = defineSystem(
const cx = cameraTransform.position.x;
const cy = cameraTransform.position.y;
+ const cz = cameraTransform.position.z;
const activeVolumes: ActiveVolume[] = [];
for (const { data, tx } of volumes) {
- const factor = computeVolumeFactor(data, tx, cx, cy);
+ const factor = computeVolumeFactor(data, tx, cx, cy, cz);
if (factor > 0) activeVolumes.push({ data, factor });
}
diff --git a/sdk/tests/volumeBlending.test.ts b/sdk/tests/volumeBlending.test.ts
index 3d728f273..23ae09167 100644
--- a/sdk/tests/volumeBlending.test.ts
+++ b/sdk/tests/volumeBlending.test.ts
@@ -11,49 +11,79 @@ import {
describe('volumeBlending', () => {
describe('signedDistanceBox', () => {
it('returns negative distance when point is inside box', () => {
- const dist = signedDistanceBox(0, 0, 0, 0, 5, 5);
+ 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, 5, 5);
+ 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, 5, 5);
+ 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, 10, 10, 5, 5);
+ 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, 5, 5);
+ 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, 5);
+ 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, 5);
+ 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, 5);
+ const dist = signedDistanceSphere(8, 0, 0, 0, 0, 0, 5);
expect(dist).toBeCloseTo(3, 5);
});
it('handles offset center', () => {
- const dist = signedDistanceSphere(15, 10, 10, 10, 5);
+ const dist = signedDistanceSphere(15, 10, 0, 10, 10, 0, 5);
expect(dist).toBeCloseTo(0, 5);
});
});
diff --git a/tools/check-gizmo-coverage.mjs b/tools/check-gizmo-coverage.mjs
index efc24d121..eeb91e32c 100644
--- a/tools/check-gizmo-coverage.mjs
+++ b/tools/check-gizmo-coverage.mjs
@@ -24,12 +24,16 @@ const SNAPSHOT = path.join(ROOT, 'docs', 'astro', 'src', 'data', 'components.gen
/** The one file where a gizmo's geometry is computed. */
const VIEWPORT = path.join(ROOT, 'desktop', 'src', 'engine', 'ViewportController.ts');
+/** Field names that mean "this component occupies a region of world". */
+const SPATIAL_FIELDS = new Set(['halfExtents', 'radius', 'shapeRadius', 'halfHeight', 'extents', 'size']);
+
/**
- * Field names that mean "this component occupies a volume of world". Deliberately
- * short: a name that also describes something flat (`size` on a UI node, `scale`)
- * would make the rule about layout rather than about space.
+ * Components whose `size` IS what they draw, so the picture is the component.
+ * Listed rather than excluded by field name: `size` covers both a sprite (drawn,
+ * needs no outline) and a post-process volume (drawn by nothing at all), and
+ * dropping the name to avoid the first hid the second for as long as it existed.
*/
-const SPATIAL_FIELDS = new Set(['halfExtents', 'radius', 'shapeRadius', 'halfHeight', 'extents']);
+const DRAWS_ITSELF = new Set(['Sprite', 'ShapeRenderer', 'Mesh2D', 'BitmapText', 'UIVisual', 'UINode']);
/** Components whose extent is deliberately not drawn, and why. */
const DECLARED_GAPS = {};
@@ -51,6 +55,7 @@ let judged = 0;
for (const component of components) {
const spatial = (component.fields ?? []).map((f) => f.key).filter((k) => SPATIAL_FIELDS.has(k));
if (spatial.length === 0) continue;
+ if (DRAWS_ITSELF.has(component.name)) continue;
judged++;
if (DECLARED_GAPS[component.name]) {
unusedGaps.delete(component.name);