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.

12.3 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    dragonbones/loadDragonBonesScene.ts
 * @brief   Turning DragonBonesAnimation components into posed armatures.
 *
 * @details The counterpart of `spine/loadSpineScene.ts`, and split for the same
 *          reason: the builder runtime and the editor must load a scene's
 *          skeletons by ONE implementation, or the viewport and the shipped game
 *          disagree about what the scene contains.
 *
 *          Two phases, because entity ids do not exist until the scene spawns.
 *          Phase 1 fetches bytes and uploads the atlas page; phase 2 binds them to
 *          entities. The split is what lets the runtime loader interleave the fetch
 *          with everything else it preloads.
 *
 *          Where this differs from Spine is the atlas. A Spine `.atlas` lists its
 *          pages inside itself; a DragonBones `_tex.json` is a JSON object naming
 *          exactly one, in `imagePath`. So there is no page loop here — one image,
 *          resolved against the atlas's AUTHORED directory, because a cook renames
 *          the atlas and the image independently and neither ends up beside the
 *          other by accident.
 */
import type { ESEngineModule } from '../wasm';
import type { Entity } from '../types';
import { getComponentSkeletalFieldDescriptor, type SceneData } from '../scene/scene';
import { discoverSceneAssets } from '../asset/discoverAssets';
import { getAssetTypeEntry } from '../assetTypes';
import { requireResourceManager } from '../wasm/resourceManager';
import { log } from '../util/logger';
import { createAtlasPageTexture, type RuntimeAssetSource } from '../runtime/runtimeAssets';
import type { BasisTranscoder } from '../asset/compressed';
import type { DragonBonesManager } from './DragonBonesManager';
import { ownAtlas, bindAtlasOwner, releaseUnusedAtlases } from './atlasOwnership';

/** Lazily yields the realm's Basis transcoder, or null where a cook cannot have
 *  produced a compressed page (editor, uncooked dev). Same seam as Spine's. */
export type TranscoderProvider = () => Promise<BasisTranscoder | null>;

/**
 * The in-place editable props from a DragonBonesAnimation component's data — the
 * SINGLE extraction the scene loader and the editor's live-sync both feed to
 * `setEntityProps`, so a prop added to the component is carried by both paths from
 * one place instead of being hand-listed twice.
 */
export function dragonBonesEntityProps(d: Record<string, unknown>): {
    skeletonScale: number; flipX: boolean; flipY: boolean; layer: number;
    timeScale: number; playing: boolean;
    color: { r: number; g: number; b: number; a: number };
} {
    const num = (v: unknown, dflt: number): number => (typeof v === 'number' ? v : dflt);
    const color = d.color;
    return {
        skeletonScale: num(d.skeletonScale, 1),
        flipX: d.flipX === true,
        flipY: d.flipY === true,
        layer: num(d.layer, 0),
        timeScale: num(d.timeScale, 1),
        playing: d.playing !== false,
        // Opaque white rather than undefined, so CLEARING the field in the editor
        // resets the tint instead of leaving the last colour applied (setEntityProps
        // only writes a colour it was given). Same reasoning as spineEntityProps.
        color: color && typeof color === 'object'
            ? (color as { r: number; g: number; b: number; a: number })
            : { r: 1, g: 1, b: 1, a: 1 },
    };
}

/** What phase 1 fetched for one skeleton/atlas pair. */
export interface DragonBonesAssetInfo {
    skeletonData: Uint8Array | string;
    atlasJson: string;
    /** The uploaded page's id, or -1 when the image could not be loaded — the
     *  armature still poses, it just draws untextured, which is visible. */
    textureId: number;
}

/** The image a `_tex.json` names, or '' when it names none. */
function atlasImageName(atlasJson: string): string {
    try {
        const parsed: unknown = JSON.parse(atlasJson);
        const path = (parsed as { imagePath?: unknown } | null)?.imagePath;
        return typeof path === 'string' ? path : '';
    } catch {
        return '';
    }
}

/**
 * Phase 1 — fetch each pair's skeleton and atlas and upload the atlas image.
 * Keyed by `skeletonRef:atlasRef` for {@link applyDragonBonesEntities}.
 */
export async function loadDragonBonesAssets(
    /** The wasm engine module, or null on a core with no heap — the upload goes
     *  through the ResourceManager's byte path there. */
    module: ESEngineModule | null,
    source: RuntimeAssetSource,
    pairs: ReadonlyArray<{ skeleton: string; atlas: string }>,
    transcoderProvider?: TranscoderProvider,
): Promise<Map<string, DragonBonesAssetInfo>> {
    const assetInfo = new Map<string, DragonBonesAssetInfo>();
    const resolveRef = source.resolveRef ?? ((r: string) => r);

    for (const pair of pairs) {
        const cacheKey = `${pair.skeleton}:${pair.atlas}`;
        if (assetInfo.has(cacheKey)) continue;

        try {
            const atlasJson = await source.backend.fetchText(resolveRef(pair.atlas));

            const skelPath = resolveRef(pair.skeleton);
            const skeletonData: Uint8Array | string =
                getAssetTypeEntry(skelPath)?.contentType === 'binary'
                    ? new Uint8Array(await source.backend.fetchBinary(skelPath))
                    : await source.backend.fetchText(skelPath);

            const page = await uploadAtlasImage_(module, source, pair.atlas, atlasJson, resolveRef, transcoderProvider);
            const info = {
                skeletonData,
                atlasJson,
                textureId: page.textureId,
            };
            if (page.release) ownAtlas(info, page.release);
            assetInfo.set(cacheKey, info);
        } catch (err) {
            log.warn('runtime',
                `Failed to load DragonBones asset: skeleton=${pair.skeleton} atlas=${pair.atlas}`, err);
        }
    }
    return assetInfo;
}

/** Acquire the page a `_tex.json` names; its release follows the skeleton's lifetime. */
async function uploadAtlasImage_(
    module: ESEngineModule | null,
    source: RuntimeAssetSource,
    atlasRef: string,
    atlasJson: string,
    resolveRef: (ref: string) => string,
    transcoderProvider?: TranscoderProvider,
): Promise<{ textureId: number; release?: () => void }> {
    const imageName = atlasImageName(atlasJson);
    if (!imageName) {
        log.warn('runtime', `DragonBones atlas names no image: ${atlasRef}`);
        return { textureId: -1 };
    }

    // The image is named relative to where the atlas was AUTHORED, not to where a
    // content-addressed build staged it — recover that directory from the atlas's
    // logical address so `<dir>/page.png` resolves through the manifest like every
    // other ref (the same recovery Spine's page loop does).
    const atlasLogical = source.resolveAddress?.(atlasRef) ?? resolveRef(atlasRef);
    const slash = atlasLogical.lastIndexOf('/');
    const imagePath = slash >= 0 ? `${atlasLogical.substring(0, slash)}/${imageName}` : imageName;

    try {
        const staged = resolveRef(imagePath);
        const rm = requireResourceManager();
        const existing = typeof rm.acquireTextureByPath === 'function' ? rm.acquireTextureByPath(imagePath) : 0;
        if (existing) return { textureId: rm.getTextureGLId(existing), release: () => rm.releaseTexture(existing) };
        const page = await createAtlasPageTexture(
            staged,
            (p) => source.backend.fetchBinary(p),
            (p) => source.decodePixels(p, false),
            transcoderProvider, module,
        );
        rm.registerTextureWithPath(page.handle, imagePath);
        return { textureId: rm.getTextureGLId(page.handle), release: () => rm.releaseTexture(page.handle) };
    } catch (err) {
        log.warn('runtime', `Failed to load DragonBones atlas image: ${imagePath}`, err);
        return { textureId: -1 };
    }
}

/**
 * Phase 2 — for each DragonBonesAnimation entity, parse its pair into the manager
 * (shared per pair, so ten of the same armature parse the file once), bind the
 * uploaded page, and apply the component's armature, props and animation.
 */
export function applyDragonBonesEntities(opts: {
    manager: DragonBonesManager;
    sceneData: SceneData;
    entityMap: Map<number, Entity>;
    assetInfo: Map<string, DragonBonesAssetInfo>;
}): void {
    const { manager, sceneData, entityMap, assetInfo } = opts;
    if (assetInfo.size === 0) return;
    const touched = new Set<string>();
    try {
        for (const sceneEntity of sceneData.entities) {
            // Prefab instances carry no inline components; the loader expands them
            // before this runs.
            if (!Array.isArray(sceneEntity.components)) continue;

            for (const comp of sceneEntity.components) {
                const desc = getComponentSkeletalFieldDescriptor(comp.type);
                if (!desc || desc.runtime !== 'dragonbones' || !comp.data) continue;

                const data = comp.data as Record<string, unknown>;
                const skeletonRef = data[desc.skeletonField];
                const atlasRef = data[desc.atlasField];
                if (typeof skeletonRef !== 'string' || typeof atlasRef !== 'string') continue;
                if (!skeletonRef || !atlasRef) continue;

                const assetKey = `${skeletonRef}:${atlasRef}`;
                const info = assetInfo.get(assetKey);
                if (!info) continue;

                const entity = entityMap.get(sceneEntity.id);
                if (entity === undefined) continue;

                const handle = manager.loadSkeleton(info.skeletonData, info.atlasJson, assetKey);
                if (handle < 0) continue;
                touched.add(assetKey);
                if (info.textureId >= 0) manager.setAtlasTexture(handle, info.textureId);
                bindAtlasOwner(info, manager, handle);

                // An unspecified armature selects the file's first armature.
                const named = typeof data.armature === 'string' ? data.armature : '';
                const armature = named || manager.getArmatures(handle)[0];
                if (!armature) {
                    log.warn('runtime', `DragonBones file holds no armature: ${skeletonRef}`);
                    continue;
                }

                const props = dragonBonesEntityProps(data);
                const added = manager.addEntity(entity, handle, {
                    armature,
                    assetKey,
                    skeletonScale: props.skeletonScale,
                    flipX: props.flipX,
                    flipY: props.flipY,
                    layer: props.layer,
                });
                if (!added) continue;

                manager.setEntityProps(entity, props);

                const animation = typeof data.animation === 'string' ? data.animation : '';
                if (animation) {
                    const fade = typeof data.fadeInTime === 'number' ? data.fadeInTime : 0;
                    const loop = data.loop !== false;
                    // fadeInTime is what this component has instead of Spine's mix
                    // table, so an authored fade belongs to the FIRST play too.
                    if (fade > 0) manager.fadeIn(entity, animation, fade, loop);
                    else manager.play(entity, animation, loop);
                }
            }
        }
    } finally {
        for (const key of touched) manager.discardUnboundSkeleton(key);
        releaseUnusedAtlases(assetInfo.values());
    }
}

/**
 * Combined convenience: discover this scene's DragonBones pairs, load them, and
 * bind them to the spawned entities. What the editor's viewport calls.
 */
export async function loadDragonBonesSceneEntities(opts: {
    module: ESEngineModule | null;
    source: RuntimeAssetSource;
    manager: DragonBonesManager;
    sceneData: SceneData;
    entityMap: Map<number, Entity>;
    transcoderProvider?: TranscoderProvider;
}): Promise<void> {
    const discovered = discoverSceneAssets(opts.sceneData);
    if (discovered.dragonBones.length === 0) return;
    const assetInfo = await loadDragonBonesAssets(
        opts.module, opts.source, discovered.dragonBones, opts.transcoderProvider);
    applyDragonBonesEntities({
        manager: opts.manager,
        sceneData: opts.sceneData,
        entityMap: opts.entityMap,
        assetInfo,
    });
}