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.

6.0 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    liveAssetRebind.ts
 * @brief   Replacing a live asset is a transaction, and its unit is the owning scope.
 *
 * @details Ownership is per scope: two scenes holding one texture hold two
 *          receipts. So a replacement that acquires ONCE and swaps the handle
 *          world-wide moves both owners onto an asset only one of them owes a
 *          release for — the other's receipt now names an era nothing on screen
 *          is using, and the new era has one holder where two are needed.
 *
 *          Hence one acquisition per scope that migrates, and within a scope
 *          all of its bindings move or none do: a scope holding the new
 *          generation for some of its bindings and the old one for the rest
 *          owes two receipts for one replacement, and nothing afterwards can
 *          say which binding belongs to which.
 *
 *          The coordinator owns nothing at rest. Every acquisition it makes
 *          ends up in an owner's scope or is given straight back.
 */
import type { World } from '../ecs/world';
import type { Entity } from '../types';
import type { AssetScope, AssetLease } from './AssetLease';
import type { AssetFieldType } from '../scene/scene';
import { findLiveAssetBindings, readLiveAssetBinding, writeLiveAssetBinding } from './liveAssetBindings';
import { isRegistrySlotLease } from './registryAssets';
import { log } from '../util/logger';

/** The scope that owns what an entity's asset fields hold. */
export type OwnerScopeResolver = (entity: Entity) => AssetScope;

/**
 * What a bound field holds for this asset value — a handle.
 *
 * One rule for both ends of a replacement: the outgoing value an invalidation
 * reports, and the incoming lease. Undefined for an asset a field names by REF
 * rather than by value, which is not migrated at all — its slot swaps under the
 * name the field already holds.
 */
export function boundValueIn(value: unknown): unknown {
    if (typeof value === 'number') return value;
    return (value as { handle?: number } | null)?.handle;
}

/** {@link boundValueIn} for what a receipt names. */
export function boundValueOf(lease: AssetLease): unknown {
    return boundValueIn(lease.value);
}

/** The receipt in `scope` that a bound value names, if the scope holds one. */
export function leaseBoundAs(scope: AssetScope, value: unknown): AssetLease | undefined {
    if (value === undefined || value === null || value === 0 || value === '') return undefined;
    return scope.leases().find((lease) => boundValueOf(lease) === value);
}

/**
 * The slot receipt in `scope` that answers to this ref, if the scope holds one.
 *
 * The other half of {@link leaseBoundAs}: a field naming an asset by ref points
 * at a SLOT, and the slot's own names say which — no resolving a path, which
 * after an invalidate names a different era than the field is reading.
 */
export function slotLeaseNamed(scope: AssetScope, ref: unknown): AssetLease | undefined {
    if (typeof ref !== 'string' || ref === '') return undefined;
    return scope.leases().find(
        (lease) => isRegistrySlotLease(lease) && lease.names.includes(ref),
    );
}

/** One acquisition of the replacement, and how to read the value a bound field
 *  holds for it. */
export interface LiveAssetReplacement {
    readonly lease: AssetLease;
    readonly boundValue: (lease: AssetLease) => unknown;
}

/** Every scope owning at least one live binding of `oldValue` — one replacement
 *  acquisition is owed to each. */
export function ownerScopesOf(
    world: World, type: AssetFieldType, oldValue: unknown, ownerScopeOf: OwnerScopeResolver,
): AssetScope[] {
    const scopes: AssetScope[] = [];
    for (const binding of findLiveAssetBindings(world, type, oldValue)) {
        const scope = ownerScopeOf(binding.entity);
        if (!scopes.includes(scope)) scopes.push(scope);
    }
    return scopes;
}

/**
 * Move one scope onto the replacement: bindings and ownership together, all or
 * none. Returns whether it migrated; when it did not, the replacement has been
 * given back rather than kept by the coordinator.
 */
export function migrateScopeBindings(
    world: World,
    scope: AssetScope,
    type: AssetFieldType,
    oldValue: unknown,
    replacement: LiveAssetReplacement,
    ownerScopeOf: OwnerScopeResolver,
): boolean {
    const bindings = findLiveAssetBindings(world, type, oldValue)
        .filter((binding) => ownerScopeOf(binding.entity) === scope);
    const newValue = replacement.boundValue(replacement.lease);
    if (bindings.length === 0 || newValue === undefined) {
        replacement.lease.release();
        return false;
    }

    // What this scope holds for the outgoing era, found BEFORE the replacement
    // joins the scope — afterwards a search by value could match either.
    const outgoing = leaseBoundAs(scope, oldValue);

    const previous = bindings.map((binding) => readLiveAssetBinding(world, binding));
    let written = 0;
    let failure: unknown = null;
    for (; written < bindings.length; written++) {
        try {
            writeLiveAssetBinding(world, bindings[written], newValue);
        } catch (e) {
            failure = e;
            break;
        }
    }
    if (failure !== null) {
        // Every binding, not only the ones whose write RETURNED: a write that
        // threw may still have landed, and one left holding the replacement is
        // the split ownership this is atomic to prevent.
        for (let i = bindings.length - 1; i >= 0; i--) {
            try {
                writeLiveAssetBinding(world, bindings[i], previous[i]);
            } catch {
                // The binding is gone; there is nothing to put back into it.
            }
        }
        replacement.lease.release();
        log.warn('asset', 'live asset rebind rolled back — a binding could not be written', failure);
        return false;
    }

    scope.add(replacement.lease);
    if (outgoing) {
        scope.forget(outgoing);
        outgoing.release();
    }
    return true;
}