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
/**
* @file EditorView.ts
* @brief Editor viewport camera — a dedicated, editor-only eye on the scene.
*
* This is NOT a scene entity: it is never serialized, never on the undo stack,
* and never part of the saved scene. When `active`, the camera system renders
* the framebuffer through this view and drives all screen<->world queries from
* it (CameraView / UICameraInfo) INSTEAD of the scene's game Camera entities —
* so editor navigation (pan / zoom / frame / orbit) moves only this view and never
* the scene's camera. In play mode it is deactivated, so the viewport shows the
* real game camera (the true "Game" view). The editor mutates the focus, the zoom
* and the angles the eye stands at; the head-on 2D view is all of them at zero.
*
* The view's view-projection is built from the SAME math primitives as scene
* cameras (see CameraPlugin) — there is one source of view-projection math; only
* the camera *configuration* (full-frame, raw orthoSize) differs.
*/
import { defineResource } from '../ecs/resource';
import { invertViewOrbit } from '../math/mat4';
import type { Vec3 } from '../types';
export interface EditorViewData {
/** When true, the framebuffer + screen<->world use this view, not scene cameras. */
active: boolean;
/** World-space point the view looks at and turns around. */
x: number;
y: number;
/** Depth of that point. Zero is the 2D plane, where a project that never
* leaves it stays. */
z: number;
/** Half-height of the view in world units (zoom; smaller = more zoomed in). */
orthoSize: number;
/**
* `false` (default) is the 2D view: an orthographic projection where zoom is
* `orthoSize` and depth cannot be seen. `true` previews the scene the way a
* perspective game camera would — the only way to look at 2.5D content while
* authoring it.
*
* The view keeps its OWN projection rather than following the scene's camera,
* which is the same choice UE and Unity make: an orthographic view of a
* perspective scene is a working mode (a top-down or side elevation), not a
* mismatch to be corrected. What the game will look like is the Game view's
* job; this is the editor's own eye.
*/
perspective: boolean;
/** Vertical field of view in degrees, used only when `perspective`. */
fov: number;
/**
* Camera distance along +z, used only when `perspective`. This is what zoom
* moves in that mode — a perspective view cannot zoom by widening a box, and
* changing the fov instead would alter the projection the user is previewing.
*/
distance: number;
/**
* Where the eye stands relative to the focus (x, y): yaw about world +Y, pitch
* above the xz plane, in DEGREES like `fov`. Both zero is the head-on 2D view,
* and every 2D projection stays exactly what it was there — orbiting is what a
* 3D scene needs to be looked at, not a different camera.
*/
yaw: number;
pitch: number;
/**
* Aspect ratio the editor lays UI out against, so the editor previews how UI adapts
* on a simulated device: `> 0` fits the design resolution into this aspect (the device
* simulator), `0` uses the authored design aspect — WYSIWYG at the design resolution.
* Editor-only; scene cameras (shipped games) ignore it. See uiLayoutRect.
*/
uiPreviewAspect: number;
}
export const DEFAULT_EDITOR_VIEW: EditorViewData = {
active: false, x: 0, y: 0, z: 0, orthoSize: 360, uiPreviewAspect: 0,
// Off by default: an existing project opens on exactly the view it always had.
perspective: false, fov: 60, distance: 1000, yaw: 0, pitch: 0,
};
/**
* Half-height, in world units, of what the view sees on the z = 0 plane — where
* 2D content lives and where the grid, the framing and the minimap all measure.
*
* Orthographically this IS `orthoSize`. In perspective the visible extent is the
* frustum's cross-section at the focus plane, `tan(fov/2) · distance` — merely
* proportional to the zoom value, not equal to it. Everything that needs "how
* much world is on screen" asks here rather than reading `orthoSize`, which
* answers for one of the two projections and silently mis-scales the other.
*/
export function editorViewHalfHeight(view: EditorViewData): number {
return view.perspective
? Math.tan((view.fov * Math.PI) / 180 / 2) * view.distance
: view.orthoSize;
}
/** {@link editorViewHalfHeight} with the panel aspect applied — the visible world rect. */
export function editorViewHalfExtent(
view: EditorViewData, aspect: number,
): { halfW: number; halfH: number } {
const halfH = editorViewHalfHeight(view);
return { halfW: halfH * (aspect > 0 ? aspect : 1), halfH };
}
/**
* World units per screen pixel at @p at — what a thing drawn at a fixed number of
* pixels measures in the world where it stands. Orthographically the same
* everywhere; in perspective it grows with the distance along the view axis, which
* is the axis the projection divides by. Without @p at, the focus answers.
*/
export function editorViewWorldPerPixel(
view: EditorViewData, heightPx: number, at?: Vec3,
): number {
const base = heightPx > 0 ? (2 * editorViewHalfHeight(view)) / heightPx : 0;
const standoff = editorViewStandoff(view);
if (!view.perspective || !at || standoff <= 0) return base;
const eye = editorViewEye(view);
const f = editorViewBasis(view).forward;
const along = (at.x - eye.x) * f.x + (at.y - eye.y) * f.y + (at.z - eye.z) * f.z;
// Behind the eye there is no size to report; the focus's own scale is the
// nearest honest answer and keeps a marker there clickable rather than infinite.
return along > 0 ? base * (along / standoff) : base;
}
/**
* Zoom the view until it sees @p halfH world units of height, writing whichever
* field this projection zooms with. The inverse of {@link editorViewHalfHeight},
* so "frame this" and "how big is what I see" cannot disagree.
*/
export function setEditorViewHalfHeight(view: EditorViewData, halfH: number): void {
if (view.perspective) {
const t = Math.tan((view.fov * Math.PI) / 180 / 2);
view.distance = t > 0 ? halfH / t : halfH;
} else {
view.orthoSize = halfH;
}
}
export const EditorView = defineResource<EditorViewData>({ ...DEFAULT_EDITOR_VIEW }, 'EditorView');
/**
* True when the view is turned away from the head-on 2D one. Absent angles read
* as zero: a workspace saved before this existed, or a partial view an embedder
* hands in, is the 2D view — not an orbit by NaN.
*/
export function editorViewIsOrbited(view: EditorViewData): boolean {
return (view.yaw ?? 0) !== 0 || (view.pitch ?? 0) !== 0;
}
/** A world axis as it points on screen: a unit direction (y down, as screens are)
* plus how far it leans toward the eye — `1` straight at it, `-1` straight away. */
export interface ScreenAxis {
dx: number;
dy: number;
depth: number;
}
/**
* Where the world axes point on screen for this view. Read off the very basis the
* camera is built from, so an indicator drawn from it cannot disagree with what is
* rendered — a second copy of the rotation is exactly how those two drift apart.
*/
export function editorViewAxes(view: EditorViewData): { x: ScreenAxis; y: ScreenAxis; z: ScreenAxis } {
const m = orbitMatrix(view);
// Column c of the view matrix is a world axis expressed in view space.
const axis = (c: number): ScreenAxis => ({ dx: m[c], dy: -m[c + 1], depth: m[c + 2] });
return { x: axis(0), y: axis(4), z: axis(8) };
}
// The one place yaw/pitch become a basis; everything below reads its rows.
function orbitMatrix(view: EditorViewData): Float32Array {
const rad = Math.PI / 180;
return invertViewOrbit(0, 0, 0, (view.yaw ?? 0) * rad, (view.pitch ?? 0) * rad, 0);
}
/** The view's own axes as world directions — unit, and right-handed with forward. */
export interface EditorViewBasis {
right: Vec3;
up: Vec3;
forward: Vec3;
}
/**
* Where the view's right / up / forward point in the world.
*
* A drag is a screen direction, and this is what it means in world terms. Read
* off the very matrix the camera is built from, so navigation cannot move along
* axes the picture was not drawn with.
*/
export function editorViewBasis(view: EditorViewData): EditorViewBasis {
const m = orbitMatrix(view);
return {
right: { x: m[0], y: m[4], z: m[8] },
up: { x: m[1], y: m[5], z: m[9] },
forward: { x: -m[2], y: -m[6], z: -m[10] },
};
}
/**
* How far the eye stands off the focus. A perspective eye has to stand
* somewhere, and so does an orbited orthographic one; head-on 2D does not.
*/
export function editorViewStandoff(view: EditorViewData): number {
return view.perspective || editorViewIsOrbited(view) ? view.distance : 0;
}
/**
* How far the view's volume reaches, from the EYE — which stands off what it is
* looking at, and spends that stand-off before the scene begins. So the reach past
* the focus is constant and the stand-off is added to it; a head-on orthographic
* eye, which has none, is left with exactly the reach it always had.
*/
export function editorViewClipFar(view: EditorViewData): number {
return editorViewStandoff(view) + EDITOR_VIEW_REACH;
}
/**
* Where the volume begins, from the eye. Zero orthographically — that projection
* builds a symmetric box and ignores it. Depth resolution goes as distance² over
* near, and the stand-off IS the distance, so how close the near plane may sit is
* a question about the zoom. The floor is what answers at a close-up eye.
*/
export function editorViewClipNear(view: EditorViewData): number {
return view.perspective
? Math.max(EDITOR_VIEW_NEAR_FLOOR, editorViewStandoff(view) * EDITOR_VIEW_NEAR_FRACTION)
: 0;
}
/** How far past what the view is looking at its volume extends. */
const EDITOR_VIEW_REACH = 100000;
/** The near plane as a fraction of the stand-off, and the closest it ever sits. */
const EDITOR_VIEW_NEAR_FRACTION = 1e-3;
const EDITOR_VIEW_NEAR_FLOOR = 0.1;
/** Where the eye stands in world space. */
export function editorViewEye(view: EditorViewData): Vec3 {
const m = orbitMatrix(view);
const d = editorViewStandoff(view);
return {
x: view.x + m[2] * d,
y: view.y + m[6] * d,
z: (view.z ?? 0) + m[10] * d,
};
}
export function editorViewpoint(view: EditorViewData): Vec3 | null {
if (!view.active) return null;
return view.perspective ? editorViewEye(view) : { x: view.x, y: view.y, z: view.z ?? 0 };
}
/**
* Move the focus by an offset in the view's OWN axes, in world units.
*
* Every navigation that is not a turn is this: a drag, a zoom about the cursor,
* a dolly. Expressing them here is what keeps them from each picking a world
* plane of their own, which is only the same answer while the eye is head-on.
*/
export function moveEditorViewFocus(
view: EditorViewData, right: number, up: number, forward = 0,
): void {
const b = editorViewBasis(view);
view.x += b.right.x * right + b.up.x * up + b.forward.x * forward;
view.y += b.right.y * right + b.up.y * up + b.forward.y * forward;
view.z = (view.z ?? 0) + b.right.z * right + b.up.z * up + b.forward.z * forward;
}
/**
* How much of the screen's two axes an axis-aligned box of half-size @p half
* covers, in world units — what "fit this in the frame" has to measure.
*/
export function editorViewBoxExtent(
view: EditorViewData, half: Vec3,
): { right: number; up: number } {
const b = editorViewBasis(view);
const along = (a: Vec3): number =>
Math.abs(a.x) * half.x + Math.abs(a.y) * half.y + Math.abs(a.z) * half.z;
return { right: along(b.right), up: along(b.up) };
}
/** A world axis, as an index into (x, y, z). */
export type WorldAxis = 0 | 1 | 2;
/** The world plane a view works on, through the origin: the two axes that run in
* it, and the one it is normal to. */
export interface EditorWorkPlane {
u: WorldAxis;
v: WorldAxis;
normal: WorldAxis;
}
/**
* 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.
*
* 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 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);
if (depth(nominal.normal) >= PLANE_SEEN_MIN) return nominal;
const normal = ([0, 1, 2] as WorldAxis[]).reduce((best, a) => (depth(a) > depth(best) ? a : best), 0);
const [u, v] = ([0, 1, 2] as WorldAxis[]).filter((a) => a !== normal);
return { u: u!, v: v!, normal };
}
/** How square-on a plane must be to be the one worked on — about 6° off edge-on. */
const PLANE_SEEN_MIN = 0.1;
/**
* The work-plane axis a screen direction names, with the sign pointing that way —
* what "right" and "up" mean for a gesture on that plane. `right` resolves first
* and `up` takes the plane's other axis, so the pair is never one axis twice.
* Head-on: +X right, +Y up.
*/
export function screenWorkAxes(
view: EditorViewData,
): { right: { axis: WorldAxis; sign: number }; up: { axis: WorldAxis; sign: number } } {
const plane = editorViewWorkPlane(view);
const screen = editorViewAxes(view);
const of = (a: WorldAxis): ScreenAxis => (a === 0 ? screen.x : a === 1 ? screen.y : screen.z);
const candidates: WorldAxis[] = [plane.u, plane.v];
// Screen y runs down, so pointing up the screen is a negative dy.
const score = (a: WorldAxis, sign: number, dir: 'right' | 'up'): number =>
sign * (dir === 'right' ? of(a).dx : -of(a).dy);
const best = (axes: WorldAxis[], dir: 'right' | 'up'): { axis: WorldAxis; sign: number } => {
let out = { axis: axes[0]!, sign: 1 };
let top = -Infinity;
for (const a of axes) {
for (const sign of [1, -1]) {
const v = score(a, sign, dir);
if (v > top) { top = v; out = { axis: a, sign }; }
}
}
return out;
};
const right = best(candidates, 'right');
const up = best(candidates.filter((a) => a !== right.axis), 'up');
return { right, up };
}
/** A world axis as a unit vector. */
export function worldAxisVector(axis: WorldAxis): Vec3 {
return { x: axis === 0 ? 1 : 0, y: axis === 1 ? 1 : 0, z: axis === 2 ? 1 : 0 };
}
/**
* Yaw/pitch that put the eye on a world axis, looking back down it — the standard
* views (front, side, top) every DCC offers. `sign` picks which end of the axis the
* eye stands on.
*/
export function editorViewAxisAngles(axis: 'x' | 'y' | 'z', sign: 1 | -1): { yaw: number; pitch: number } {
if (axis === 'y') return { yaw: 0, pitch: 90 * sign };
if (axis === 'x') return { yaw: 90 * sign, pitch: 0 };
return { yaw: sign > 0 ? 0 : 180, pitch: 0 };
}