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 { Entity } from '../../types';
import type { World } from '../../ecs/world';
import type { UICameraData } from '../core/ui-camera-info';
import type { ScreenOverlayData } from '../core/screen-overlay';
import { worldEngineApi } from '../../ecs/bridge/engineApi';
import { screenToWorld, projectWorldPoint, createInvVPCache, screenRay, type WorldRay } from './math';
const NO_HIT = 0xffffffff;
const vpCache = createInvVPCache();
const overlayCache = createInvVPCache();
export function screenToUiWorld(camera: UICameraData, screenGLX: number, screenGLY: number): { x: number; y: number } {
vpCache.update(camera.viewProjection);
const invVP = vpCache.getInverse(camera.viewProjection);
return screenToWorld(screenGLX, screenGLY, invVP, camera.vpX, camera.vpY, camera.vpW, camera.vpH);
}
/**
* The world ray a screen point names, through the UI camera.
*
* @details {@link screenToUiWorld} answers with this ray meeting ONE plane, which
* picking cannot use: a mesh is a solid and a sprite stands at any depth.
*/
export function uiPointerRay(camera: UICameraData, screenGLX: number, screenGLY: number): WorldRay {
vpCache.update(camera.viewProjection);
const invVP = vpCache.getInverse(camera.viewProjection);
return screenRay(screenGLX, screenGLY, invVP, camera.vpX, camera.vpY, camera.vpW, camera.vpH);
}
/**
* The LAYOUT point a screen pixel names, through the same matrix the overlay
* draws with — the same one, not an equivalent one. Two derivations agree until
* either gains a case, and the symptom then is a HUD that looks right and clicks
* somewhere else.
*/
export function screenToUiLayout(
overlay: ScreenOverlayData, screenGLX: number, screenGLY: number,
): { x: number; y: number } {
overlayCache.update(overlay.projection);
const invVP = overlayCache.getInverse(overlay.projection);
return screenToWorld(screenGLX, screenGLY, invVP,
overlay.vpX, overlay.vpY, overlay.vpW, overlay.vpH);
}
/** The layout-domain ray a screen point names — {@link screenToUiLayout}'s
* answer as the ray a pick needs, since a UI node stands at its own z. */
export function uiLayoutRay(
overlay: ScreenOverlayData, screenGLX: number, screenGLY: number,
): WorldRay {
overlayCache.update(overlay.projection);
const invVP = overlayCache.getInverse(overlay.projection);
return screenRay(screenGLX, screenGLY, invVP,
overlay.vpX, overlay.vpY, overlay.vpW, overlay.vpH);
}
/**
* The pointer, in the coordinates @p entity's own transform lives in.
*
* A UI system that subtracts a pointer from a transform — a drag, a slider's
* fraction, a caret — needs the two in one domain, and which domain that is
* depends on the entity.
*/
export function uiPointerFor(
world: PickableWorld,
entity: Entity,
camera: UICameraData,
overlay: ScreenOverlayData,
): { x: number; y: number } {
return isScreenEntity(world, entity)
? { x: overlay.pointerX, y: overlay.pointerY }
: { x: camera.worldMouseX, y: camera.worldMouseY };
}
/** Whether @p entity is laid out on the screen rather than in the world — the
* engine's own answer (UISystem::screenDomain), never a second derivation. */
export function isScreenEntity(world: PickableWorld, entity: Entity): boolean {
const c = core(world);
return c?.engine.ui_isScreenDomain?.(c.registry, entity as number) ?? false;
}
/** A layout point's pixel on the surface, through the overlay's own projection —
* the forward of {@link screenToUiLayout}, for anchoring something the OS draws
* (an IME candidate window) under something the engine drew. */
export function uiLayoutToScreen(
overlay: ScreenOverlayData, x: number, y: number,
): { x: number; y: number } {
const p = projectWorldPoint(x, y, 0, overlay.projection,
overlay.vpX, overlay.vpY, overlay.vpW, overlay.vpH);
return { x: p.x, y: p.y };
}
export function uiWorldToScreen(camera: UICameraData, worldX: number, worldY: number): { x: number; y: number } {
const p = projectWorldPoint(worldX, worldY, 0, camera.viewProjection,
camera.vpX, camera.vpY, camera.vpW, camera.vpH);
return { x: p.x, y: p.y };
}
/**
* What picking asks of a world: the two accessors that reach the engine core.
* Named as a subset so a host holding a narrowed view of the world can still
* pick, without the helpers claiming to need the rest of it.
*/
export type PickableWorld = Pick<World, 'getCppRegistry' | 'getWasmModule'>;
/** The engine and the registry behind a world, or null when either is absent. */
function core(world: PickableWorld) {
const engine = worldEngineApi(world);
const registry = world.getCppRegistry();
return engine && registry ? { engine, registry } : null;
}
/**
* The topmost **interactable** entity along a pointer ray — the same raycast the
* interaction system runs, so a custom cursor agrees with the built-in one.
* A query: what a press or a hover MEANS is the interaction system's business.
*/
export function uiHitTestWorld(
world: PickableWorld, ray: WorldRay, screenRay?: WorldRay,
): Entity | null {
const c = core(world);
if (!c?.engine.uiHitTest_getHitEntity) return null;
// Two rays when the caller has a screen: each entity is tested through the
// projection it was drawn with. One ray is the older core's only question, and
// the right answer to it while the two domains coincide.
if (screenRay && c.engine.uiHitTest_updateDomains) {
c.engine.uiHitTest_updateDomains(c.registry,
ray.origin.x, ray.origin.y, ray.origin.z,
ray.dir.x, ray.dir.y, ray.dir.z,
screenRay.origin.x, screenRay.origin.y, screenRay.origin.z,
screenRay.dir.x, screenRay.dir.y, screenRay.dir.z);
} else if (c.engine.uiHitTest_update) {
c.engine.uiHitTest_update(c.registry,
ray.origin.x, ray.origin.y, ray.origin.z,
ray.dir.x, ray.dir.y, ray.dir.z);
} else {
return null;
}
const hit = c.engine.uiHitTest_getHitEntity();
return hit === NO_HIT ? null : hit;
}
/** Editor pick: topmost UI entity under the point, regardless of Interactable;
* {@link uiHitTestWorld} is the runtime raycast. */
/**
* What the GAME's pointer would hit at framebuffer pixel (@p screenGLX, @p screenGLY)
* — the interaction system's own question, so anything that synthesises a click
* (an automation driver) is refused exactly where a player's would land
* elsewhere: a subtree under `pointerEvents: None` passes the pointer through.
* Unlike {@link uiPickWorld}, the editor's selection pick, which sees everything.
*/
export function uiHitAtScreen(
world: PickableWorld, camera: UICameraData, overlay: ScreenOverlayData,
screenGLX: number, screenGLY: number,
): Entity | null {
if (!camera.valid && !overlay.active) return null;
// With no camera there is no world ray: inverting a projection never written
// yields NaN, which answers "no" by accident. The screen's ray stands in.
const screenRay = overlay.active ? uiLayoutRay(overlay, screenGLX, screenGLY) : undefined;
const worldRay = camera.valid ? uiPointerRay(camera, screenGLX, screenGLY) : screenRay!;
return uiHitTestWorld(world, worldRay, screenRay);
}
export function uiPickWorld(world: PickableWorld, worldX: number, worldY: number): Entity | null {
const c = core(world);
if (!c?.engine.uiHitTest_pick) return null;
const hit = c.engine.uiHitTest_pick(c.registry, worldX, worldY);
return hit === NO_HIT ? null : hit;
}
/** All editor-pickable UI entities under the point, most specific first. */
export function uiPickAllWorld(world: PickableWorld, worldX: number, worldY: number): Entity[] {
const c = core(world);
if (!c?.engine.uiHitTest_pickAll || !c.engine.uiHitTest_pickResult) return [];
const count = c.engine.uiHitTest_pickAll(c.registry, worldX, worldY);
const out: Entity[] = [];
for (let i = 0; i < count; i++) {
const e = c.engine.uiHitTest_pickResult(i);
if (e !== NO_HIT) out.push(e);
}
return out;
}