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.

15.3 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  rainShelter.ts
 * @brief A roof, an awning or a tree crown that keeps the ground under it dry, for the 2D rain.
 *
 * @details The 3D rain finds what stands over a place by drawing the scene from straight above. A 2D scene has no "above" to draw it from, so the
 *          sprite that covers says so: `RainShelter` goes on it, and the ground it covers (its rectangle, or the ellipse inside it) is dry. How dry
 *          follows how much of that ground can be SEEN: an opaque roof shows the roof, which the rain falls on, and the same roof faded by a
 *          `CoverFade` to show the room has a room that is dry. So one roof carries both components and the rain stops as the room appears.
 *
 *          Every frame the shelters are painted into a small texture that covers the view, each one's dryness in its alpha, and a `rain2d` effect
 *          reads that. A shelter costs a rectangle or a few strips of one draw, not a test in the shader on every pixel, so a village of roofs
 *          costs what a hut does.
 */
import type { App } from '../app/app';
import type { Entity } from '../types';
import { defineComponent, Sprite, Transform, type SpriteData, type TransformData } from '../ecs/component';
import { defineSystem, Schedule } from '../ecs/system';
import { Query } from '../ecs/query';
import { CameraView } from '../camera/Camera';
import { coveredGround } from './coverFade';
import { Draw } from './draw';
import { BlendMode } from './blend';
import { Renderer } from './renderer';
import { RenderTexture, type RenderTextureHandle } from './renderTexture';
import { log } from '../util/logger';
import { RAIN_SHELTER_MASK_SIZE, RAIN_SHELTER_MASK_MIN, RAIN_SHELTER_MASK_MAX, RAIN_SHELTER_MASK_TEXTURE } from '../postprocess/rainShelterMask';
import { Quality } from './qualityRuntime';
import { runtimeTextureRef } from '../postprocess/runtimeTextures';
import type { BlendedEffect } from '../postprocess/volumeBlending';

/** The fields of the `RainShelter` component. @experimental */
export interface RainShelterData {
    /** The covered ground is the ellipse inside the sprite's rectangle (a crown), not the whole of it (a roof). */
    round: boolean;
    /** Ground around the sprite's edge that stays dry too, in world units: eaves. */
    margin: number;
    /** Off: the sprite shelters nothing. */
    enabled: boolean;
}

/**
 * Keeps the ground under this sprite dry in the 2D rain, as far as the sprite lets it be seen.
 *
 * @experimental
 */
export const RainShelter = defineComponent<RainShelterData>('RainShelter',
    { round: false, margin: 0, enabled: true },
    {
        fields: {
            round: { tooltip: "The covered ground is the ellipse inside the sprite's rectangle (a tree crown) and not the whole of it (a roof)." },
            margin: { min: 0, step: 1, tooltip: 'Ground around the sprite\'s edge that stays dry too, in world units.' },
        },
    },
);

/** The fields of the `RainUpright` component. @experimental */
export interface RainUprightData {
    /** Ground around the sprite's edge that the rain still draws on, in world units: the feet, or a trunk's base. */
    inset: number;
    /** Off: the sprite is treated as ground like any other. */
    enabled: boolean;
}

/**
 * Marks a sprite that STANDS on the ground (a character, a trunk, a crate), so the 2D rain's rings, splashes and wet darkening are not drawn over
 * it. The rain is laid over the finished picture and cannot tell a character from the floor under them; this tells it. Falling streaks still cross it.
 *
 * @experimental
 */
export const RainUpright = defineComponent<RainUprightData>('RainUpright',
    { inset: 0, enabled: true },
    {
        fields: {
            inset: { min: 0, step: 1, tooltip: 'Ground around the sprite\'s edge that the rain still draws on, in world units: the feet, or a trunk\'s base.' },
        },
    },
);

/** One upright sprite's rectangle, and how much of it shows (a faded one shows the ground behind it). */
export interface Upright {
    x: number;
    y: number;
    hx: number;
    hy: number;
    amount: number;
}

/** The upright a sprite is, or null where it has no body to keep the rain off. */
export function uprightOf(sprite: SpriteData, transform: TransformData, data: RainUprightData): Upright | null {
    if (!data.enabled || !sprite.enabled) return null;
    const amount = Math.min(Math.max(sprite.color.a, 0), 1);
    if (amount <= 0) return null;
    const { centre, half } = coveredGround(sprite, transform);
    const hx = half.x - data.inset;
    const hy = half.y - data.inset;
    if (hx <= 0 || hy <= 0) return null;
    return { x: centre.x, y: centre.y, hx, hy, amount };
}

/** What to draw for the uprights the view can see: a rectangle each, the amount in the red channel. */
export function uprightRects(uprights: readonly Upright[], view: { left: number; bottom: number; right: number; top: number }): MaskRect[] {
    const rects: MaskRect[] = [];
    for (const u of uprights) {
        if (u.x + u.hx < view.left || u.x - u.hx > view.right || u.y + u.hy < view.bottom || u.y - u.hy > view.top) continue;
        rects.push({ x: u.x, y: u.y, w: u.hx * 2, h: u.hy * 2, dry: u.amount });
    }
    return rects;
}

/** One shelter: its ground and how dry it is. A negative half height says round. */
export interface Shelter {
    x: number;
    y: number;
    hx: number;
    /** Negative for an ellipse. */
    hy: number;
    /** 0 where the ground under it cannot be seen, 1 where all of it can. */
    dry: number;
}

/** A filled rectangle of the mask, centred, in world units. */
export interface MaskRect {
    x: number;
    y: number;
    w: number;
    h: number;
    dry: number;
}

let sheltersNow: Shelter[] = [];

/** The shelters the last frame found. */
export function currentRainShelters(): readonly Shelter[] {
    return sheltersNow;
}

/** How dry the ground under a sprite is, from how much of it shows through: an opaque sprite hides it, a clear one hides nothing. */
export function drynessOf(alpha: number): number {
    return 1 - Math.min(Math.max(alpha, 0), 1);
}

/** The shelter a sprite is, or null where it has no ground to cover or no dryness to give. */
export function shelterOf(sprite: SpriteData, transform: TransformData, data: RainShelterData): Shelter | null {
    if (!data.enabled || !sprite.enabled) return null;
    const dry = drynessOf(sprite.color.a);
    if (dry <= 0) return null;
    const { centre, half } = coveredGround(sprite, transform);
    const hx = half.x + data.margin;
    const hy = half.y + data.margin;
    if (hx <= 0 || hy <= 0) return null;
    return { x: centre.x, y: centre.y, hx, hy: data.round ? -hy : hy, dry };
}

/** How many strips an ellipse is cut into at the default mask size. */
export const ELLIPSE_STRIPS = 32;

/** The size a mask is painted at: what the effect asks for, held to what the quality level allows (none: as asked), in whole sixteens of texels. */
export function shelterMaskSizeOf(asked: number, allowed: number | null): number {
    const wanted = Number.isFinite(asked) ? asked : RAIN_SHELTER_MASK_SIZE;
    const size = Math.round(Math.min(wanted, allowed ?? wanted) / 16) * 16;
    return Math.min(Math.max(size, RAIN_SHELTER_MASK_MIN), RAIN_SHELTER_MASK_MAX);
}

/** How many strips an ellipse is cut into for a mask this big: one per sixteen texels, since more would draw what the mask cannot show. */
export function ellipseStripsOf(size: number): number {
    return Math.min(Math.max(Math.round(size / 16), 8), 64);
}

/**
 * What to draw for the shelters: a rectangle each, an ellipse as strips of one, the driest last so where two overlap the drier wins (a draw
 * overwrites, and a max is what overlapping shelters want). The mask is not drawn for shelters the view cannot see.
 *
 * @param view  The world rectangle the mask covers.
 */
export function maskRects(
    shelters: readonly Shelter[], view: { left: number; bottom: number; right: number; top: number }, strips: number = ELLIPSE_STRIPS,
): MaskRect[] {
    const rects: MaskRect[] = [];
    const ordered = [...shelters].sort((a, b) => a.dry - b.dry);
    for (const s of ordered) {
        const h = Math.abs(s.hy);
        if (s.x + s.hx < view.left || s.x - s.hx > view.right || s.y + h < view.bottom || s.y - h > view.top) continue;
        if (s.hy >= 0) {
            rects.push({ x: s.x, y: s.y, w: s.hx * 2, h: h * 2, dry: s.dry });
            continue;
        }
        const strip = (h * 2) / strips;
        for (let i = 0; i < strips; i++) {
            const t = ((i + 0.5) / strips) * 2 - 1;
            const width = s.hx * 2 * Math.sqrt(Math.max(1 - t * t, 0));
            if (width <= 0) continue;
            rects.push({ x: s.x, y: s.y + t * h, w: width, h: strip, dry: s.dry });
        }
    }
    return rects;
}

/** The mask as the last frame painted it: the texture the effect reads and the world rectangle it covers. */
interface MaskState {
    ref: string;
    left: number;
    bottom: number;
    width: number;
    height: number;
}

let maskNow: MaskState | null = null;
/** The mask size the last resolved `rain2d` asked for. */
let askedSize = RAIN_SHELTER_MASK_SIZE;

/** Column-major orthographic projection over a rectangle: what RenderTexture.begin wants. */
function ortho(l: number, r: number, b: number, t: number): Float32Array {
    const m = new Float32Array(16);
    m[0] = 2 / (r - l);
    m[5] = 2 / (t - b);
    m[10] = -1;
    m[12] = -(r + l) / (r - l);
    m[13] = -(t + b) / (t - b);
    m[15] = 1;
    return m;
}

/**
 * Hands a `rain2d` effect the mask painted this frame and where it lies in the world; with no mask (no shelters, no view) the effect
 * keeps its black default, which is dry nowhere. Other effects, and a disabled rain, are left alone.
 */
export function applyRainSheltersToRain(effects: Map<string, BlendedEffect>): void {
    const rain = effects.get('rain2d');
    if (!rain || !rain.enabled) return;
    const mask = maskNow;
    askedSize = rain.uniforms.get('u_maskSize') ?? RAIN_SHELTER_MASK_SIZE;
    rain.uniforms.set('u_maskL', mask ? mask.left : 0);
    rain.uniforms.set('u_maskB', mask ? mask.bottom : 0);
    rain.uniforms.set('u_maskW', mask ? mask.width : 0);
    rain.uniforms.set('u_maskH', mask ? mask.height : 0);
    if (mask) rain.textures.set(RAIN_SHELTER_MASK_TEXTURE, mask.ref);
}

/** Installs the system that lists the shelters and paints the mask each frame. Returns the function that lets both go. */
export function installRainShelter(app: App): () => void {
    let target: RenderTextureHandle | null = null;
    let failed = false;

    /** The size the quality level lets the mask be, or null with no quality policy running. */
    const allowedSize = (): number | null => {
        const policy = app.hasResource(Quality) ? app.getResource(Quality) : null;
        return policy && policy.enabled ? policy.profile.shelterMaskSize : null;
    };

    /** The world rectangle the camera shows, or null where there is none to cover. */
    const viewOf = (): { left: number; right: number; bottom: number; top: number } | null => {
        const view = app.hasResource(CameraView) ? app.getResource(CameraView).getWorldBounds() : null;
        return view && view.right > view.left && view.top > view.bottom ? view : null;
    };

    const paint = (rects: readonly MaskRect[], stands: readonly MaskRect[], view: { left: number; right: number; bottom: number; top: number }): boolean => {
        if (failed) return false;
        try {
            const size = shelterMaskSizeOf(askedSize, allowedSize());
            // Asked for another size (the effect's field, or the level changed): the old one goes and a new one is made.
            if (target && target.width !== size) { RenderTexture.release(target); target = null; }
            if (!target) {
                const created = RenderTexture.create({ width: size, height: size, depth: false, filter: 'linear' });
                // The renderer may not be up yet: try again next frame.
                if (created.textureId === 0 || created.texture === 0) { RenderTexture.release(created); return false; }
                target = created;
            }
            const vp = ortho(view.left, view.right, view.bottom, view.top);
            const cx = (view.left + view.right) / 2;
            const cy = (view.bottom + view.top) / 2;
            RenderTexture.begin(target, vp);
            Draw.begin(vp);
            // Draw.begin resets the viewport to the screen's; the target's own is what this pass is.
            Renderer.setViewport(0, 0, target.width, target.height);
            // Blend off, so a draw writes its colour AND its alpha as given, and the dryness in the alpha is exact whatever the colour space does to the colour.
            Draw.setBlendMode(BlendMode.None);
            Draw.rect({ x: cx, y: cy }, { x: view.right - view.left, y: view.top - view.bottom }, { r: 0, g: 0, b: 0, a: 0 });
            for (const r of rects) Draw.rect({ x: r.x, y: r.y }, { x: r.w, y: r.h }, { r: 0, g: 0, b: 0, a: r.dry });
            // What stands on the ground goes in the red channel, and Lighten keeps the alpha the shelters wrote.
            Draw.setBlendMode(BlendMode.Lighten);
            for (const r of stands) Draw.rect({ x: r.x, y: r.y }, { x: r.w, y: r.h }, { r: r.dry, g: 0, b: 0, a: 0 });
            Draw.end();
            RenderTexture.end();
            RenderTexture.contentDrawn(target);
            maskNow = {
                ref: runtimeTextureRef(RAIN_SHELTER_MASK_TEXTURE, target.texture),
                left: view.left, bottom: view.bottom, width: view.right - view.left, height: view.top - view.bottom,
            };
            return true;
        } catch (error) {
            failed = true;
            log.warn('rain', `the rain shelter mask cannot be painted on this device: ${String(error)}`);
            return false;
        }
    };

    const system = defineSystem(
        [Query(RainShelter, Sprite, Transform), Query(RainUpright, Sprite, Transform)],
        (shelters: Iterable<[Entity, RainShelterData, SpriteData, TransformData]>, uprights: Iterable<[Entity, RainUprightData, SpriteData, TransformData]>) => {
            const found: Shelter[] = [];
            for (const [, data, sprite, transform] of shelters) {
                const shelter = shelterOf(sprite, transform, data);
                if (shelter) found.push(shelter);
            }
            const standing: Upright[] = [];
            for (const [, data, sprite, transform] of uprights) {
                const upright = uprightOf(sprite, transform, data);
                if (upright) standing.push(upright);
            }
            sheltersNow = found;
            maskNow = null;
            if (found.length === 0 && standing.length === 0) return;
            const view = viewOf();
            if (view) paint(maskRects(found, view, ellipseStripsOf(shelterMaskSizeOf(askedSize, allowedSize()))), uprightRects(standing, view), view);
        },
        { name: 'RainShelterSystem' },
    );
    // After the cover fade has moved the sprites' alpha (it is installed first), and before the frame is drawn.
    // Nothing to do in a scene without one; the frame after the last goes still runs, to put back what it changed.
    app.addSystemToSchedule(Schedule.PostUpdate, system, { activeWhen: [RainShelter, RainUpright] });

    return () => {
        sheltersNow = [];
        maskNow = null;
        if (target) RenderTexture.release(target);
        target = null;
    };
}