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.

10.4 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    entityBox.ts
 * @brief   How much room an entity takes up in the world, and where.
 *
 * The box an editor outlines, hit-tests and drags is the box the renderer
 * draws, so both have to be derived from one description of it. Two of them
 * agree until a pivot or a parent scale is involved, and then a selection
 * outline sits beside the sprite it claims to be around.
 */
import type { Entity, Quat, Vec3 } from '../types';
import type { World } from './world';
import { Transform, Sprite, MeshRenderer, ShapeRenderer } from './component';
import { UINode } from '../ui/core/ui-node';
import { q } from '../math/quat';
import { worldEngineApi } from './bridge/engineApi';

/**
 * The three reads a box derivation needs — so an editor's read-only projection
 * of a World satisfies it without being handed the mutators.
 *
 * @experimental
 */
export type ReadableWorld = Pick<World, 'valid' | 'has' | 'get'>;

/**
 * An oriented box in world units: a centre, half-extents along its own three
 * axes, and the rotation that turns those axes into the world's.
 *
 * A sprite, a UI node and any other quad have `hd` zero — they are flat, and a
 * box given thickness they do not have is hit by a ray that passes in front.
 *
 * @experimental
 */
export interface EntityBox {
    cx: number;
    cy: number;
    cz: number;
    hw: number;
    hh: number;
    hd: number;
    rot: Quat;
}

/** @experimental */
export interface EntityBoxOptions {
    /**
     * World half-size for an entity that draws nothing of its own — a camera, a
     * light, an empty. Zero (the default) reports no box for those; an editor
     * that wants them clickable passes the size of the icon it drew.
     *
     * A function when that size is not a world size: an icon drawn at a fixed
     * number of PIXELS covers a world extent that depends on where it is, and the
     * caller is handed the entity's world position to answer for it.
     */
    iconHalf?: number | ((at: Vec3) => number);
    /**
     * The drawn extent of an entity whose size is not in a component the box reads — a skeleton, a
     * tilemap: a rectangle in the entity's own units, `x`/`y` its lower-left corner from the origin.
     * Scaled and turned by the world transform like a sprite's.
     */
    extentOf?: (entity: Entity) => { x: number; y: number; width: number; height: number } | null;
}

/** The rotation an entity is drawn with, defaulted for a partial write. */
function worldRot(t: { worldRotation: unknown }): Quat {
    const r = t.worldRotation as Partial<Quat> | undefined;
    return { x: r?.x ?? 0, y: r?.y ?? 0, z: r?.z ?? 0, w: r?.w ?? 1 };
}

/**
 * The world box of `entity`, or null when it has none.
 *
 * Size scaled by the WORLD scale, centred by the pivot, turned by the world
 * rotation — the three fields the renderer composes. UI nodes get null: they
 * live in the layout's own screen space and are hit-tested there.
 *
 * @experimental
 */
export function entityWorldBox(world: ReadableWorld, entity: Entity, opts?: EntityBoxOptions): EntityBox | null {
    if (!world.valid(entity) || !world.has(entity, Transform)) return null;
    if (world.has(entity, UINode)) return null;

    const t = world.get(entity, Transform);
    const rot = worldRot(t);

    const spec = opts?.iconHalf ?? 0;
    const iconHalf = typeof spec === 'function' ? spec(t.worldPosition as Vec3) : spec;
    // An icon is a marker in space rather than a card, so it is a cube: it reads
    // and clicks the same from wherever the view has been turned to.
    let w = iconHalf * 2;
    let h = iconHalf * 2;
    let d = iconHalf * 2;
    let px = 0.5;
    let py = 0.5;
    if (world.has(entity, Sprite)) {
        const sp = world.get(entity, Sprite);
        w = sp.size.x * t.worldScale.x;
        h = sp.size.y * t.worldScale.y;
        d = 0;
        px = sp.pivot?.x ?? 0.5;
        py = sp.pivot?.y ?? 0.5;
    } else if (world.has(entity, ShapeRenderer)) {
        const shape = world.get(entity, ShapeRenderer);
        w = Math.max(shape.size.x * t.worldScale.x, iconHalf * 2);
        h = Math.max(shape.size.y * t.worldScale.y, iconHalf * 2);
        d = 0;
    } else if (opts?.extentOf?.(entity)) {
        const ext = opts.extentOf(entity)!;
        w = Math.max(ext.width * t.worldScale.x, iconHalf * 2);
        h = Math.max(ext.height * t.worldScale.y, iconHalf * 2);
        d = 0;
        px = 0.5 - ((ext.x + ext.width / 2) * t.worldScale.x) / (w || 1);
        py = 0.5 - ((ext.y + ext.height / 2) * t.worldScale.y) / (h || 1);
    } else if (iconHalf === 0) {
        return null;
    }

    // The centre orbits the transform position when the pivot is off-centre —
    // the position is what rotation turns around, not the middle of the sprite.
    const offset = q.rotate(rot, { x: w * (0.5 - px), y: h * (0.5 - py), z: 0 });
    return {
        cx: t.worldPosition.x + offset.x,
        cy: t.worldPosition.y + offset.y,
        cz: (t.worldPosition.z ?? 0) + offset.z,
        hw: Math.abs(w) / 2,
        hh: Math.abs(h) / 2,
        hd: Math.abs(d) / 2,
        rot,
    };
}

/**
 * What a UI box derivation needs on top of the reads: a laid-out size lives in
 * the engine core, not in a component.
 *
 * @experimental
 */
export type LayoutWorld = ReadableWorld & Pick<World, 'getCppRegistry' | 'getWasmModule'>;

/**
 * The world box of a UI node's resolved layout — {@link entityWorldBox} for the
 * space UI lives in. Null for anything that is not a laid-out UI node.
 *
 * @experimental
 */
export function uiNodeWorldBox(world: LayoutWorld, entity: Entity): EntityBox | null {
    if (!world.valid(entity) || !world.has(entity, UINode) || !world.has(entity, Transform)) return null;
    const engine = worldEngineApi(world);
    const registry = world.getCppRegistry();
    if (!registry || !engine?.uiNode_computedWidth || !engine.uiNode_computedHeight) return null;

    const t = world.get(entity, Transform);
    const w = engine.uiNode_computedWidth(registry, entity) * t.worldScale.x;
    const h = engine.uiNode_computedHeight(registry, entity) * t.worldScale.y;
    if (!(w > 0) || !(h > 0)) return null;
    return {
        cx: t.worldPosition.x,
        cy: t.worldPosition.y,
        cz: t.worldPosition.z ?? 0,
        hw: Math.abs(w) / 2,
        hh: Math.abs(h) / 2,
        hd: 0,
        rot: worldRot(t),
    };
}

/** What the engine answers about a mesh's extent. The z pair is optional: a core
 *  without it is reporting geometry with no thickness. */
interface LocalBounds {
    minX: number; minY: number; minZ?: number;
    maxX: number; maxY: number; maxZ?: number;
}

/**
 * The world box of a MeshRenderer's geometry — {@link entityWorldBox} for a mesh,
 * whose extent is in its vertices rather than in a size field. The engine
 * answers: only it knows whether the live geometry is the resident one or the
 * inline payload. Null for anything else, and for a mesh that draws nothing.
 *
 * @experimental
 */
export function meshWorldBox(world: LayoutWorld, entity: Entity): EntityBox | null {
    if (!world.valid(entity) || !world.has(entity, MeshRenderer) || !world.has(entity, Transform)) return null;
    if (world.has(entity, UINode)) return null;
    // The wasm module, not the shared engine api: this answer is a small object,
    // which is a shape only that binding surface carries.
    const module = world.getWasmModule() as {
        meshRenderer_localBounds?(registry: unknown, entity: number): LocalBounds | null;
    } | null;
    const registry = world.getCppRegistry();
    if (!registry || !module?.meshRenderer_localBounds) return null;
    const b = module.meshRenderer_localBounds(registry, entity);
    if (!b) return null;

    const t = world.get(entity, Transform);
    const rot = worldRot(t);
    const minZ = b.minZ ?? 0;
    const maxZ = b.maxZ ?? 0;
    const scaleZ = t.worldScale.z ?? 1;
    // The geometry's centre is its own, not the transform's: a mesh authored
    // off-origin is drawn off-origin, and its box has to follow.
    const offset = q.rotate(rot, {
        x: ((b.minX + b.maxX) / 2) * t.worldScale.x,
        y: ((b.minY + b.maxY) / 2) * t.worldScale.y,
        z: ((minZ + maxZ) / 2) * scaleZ,
    });
    return {
        cx: t.worldPosition.x + offset.x,
        cy: t.worldPosition.y + offset.y,
        cz: (t.worldPosition.z ?? 0) + offset.z,
        hw: Math.abs((b.maxX - b.minX) * t.worldScale.x) / 2,
        hh: Math.abs((b.maxY - b.minY) * t.worldScale.y) / 2,
        hd: Math.abs((maxZ - minZ) * scaleZ) / 2,
        rot,
    };
}

/**
 * The box's eight corners in world units — what an outline is drawn through and
 * what a union is taken over. A flat box reports four of them twice, which is
 * what a quad's eight corners are.
 *
 * @experimental
 */
export function entityBoxCorners(b: EntityBox): Vec3[] {
    const out: Vec3[] = [];
    for (const sz of [-1, 1]) {
        for (const sy of [-1, 1]) {
            for (const sx of [-1, 1]) {
                const r = q.rotate(b.rot, { x: sx * b.hw, y: sy * b.hh, z: sz * b.hd });
                out.push({ x: b.cx + r.x, y: b.cy + r.y, z: b.cz + r.z });
            }
        }
    }
    return out;
}

/**
 * How far along @p dir a ray from @p origin travels to meet the box, or null
 * when it misses.
 *
 * The slab test in the box's own frame. Zero half-extent is a flat box rather
 * than a degenerate one: a ray parallel to it hits only from within its plane.
 *
 * @experimental
 */
export function entityBoxRayHit(b: EntityBox, origin: Vec3, dir: Vec3): number | null {
    const inv = q.conjugate(b.rot);
    const o = q.rotate(inv, { x: origin.x - b.cx, y: origin.y - b.cy, z: origin.z - b.cz });
    const d = q.rotate(inv, dir);
    const at = [o.x, o.y, o.z];
    const along = [d.x, d.y, d.z];
    const half = [b.hw, b.hh, b.hd];

    let enter = -Infinity;
    let exit = Infinity;
    for (let i = 0; i < 3; i++) {
        if (Math.abs(along[i]!) < 1e-9) {
            if (Math.abs(at[i]!) > half[i]! + 1e-6) return null;
            continue;
        }
        const t1 = (-half[i]! - at[i]!) / along[i]!;
        const t2 = (half[i]! - at[i]!) / along[i]!;
        enter = Math.max(enter, Math.min(t1, t2));
        exit = Math.min(exit, Math.max(t1, t2));
    }
    // A screen ray starts on the near plane, so everything drawn is ahead of it;
    // a box the ray starts inside is entered at zero rather than behind.
    if (exit < enter || exit < 0) return null;
    return Math.max(enter, 0);
}