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 lights.mjs — oracle scenes for lights: a sphere's brightness is a formula.
*/
import { scene, camera, mesh, sun, ambient, lamp, probe } from './scene.mjs';
import { sunAim, axisAngle, smoothstep, dot, norm, encodeLinear8, encodeGamma8, inverseSquare, linearFalloff, srgbDecode } from './formulas.mjs';
/** A light's colour is authored as sRGB: a linear-light frame decodes it, a gamma frame uses it as it is. (MeshRenderer.color is linear already.) */
const lightColour = (colorSpace, c) => (colorSpace === 'linear' ? c.map(srgbDecode) : c);
const R = 50; // the builtin sphere is 100 units across
/** The normal of a ball of radius R, centred over the origin, at the point the camera sees at world (x, z). */
function ballNormal(x, z) {
const r2 = x * x + z * z;
if (r2 >= R * R) return null;
return [x / R, Math.sqrt(R * R - r2) / R, z / R];
}
const BALL_PROBES = [[0, 0], [16, 0], [-16, 0], [0, 16], [0, -16], [30, 12], [-30, -12], [12, -34], [40, 0], [-40, 0]];
/**
* A lit ball under a sun and one ambient light. Expected = albedo * (ambient + sun * max(N.L, 0)), sampled across the whole
* disc: a wrong cosine, a flipped light direction or a lost channel each shows on a different probe.
*/
function ballUnderSun({ id, colorSpace, pitch, yaw, albedo, sunI, sunColor, ambientI, ambientColor }) {
const aim = sunAim(pitch, yaw);
const doc = scene(id, () => [
camera(),
mesh('Ball', 'sphere', [0, R, 0], [1, 1, 1], albedo),
sun(aim, sunI, sunColor),
ambient(ambientI, ambientColor),
]);
const encode = colorSpace === 'linear' ? encodeLinear8 : encodeGamma8;
const expect = BALL_PROBES.map(([x, z]) => {
const p = probe(x, z), n = ballNormal(...p.at);
const ac = lightColour(colorSpace, ambientColor), sc = lightColour(colorSpace, sunColor);
const e = ac.map((c, k) => c * ambientI + sc[k] * sunI * Math.max(0, dot(n, aim.toLight)));
return { x: p.x, y: p.y, rgb: encode(albedo.map((a, k) => a * e[k])), tol: 4 };
});
return { id, doc, colorSpace, expect, about: 'Lambert across a ball: albedo x (ambient + sun x N.L)' };
}
/** A flat floor with one point lamp over its middle: the falloff curve, sampled out along a radius. */
function floorUnderLamp({ id, colorSpace, height, intensity, light, fall }) {
const floorTop = 5; // the 10-unit-thick slab's top face
const doc = scene(id, () => [
camera(),
mesh('Floor', 'cube', [0, 0, 0], [4, 0.1, 4], [1, 1, 1]),
lamp([0, floorTop + height, 0], intensity, [1, 1, 1], light),
]);
const encode = colorSpace === 'linear' ? encodeLinear8 : encodeGamma8;
const expect = [[0, 0], [40, 0], [-40, 0], [0, 70], [80, 0], [60, 60]].map(([x, z]) => {
const p = probe(x, z), [wx, wz] = p.at;
const toLamp = [-wx, height, -wz], dist = Math.hypot(...toLamp);
const e = intensity * fall(dist) * Math.max(0, dot(norm(toLamp), [0, 1, 0]));
return { x: p.x, y: p.y, rgb: encode([e, e, e]), tol: 4 };
});
return { id, doc, colorSpace, expect, about: 'Point lamp falloff over a floor' };
}
/** A ball under an ambient light with a hemisphere: sky colour from above, ground colour from below, blended by the facing. */
function ballUnderHemisphere({ id, colorSpace, albedo, intensity, sky, ground }) {
const doc = scene(id, () => [
camera(),
mesh('Ball', 'sphere', [0, R, 0], [1, 1, 1], albedo),
ambient(intensity, sky, { hemisphere: true, groundColor: { r: ground[0], g: ground[1], b: ground[2], a: 1 } }),
]);
const encode = colorSpace === 'linear' ? encodeLinear8 : encodeGamma8;
const skyC = lightColour(colorSpace, sky), groundC = lightColour(colorSpace, ground);
const expect = BALL_PROBES.map(([x, z]) => {
const p = probe(x, z), n = ballNormal(...p.at), up = 0.5 + 0.5 * n[1];
const e = skyC.map((c, k) => intensity * (c * up + groundC[k] * (1 - up)));
return { x: p.x, y: p.y, rgb: encode(albedo.map((a, k) => a * e[k])), tol: 4 };
});
return { id, doc, colorSpace, expect, about: 'Hemisphere ambient: sky x (0.5 + 0.5 N.y) + ground x (0.5 - 0.5 N.y)' };
}
/**
* A spot lamp straight over a floor. `innerAngle` and `outerAngle` are the cone's FULL angles: the light is full strength inside
* the inner half-angle, gone outside the outer one, and smoothstep between them in the cosine of the angle off the axis.
*/
function floorUnderSpot({ id, height, intensity, inner, outer, reach }) {
const floorTop = 5;
const doc = scene(id, () => [
camera(),
mesh('Floor', 'cube', [0, 0, 0], [4, 0.1, 4], [1, 1, 1]),
lamp([0, floorTop + height, 0], intensity, [1, 1, 1], { type: 3, radius: reach, falloff: 1, innerAngle: inner, outerAngle: outer }),
]);
// The lamp's rotation belongs to its Transform: aim it down its own -Z.
const lampEntity = doc.entities.find((e) => e.name === 'Lamp');
lampEntity.components[0].data.rotation = axisAngle([1, 0, 0], -90);
const cosInner = Math.cos((inner * 0.5 * Math.PI) / 180), cosOuter = Math.cos((outer * 0.5 * Math.PI) / 180);
const expect = [0, 10, 20, 30, 40, 50, 65].map((x) => {
const p = probe(x, 0), [wx, wz] = p.at;
const toLamp = [-wx, height, -wz], dist = Math.hypot(...toLamp);
const cone = smoothstep(cosOuter, cosInner, height / dist);
const e = intensity * linearFalloff(dist, reach, 0, 1) * cone * (height / dist);
return { x: p.x, y: p.y, rgb: encodeLinear8([e, e, e]), tol: 4 };
});
return { id, doc, colorSpace: 'linear', expect, about: 'Spot cone: smoothstep(cos outer/2, cos inner/2, cos off-axis)' };
}
export const LIGHT_SCENES = [
ballUnderSun({ id: 'oracle-lambert-sun', colorSpace: 'linear', pitch: 50, yaw: 30, albedo: [0.9, 0.5, 0.2], sunI: 1.5, sunColor: [1, 1, 1], ambientI: 0.1, ambientColor: [1, 1, 1] }),
ballUnderSun({ id: 'oracle-lambert-sun-gamma', colorSpace: 'gamma', pitch: 50, yaw: 30, albedo: [0.9, 0.5, 0.2], sunI: 1.0, sunColor: [1, 1, 1], ambientI: 0.1, ambientColor: [1, 1, 1] }),
ballUnderSun({ id: 'oracle-sun-colour', colorSpace: 'linear', pitch: 35, yaw: -60, albedo: [0.8, 0.8, 0.8], sunI: 2, sunColor: [1, 0.5, 0.25], ambientI: 0.2, ambientColor: [0.4, 0.6, 1] }),
floorUnderLamp({ id: 'oracle-point-linear', colorSpace: 'linear', height: 100, intensity: 1.2, light: { radius: 400, falloff: 1 }, fall: (d) => linearFalloff(d, 400, 0, 1) }),
floorUnderLamp({ id: 'oracle-point-linear-curve', colorSpace: 'linear', height: 100, intensity: 1.2, light: { radius: 400, falloff: 2.5 }, fall: (d) => linearFalloff(d, 400, 0, 2.5) }),
floorUnderLamp({ id: 'oracle-point-isq', colorSpace: 'linear', height: 100, intensity: 0.8, light: { radius: 800, inverseSquare: true }, fall: (d) => inverseSquare(d, 800, 100) }),
ballUnderHemisphere({ id: 'oracle-hemisphere', colorSpace: 'linear', albedo: [0.8, 0.8, 0.8], intensity: 1.2, sky: [0.3, 0.5, 1], ground: [0.6, 0.4, 0.2] }),
ballUnderHemisphere({ id: 'oracle-hemisphere-gamma', colorSpace: 'gamma', albedo: [0.8, 0.8, 0.8], intensity: 1.0, sky: [0.3, 0.5, 1], ground: [0.6, 0.4, 0.2] }),
floorUnderSpot({ id: 'oracle-spot-cone', height: 100, intensity: 0.6, inner: 20, outer: 50, reach: 600 }),
];