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.

4.6 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    components.ts
 * @brief   What a project AUTHORS about residency: that a world is streamed, what
 *          stays out of the streaming, and who asks for content to be present.
 *
 * @details Three declarations and no policy. The grid is read by the cook, which
 *          is what turns one authored world into a persistent scene plus cells;
 *          the source is read by the streamer, which is the only thing that
 *          decides what exists. Neither is a place to put "load this now" — a
 *          game that could say that has an answer the engine can never make
 *          asynchronous.
 */

import { defineComponent, defineTag, type ComponentDef } from '../ecs/component';

/** The plane a streamed world is cut on. @experimental */
export enum StreamPlane {
    /** A 3D world's ground: cells along world x and z, and y does not partition. */
    Ground = 0,
    /** A 2D world's screen plane: cells along world x and y, and z (depth, layering) does not partition. */
    Screen = 1,
}

/** The fields of the `StreamedWorld` component. @experimental */
export interface StreamedWorldData {
    /**
     * Edge of one square cell in world units, on the plane below. The axis that is not on the plane does not
     * partition: on the ground a cell is a vertical column, so a tower's floors are one place.
     */
    cellSize: number;
    /** The plane the cells lie on: the ground (x, z) of a 3D world, or the screen (x, y) of a 2D one. */
    plane: StreamPlane;
}

/**
 * Declares the scene carrying it a streamed world, and how the cook cuts it.
 *
 * Its entity is persistent by construction — it is what says the world streams.
 * Presence is the switch: remove it and the scene loads whole, which is what a
 * small one should do and what every scene did before.
 *
 * @experimental
 */
export const StreamedWorld: ComponentDef<StreamedWorldData> = defineComponent<StreamedWorldData>(
    'StreamedWorld',
    { cellSize: 1000, plane: StreamPlane.Ground },
    {
        fields: {
            cellSize: { min: 1, unit: 'wu', tooltip: 'Edge of one cell on the plane.' },
            plane: { enum: [{ label: 'Ground (x, z)', value: StreamPlane.Ground }, { label: 'Screen (x, y)', value: StreamPlane.Screen }], tooltip: 'Which two world axes the cells are cut along: a 3D world is cut on the ground, a 2D world on the screen plane.' },
        },
    },
);

/**
 * Keeps the entity's whole subtree out of the partition — the player, the camera,
 * the sun, the services that outlive any place.
 *
 * NOT scene persistence (`setPersistent`, which is about surviving a scene
 * SWITCH): this decides which cooked scene an entity is written into.
 *
 * @experimental
 */
export const WorldPersistent: ComponentDef<{}> = defineTag('WorldPersistent');

/** The fields of the `WorldStreamingSource` component. @experimental */
export interface WorldStreamingSourceData {
    /**
     * Cells this close are PREPARED — fetched, decoded, their assets acquired —
     * without being brought into the world. Speculation, never authority: a
     * prepared cell a source turns away from is thrown away, not published.
     * Clamped up to `loadRadius`.
     */
    prefetchRadius: number;
    /** Cells whose nearest edge is within this distance are asked for. */
    loadRadius: number;
    /**
     * A resident cell is only given up once its nearest edge passes this. Must
     * exceed `loadRadius`: the gap between the two is the band that stops a
     * source standing on a boundary from loading and unloading every frame.
     */
    unloadRadius: number;
    enabled: boolean;
}

/**
 * "Keep the world near me present." Add it beside a `Transform`.
 *
 * A source states a need, never a decision: several may exist and their asks are
 * UNIONED, which is what makes split screen, a spectator, a cinematic camera and
 * an editor preview the same kind of thing.
 *
 * @experimental
 */
export const WorldStreamingSource: ComponentDef<WorldStreamingSourceData> =
    defineComponent<WorldStreamingSourceData>(
        'WorldStreamingSource',
        { prefetchRadius: 3000, loadRadius: 2000, unloadRadius: 3000, enabled: true },
        {
            fields: {
                prefetchRadius: { min: 0, unit: 'wu', tooltip: 'Cells this close are prepared, not shown.' },
                loadRadius: { min: 0, unit: 'wu', tooltip: 'Cells this close are brought in.' },
                unloadRadius: { min: 0, unit: 'wu', tooltip: 'Resident cells are kept until past this.' },
            },
        },
    );