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.

11.6 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  Picking an entity that is NOT in the UI layout tree, via the real raycast.
 *
 * ui-drag-plugin.test.ts sets `hovered` by hand, so it covers the drag logic and
 * not whether such an entity can be hovered at all.
 * Requires pre-built WASM at build/wasm/web/esengine.wasm.
 */
import { describe, it, expect, beforeAll } from 'vitest';
import { World } from '../src/ecs/world';
import { App, flushPendingRegistrations } from '../src/app/app';
import { AppContext, setDefaultContext } from '../src/ecs/context';
import { Input, InputState } from '../src/input/input';
import { UICameraInfo } from '../src/ui/core/ui-camera-info';
import { UILayoutGeneration } from '../src/ui/layout/ui-layout-generation';
import { uiInteractionPlugin } from '../src/ui/input/interaction';
import { Transform, Sprite, MeshRenderer } from '../src/ecs/component';
import { Interactable, UIInteraction } from '../src/ui/input/interactable';
import type { Entity, Vec3 } from '../src/types';
import type { ESEngineModule, CppRegistry } from '../src/wasm';
import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';

const NO_HIT = 0xffffffff;

describe.skipIf(!HAS_WASM)('world-space picking (WASM integration)', () => {
    let module: ESEngineModule;

    beforeAll(async () => {
        module = await loadWasmModule();
    });

    function createWorld(): { world: World; registry: CppRegistry } {
        const registry = new module.Registry() as unknown as CppRegistry;
        const world = new World();
        world.connectCpp(registry, module);
        return { world, registry };
    }

    function disposeWorld(world: World, registry: CppRegistry): void {
        for (const e of world.getAllEntities()) {
            try { world.despawn(e); } catch { /* already gone */ }
        }
        world.disconnectCpp();
        (registry as unknown as { delete(): void }).delete();
    }

    /** A plain world-space sprite: no UINode, so the layout tree never sees it. */
    function sprite(
        world: World, x: number, y: number,
        opts: { size?: number; layer?: number; raycastTarget?: boolean; scale?: number;
                z?: number } = {},
    ): Entity {
        const e = world.spawn();
        const s = opts.size ?? 100;
        const k = opts.scale ?? 1;
        world.insert(e, Transform, { position: { x, y, z: opts.z ?? 0 }, scale: { x: k, y: k, z: 1 } });
        world.insert(e, Sprite, { size: { x: s, y: s }, layer: opts.layer ?? 0 });
        world.insert(e, Interactable, { raycastTarget: opts.raycastTarget ?? true });
        return e;
    }

    /**
     * A world-space mesh: a quad of inline geometry, which is the only kind a
     * bare registry can hold — a resident .esmesh needs a ResourceManager, and
     * the only difference downstream is where localMin/localMax are read from.
     */
    function mesh(
        world: World, x: number, y: number, z: number,
        opts: { half?: number; layer?: number } = {},
    ): Entity {
        const h = opts.half ?? 50;
        const e = world.spawn();
        world.insert(e, Transform, { position: { x, y, z } });
        world.insert(e, MeshRenderer, { layer: opts.layer ?? 0 });
        world.insert(e, Interactable, { raycastTarget: true });

        const positions = [-h, -h, h, -h, h, h, -h, h];
        const posUv = new Float32Array(positions.length * 2);
        for (let v = 0; v < 4; v++) {
            posUv[v * 4 + 0] = positions[v * 2 + 0];
            posUv[v * 4 + 1] = positions[v * 2 + 1];
        }
        const indices = new Uint32Array([0, 1, 2, 0, 2, 3]);
        const posPtr = module._malloc!(posUv.byteLength);
        const idxPtr = module._malloc!(indices.byteLength);
        module.HEAPF32!.set(posUv, posPtr >> 2);
        module.HEAPU32!.set(indices, idxPtr >> 2);
        module.meshRenderer_setGeometry!(
            world.getCppRegistry() as never, e, posPtr, 4, 0, idxPtr, indices.length);
        module._free!(posPtr);
        module._free!(idxPtr);
        return e;
    }

    let frame = 0;
    /** An orthographic pointer: straight down -Z from above everything. */
    function pickAt(registry: CppRegistry, x: number, y: number): number {
        return pickRay(registry, { x, y, z: 1000 }, { x: 0, y: 0, z: -1 });
    }

    function pickRay(registry: CppRegistry, origin: Vec3, dir: Vec3): number {
        // transforms_updated is memoised per frame, so each pick needs its own.
        module.renderer_beginFrame(frame++);
        module.renderer_updateTransforms(registry as never);
        module.uiHitTest_update(registry as never,
                                origin.x, origin.y, origin.z, dir.x, dir.y, dir.z);
        return module.uiHitTest_getHitEntity();
    }

    it('picking leaves interaction ownership and cached membership to the SDK', () => {
        const { world, registry } = createWorld();
        const e = sprite(world, 0, 0);
        expect(world.getEntitiesWithComponents([UIInteraction])).toEqual([]);
        expect(pickAt(registry, 0, 0)).toBe(e);
        expect(registry.hasUIInteraction(e)).toBe(false);
        expect(world.getEntitiesWithComponents([UIInteraction])).toEqual([]);
        world.insert(e, UIInteraction, { hovered: true });
        expect(world.getEntitiesWithComponents([UIInteraction])).toEqual([e]);
        disposeWorld(world, registry);
    });

    it('hits a sprite that has no UINode', () => {
        const { world, registry } = createWorld();
        const e = sprite(world, 0, 0);

        expect(pickAt(registry, 0, 0)).toBe(e);

        disposeWorld(world, registry);
    });

    it('misses outside the sprite, so the box is the sprite and not the world', () => {
        const { world, registry } = createWorld();
        sprite(world, 0, 0, { size: 100 });

        // Just inside, then well outside: a pass that always hits would fail here.
        expect(pickAt(registry, 49, 49)).not.toBe(NO_HIT);
        expect(pickAt(registry, 400, 400)).toBe(NO_HIT);

        disposeWorld(world, registry);
    });

    it('the interaction system publishes hover membership and clears it after moving away', async () => {
        setDefaultContext(new AppContext());
        const registry = new module.Registry();
        const app = App.new(); app.connectCpp(registry, module);
        const world = app.world;
        const e = sprite(world, 0, 0);
        const input = new InputState(); input.mouseX = 50; input.mouseY = 50;
        app.insertResource(Input, input);
        const projection = new Float32Array([.02,0,0,0, 0,.02,0,0, 0,0,-.001,0, 0,0,0,1]);
        app.insertResource(UICameraInfo, { ...UICameraInfo._default, viewProjection: projection,
            vpW: 100, vpH: 100, screenW: 100, screenH: 100, valid: true });
        app.insertResource(UILayoutGeneration, { generation: 0 });
        uiInteractionPlugin.build(app); flushPendingRegistrations(app);
        try {
            expect(world.getEntitiesWithComponents([UIInteraction])).toEqual([]);
            world.ensureTransformsComposed();
            await app.tick(1 / 60);
            expect(world.getEntitiesWithComponents([UIInteraction])).toEqual([e]);
            expect(world.get(e, UIInteraction).hovered).toBe(true);
            input.mouseX = 500; await app.tick(1 / 60);
            expect(world.get(e, UIInteraction).hovered).toBe(false);
        } finally {
            uiInteractionPlugin.cleanup(app); disposeWorld(world, registry);
        }
    });

    it('honours raycastTarget: false', () => {
        const { world, registry } = createWorld();
        const opaque = sprite(world, 0, 0);

        // Prove the point IS pickable first: asserting only the miss would pass
        // just as well with no world-space pass at all.
        expect(pickAt(registry, 0, 0)).toBe(opaque);

        world.insert(opaque, Interactable, { raycastTarget: false });
        expect(pickAt(registry, 0, 0)).toBe(NO_HIT);

        disposeWorld(world, registry);
    });

    it('takes the higher layer when two overlap', () => {
        const { world, registry } = createWorld();
        sprite(world, 0, 0, { layer: 0 });
        const top = sprite(world, 0, 0, { layer: 5 });

        expect(pickAt(registry, 0, 0)).toBe(top);

        disposeWorld(world, registry);
    });

    it('scales the box with the transform', () => {
        const { world, registry } = createWorld();
        const e = sprite(world, 0, 0, { size: 100, scale: 3 });

        // 140 is outside the unscaled box (±50) and inside the scaled one (±150).
        expect(pickAt(registry, 140, 0)).toBe(e);

        disposeWorld(world, registry);
    });

    it('hits a MeshRenderer, which no pass reached before', () => {
        const { world, registry } = createWorld();
        const e = mesh(world, 0, 0, 0);

        expect(pickAt(registry, 0, 0)).toBe(e);
        // Outside the quad, so a pass that answers with the only mesh present
        // would pass the line above and fail this one.
        expect(pickAt(registry, 400, 0)).toBe(NO_HIT);

        disposeWorld(world, registry);
    });

    it('takes the NEARER of two meshes stacked in depth', () => {
        const { world, registry } = createWorld();
        const far = mesh(world, 0, 0, -500);
        const near = mesh(world, 0, 0, -100);

        // Both are under the pointer; only depth separates them, and the far one
        // was created first — so an answer that ignored depth would return it.
        expect(pickAt(registry, 0, 0)).toBe(near);
        expect(far).not.toBe(near);

        // Cast the other way and the ranking has to invert.
        expect(pickRay(registry, { x: 0, y: 0, z: -1000 }, { x: 0, y: 0, z: 1 })).toBe(far);

        disposeWorld(world, registry);
    });

    it('follows a perspective ray to where content actually stands', () => {
        const { world, registry } = createWorld();
        // 200 units to the right and 300 back. A pointer from the origin reaches
        // it only if the ray is followed to ITS plane; resolved at z = 0 — which
        // is every answer this pass could give before — it lands at x = 0.
        const e = mesh(world, 200, 0, -300, { half: 40 });

        const len = Math.hypot(200, 0, -300);
        expect(pickRay(registry, { x: 0, y: 0, z: 0 },
                       { x: 200 / len, y: 0, z: -300 / len })).toBe(e);
        // Straight down -Z from the origin misses it, so the hit above is the
        // ray's doing and not a box wide enough to catch anything.
        expect(pickAt(registry, 0, 0)).toBe(NO_HIT);

        disposeWorld(world, registry);
    });

    it('meets a sprite on the sprite\'s own plane, not on z = 0', () => {
        const { world, registry } = createWorld();
        // Same geometry as the mesh case, so what differs is only which pass
        // answers: a sprite resolves the ray against a plane, a mesh against a box.
        const e = sprite(world, 200, 0, { size: 80, z: -300 });

        const len = Math.hypot(200, 0, -300);
        expect(pickRay(registry, { x: 0, y: 0, z: 0 },
                       { x: 200 / len, y: 0, z: -300 / len })).toBe(e);
        expect(pickAt(registry, 0, 0)).toBe(NO_HIT);

        disposeWorld(world, registry);
    });

    it('lets a sprite in front of a mesh win, by depth alone', () => {
        const { world, registry } = createWorld();
        const behind = mesh(world, 0, 0, -200);
        const front = sprite(world, 0, 0, { size: 100 });

        expect(pickAt(registry, 0, 0)).toBe(front);
        // From behind, the mesh is the near one — so the line above is depth
        // deciding and not sprites simply outranking meshes.
        expect(pickRay(registry, { x: 0, y: 0, z: -1000 }, { x: 0, y: 0, z: 1 })).toBe(behind);

        disposeWorld(world, registry);
    });
});