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.

feat(scene): proximity scene streaming + load progress (2D-parity A3)

esengined32dde608c44
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index f916dd320..1e4fa3a4f 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -118,6 +118,17 @@ export {
type TransitionOptions,
} from './sceneManager';
+export {
+ SceneStreaming,
+ SceneStreamingController,
+ computeStreaming,
+ type StreamCell,
+ type StreamDecision,
+ type StreamPolicy,
+ type SceneStreamingConfig,
+ type SceneStreamHost,
+} from './sceneStreaming';
+
export { sceneManagerPlugin } from './scenePlugin';
export {
diff --git a/sdk/src/sceneManager.ts b/sdk/src/sceneManager.ts
index 9121b3a32..2141d0896 100644
--- a/sdk/src/sceneManager.ts
+++ b/sdk/src/sceneManager.ts
@@ -7,7 +7,7 @@
import type { App } from './app';
import type { Entity, Color } from './types';
-import type { SceneData, SceneLoadOptions, LoadedSceneAssets } from './scene';
+import type { SceneData, SceneLoadOptions, LoadedSceneAssets, SceneLoadProgressCallback } from './scene';
import { discoverSceneAssets } from './asset/discoverAssets';
import type { SystemDef } from './system';
import { Material } from './material';
@@ -263,7 +263,7 @@ export class SceneManagerState {
this.transitionController_.update(dt);
}
- async load(name: string): Promise<SceneContext> {
+ async load(name: string, onProgress?: SceneLoadProgressCallback): Promise<SceneContext> {
if (this.scenes_.has(name)) {
const existing = this.scenes_.get(name)!;
if (existing.status === 'loading') {
@@ -299,7 +299,7 @@ export class SceneManagerState {
}
}
- await this.loadSceneData_(instance, name, config, sceneData);
+ await this.loadSceneData_(instance, name, config, sceneData, onProgress);
instance.status = 'running';
this.activeScene_ = name;
@@ -318,7 +318,7 @@ export class SceneManagerState {
}
}
- async loadAdditive(name: string): Promise<SceneContext> {
+ async loadAdditive(name: string, onProgress?: SceneLoadProgressCallback): Promise<SceneContext> {
if (this.scenes_.has(name)) {
const existing = this.scenes_.get(name)!;
if (existing.status === 'loading') {
@@ -354,7 +354,7 @@ export class SceneManagerState {
}
}
- await this.loadSceneData_(instance, name, config, sceneData);
+ await this.loadSceneData_(instance, name, config, sceneData, onProgress);
instance.status = 'running';
this.additiveScenes_.add(name);
@@ -459,6 +459,7 @@ export class SceneManagerState {
name: string,
config: SceneConfig,
sceneData: SceneData | undefined,
+ onProgress?: SceneLoadProgressCallback,
): Promise<void> {
if (sceneData) {
const discovered = discoverSceneAssets(sceneData);
@@ -481,6 +482,7 @@ export class SceneManagerState {
};
const loadOptions: SceneLoadOptions = { collectAssets };
+ if (onProgress) loadOptions.onProgress = onProgress;
if (this.app_.hasResource(Assets)) {
loadOptions.assets = this.app_.getResource(Assets);
}
diff --git a/sdk/src/scenePlugin.ts b/sdk/src/scenePlugin.ts
index d6c4d20bc..d8e5b121c 100644
--- a/sdk/src/scenePlugin.ts
+++ b/sdk/src/scenePlugin.ts
@@ -7,9 +7,13 @@
import type { App, Plugin } from './app';
import { SceneManager, SceneManagerState } from './sceneManager';
-import { defineSystem, Schedule } from './system';
+import { SceneStreaming, SceneStreamingController } from './sceneStreaming';
+import { defineSystem, Schedule, GetWorld } from './system';
import { Res, ResMut, Time } from './resource';
+import { Transform, type TransformData } from './component';
+import { playModeOnly } from './env';
import type { SystemDef } from './system';
+import type { World } from './world';
import { log } from './logger';
const sceneTransitionSystem = defineSystem(
@@ -21,11 +25,27 @@ const sceneTransitionSystem = defineSystem(
{ name: 'SceneTransitionSystem' }
);
+// Drives proximity streaming: pulls the focus from a follow-entity's Transform (if
+// one is set), then reconciles resident cells. A no-op until cells are registered.
+const sceneStreamingSystem = defineSystem(
+ [Res(SceneStreaming), GetWorld()],
+ (streaming: SceneStreamingController, world: World) => {
+ const focus = streaming.getFocusEntity();
+ if (focus != null && world.valid(focus) && world.has(focus, Transform)) {
+ const t = world.get(focus, Transform) as TransformData;
+ streaming.setFocus(t.position.x, t.position.y);
+ }
+ streaming.update();
+ },
+ { name: 'SceneStreamingSystem' }
+);
+
export const sceneManagerPlugin: Plugin = {
name: 'sceneManager',
build(app: App): void {
const state = new SceneManagerState(app);
app.insertResource(SceneManager, state);
+ app.insertResource(SceneStreaming, new SceneStreamingController(state));
const initSystem: SystemDef = {
_id: Symbol('SceneInitSystem'),
@@ -44,5 +64,6 @@ export const sceneManagerPlugin: Plugin = {
app.addSystemToSchedule(Schedule.Startup, initSystem);
app.addSystemToSchedule(Schedule.Last, sceneTransitionSystem);
+ app.addSystemToSchedule(Schedule.Update, sceneStreamingSystem, { runIf: playModeOnly });
},
};
diff --git a/sdk/src/sceneStreaming.ts b/sdk/src/sceneStreaming.ts
new file mode 100644
index 000000000..dd3b9e31d
--- /dev/null
+++ b/sdk/src/sceneStreaming.ts
@@ -0,0 +1,188 @@
+// 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 './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;
+ /** 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.
+ */
+export function computeStreaming(
+ cells: readonly StreamCell[],
+ focusX: number,
+ focusY: number,
+ loadRadius: number,
+ unloadRadius: number,
+ active: ReadonlySet<string>,
+): 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) - 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 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). */
+ setFocus(x: number, y: number): void {
+ this.focusX_ = x;
+ this.focusY_ = y;
+ }
+
+ /** 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_,
+ );
+ 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');
diff --git a/sdk/tests/scene-load-progress-forward.test.ts b/sdk/tests/scene-load-progress-forward.test.ts
new file mode 100644
index 000000000..4d237fb9a
--- /dev/null
+++ b/sdk/tests/scene-load-progress-forward.test.ts
@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file load()/loadAdditive() forward an onProgress callback to the scene loader,
+ * so a loading screen can track per-asset progress through the manager.
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('../src/scene', () => ({
+ // Invoke the caller's onProgress so we can assert the manager forwarded it.
+ loadSceneWithAssets: vi.fn((_w: unknown, _d: unknown, opts: { onProgress?: (l: number, t: number) => void }) => {
+ opts?.onProgress?.(3, 3);
+ return Promise.resolve(new Map());
+ }),
+}));
+vi.mock('../src/customDraw', () => ({ registerDrawCallback: vi.fn(), unregisterDrawCallback: vi.fn() }));
+vi.mock('../src/postprocess', () => ({ PostProcess: { bind: vi.fn(), unbind: vi.fn() }, PostProcessStack: vi.fn() }));
+vi.mock('../src/material', () => ({ Material: { release: vi.fn(), createShader: vi.fn() }, defineResource: vi.fn() }));
+
+import { SceneManagerState } from '../src/sceneManager';
+
+function createMockApp() {
+ const entities = new Map<number, Map<symbol, unknown>>();
+ let next = 1;
+ const world = {
+ spawn: vi.fn(() => { const e = next++; entities.set(e, new Map()); return e; }),
+ despawn: vi.fn((e: number) => entities.delete(e)),
+ valid: vi.fn((e: number) => entities.has(e)),
+ has: vi.fn(() => false),
+ get: vi.fn(() => undefined),
+ insert: vi.fn(),
+ set: vi.fn(),
+ remove: vi.fn(),
+ };
+ return { world, hasResource: vi.fn(() => false), getResource: vi.fn(), addSystemToSchedule: vi.fn() };
+}
+
+const sceneData = { version: '1.0', name: 'lvl', entities: [] };
+
+describe('SceneManager load progress forwarding', () => {
+ it('load() forwards onProgress to the scene loader', async () => {
+ const manager = new SceneManagerState(createMockApp() as never);
+ manager.register({ name: 'lvl', data: sceneData });
+ const cb = vi.fn();
+ await manager.load('lvl', cb);
+ expect(cb).toHaveBeenCalledWith(3, 3);
+ });
+
+ it('loadAdditive() forwards onProgress to the scene loader', async () => {
+ const manager = new SceneManagerState(createMockApp() as never);
+ manager.register({ name: 'lvl2', data: { ...sceneData, name: 'lvl2' } });
+ const cb = vi.fn();
+ await manager.loadAdditive('lvl2', cb);
+ expect(cb).toHaveBeenCalledWith(3, 3);
+ });
+
+ it('load() without a callback still loads', async () => {
+ const manager = new SceneManagerState(createMockApp() as never);
+ manager.register({ name: 'lvl3', data: { ...sceneData, name: 'lvl3' } });
+ await expect(manager.load('lvl3')).resolves.toBeDefined();
+ });
+});
diff --git a/sdk/tests/scene-streaming.test.ts b/sdk/tests/scene-streaming.test.ts
new file mode 100644
index 000000000..7956ec83b
--- /dev/null
+++ b/sdk/tests/scene-streaming.test.ts
@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect } from 'vitest';
+import {
+ computeStreaming,
+ SceneStreamingController,
+ type StreamCell,
+ type SceneStreamHost,
+} from '../src/sceneStreaming';
+
+const flush = async () => { await Promise.resolve(); await Promise.resolve(); };
+
+function mockHost() {
+ const loaded = new Set<string>();
+ const sleeping = new Set<string>();
+ const calls: string[] = [];
+ const host: SceneStreamHost = {
+ loadAdditive(n) { calls.push(`load:${n}`); loaded.add(n); sleeping.delete(n); return Promise.resolve({}); },
+ unload(n) { calls.push(`unload:${n}`); loaded.delete(n); return Promise.resolve(); },
+ sleep(n) { calls.push(`sleep:${n}`); sleeping.add(n); },
+ wake(n) { calls.push(`wake:${n}`); sleeping.delete(n); },
+ isLoaded: (n) => loaded.has(n),
+ isSleeping: (n) => sleeping.has(n),
+ };
+ return { host, loaded, sleeping, calls };
+}
+
+const cells = (...cs: StreamCell[]) => cs;
+
+describe('computeStreaming', () => {
+ const a: StreamCell = { scene: 'a', x: 0, y: 0, radius: 0 };
+
+ it('activates a cell whose edge is within loadRadius', () => {
+ const d = computeStreaming(cells(a), 5, 0, 10, 20, new Set());
+ expect(d.toActivate).toEqual(['a']);
+ expect(d.toDeactivate).toEqual([]);
+ });
+
+ it('does not activate a cell beyond loadRadius', () => {
+ expect(computeStreaming(cells(a), 50, 0, 10, 20, new Set()).toActivate).toEqual([]);
+ });
+
+ it('measures distance to the cell edge (radius)', () => {
+ const big: StreamCell = { scene: 'big', x: 0, y: 0, radius: 40 };
+ // center is 45 away, but the edge is only 5 away → within loadRadius 10.
+ expect(computeStreaming(cells(big), 45, 0, 10, 20, new Set()).toActivate).toEqual(['big']);
+ });
+
+ it('keeps an active cell inside the hysteresis band (load < edge ≤ unload)', () => {
+ // edge 15 is past loadRadius 10 but within unloadRadius 20 → no change.
+ const d = computeStreaming(cells(a), 15, 0, 10, 20, new Set(['a']));
+ expect(d.toActivate).toEqual([]);
+ expect(d.toDeactivate).toEqual([]);
+ });
+
+ it('deactivates an active cell past unloadRadius', () => {
+ expect(computeStreaming(cells(a), 25, 0, 10, 20, new Set(['a'])).toDeactivate).toEqual(['a']);
+ });
+});
+
+describe('SceneStreamingController', () => {
+ const near: StreamCell = { scene: 'near', x: 0, y: 0, radius: 0 };
+
+ it('loads a cell when the focus comes within range', async () => {
+ const { host, calls, loaded } = mockHost();
+ const c = new SceneStreamingController(host, { loadRadius: 10, unloadRadius: 20 });
+ c.register(near);
+ c.setFocus(100, 0);
+ c.update();
+ expect(calls).toEqual([]); // out of range
+ c.setFocus(5, 0);
+ c.update();
+ await flush();
+ expect(calls).toEqual(['load:near']);
+ expect(loaded.has('near')).toBe(true);
+ expect(c.getActive()).toEqual(['near']);
+ });
+
+ it('unloads a cell when the focus leaves (past unloadRadius)', async () => {
+ const { host, calls, loaded } = mockHost();
+ const c = new SceneStreamingController(host, { loadRadius: 10, unloadRadius: 20 });
+ c.register(near);
+ c.setFocus(5, 0); c.update(); await flush();
+ c.setFocus(15, 0); c.update(); await flush(); // in the band → stays
+ expect(loaded.has('near')).toBe(true);
+ c.setFocus(25, 0); c.update(); await flush(); // past unload → drop
+ expect(calls).toEqual(['load:near', 'unload:near']);
+ expect(loaded.has('near')).toBe(false);
+ expect(c.getActive()).toEqual([]);
+ });
+
+ it('sleep policy sleeps/wakes instead of unload/load', async () => {
+ const { host, calls } = mockHost();
+ const c = new SceneStreamingController(host, { loadRadius: 10, unloadRadius: 20, policy: 'sleep' });
+ c.register(near);
+ c.setFocus(5, 0); c.update(); await flush(); // load
+ c.setFocus(25, 0); c.update(); await flush(); // sleep
+ c.setFocus(5, 0); c.update(); await flush(); // wake
+ expect(calls).toEqual(['load:near', 'sleep:near', 'wake:near']);
+ });
+
+ it('does not re-issue a load while one is in flight', async () => {
+ const { host, calls } = mockHost();
+ const c = new SceneStreamingController(host, { loadRadius: 10, unloadRadius: 20 });
+ c.register(near);
+ c.setFocus(5, 0);
+ c.update();
+ c.update(); // same tick range, still active → no second load
+ await flush();
+ expect(calls).toEqual(['load:near']);
+ });
+
+ it('clamps unloadRadius up to loadRadius', () => {
+ const { host } = mockHost();
+ const c = new SceneStreamingController(host, { loadRadius: 30, unloadRadius: 10 });
+ c.register(near);
+ c.setFocus(20, 0); // within load(30)
+ c.update();
+ // unload clamped to 30, so at edge 20 (≤30) it must NOT immediately deactivate.
+ expect(c.getActive()).toEqual(['near']);
+ });
+});