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 runtimeConfig — the one derivation of "what the game will run with".
*
* The play realm and every exported build read this, so what it says a project
* runs with IS what both do. The cases here are the ones a second, hand-written
* copy of the list used to get wrong: a mask that never made it out of the
* editor, and a default that has to stay expressed by ABSENCE or an untouched
* project ships different bytes.
*/
import { describe, it, expect } from 'vitest';
import {
DEFAULT_RUNTIME_CONFIG, packagedRuntimeFields, runtimeConfigOf, withAudioLoadTypes,
} from '../src/project/runtimeConfig';
import { importerDefaults } from '../src/project/importSettings';
import { audioLoadTypeOf } from '../src/assets/audioCook';
describe('runtimeConfigOf', () => {
it('carries the same normalized quality policy into exported builds', () => {
const rc = runtimeConfigOf({ features: { rendering: {
quality: { mode: 'low', dynamicResolution: true, targetFps: 30 },
} } });
expect(packagedRuntimeFields(rc).quality).toEqual(rc.quality);
expect(rc.quality.targetFps).toBe(30);
expect(packagedRuntimeFields(runtimeConfigOf({}))).not.toHaveProperty('quality');
});
it('answers with the engine defaults for a project that declares nothing', () => {
const rc = runtimeConfigOf({});
expect(rc.ySortLayers).toBe(0);
expect(rc.depthLayers).toBe(0);
expect(rc.colorSpace).toBe('gamma');
// The device clamps this later; 4 is what the project asks for by default,
// which is what a browser gives its own drawing buffer.
expect(rc.msaaSamples).toBe(4);
expect(rc.outputTransform).toBe('none');
expect(rc.uiTheme).toBe('dark');
expect(rc.uiThemeColors).toEqual({});
expect(rc.physicsEnabled).toBe(false);
expect(rc.audioConfig).toEqual({});
expect(rc.screenFit.scaleMode).toBe(-1); // fit off
expect(rc.physicsConfig.gravity).toEqual({ x: 0, y: -9.81 });
expect(rc).toEqual(DEFAULT_RUNTIME_CONFIG);
});
it('turns the sorting-layer lists into the masks the renderer takes', () => {
const rc = runtimeConfigOf({
features: { rendering: { ySortLayers: [0, 3], depthLayers: [1, 2] } },
});
expect(rc.ySortLayers).toBe(0b1001);
expect(rc.depthLayers).toBe(0b0110);
});
it('drops layer indices no 32-bit mask can carry, rather than wrapping them', () => {
const rc = runtimeConfigOf({
features: { rendering: { depthLayers: [-1, 0, 31, 32, 1.5] } },
});
// Bit 31 + bit 0, UNSIGNED: the mask crosses to C++ as a u32, so a signed
// `|` result here would be a different number than the renderer receives.
expect(rc.depthLayers).toBe(((1 << 31) >>> 0) + 1);
});
it('sends the collision matrix only when it actually restricts a pair', () => {
const open = runtimeConfigOf({ features: { physics: { collisionLayerMasks: [0xffff, 0xffff] } } });
expect(open.physicsConfig.collisionLayerMasks).toBeUndefined();
const restricted = runtimeConfigOf({ features: { physics: { collisionLayerMasks: [0xfffe] } } });
expect(restricted.physicsConfig.collisionLayerMasks?.[0]).toBe(0xfffe);
expect(restricted.physicsConfig.collisionLayerMasks).toHaveLength(16); // padded to the filter bits
});
it('folds the solver defaults in, so the settings page and the game agree', () => {
const rc = runtimeConfigOf({ features: { physics: { enabled: true, subStepCount: 8 } } });
expect(rc.physicsEnabled).toBe(true);
expect(rc.physicsConfig.subStepCount).toBe(8);
expect(rc.physicsConfig.fixedTimestep).toBeCloseTo(1 / 60, 9);
expect(rc.physicsConfig.enableSleep).toBe(true);
});
});
describe('packagedRuntimeFields', () => {
// Absence IS the default in game.config.json, so an untouched project carries
// nothing it did not declare.
it('carries only the design resolution for a project that declared nothing', () => {
// Not a setting a project opts into: every project HAS a design resolution,
// and a desktop window opens at it. Everything else stays absent so a build
// with default settings keeps the config it has always had.
expect(packagedRuntimeFields(runtimeConfigOf({}))).toEqual({
screenFit: { designWidth: 1920, designHeight: 1080, scaleMode: -1, matchWidthOrHeight: 0.5, renderPolicy: 0 },
});
});
it('carries the 2.5D depth mask — the field that used to reach Play and no build', () => {
const fields = packagedRuntimeFields(runtimeConfigOf({
features: { rendering: { depthLayers: [1, 2] } },
}));
expect(fields.depthLayers).toBe(0b110);
});
it('reads the neutral output transform and ships it', () => {
const rc = runtimeConfigOf({ features: { rendering: { outputTransform: 'neutral' } } });
expect(rc.outputTransform).toBe('neutral');
expect(packagedRuntimeFields(rc).outputTransform).toBe('neutral');
});
it('carries every non-default and nothing else', () => {
const fields = packagedRuntimeFields(runtimeConfigOf({
designResolution: { width: 800, height: 600 },
features: {
rendering: {
ySortLayers: [1], depthLayers: [2], colorSpace: 'linear',
outputTransform: 'aces', cameraScaleMode: 'expand', msaa: 1,
},
ui: { theme: 'light', colors: { accent: '#ff0000ff' } },
},
}));
expect(Object.keys(fields).sort()).toEqual(
['colorSpace', 'depthLayers', 'msaaSamples', 'outputTransform', 'screenFit', 'uiTheme',
'uiThemeColors', 'ySortLayers'],
);
expect(fields.screenFit).toEqual({
designWidth: 800, designHeight: 600, scaleMode: 2, matchWidthOrHeight: 0.5, renderPolicy: 0
});
});
// The design resolution is what a desktop window opens at, and a window has a
// size whether or not the camera scales to it — so it ships even with the fit
// off, which is the case every project starts in.
it('carries the design resolution even when the camera fit is off', () => {
const fields = packagedRuntimeFields(runtimeConfigOf({
designResolution: { width: 1080, height: 1920 },
}));
expect(fields.screenFit).toEqual({
designWidth: 1080, designHeight: 1920, scaleMode: -1, matchWidthOrHeight: 0.5, renderPolicy: 0
});
});
// Physics and the mixer used to reach Play and no shipped build at all, so a
// game verified in Play could ship with different gravity and a silent mixer.
it('carries physics and the mixer, which used to reach Play and no build', () => {
const fields = packagedRuntimeFields(runtimeConfigOf({
features: {
physics: { enabled: true, gravity: { x: 0, y: -20 }, collisionLayerMasks: [0xfffe] },
audio: { buses: [{ name: 'sfx', volume: 0.5 }] },
},
}));
expect(fields.physicsEnabled).toBe(true);
expect(fields.physicsConfig?.gravity).toEqual({ x: 0, y: -20 });
expect(fields.physicsConfig?.collisionLayerMasks?.[0]).toBe(0xfffe);
expect(fields.audioConfig?.buses?.[0]).toEqual({ name: 'sfx', volume: 0.5 });
});
// ...but only when declared: a default world would otherwise be spelled out in
// every existing build's config, and a runtime falls back to the same values.
it('omits a physics world and a mixer that are just the defaults', () => {
const declaredButDefault = packagedRuntimeFields(runtimeConfigOf({
features: { physics: { gravity: { x: 0, y: -9.81 } }, audio: {} },
}));
expect(declaredButDefault.physicsConfig).toBeUndefined();
expect(declaredButDefault.audioConfig).toBeUndefined();
expect(declaredButDefault.physicsEnabled).toBeUndefined();
});
// The editor's live project state is not a manifest object, but it has the two
// fields this reads — that structural match is what lets one derivation serve
// the renderer and the main process.
it('reads a project state as readily as a parsed manifest', () => {
const state = { name: 'X', root: '/p', designResolution: { width: 640, height: 480 }, features: {} };
expect(runtimeConfigOf(state).screenFit.designWidth).toBe(640);
});
});
describe('how an audio clip loads', () => {
it('is Auto until the importer says otherwise, and a hand-edited value cannot break the cook', () => {
expect(importerDefaults('audio').loadType).toBe('auto');
expect(audioLoadTypeOf(undefined)).toBeNull();
expect(audioLoadTypeOf({ loadType: 'auto' })).toBeNull();
expect(audioLoadTypeOf({ loadType: 'streaming' })).toBe('streaming');
expect(audioLoadTypeOf({ loadType: 'decompress' })).toBe('decompress');
expect(audioLoadTypeOf({ loadType: 'sideways' })).toBeNull();
});
it('rides the packaged audio config only when a clip asked for something', () => {
expect(packagedRuntimeFields(DEFAULT_RUNTIME_CONFIG).audioConfig).toBeUndefined();
expect(packagedRuntimeFields(withAudioLoadTypes(DEFAULT_RUNTIME_CONFIG, {})).audioConfig).toBeUndefined();
// What the cook's encoding did to a clip rides in the same place, with or without a load type beside it.
const encoded = { 'assets/theme.wav': { seconds: 53.3, lead: 0.02506 } };
expect(packagedRuntimeFields(withAudioLoadTypes(DEFAULT_RUNTIME_CONFIG, {}, encoded)).audioConfig).toEqual({ encoded });
expect(packagedRuntimeFields(withAudioLoadTypes(DEFAULT_RUNTIME_CONFIG, { 'assets/bgm.mp3': 'streaming' }, encoded)).audioConfig)
.toEqual({ loadTypes: { 'assets/bgm.mp3': 'streaming' }, encoded });
expect(packagedRuntimeFields(withAudioLoadTypes(DEFAULT_RUNTIME_CONFIG, {}, {})).audioConfig).toBeUndefined();
const rc = withAudioLoadTypes(DEFAULT_RUNTIME_CONFIG, { 'assets/bgm.mp3': 'streaming' });
expect(packagedRuntimeFields(rc).audioConfig).toEqual({ loadTypes: { 'assets/bgm.mp3': 'streaming' } });
expect(DEFAULT_RUNTIME_CONFIG.audioConfig.loadTypes).toBeUndefined();
});
});
describe('the quality block that ships with the level off', () => {
it('carries a delivery choice, because it holds whatever the level', () => {
for (const choice of [{ asyncShaderCompile: true }, { prewarmShaders: true }, { renderOnDemand: true }]) {
const rc = runtimeConfigOf({ features: { rendering: { quality: { mode: 'off', ...choice } } } });
expect(packagedRuntimeFields(rc).quality).toEqual(rc.quality);
expect(packagedRuntimeFields(rc).quality?.mode).toBe('off');
}
});
it('ships a level named off, or a phone would read it as none named and take medium', () => {
const rc = runtimeConfigOf({ features: { rendering: { quality: { mode: 'off', targetFps: 30 } } } });
expect(packagedRuntimeFields(rc).quality?.mode).toBe('off');
});
it('leaves the block out when the project says nothing in it', () => {
expect(packagedRuntimeFields(runtimeConfigOf({ features: { rendering: {} } }))).not.toHaveProperty('quality');
expect(packagedRuntimeFields(runtimeConfigOf({ features: { rendering: { quality: { targetFps: 30 } } } }))).not.toHaveProperty('quality');
});
it('ships delivery choices with no level when none is named', () => {
const fields = packagedRuntimeFields(runtimeConfigOf({ features: { rendering: { quality: { renderOnDemand: true } } } }));
expect(fields.quality?.renderOnDemand).toBe(true);
expect(fields.quality).not.toHaveProperty('mode');
});
});
describe('the runtime tuning', () => {
it('is empty for a project that declares nothing, and ships nothing', () => {
const rc = runtimeConfigOf({});
expect(rc.runtime).toEqual({});
expect(packagedRuntimeFields(rc)).not.toHaveProperty('runtime');
});
it('ships only what differs from the engine, held to its range', () => {
const rc = runtimeConfigOf({ features: { runtime: {
maxDeltaTime: 0.25, // the engine's own value: absence is how a default is written
assetLoadTimeout: 60000, textureCacheBudget: 128 * 1024 * 1024, maxFixedSteps: 1000, sceneTransitionColor: '#FF0000',
} } });
expect(rc.runtime).toEqual({
assetLoadTimeout: 60000, textureCacheBudget: 128 * 1024 * 1024, maxFixedSteps: 64, sceneTransitionColor: '#ff0000',
});
expect(packagedRuntimeFields(rc).runtime).toEqual(rc.runtime);
});
it('drops a field of the wrong type instead of inventing a value', () => {
const rc = runtimeConfigOf({ features: { runtime: { maxDeltaTime: '1', defaultFontFamily: 5, sceneTransitionColor: 'red' } as never } });
expect(rc.runtime).toEqual({});
});
});