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.

5.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { AssetLoader, LoadContext } from '../AssetLoader';
import { resolveDocumentRef } from '../documentRef';
import type { EngineApi } from '../../ecs/bridge/engineApi';
import { marshallingCore } from './engineCore';
import { withScratch } from '../../wasm/wasmScratch';
import { log } from '../../util/logger';

/** The `.esenv` document, as the importer wrote it. */
interface EnvironmentAssetData {
    version: number;
    irradiance: number[];
    /** Project path of the prefiltered octahedral atlas. */
    specular?: string;
    faceSize?: number;
    mipCount?: number;
    maxRange?: number;
    /** Octahedral pyramids standing side by side in that atlas. A scene BAKE
     *  writes several — column 0 the sky, the rest a reflection probe each. */
    columns?: number;
    /** The panorama the sky is drawn from, a sibling of the document. */
    sky?: string;
    /** The sun the importer separated from the sky, for a Light to follow. */
    sun?: {
        /** Toward the sun, in the panorama's frame. */
        direction: number[];
        /** Its irradiance over pi. */
        color: number[];
        /** The nine coefficients without it. */
        skyIrradiance: number[];
    };
}

/** A baked environment, named by the handle a Light references. */
export interface EnvironmentResult {
    handle: number;
}

/**
 * Loads `.esenv` — an environment's irradiance and its prefiltered reflection.
 *
 * The reflection is an ordinary texture asset, acquired through the same door as
 * any other — so the preparation holds the receipt and the era gives it back.
 * Only the nine coefficients are the environment's own.
 */
export class EnvironmentAssetLoader implements AssetLoader<EnvironmentResult> {
    readonly type = 'environment';
    readonly extensions = ['.esenv'];

    /** Lazy like the mesh loader's: the module arrives after construction. */
    constructor(private readonly core_: () => EngineApi | null) {}

    async load(path: string, ctx: LoadContext): Promise<EnvironmentResult> {
        const text = await ctx.loadText(ctx.catalog.getBuildPath(path));
        const data = JSON.parse(text) as EnvironmentAssetData;
        if (!Array.isArray(data.irradiance) || data.irradiance.length !== 27) {
            throw new Error(`${path}: an environment is nine RGB coefficients, got `
                + `${data.irradiance?.length ?? 0} numbers`);
        }
        const m = marshallingCore(this.core_());
        if (!m?.environment_create) {
            throw new Error('this engine build carries no environment_create');
        }

        // A missing atlas leaves the environment diffuse-only rather than failing
        // the load: nine coefficients still light the scene, and a reflection that
        // silently took the whole asset down would be the worse answer.
        let specularHandle = 0;
        if (data.specular) {
            const resolved = resolveDocumentRef(path, data.specular);
            try {
                // flipY false: the atlas' rows are a layout, not a picture. Row 0
                // is mip 0, and a load that turned it over would put the mip
                // offsets — and every face's v — upside down.
                specularHandle = (await ctx.acquireTexture(resolved, false)).value.handle;
            } catch (e) {
                log.warn('asset', `${path}: no reflection atlas at '${resolved}'`, e);
            }
        }

        const handle = withScratch(m, (alloc) => {
            const shPtr = alloc(27 * 4);
            m.HEAPF32.set(Float32Array.from(data.irradiance), shPtr >> 2);
            return m.environment_create!(shPtr, specularHandle, data.faceSize ?? 0,
                                         data.mipCount ?? 0, data.maxRange ?? 0,
                                         data.columns ?? 1);
        });

        if (!handle) {
            throw new Error(`the engine rejected the environment in ${path}`);
        }

        const sun = data.sun;
        if (sun && m.environment_setSun) {
            if (sun.skyIrradiance?.length === 27 && sun.direction?.length === 3 && sun.color?.length === 3) {
                withScratch(m, (alloc) => {
                    const shPtr = alloc(27 * 4);
                    m.HEAPF32.set(Float32Array.from(sun.skyIrradiance), shPtr >> 2);
                    m.environment_setSun!(handle, shPtr, sun.direction[0]!, sun.direction[1]!,
                                          sun.direction[2]!, sun.color[0]!, sun.color[1]!, sun.color[2]!);
                });
            } else {
                log.warn('asset', `${path}: a sun needs a direction, a colour and nine sky coefficients`);
            }
        }

        // Missing, the sky falls back to the atlas: coarser, never absent.
        if (data.sky && m.environment_setSky) {
            const resolved = resolveDocumentRef(path, data.sky);
            try {
                // flipY false for the atlas' reason: row 0 is up, and the shader
                // reads rows by index.
                m.environment_setSky(handle, (await ctx.acquireTexture(resolved, false)).value.handle);
            } catch (e) {
                log.warn('asset', `${path}: no sky panorama at '${resolved}'`, e);
            }
        }
        return { handle };
    }

    unload(asset: EnvironmentResult): void {
        this.core_()?.environment_release?.(asset.handle);
    }
}

/** Resolve the atlas ref relative to the `.esenv`; rooted refs pass through. */