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 hotUpdateRebind.ts
* @brief Built-in live-binding coordinator — makes a new generation transparent
* to game code. When applyUpdate / invalidate ends an asset's era this
* reloads the ref (now resolved to the fresh content) and moves every
* live binding of it onto the new one, so a scene that references an
* asset by @uuid updates on screen with ZERO game code.
*
* A RECEIPT never changes generation: whoever holds one keeps the era
* they acquired until they release it. A live BINDING is the other
* thing — a field that names an asset and follows what that name means
* now — and it is the only thing migrated here.
*
* Which types are migrated is read, not listed: an asset a component
* holds by handle has a `load` door, and one it holds by ref has a slot
* that swaps under the name the field already carries.
*
* It is a transaction coordinator, not an owner: which fields hold the
* asset comes from `component.assetFields` (liveAssetBindings.ts), and
* the replacement is acquired once per owning scope and handed to that
* scope (liveAssetRebind.ts). What it acquires and cannot place, it
* gives back.
*
* Registered once per App (initRuntime). State lives in this closure —
* per install, not module-global — so realms don't share queues.
*/
import type { App } from './app/app';
import { defineResource } from './ecs/resource';
import { Schedule, defineSystem, GetWorld } from './ecs/system';
import { assetScopeForEntity } from './scene/sceneManager';
import type { Entity } from './types';
import type { Assets } from './asset/Assets';
import type { AssetScope, AssetLease } from './asset/AssetLease';
import type { AssetFieldType } from './scene/scene';
import { componentsBindingAssetTypes } from './asset/liveAssetBindings';
import { boundValueIn, boundValueOf, migrateScopeBindings, ownerScopesOf } from './asset/liveAssetRebind';
import { log } from './util/logger';
/** Take the replacement out of the realm — by receipt, whatever its kind. */
function acquire(assets: Assets, type: AssetFieldType, ref: string): Promise<AssetLease> {
return type === 'texture'
? assets.acquireTexture(ref)
: assets.acquireTyped(type, ref);
}
/**
* The second barrier of an update. `Assets.applyUpdate` resolves when the ASSET
* graph has caught up; the bindings that read it move on a frame, so a paused
* app converges when it resumes and this is how to wait for that.
*
* @beta
*/
export interface LiveBindingsData {
/** Resolves once every ended era seen so far has been migrated onto its
* replacement, or given up on. Needs the app to be ticking. */
settled(): Promise<void>;
}
/** The per-App live-binding coordinator, for a game or host that has to know
* when the world has caught up with an update.
*
* @beta
*/
export const LiveBindings = defineResource<LiveBindingsData>(null!, 'LiveBindings');
export function installHotUpdateRebind(app: App, assets: Assets): LiveBindingsData {
// Ended eras (with the value bound before the drop), awaiting the reload;
// and replacements awaiting their owner's transaction.
const pending: Array<{ ref: string; type: AssetFieldType; oldValue: unknown }> = [];
const ready: Array<{
type: AssetFieldType; oldValue: unknown; scope: AssetScope; lease: AssetLease;
}> = [];
// Reloads started but not yet placed. Without them a caller can ask between
// the queues and be told the world has caught up while an acquisition is in
// the air.
let reloading = 0;
const waiting: Array<() => void> = [];
const converged = (): boolean => pending.length === 0 && ready.length === 0 && reloading === 0;
assets.onInvalidate((event) => {
// The type vocabulary is one: what a loader answers to is what a field
// declares. A ref-bound asset reports one too, and has nothing to move.
const type = event.type as AssetFieldType;
if (!assets.handleBoundTypes().includes(type)) return;
const oldValue = boundValueIn(event.oldValue);
if (oldValue !== undefined && oldValue !== 0) pending.push({ ref: event.ref, type, oldValue });
});
// Who owns what an entity holds is answered in ONE place, not here: a
// promoted entity carries no scene tag and owns its assets itself, and a
// second copy of this rule is how it came to be handed to the app instead.
const ownerScopeOf = (entity: Entity): AssetScope =>
assetScopeForEntity(app, assets, entity);
app.addSystemToSchedule(Schedule.Update, defineSystem(
[GetWorld()],
(world) => {
// One acquisition per owning scope; the async results land in
// `ready` a frame or two later, each with the scope it is for.
while (pending.length > 0) {
const { ref, type, oldValue } = pending.shift()!;
// Nobody holding it is the other silent end: the update committed,
// the pixels did not move, nothing said why. Usually two cache
// entries for one image, under two spellings of the same asset.
let owners = 0;
for (const scope of ownerScopesOf(world, type, oldValue, ownerScopeOf)) {
owners++;
reloading++;
void acquire(assets, type, ref).then(
(lease) => { ready.push({ type, oldValue, scope, lease }); },
(e: unknown) => {
log.warn('asset', `hot-update rebind: reloading "${ref}" failed; its holders keep the asset they have`, e);
},
).finally(() => { reloading--; });
}
if (owners === 0) {
log.warn('asset', `hot-update rebind: nothing holds "${ref}" (${type}) at ${String(oldValue)}`
+ ' — the update landed and no live binding moved');
}
}
while (ready.length > 0) {
const { type, oldValue, scope, lease } = ready.shift()!;
// Re-acquiring and getting the era the update just ended places the
// same pixels back and reads as success everywhere. The cache
// answered for a key the revision did not move.
if (boundValueOf(lease) === oldValue) {
log.warn('asset', `hot-update rebind: re-acquiring "${type}" returned the same value`
+ ` (${String(oldValue)}) — the update ended an era the cache still serves`);
}
// It returns whether it placed anything, and the answer was being
// dropped: false means the scope held no binding after all, which
// is a rebind that did nothing and said nothing.
const moved = migrateScopeBindings(
world, scope, type, oldValue,
{ lease, boundValue: boundValueOf }, ownerScopeOf,
);
if (!moved) {
log.warn('asset', `hot-update rebind: placed nothing for "${type}" at ${String(oldValue)}`
+ ' — the scope holds no live binding of it, so the old content stays on screen');
}
}
if (converged()) for (const wake of waiting.splice(0)) wake();
},
{
name: 'HotUpdateRebindSystem',
// The reach is every component declaring a handle-bound asset field,
// read from the registry at access time — a project component
// registered after this system was installed binds them too.
touches: () => ({ writes: componentsBindingAssetTypes(assets.handleBoundTypes()) }),
},
));
const coordinator: LiveBindingsData = {
settled: () => (converged()
? Promise.resolve()
: new Promise<void>((resolve) => { waiting.push(resolve); })),
};
app.insertResource(LiveBindings, coordinator);
return coordinator;
}