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(postprocess): a volume is a volume, and the gate now sees one
esenginec251b8c392c2
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 agentsdiff --git a/desktop b/desktopindex 8bb5fd75b..bec0d367d 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 8bb5fd75bdeaa4c2ef73a001d5e0e0d3955f3527+Subproject commit bec0d367d4dc627bba586c0ed7a085d313ed6daediff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 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>; texisGlobal: booleanpriority: numbershape: "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.mdindex 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>; texisGlobal: booleanpriority: numbershape: "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.mdindex 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>; texisGlobal: booleanpriority: numbershape: "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.mdindex 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>; texisGlobal: booleanpriority: numbershape: "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.mdindex 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>; texisGlobal: booleanpriority: numbershape: "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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mjsindex 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);