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(editor): the grid stops changing plane partway through an orbit

yhh0bb4978d18b1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index aacea9984..0ecebd4bc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,35 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Fixed
+
+- **The editor grid stops changing plane mid-orbit.** Turning a 3D view down
+ toward the horizon used to swap the grid off the ground and onto a vertical
+ plane as it passed about 6 degrees: the frame you judge a scene against turned
+ over under the drag. One function was answering two questions. A GESTURE does
+ need to hand over — a drag on a plane seen edge-on turns a pixel of cursor
+ travel into unbounded world motion — and `editorViewWorkPlane` still does,
+ unchanged. The grid now asks `editorViewGridPlane`, which is the plane the view
+ is about and nothing else: the ground in a 3D view, the 2D plane in a flat one,
+ at every angle. Held edge-on it converges into the horizon and the shader's
+ existing fade takes it, which is what every editor does and what the plane
+ saying where you are standing looks like.
+
+ Measured across the old threshold, quadrant by quadrant: at 4° above the ground
+ the grid was near-uniform (a plane turned to meet the eye) and is now
+ bottom-heavy by 1.7× (a floor receding to a horizon); exactly head-on, where
+ this scene's eye lies IN the ground, it drew a full frame and now correctly
+ draws nothing.
+
+ The three grid pixel gates moved from the editor host to the engine's own —
+ the grid is SDK code (`installEditorGrid` draws through the `EditorView`
+ resource), so `tools/render-host` opens those doors now and the gates run
+ without a private editor checkout, on both backends. A fourth
+ (`editor-grid-grazing`) pins the angle the bug lived at, with a `grazing`
+ verdict that tells a lopsided floor from an evenly-lit wall — the old
+ behaviour passed the frame-coverage check, so nothing in the suite could have
+ caught this.
+
### Changed
- **The flat physics components take the `2D` suffix the solid ones already had.**
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index b0ebaff23..5f1c16cca 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 73,
- "experimental": 1623,
+ "experimental": 1624,
"deprecated": 3
},
- "total": 1809,
+ "total": 1810,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 80f33d6d1..3b758892e 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1507 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1508 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -10182,6 +10182,11 @@ DragPlugin
(view: EditorViewData): Vec3
```
+## editorViewGridPlane — function @experimental
+```
+(view: EditorViewData): EditorWorkPlane
+```
+
## editorViewHalfExtent — function @experimental
```
(view: EditorViewData, aspect: number): { halfW: number; halfH: number; }
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 9cc74c8a8..c546e5f8c 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 71 beta · 1526 experimental · 3 deprecated
+Symbols: 113 public · 71 beta · 1527 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -10415,6 +10415,11 @@ DragPlugin
(view: EditorViewData): Vec3
```
+## editorViewGridPlane — function @experimental
+```
+(view: EditorViewData): EditorWorkPlane
+```
+
## editorViewHalfExtent — function @experimental
```
(view: EditorViewData, aspect: number): { halfW: number; halfH: number; }
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 619cdfe2c..fb3e5a935 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 68 beta · 1506 experimental · 3 deprecated
+Symbols: 113 public · 68 beta · 1507 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -10177,6 +10177,11 @@ DragPlugin
(view: EditorViewData): Vec3
```
+## editorViewGridPlane — function @experimental
+```
+(view: EditorViewData): EditorWorkPlane
+```
+
## editorViewHalfExtent — function @experimental
```
(view: EditorViewData, aspect: number): { halfW: number; halfH: number; }
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 66857d5bc..d62e6ad19 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1528 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1529 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -10433,6 +10433,11 @@ DragPlugin
(view: EditorViewData): Vec3
```
+## editorViewGridPlane — function @experimental
+```
+(view: EditorViewData): EditorWorkPlane
+```
+
## editorViewHalfExtent — function @experimental
```
(view: EditorViewData, aspect: number): { halfW: number; halfH: number; }
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index de7800dbc..e30a5c271 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1518 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1519 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -10204,6 +10204,11 @@ DragPlugin
(view: EditorViewData): Vec3
```
+## editorViewGridPlane — function @experimental
+```
+(view: EditorViewData): EditorWorkPlane
+```
+
## editorViewHalfExtent — function @experimental
```
(view: EditorViewData, aspect: number): { halfW: number; halfH: number; }
diff --git a/sdk/src/camera/EditorView.ts b/sdk/src/camera/EditorView.ts
index 4293b59f6..d34a8e4cd 100644
--- a/sdk/src/camera/EditorView.ts
+++ b/sdk/src/camera/EditorView.ts
@@ -282,18 +282,28 @@ export interface EditorWorkPlane {
}
/**
- * Which plane that is.
+ * The plane this view is ABOUT: the ground under a 3D scene (perspective is the
+ * editor's word for looking at one), the plane 2D content lives on otherwise.
*
- * The perspective toggle is the editor's word for "this view is looking at a 3D
- * scene", and a 3D scene stands on the ground (y = 0); orthographic is the 2D
- * editor, whose plane is the one 2D content lives on. A plane the eye looks ALONG
- * offers nothing to work on, so there the plane the eye most faces answers instead
- * — which is how a perspective view held head-on is the 2D one again.
+ * Answered by the view alone, at every angle — what the GRID draws. A grid is the
+ * frame the eye judges the scene against, so one that changes plane partway
+ * through an orbit moves the frame itself; edge-on it converges into the horizon
+ * and the shader's fade takes it.
*/
-export function editorViewWorkPlane(view: EditorViewData): EditorWorkPlane {
- const nominal: EditorWorkPlane = view.perspective
+export function editorViewGridPlane(view: EditorViewData): EditorWorkPlane {
+ return view.perspective
? { u: 0, v: 2, normal: 1 }
: { u: 0, v: 1, normal: 2 };
+}
+
+/**
+ * The plane a GESTURE acts on: {@link editorViewGridPlane}, handed over to the
+ * plane the eye most faces where it would otherwise look along it — a drag on a
+ * plane seen edge-on turns a pixel of cursor travel into unbounded world motion.
+ * Input only; the grid asks the other one.
+ */
+export function editorViewWorkPlane(view: EditorViewData): EditorWorkPlane {
+ const nominal = editorViewGridPlane(view);
const screen = editorViewAxes(view);
const depth = (a: WorldAxis): number =>
Math.abs((a === 0 ? screen.x : a === 1 ? screen.y : screen.z).depth);
diff --git a/sdk/src/camera/editorGridRenderer.ts b/sdk/src/camera/editorGridRenderer.ts
index 31d322b35..b8ac55e34 100644
--- a/sdk/src/camera/editorGridRenderer.ts
+++ b/sdk/src/camera/editorGridRenderer.ts
@@ -2,15 +2,15 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file editorGridRenderer.ts
- * @brief Infinite world-space editor grid, drawn on the view's work plane.
+ * @brief Infinite world-space editor grid, drawn on the plane the view is about.
*
* `installEditorGrid(app)` registers a pre-scene draw callback (see customDraw /
* RenderPipeline): each editor frame, when `EditorGrid.enabled` and the
* `EditorView` is active, it draws one full-screen quad whose fragment shader
- * intersects that pixel's world ray with the plane the view works on
- * (`editorViewWorkPlane`) and paints minor / major / axis lines there. Because it
- * runs in the pre-scene pass, scene entities draw over it (UE5 / Unity
- * behaviour).
+ * intersects that pixel's world ray with the plane the view is about
+ * (`editorViewGridPlane` — the ground in a 3D view, the 2D plane in a flat one,
+ * at every angle) and paints minor / major / axis lines there. Because it runs in
+ * the pre-scene pass, scene entities draw over it (UE5 / Unity behaviour).
*
* The ray is built from the view's own basis rather than from a matrix inverse:
* four vec4 params carry the eye, the two screen axes scaled to what the view
@@ -37,7 +37,7 @@ import { BlendMode } from '../render/blend';
import { registerPreSceneDrawCallback } from '../render/customDraw';
import {
EditorView, editorViewHalfHeight, editorViewBasis, editorViewEye,
- editorViewStandoff, editorViewWorkPlane, worldAxisVector,
+ editorViewStandoff, editorViewGridPlane, worldAxisVector,
} from './EditorView';
import { EditorGrid, DEFAULT_EDITOR_GRID } from './EditorGrid';
@@ -257,7 +257,7 @@ export function installEditorGrid(app: App): void {
if (!grid.enabled || !view.active || grid.spacing <= 0) return;
if (!ensureResources()) return;
- const plane = editorViewWorkPlane(view);
+ const plane = editorViewGridPlane(view);
const u = worldAxisVector(plane.u);
const v = worldAxisVector(plane.v);
const basis = editorViewBasis(view);
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index b767eb557..7cad20e7a 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -42,7 +42,7 @@ export { TextureFilter, TextureWrap, setTextureFilter, setTextureWrap, setTextur
// =============================================================================
export { CameraView, CameraViewAPI } from './camera/Camera';
-export { EditorView, DEFAULT_EDITOR_VIEW, editorViewHalfHeight, editorViewHalfExtent, editorViewWorldPerPixel, setEditorViewHalfHeight, editorViewIsOrbited, editorViewAxes, editorViewAxisAngles, editorViewBasis, editorViewEye, editorViewStandoff, editorViewClipFar, editorViewClipNear, editorViewWorkPlane, screenWorkAxes, worldAxisVector, moveEditorViewFocus, editorViewBoxExtent } from './camera/EditorView';
+export { EditorView, DEFAULT_EDITOR_VIEW, editorViewHalfHeight, editorViewHalfExtent, editorViewWorldPerPixel, setEditorViewHalfHeight, editorViewIsOrbited, editorViewAxes, editorViewAxisAngles, editorViewBasis, editorViewEye, editorViewStandoff, editorViewClipFar, editorViewClipNear, editorViewWorkPlane, editorViewGridPlane, screenWorkAxes, worldAxisVector, moveEditorViewFocus, editorViewBoxExtent } from './camera/EditorView';
export type { EditorViewData, ScreenAxis, EditorViewBasis, EditorWorkPlane, WorldAxis } from './camera/EditorView';
export { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './camera/ScreenScaling';
export type { ScreenScalingData } from './camera/ScreenScaling';
diff --git a/sdk/tests/editor-view.test.ts b/sdk/tests/editor-view.test.ts
index d7d1e21cb..cda0071c3 100644
--- a/sdk/tests/editor-view.test.ts
+++ b/sdk/tests/editor-view.test.ts
@@ -69,6 +69,7 @@ import {
editorViewBoxExtent,
editorViewEye,
editorViewWorkPlane,
+ editorViewGridPlane,
moveEditorViewFocus,
worldAxisVector,
} from '../src/camera/EditorView';
@@ -272,6 +273,43 @@ describe('the work plane', () => {
});
});
+describe('the grid plane', () => {
+ it('is the 2D plane in the 2D view and the ground in the 3D one', () => {
+ expect(worldAxisVector(editorViewGridPlane(view({})).normal)).toEqual({ x: 0, y: 0, z: 1 });
+ expect(worldAxisVector(editorViewGridPlane(view({ perspective: true, pitch: 40 })).normal))
+ .toEqual({ x: 0, y: 1, z: 0 });
+ });
+
+ // Straight through the angle the work plane hands over at: a reference that
+ // changes plane mid-orbit turns the frame the eye judges the scene against.
+ it('stays the ground through the angle the work plane hands over at', () => {
+ for (const pitch of [40, 12, 6, 3, 0, -3, -12]) {
+ const p = editorViewGridPlane(view({ perspective: true, pitch }));
+ expect({ pitch, normal: worldAxisVector(p.normal) })
+ .toEqual({ pitch, normal: { x: 0, y: 1, z: 0 } });
+ }
+ });
+
+ it('stays the 2D plane through a top-down orthographic orbit', () => {
+ for (const pitch of [0, 45, 85, 90]) {
+ const p = editorViewGridPlane(view({ pitch }));
+ expect({ pitch, normal: worldAxisVector(p.normal) })
+ .toEqual({ pitch, normal: { x: 0, y: 0, z: 1 } });
+ }
+ });
+
+ // Where they differ is the whole point: a gesture cannot be aimed on a plane
+ // seen edge-on, and a reference must not move. Same view, two answers.
+ it('parts from the work plane exactly where the eye looks along it', () => {
+ const headOn = view({ perspective: true });
+ expect(editorViewGridPlane(headOn).normal).toBe(1);
+ expect(editorViewWorkPlane(headOn).normal).toBe(2);
+
+ const tilted = view({ perspective: true, pitch: 40 });
+ expect(editorViewWorkPlane(tilted)).toEqual(editorViewGridPlane(tilted));
+ });
+});
+
describe('moving the focus', () => {
it('is world x / y head-on, which is the 2D editor exactly as it was', () => {
const v = view({ x: 5, y: 7 });
diff --git a/tools/render-host/host.ts b/tools/render-host/host.ts
index 24e1b136b..b0e4c8604 100644
--- a/tools/render-host/host.ts
+++ b/tools/render-host/host.ts
@@ -9,10 +9,12 @@
* there is no authoring model between the scene file and the World.
*
* It publishes `window.__estellaHeadless`, the same shape the editor's host
- * does, so one runner drives either. Doors that only exist inside an editor
- * (the reference grid, hit-testing, the editor eye, material/mesh preview
- * renders) are absent rather than faked: a gate that needs one names the editor
- * host, and asking for one here fails with which door and why.
+ * does, so one runner drives either. Doors that need an editor SESSION —
+ * hit-testing over the authoring model, the asset previews it renders — are
+ * absent rather than faked: a gate that needs one names the editor host, and
+ * asking for one here fails with which door and why. The editor EYE and its
+ * reference grid are not among them: both are SDK resources, so the host that
+ * verifies the renderer verifies them too.
*/
import {
createWebApp, setEditorMode, setPlayMode, Assets, acquireWebGPUDevice,
@@ -20,6 +22,7 @@ import {
getComponent, DeviceStatus, getDeviceStatus, getDeviceLostReport, recoverDevice,
finishDeviceRecovery, getContextLossGuardInfo, decodeImagePixels, captureFramePixels,
RenderTexture, Camera, Sprite,
+ EditorView, EditorGrid, installEditorGrid, editorViewHalfHeight, setEditorViewHalfHeight,
} from 'esengine';
import type { App, SceneData, PrefabData, RenderSurfaceSource } from 'esengine';
import type { ESEngineModule } from 'esengine/wasm';
@@ -132,6 +135,11 @@ async function boot(): Promise<void> {
// ESTELLA_VERIFY_PLAY flips this per gate via setRunMode.
setEditorMode(true);
setPlayMode(false);
+
+ // The reference grid is SDK code drawn through an SDK resource, so the engine's
+ // own host can verify it. It stays dark until a gate asks: the renderer self-
+ // gates on EditorGrid.enabled and EditorView.active, and this host leaves both off.
+ installEditorGrid(app);
}
/**
@@ -354,16 +362,78 @@ const api = {
return nodes.filter((e) => e.parent === null || e.parent === undefined).map((e) => build(e.id));
},
- // Editor doors, absent by design.
- setGrid: () => editorOnly('set_grid'),
+ /**
+ * The editor's eye, which is an SDK resource and not an editor session: the
+ * camera plugin inserts `EditorView` into every App, and `installEditorGrid`
+ * draws through it. Seeded from the scene's own camera on the way on, as the
+ * editor's door does, so a gate frames what the scene frames.
+ */
+ useEditorView(on: boolean): void {
+ if (!app) throw new Error('use_editor_view before boot');
+ const view = app.getResource(EditorView);
+ if (on) seedEditorViewFromScene();
+ view.active = on;
+ },
+
+ /** Turn the eye: yaw about world +Y, pitch above the ground, in degrees. */
+ setViewOrbit(yaw: number, pitch: number): void {
+ if (!app) throw new Error('set_view_orbit before boot');
+ const view = app.getResource(EditorView);
+ view.yaw = Number(yaw) || 0;
+ view.pitch = Number(pitch) || 0;
+ },
+
+ /** Look at the scene as a 3D one, keeping the framing: the two projections
+ * zoom with different fields, so flipping the flag alone jumps the zoom. */
+ setViewPerspective(on: boolean): void {
+ if (!app) throw new Error('set_view_perspective before boot');
+ const view = app.getResource(EditorView);
+ if (view.perspective === on) return;
+ const seen = editorViewHalfHeight(view);
+ view.perspective = on;
+ setEditorViewHalfHeight(view, seen);
+ },
+
+ /** The reference grid. Enabling seeds and activates the eye it draws through,
+ * because this host boots with that eye inactive. */
+ setGrid(enabled: boolean, spacing?: number): void {
+ if (!app) throw new Error('set_grid before boot');
+ if (enabled) {
+ seedEditorViewFromScene();
+ app.getResource(EditorView).active = true;
+ }
+ const grid = app.getResource(EditorGrid);
+ grid.enabled = enabled;
+ if (spacing != null && Number(spacing) > 0) grid.spacing = Number(spacing);
+ },
+
+ // Editor doors, absent by design: these need an editor SESSION (a hit test
+ // over the authoring model, the asset previews it renders), not a resource.
pick: () => editorOnly('pick'),
- useEditorView: () => editorOnly('use_editor_view'),
- setViewOrbit: () => editorOnly('set_view_orbit'),
- setViewPerspective: () => editorOnly('set_view_perspective'),
renderSceneMaterialPreview: () => editorOnly('render_scene_material_preview'),
renderSceneMeshPreview: () => editorOnly('render_scene_mesh_preview'),
};
+/**
+ * Point the editor eye where the scene's own camera looks, at the extent it sees.
+ * Not the camera's z: that is where its EYE stands, and adopting it as a focus
+ * would put everything the camera frames behind the editor's own.
+ */
+function seedEditorViewFromScene(): void {
+ if (!app) return;
+ const view = app.getResource(EditorView);
+ for (const e of app.world.getAllEntities()) {
+ const cam = app.world.get(e, Camera) as { isActive?: boolean; orthoSize?: number } | undefined;
+ if (!cam?.isActive) continue;
+ const t = app.world.get(e, Transform) as { position?: { x: number; y: number } } | undefined;
+ view.x = t?.position?.x ?? 0;
+ view.y = t?.position?.y ?? 0;
+ view.z = 0;
+ if (cam.orthoSize) setEditorViewHalfHeight(view, cam.orthoSize);
+ return;
+ }
+}
+
/** Reads `path` ("a.b.c") out of `obj`, or undefined at the first missing hop. */
function readFieldPath(obj: unknown, path: string): unknown {
let at: unknown = obj;
diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjs
index 83f269d1a..71b563cfb 100644
--- a/tools/render-host/run.mjs
+++ b/tools/render-host/run.mjs
@@ -603,12 +603,12 @@ app.whenReady().then(async () => {
let grid = null;
if (process.env.ESTELLA_VERIFY_GRID) {
const spacing = Number(process.env.ESTELLA_VERIFY_GRID) || 64;
- // What the grid owes this view. A plane the eye lies IN is edge-on through
- // the eye's own point: it has no picture, and "none" is the answer rather
- // than a frame nobody can read.
+ // "nothing": a plane the eye lies IN meets every ray at its own point and
+ // has no picture. "grazing": a plane the eye looks ALONG lights one half far
+ // more than the other, where one it FACES lights the frame evenly.
const wantGrid = process.env.ESTELLA_VERIFY_GRID_EXPECT ?? 'frame';
- if (wantGrid !== 'frame' && wantGrid !== 'nothing') {
- throw new Error(`ESTELLA_VERIFY_GRID_EXPECT is "frame" or "nothing", not "${wantGrid}"`);
+ if (!['frame', 'nothing', 'grazing'].includes(wantGrid)) {
+ throw new Error(`ESTELLA_VERIFY_GRID_EXPECT is "frame", "grazing" or "nothing", not "${wantGrid}"`);
}
await exec(`window.__estellaHeadless.api.setGrid(true, ${spacing})`);
await exec('window.__estellaHeadless.api.step(2, 1 / 60)');
@@ -644,10 +644,16 @@ app.whenReady().then(async () => {
// A grid is there everywhere you look, so every quarter of the frame has
// some of it. A plane seen edge-on lights one band and passes a total.
const covers = differing > 300 && quadrants.every((q) => q > 20);
+ // Lopsided by half the frame: 1.4 sits between what the two cases measure
+ // (a floor at 4 degrees is ~1.7, a plane turned to face the eye ~1.1).
+ const top = quadrants[0] + quadrants[1];
+ const bottom = quadrants[2] + quadrants[3];
+ const lopsided = differing > 300 && Math.min(top, bottom) > 0
+ && Math.max(top, bottom) >= 1.4 * Math.min(top, bottom);
const want = ${JSON.stringify(wantGrid)};
return {
- differingPixels: differing, quadrants, want,
- ok: want === 'nothing' ? differing === 0 : covers,
+ differingPixels: differing, quadrants, want, halves: [top, bottom],
+ ok: want === 'nothing' ? differing === 0 : want === 'grazing' ? lopsided : covers,
};
`);
}
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 59f0010cf..fd5e05b53 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -58,13 +58,17 @@ export function sceneWatchdogMs(backend, host) {
export const SCENES = [
{ id: "sprite-default", tier: "pr", webgpu: true, env: { } },
// Editor grid on/off pixel diff — guards the custom-draw reflected material path (drawMeshWithMaterial + MaterialConstants UBO).
- { id: "editor-grid", tier: "pr", host: "editor", webgpu: true, env: { ESTELLA_VERIFY_GRID: "64", ESTELLA_VERIFY_STEPS: "3" } },
+ { id: "editor-grid", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_GRID: "64", ESTELLA_VERIFY_STEPS: "3" } },
// The same grid from straight above a 3D view. It stands on the ground there, so it fills the frame; the 2D plane would be edge-on and light one band.
- { id: "editor-grid-3d", tier: "pr", host: "editor", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-instanced.esscene", ESTELLA_VERIFY_GRID: "64", ESTELLA_VERIFY_PERSPECTIVE: "1", ESTELLA_VERIFY_ORBIT: "0,90", ESTELLA_VERIFY_STEPS: "3" } },
- // The same 3D view head-on. A plane within ~6 degrees of edge-on hands over to the
- // plane the eye most faces, which head-on is the 2D plane — so the grid covers the
- // frame instead of collapsing to the one stroke an edge-on plane draws.
- { id: "editor-grid-head-on", tier: "pr", host: "editor", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-instanced.esscene", ESTELLA_VERIFY_GRID: "64", ESTELLA_VERIFY_PERSPECTIVE: "1", ESTELLA_VERIFY_ORBIT: "0,0", ESTELLA_VERIFY_STEPS: "3" } },
+ { id: "editor-grid-3d", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-instanced.esscene", ESTELLA_VERIFY_GRID: "64", ESTELLA_VERIFY_PERSPECTIVE: "1", ESTELLA_VERIFY_ORBIT: "0,90", ESTELLA_VERIFY_STEPS: "3" } },
+ // The same 3D view head-on, where this fixture's eye lies IN the ground: every
+ // ray meets it at the eye's own point, so it has no picture. The grid does NOT
+ // hand over to the plane the eye most faces — that hand-over is for gestures.
+ { id: "editor-grid-head-on", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-instanced.esscene", ESTELLA_VERIFY_GRID: "64", ESTELLA_VERIFY_GRID_EXPECT: "nothing", ESTELLA_VERIFY_PERSPECTIVE: "1", ESTELLA_VERIFY_ORBIT: "0,0", ESTELLA_VERIFY_STEPS: "3" } },
+ // Just off head-on: the ground, bottom-heavy the way a floor receding to a
+ // horizon is. A plane turned to meet the eye lights the frame evenly and passes
+ // the coverage check, so "grazing" is what tells the two apart.
+ { id: "editor-grid-grazing", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-instanced.esscene", ESTELLA_VERIFY_GRID: "64", ESTELLA_VERIFY_GRID_EXPECT: "grazing", ESTELLA_VERIFY_PERSPECTIVE: "1", ESTELLA_VERIFY_ORBIT: "0,4", ESTELLA_VERIFY_STEPS: "3" } },
{ id: "mesh-renderer", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-renderer.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-renderer.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.30,\"y\":0.556,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.70,\"y\":0.556,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.30,\"y\":0.40,\"rgb\":[255,0,0],\"tol\":40}]" } },
{ id: "parallax-shape", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/parallax-shape.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/parallax-shape.textures.json", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.25,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40}]" } },
{ id: "tilemap-flip", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/tilemap-flip.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/tilemap-flip.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.40,\"y\":0.36,\"rgb\":[255,0,0]},{\"x\":0.60,\"y\":0.36,\"rgb\":[0,255,0]},{\"x\":0.40,\"y\":0.58,\"rgb\":[0,0,255]},{\"x\":0.60,\"y\":0.58,\"rgb\":[255,255,0]}]" } },