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
feat(scene): proximity scene streaming + load progress (2D-parity A3)
esengined32dde608c44
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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']);+ });+});