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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file sceneStreaming.ts
* @brief Proximity-driven scene streaming over the SceneManager primitives.
*
* Large/open worlds split into cells, each an additively-loaded scene. A focus
* point (usually the player/camera) drives which cells are resident: cells within
* `loadRadius` of the focus are brought in, cells past `unloadRadius` are dropped.
* The two radii form a hysteresis band so a focus hovering at a boundary does not
* thrash. This is pure orchestration — it owns no loading itself, only calls the
* existing `loadAdditive`/`unload`/`sleep`/`wake` primitives.
*/
import { defineResource } from '../ecs/resource';
import type { Entity } from '../types';
/** A streamable cell: an additive scene with a world-space center + radius. */
export interface StreamCell {
/** Registered scene name (must be a `SceneManager.register`ed scene). */
scene: string;
x: number;
y: number;
/** Where the cell sits in depth. Absent = the plane a flat scene draws on. */
z?: number;
/** Cell radius in world units; distances are measured to the cell edge. */
radius: number;
}
export interface StreamDecision {
toActivate: string[];
toDeactivate: string[];
}
/**
* Decide which cells cross the load/unload thresholds this tick. A cell becomes
* active when its edge is within `loadRadius`; an active cell deactivates only
* once its edge passes `unloadRadius` (hysteresis). Cells inside the band keep
* their current state. Pure.
*
* A cell is a sphere, not a circle: measuring in two axes makes every floor of a
* tower the same place, so a world stacked in depth holds all of it resident at
* once. Both z default to 0, which is where a flat game's cells and focus are —
* the third term vanishes and the answer is the plane one.
*/
export function computeStreaming(
cells: readonly StreamCell[],
focusX: number,
focusY: number,
loadRadius: number,
unloadRadius: number,
active: ReadonlySet<string>,
focusZ = 0,
): StreamDecision {
const toActivate: string[] = [];
const toDeactivate: string[] = [];
for (const c of cells) {
const edge = Math.max(
0, Math.hypot(focusX - c.x, focusY - c.y, focusZ - (c.z ?? 0)) - c.radius);
const isActive = active.has(c.scene);
if (!isActive && edge <= loadRadius) toActivate.push(c.scene);
else if (isActive && edge > unloadRadius) toDeactivate.push(c.scene);
}
return { toActivate, toDeactivate };
}
/** Out-of-range cells are fully unloaded, or merely put to sleep (faster wake). */
export type StreamPolicy = 'unload' | 'sleep';
export interface SceneStreamingConfig {
loadRadius: number;
/** Clamped up to `loadRadius` if smaller (hysteresis requires unload ≥ load). */
unloadRadius: number;
policy?: StreamPolicy;
}
/**
* The slice of SceneManager the streamer drives. `SceneManagerState` satisfies it
* structurally; tests inject a recording stub.
*/
export interface SceneStreamHost {
loadAdditive(name: string): Promise<unknown>;
unload(name: string): Promise<void>;
sleep(name: string): void;
wake(name: string): void;
isLoaded(name: string): boolean;
isSleeping(name: string): boolean;
}
export class SceneStreamingController {
private readonly host_: SceneStreamHost;
private readonly cells_ = new Map<string, StreamCell>();
/** Cells the controller currently considers in-range (hysteresis state). */
private readonly active_ = new Set<string>();
/** Cells with an async load/unload in flight, so it isn't issued twice. */
private readonly inFlight_ = new Set<string>();
private focusX_ = 0;
private focusY_ = 0;
private focusZ_ = 0;
private loadRadius_ = 0;
private unloadRadius_ = 0;
private policy_: StreamPolicy = 'unload';
private focusEntity_: Entity | null = null;
constructor(host: SceneStreamHost, config?: SceneStreamingConfig) {
this.host_ = host;
if (config) this.configure(config);
}
configure(config: SceneStreamingConfig): void {
this.loadRadius_ = config.loadRadius;
this.unloadRadius_ = Math.max(config.loadRadius, config.unloadRadius);
this.policy_ = config.policy ?? 'unload';
}
register(cell: StreamCell): void {
this.cells_.set(cell.scene, cell);
}
unregister(scene: string): void {
this.cells_.delete(scene);
this.active_.delete(scene);
}
clear(): void {
this.cells_.clear();
this.active_.clear();
this.inFlight_.clear();
this.focusEntity_ = null;
}
/** Set the focus directly (or let the streaming system read a focus entity).
* @p z defaults to the plane a flat game's cells sit on. */
setFocus(x: number, y: number, z = 0): void {
this.focusX_ = x;
this.focusY_ = y;
this.focusZ_ = z;
}
/** Follow an entity; the streaming system reads its Transform each tick. */
setFocusEntity(entity: Entity | null): void {
this.focusEntity_ = entity;
}
getFocusEntity(): Entity | null {
return this.focusEntity_;
}
/** Scenes the controller currently holds in-range. */
getActive(): string[] {
return [...this.active_];
}
/** Reconcile resident cells against the current focus. Idempotent per tick. */
update(): void {
if (this.cells_.size === 0) return;
const decision = computeStreaming(
[...this.cells_.values()],
this.focusX_, this.focusY_,
this.loadRadius_, this.unloadRadius_,
this.active_,
this.focusZ_,
);
for (const scene of decision.toActivate) {
this.active_.add(scene);
this.activate_(scene);
}
for (const scene of decision.toDeactivate) {
this.active_.delete(scene);
this.deactivate_(scene);
}
}
private activate_(scene: string): void {
if (this.policy_ === 'sleep' && this.host_.isSleeping(scene)) {
this.host_.wake(scene);
return;
}
if (this.host_.isLoaded(scene) || this.inFlight_.has(scene)) return;
this.inFlight_.add(scene);
Promise.resolve(this.host_.loadAdditive(scene)).then(
// If the focus left during the load, drop it now (avoids a resident leak).
() => { this.inFlight_.delete(scene); if (!this.active_.has(scene)) this.deactivate_(scene); },
() => { this.inFlight_.delete(scene); },
);
}
private deactivate_(scene: string): void {
if (this.policy_ === 'sleep') {
if (this.host_.isLoaded(scene)) this.host_.sleep(scene);
return;
}
if (!this.host_.isLoaded(scene) || this.inFlight_.has(scene)) return;
this.inFlight_.add(scene);
Promise.resolve(this.host_.unload(scene)).then(
() => { this.inFlight_.delete(scene); if (this.active_.has(scene)) this.activate_(scene); },
() => { this.inFlight_.delete(scene); },
);
}
}
export const SceneStreaming = defineResource<SceneStreamingController>(null!, 'SceneStreaming');