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.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  sight.ts
 * @brief What a viewer can see in a 2D scene: the walls that block a line, and the things that are hidden while a wall stands between.
 *
 * @details A lit sprite behind a wall is already dark, because the wall's `ShadowCaster2D` shadows the light that would show it. Everything that
 *          is not lit is not: an enemy drawn unlit, its health bar, a pickup glowing on its own. So the same walls are read again here as a
 *          test on the CPU, `segmentBlocked`, and two components use it. `SightViewer` is an eye (the player); `SightTarget` goes on a sprite that
 *          should not be seen unless some viewer has a clear line to it, and eases to `hiddenOpacity` while none does. The viewer's own `radius`
 *          is how far it sees (0: as far as the line is clear).
 *
 *          A caster that contains the viewer or the target blocks nothing for that pair: standing in a bush you see out of it, and a thing in a
 *          wall's own footprint is seen from outside. The test is segment against edge, so its cost is viewers times targets times the edges near
 *          the line, which is what a few hundred targets and a village of walls cost on a phone. It runs in play only.
 *
 *          A sprite carries one fade: do not put a `SightTarget` and a `CoverFade` on the same sprite.
 */
import type { App } from '../app/app';
import type { Entity } from '../types';
import { defineComponent, ShadowCaster2D, Sprite, Transform, type ShadowCaster2DData, type SpriteData, type TransformData } from '../ecs/component';
import { defineSystem, Schedule, GetWorld } from '../ecs/system';
import { Res, Time, type TimeData } from '../ecs/resource';
import { Query } from '../ecs/query';
import type { World } from '../ecs/world';
import { isEditor, isPlayMode } from '../ecs/env';
import { stepFade } from './coverFade';

/** The fields of the `SightViewer` component. @experimental */
export interface SightViewerData {
    /** How far this eye sees, in world units. 0 is no limit: only a wall stops it. */
    radius: number;
    /** Off: this eye sees nothing. */
    enabled: boolean;
}

/**
 * An eye: the sprites with a `SightTarget` are seen while some viewer has a clear line to them.
 *
 * @experimental
 */
export const SightViewer = defineComponent<SightViewerData>('SightViewer',
    { radius: 0, enabled: true },
    { fields: { radius: { min: 0, step: 1, unit: 'wu', tooltip: 'How far this eye sees. 0 is no limit: only a wall stops it.' } } },
);

/** The fields of the `SightTarget` component. @experimental */
export interface SightTargetData {
    /** The sprite's alpha, as a share of its own, while no viewer sees it. 0 is gone. */
    hiddenOpacity: number;
    /** Seconds the fade takes, either way. */
    fadeTime: number;
    /** Off: the sprite stays as authored. */
    enabled: boolean;
}

/**
 * Hides the sprite on this entity while no `SightViewer` has a clear line to it.
 *
 * @experimental
 */
export const SightTarget = defineComponent<SightTargetData>('SightTarget',
    { hiddenOpacity: 0, fadeTime: 0.15, enabled: true },
    {
        fields: {
            hiddenOpacity: { min: 0, max: 1, step: 0.01, tooltip: "The sprite's alpha, as a share of its own, while no viewer sees it." },
            fadeTime: { min: 0, max: 5, step: 0.05, unit: 's', tooltip: 'Seconds the fade takes, either way.' },
        },
    },
);

/** A point in the world plane. */
export interface SightPoint {
    x: number;
    y: number;
}

/** One blocker: the outline of a wall, in world units, in order round the shape. */
export type SightRing = readonly SightPoint[];

/** Whether the open segments a-b and c-d cross. A touch at an end is not a crossing: a viewer standing against a wall is not behind it. */
function crosses(a: SightPoint, b: SightPoint, c: SightPoint, d: SightPoint): boolean {
    const d1x = b.x - a.x, d1y = b.y - a.y, d2x = d.x - c.x, d2y = d.y - c.y;
    const denom = d1x * d2y - d1y * d2x;
    if (denom === 0) return false;
    const t = ((c.x - a.x) * d2y - (c.y - a.y) * d2x) / denom;
    const u = ((c.x - a.x) * d1y - (c.y - a.y) * d1x) / denom;
    return t > 1e-6 && t < 1 - 1e-6 && u >= 0 && u <= 1;
}

/** Whether a point lies inside a ring (even-odd). */
export function ringContains(ring: SightRing, p: SightPoint): boolean {
    let inside = false;
    for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
        const a = ring[i]!, b = ring[j]!;
        if ((a.y > p.y) !== (b.y > p.y) && p.x < ((b.x - a.x) * (p.y - a.y)) / (b.y - a.y) + a.x) inside = !inside;
    }
    return inside;
}

/**
 * Whether the line from `from` to `to` runs through a wall. A ring that contains either end blocks nothing for this pair.
 */
export function segmentBlocked(from: SightPoint, to: SightPoint, rings: readonly SightRing[]): boolean {
    const minX = Math.min(from.x, to.x), maxX = Math.max(from.x, to.x);
    const minY = Math.min(from.y, to.y), maxY = Math.max(from.y, to.y);
    for (const ring of rings) {
        if (ring.length < 3) continue;
        let rx0 = Infinity, rx1 = -Infinity, ry0 = Infinity, ry1 = -Infinity;
        for (const p of ring) {
            if (p.x < rx0) rx0 = p.x;
            if (p.x > rx1) rx1 = p.x;
            if (p.y < ry0) ry0 = p.y;
            if (p.y > ry1) ry1 = p.y;
        }
        if (rx1 < minX || rx0 > maxX || ry1 < minY || ry0 > maxY) continue;
        if (ringContains(ring, from) || ringContains(ring, to)) continue;
        for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
            if (crosses(from, to, ring[j]!, ring[i]!)) return true;
        }
    }
    return false;
}

/** A caster's outline in the world: its box or its traced path, scaled, turned and placed by its transform. Null for one that blocks nothing. */
export function sightRingOf(caster: ShadowCaster2DData, transform: TransformData): SightRing | null {
    if (!caster.enabled) return null;
    const local: SightPoint[] = caster.path.length >= 3
        ? caster.path
        : [
            { x: -caster.size.x / 2, y: -caster.size.y / 2 }, { x: caster.size.x / 2, y: -caster.size.y / 2 },
            { x: caster.size.x / 2, y: caster.size.y / 2 }, { x: -caster.size.x / 2, y: caster.size.y / 2 },
        ];
    if (caster.path.length < 3 && (caster.size.x <= 0 || caster.size.y <= 0)) return null;
    const q = transform.worldRotation;
    const angle = Math.atan2(2 * (q.w * q.z + q.x * q.y), 1 - 2 * (q.y * q.y + q.z * q.z));
    const cos = Math.cos(angle), sin = Math.sin(angle);
    const s = transform.worldScale, o = transform.worldPosition;
    return local.map((p) => {
        const x = p.x * s.x, y = p.y * s.y;
        return { x: o.x + x * cos - y * sin, y: o.y + x * sin + y * cos };
    });
}

/** Whether `viewer` sees `target`: inside its radius (when it has one) and with no wall between. */
export function seesPoint(viewer: SightPoint, radius: number, target: SightPoint, rings: readonly SightRing[]): boolean {
    if (radius > 0 && Math.hypot(target.x - viewer.x, target.y - viewer.y) > radius) return false;
    return !segmentBlocked(viewer, target, rings);
}

interface Fading {
    authored: number;
    shown: number;
}

let ringsNow: SightRing[] = [];

/** The walls the last frame read, for a game that wants the same answer the sprites got. */
export function currentSightRings(): readonly SightRing[] {
    return ringsNow;
}

/** Installs the system that hides and shows sight targets. Returns the function that puts every sprite back as authored. */
export function installSight(app: App): () => void {
    const fading = new Map<Entity, Fading>();

    const put = (world: World, entity: Entity, alpha: number): void => {
        const sprite = world.get(entity, Sprite) as SpriteData;
        if (sprite.color.a === alpha) return;
        world.set(entity, Sprite, { ...sprite, color: { ...sprite.color, a: alpha } });
    };
    const restore = (world: World, entity: Entity, state: Fading): void => {
        if (world.has(entity, Sprite)) put(world, entity, state.authored);
        fading.delete(entity);
    };

    // system-access: the sprite's alpha is read and written through the world, per entity, because the fade owns a share of it.
    const system = defineSystem(
        [Query(ShadowCaster2D, Transform), Query(SightViewer, Transform), Query(SightTarget, Sprite, Transform), Res(Time), GetWorld()],
        (
            casters: Iterable<[Entity, ShadowCaster2DData, TransformData]>,
            viewers: Iterable<[Entity, SightViewerData, TransformData]>,
            targets: Iterable<[Entity, SightTargetData, SpriteData, TransformData]>,
            time: TimeData, world: World,
        ) => {
            if (isEditor() && !isPlayMode()) {
                if (fading.size > 0) for (const [entity, state] of [...fading]) restore(world, entity, state);
                return;
            }
            const eyes: Array<{ at: SightPoint; radius: number }> = [];
            for (const [, viewer, transform] of viewers) {
                if (viewer.enabled) eyes.push({ at: { x: transform.worldPosition.x, y: transform.worldPosition.y }, radius: viewer.radius });
            }
            const rings: SightRing[] = [];
            if (eyes.length > 0) {
                for (const [, caster, transform] of casters) {
                    const ring = sightRingOf(caster, transform);
                    if (ring) rings.push(ring);
                }
            }
            ringsNow = rings;

            const seen = new Set<Entity>();
            for (const [entity, target, sprite, transform] of targets) {
                seen.add(entity);
                let state = fading.get(entity);
                if (!target.enabled) { if (state) restore(world, entity, state); continue; }
                if (!state) { state = { authored: sprite.color.a, shown: 1 }; fading.set(entity, state); }
                const at = { x: transform.worldPosition.x, y: transform.worldPosition.y };
                // With no viewer at all there is nobody to see: a scene that has not placed its eye yet hides its targets, which is what "seen by none" means.
                const visible = eyes.some((eye) => seesPoint(eye.at, eye.radius, at, rings));
                const goal = visible ? 1 : Math.min(Math.max(target.hiddenOpacity, 0), 1);
                if (state.shown === goal) continue;
                state.shown = stepFade(state.shown, goal, time.delta, target.fadeTime);
                put(world, entity, state.authored * state.shown);
            }
            for (const [entity, state] of [...fading]) if (!seen.has(entity)) restore(world, entity, state);
        },
        { name: 'SightSystem' },
    );
    // Nothing to do in a scene without one; the frame after the last goes still runs, to restore what it hid.
    app.addSystemToSchedule(Schedule.PostUpdate, system, { activeWhen: [SightViewer, SightTarget] });

    return () => {
        ringsNow = [];
        const world = app.world;
        for (const [entity, state] of [...fading]) restore(world, entity, state);
    };
}