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
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. */