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
import type { App } from '../app/app';
import { defineResource } from '../ecs/resource';
import { UICameraInfo, type UICameraData } from '../ui/core/ui-camera-info';
import { platformDevicePixelRatio } from '../platform';
import { CameraCommit } from './CameraCommit';
import type { Vec3 } from '../types';
import { pointerToScreen, screenToWorld, projectWorldPoint, projectDirectionAt, nearPlaneSide, isProjectable, createInvVPCache, screenRay, type WorldRay } from '../ui/util/math';
/**
* Per-App camera-space query API: screen<->world conversions, the world-space
* mouse position, and the active camera's world bounds.
*
* Reads the per-App {@link UICameraInfo} resource. Each App holds its own
* instance (published as the {@link CameraView} resource) and its own
* inverse-view-projection cache, so two Apps running at once never share a
* single cached `app` or clobber each other's cache.
*/
/** How far inside the near plane a cut lands, as a fraction of the segment. */
const CLIP_NUDGE = 1e-4;
/**
* The camera as a LENS — what a projection needs, and nothing about the surface.
*
* Narrower than {@link UICameraData} on purpose: it is the part two different
* cameras can both supply, one being resolved and one already drawn with.
* @beta
*/
export interface CameraLens {
viewProjection: Float32Array;
vpX: number;
vpY: number;
vpW: number;
vpH: number;
}
/** The camera currently being resolved — moves twice a frame. */
const liveLens = (app: App): CameraLens | null => {
const cam: UICameraData = app.getResource(UICameraInfo);
return cam.valid ? cam : null;
};
/** The camera the last frame was drawn with. */
const committedLens = (app: App): CameraLens | null => {
const commit = app.getResource(CameraCommit);
return commit.valid ? commit : null;
};
export class CameraViewAPI {
private readonly invVPCache = createInvVPCache();
/**
* @param lens_ Which camera this view answers for. The default is the one
* being resolved — what a system inside the frame wants.
* Anything aligning to the PICTURE wants
* {@link PresentedCameraView}: the live one moves mid-frame and
* can hold a state no frame was drawn from.
*/
constructor(
private readonly app_: App,
private readonly lens_: (app: App) => CameraLens | null = liveLens,
) {}
private cam(): CameraLens | null {
return this.lens_(this.app_);
}
/**
* The live UI surface, for the two answers that are not projections.
*
* Where the pointer is and what box UI lays out within are facts about the
* surface as it stands, not about a picture that was drawn — so they read
* the live resource even on a view over the committed camera.
*/
private surface(): UICameraData | null {
const cam = this.app_.getResource(UICameraInfo);
return cam.valid ? cam : null;
}
/**
* Where a screen point lands on the world plane at @p planeZ.
*
* @p screenX / @p screenY are FRAMEBUFFER pixels, y growing up from the
* bottom edge. For the pointer use {@link pointerToWorld}, which takes
* `input.mouseX` / `input.mouseY` as they come.
*
* A screen point is a ray. Orthographically its x/y do not vary along it, so
* the plane is irrelevant and the default answers for everyone. Under a
* perspective camera it decides the answer, and the right plane is the one
* the thing being hit or dragged actually sits on — z = 0 would place a
* sprite at z = -400 wherever its shadow on the 2D plane happens to fall.
*/
screenToWorld(screenX: number, screenY: number, planeZ = 0): { x: number; y: number } | null {
const cam = this.cam();
if (!cam) return null;
this.invVPCache.update(cam.viewProjection);
const invVP = this.invVPCache.getInverse(cam.viewProjection);
return screenToWorld(screenX, screenY, invVP, cam.vpX, cam.vpY, cam.vpW, cam.vpH, planeZ);
}
/**
* Where the POINTER lands on the world plane at @p planeZ, taking the
* coordinates {@link Input} reports (`input.mouseX` / `input.mouseY`, a
* touch's x / y): CSS pixels, y down from the top.
*
* `screenToWorld` takes framebuffer pixels with y UP — what the renderer and
* the editor viewport work in. Feeding it the pointer directly mirrors the
* answer about the viewport's centre; this is the call a game wants.
*/
pointerToWorld(pointerX: number, pointerY: number, planeZ = 0): { x: number; y: number } | null {
const s = this.pointerScreen(pointerX, pointerY);
return s ? this.screenToWorld(s.x, s.y, planeZ) : null;
}
/** The world ray under the pointer, in {@link Input}'s coordinates — see {@link pointerToWorld}. */
pointerRay(pointerX: number, pointerY: number): WorldRay | null {
const s = this.pointerScreen(pointerX, pointerY);
return s ? this.screenRay(s.x, s.y) : null;
}
private pointerScreen(pointerX: number, pointerY: number): { x: number; y: number } | null {
const surface = this.surface();
if (!surface) return null;
return pointerToScreen(pointerX, pointerY, platformDevicePixelRatio(), surface.screenH);
}
/**
* The world ray a screen point names — what `screenToWorld` intersects with
* the z plane. Callers that drag along an arbitrary plane (an editor moving
* along a world axis, a pick against the ground) need the ray itself: a
* z-keyed answer cannot express a plane that is not z-keyed.
*/
screenRay(screenX: number, screenY: number): WorldRay | null {
const cam = this.cam();
if (!cam) return null;
this.invVPCache.update(cam.viewProjection);
const invVP = this.invVPCache.getInverse(cam.viewProjection);
return screenRay(screenX, screenY, invVP, cam.vpX, cam.vpY, cam.vpW, cam.vpH);
}
/**
* Where the world point lands on screen — the inverse of `screenToWorld`,
* taking the same third dimension. Under a perspective camera a point at
* @p worldZ projects nowhere near its shadow on the 2D plane, so anything
* drawing an overlay ON an entity (an outline, a gizmo, a screen rect) has to
* pass the entity's z or it draws where the entity is not.
*
* Null means the point has NO screen position: no camera, or it stands at or
* behind the eye, where the divide mirrors it to the far side of the view.
* Outside the viewport is NOT that, and keeps its coordinates.
*/
worldToScreen(worldX: number, worldY: number, worldZ = 0): { x: number; y: number } | null {
const cam = this.cam();
if (!cam) return null;
const p = projectWorldPoint(worldX, worldY, worldZ,
cam.viewProjection, cam.vpX, cam.vpY, cam.vpW, cam.vpH);
return isProjectable(p) ? { x: p.x, y: p.y } : null;
}
/**
* The part of segment @p a → @p b that can be drawn, cut at the near plane.
*
* @details One end behind the eye still leaves a visible part, and dropping the
* whole segment is what makes a wireframe come apart as the eye moves
* into it. Null when none of it is in front.
*/
clipSegment(a: Vec3, b: Vec3): { a: Vec3; b: Vec3 } | null {
const cam = this.cam();
if (!cam) return null;
const at = (p: Vec3) => projectWorldPoint(p.x, p.y, p.z,
cam.viewProjection, cam.vpX, cam.vpY, cam.vpW, cam.vpH);
const sa = nearPlaneSide(at(a));
const sb = nearPlaneSide(at(b));
if (sa >= 0 && sb >= 0) return { a, b };
if (sa < 0 && sb < 0) return null;
const cross = sa / (sa - sb);
const t = sa >= 0 ? cross * (1 - CLIP_NUDGE) : cross + (1 - cross) * CLIP_NUDGE;
const cut = {
x: a.x + (b.x - a.x) * t,
y: a.y + (b.y - a.y) * t,
z: a.z + (b.z - a.z) * t,
};
return sa >= 0 ? { a, b: cut } : { a: cut, b };
}
/**
* Where a world DIRECTION points on screen at @p at — px per world unit, y-up.
*
* @details Null when @p at has no projection. Perspective makes this a fact
* about the POINT: an arm drawn on something asks here, where a basis
* read off the camera answers only for the centre of the view.
*/
projectDirectionAt(at: Vec3, dir: Vec3): { x: number; y: number } | null {
const cam = this.cam();
if (!cam) return null;
const p = projectWorldPoint(at.x, at.y, at.z,
cam.viewProjection, cam.vpX, cam.vpY, cam.vpW, cam.vpH);
if (!isProjectable(p)) return null;
return projectDirectionAt(p, dir.x, dir.y, dir.z,
cam.viewProjection, cam.vpX, cam.vpY, cam.vpW, cam.vpH);
}
getWorldMousePosition(): { x: number; y: number } | null {
const cam = this.surface();
if (!cam) return null;
return { x: cam.worldMouseX, y: cam.worldMouseY };
}
getWorldBounds(): { left: number; right: number; bottom: number; top: number } | null {
const cam = this.surface();
if (!cam) return null;
return { left: cam.worldLeft, right: cam.worldRight, bottom: cam.worldBottom, top: cam.worldTop };
}
}
/**
* Per-App camera-query API resource, published by `cameraPlugin` on every core
* (web and native alike). Read it as
* `app.getResource(CameraView)` to convert screen<->world etc. (Named
* `CameraView` rather than `Camera` because `Camera` is the ECS component.)
*/
export const CameraView = defineResource<CameraViewAPI>(null!, 'CameraView');
/**
* The same queries, against the camera the last frame was actually drawn with.
*
* One implementation, two sources: a second projection written over the commit
* would be a second near-plane cut to keep in step, and a wireframe cut by one
* and drawn by the other comes apart exactly where a segment leaves the view.
* @beta
*/
export const PresentedCameraView = defineResource<CameraViewAPI>(null!, 'PresentedCameraView');
/** A view over the camera the last frame was drawn with. @beta */
export const presentedCameraView = (app: App): CameraViewAPI => new CameraViewAPI(app, committedLens);