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 Camera POV — verifies the authored-view-params → view-projection seam
* (buildCameraInfo), including the newly-honored camera rotation. The POV
* is the decoupling point a camera director will blend over (Phase C).
*/
import { describe, it, expect, vi } from 'vitest';
import {
buildCameraInfo, cameraFrustumCorners, snapToPixelGrid, type CameraPOV,
} from '../src/camera/CameraPlugin';
import { ProjectionType, ClearFlags } from '../src/ecs/component';
import { RenderTexture } from '../src/render/renderTexture';
import { Renderer } from '../src/render/renderer';
function ndc(vp: Float32Array, x: number, y: number) {
return { x: vp[0] * x + vp[4] * y + vp[12], y: vp[1] * x + vp[5] * y + vp[13] };
}
const pov = (over: Partial<CameraPOV>): CameraPOV => ({
entity: -1,
isActive: true,
x: 0,
y: 0,
z: 0,
rotation: 0,
projection: ProjectionType.Orthographic,
orthoSize: 100,
fov: 0,
near: 0,
far: 1000,
viewport: { x: 0, y: 0, z: 1, w: 1 },
clearFlags: ClearFlags.ColorAndDepth,
priority: 0,
pixelPerfect: false,
...over,
});
describe('camera POV → view-projection', () => {
it('uses the target aspect and pixel grid for a portrait texture on a landscape screen', () => {
const create = vi.spyOn(Renderer, 'createRenderTarget').mockReturnValue(7);
const texture = vi.spyOn(Renderer, 'getTargetTexture').mockReturnValue(0);
const release = vi.spyOn(Renderer, 'releaseRenderTarget').mockImplementation(() => {});
const rt = RenderTexture.create({ width: 200, height: 400 });
let released = false;
try {
const cam = buildCameraInfo(pov({ renderTarget: rt._handle, orthoSize: 100, x: 0.3, pixelPerfect: true }), 800, 600, null, [], 0);
expect(cam.halfW).toBe(50);
expect(cam.cameraX).toBe(0.5); // 200 world units / 400 target pixels
const corner = ndc(cam.viewProjection, 50.5, 100);
expect(corner.x).toBeCloseTo(1);
expect(corner.y).toBeCloseTo(1);
RenderTexture.release(rt);
released = true;
const fallback = buildCameraInfo(pov({ renderTarget: rt._handle, orthoSize: 100 }), 800, 600, null, [], 0);
expect(fallback.halfW).toBeCloseTo(100 * 800 / 600);
} finally {
if (!released) RenderTexture.release(rt);
create.mockRestore(); texture.mockRestore(); release.mockRestore();
}
});
it.each([
{ viewport: { x: 0.75, y: 0.75, z: 0.25, w: 0.25 } },
{ renderTarget: 7 },
])('keeps independent camera zoom under a screen fit (%j)', (over) => {
const fit = { designResolution: { x: 1920, y: 1080 }, scaleMode: 1, matchWidthOrHeight: 0.5 };
const cam = buildCameraInfo(pov({ orthoSize: 100, ...over }), 800, 600, fit, [], 0);
expect(cam.halfH).toBe(100);
expect(ndc(cam.viewProjection, 0, 100).y).toBeCloseTo(1);
// The full-screen camera is fitted too, but around its OWN size: orthoSize is
// the zoom, and FixedHeight keeps it as the half-height.
const main = buildCameraInfo(pov({ orthoSize: 100 }), 800, 600, fit, [], 0);
expect(main.halfH).toBe(100);
// FixedWidth keeps the design's width instead: 100 at 16:9 is 177.8 wide, on 4:3.
const wide = buildCameraInfo(pov({ orthoSize: 100 }), 800, 600, { ...fit, scaleMode: 0 }, [], 0);
expect(wide.halfW).toBeCloseTo(100 * 1920 / 1080);
});
it('rotation 0 keeps the old translation-only view (center → clip origin)', () => {
const cam = buildCameraInfo(pov({ x: 100, y: 50 }), 800, 600, null, [], 0);
const c = ndc(cam.viewProjection, 100, 50);
expect(c.x).toBeCloseTo(0);
expect(c.y).toBeCloseTo(0);
// a point at +halfW to the right maps to clip x = +1
expect(ndc(cam.viewProjection, 100 + cam.halfW, 50).x).toBeCloseTo(1);
});
it('camera rotation rotates the view (+90° → a point on the right maps to the bottom)', () => {
const cam = buildCameraInfo(pov({ rotation: Math.PI / 2 }), 800, 600, null, [], 0);
const r = ndc(cam.viewProjection, 50, 0); // world point to the right of the camera
expect(r.x).toBeCloseTo(0);
expect(r.y).toBeCloseTo(-0.5); // appears at the bottom of the view
});
it('snapToPixelGrid rounds to the nearest cell (and no-ops at 0)', () => {
expect(snapToPixelGrid(10.4, 1)).toBeCloseTo(10);
expect(snapToPixelGrid(10.6, 1)).toBeCloseTo(11);
expect(snapToPixelGrid(-3.6, 1)).toBeCloseTo(-4);
expect(snapToPixelGrid(2.7, 0.5)).toBeCloseTo(2.5);
expect(snapToPixelGrid(7.3, 0)).toBe(7.3); // worldPerPixel 0 → unchanged
});
it('pixel-perfect collapses sub-pixel-grid positions to one view', () => {
// orthoSize 100, 200px tall, full viewport → worldPerPixel = 2*100/200 = 1.
const a = buildCameraInfo(pov({ x: 10.1, y: 0.2, pixelPerfect: true }), 200, 200, null, [], 0);
const b = buildCameraInfo(pov({ x: 10.4, y: -0.3, pixelPerfect: true }), 200, 200, null, [], 1);
// Both snap to (10, 0) → identical view-projection.
expect(Array.from(b.viewProjection)).toEqual(Array.from(a.viewProjection));
expect(b.cameraX).toBeCloseTo(10);
expect(b.cameraY).toBeCloseTo(0);
});
it('without pixel-perfect those same positions produce different views', () => {
const a = buildCameraInfo(pov({ x: 10.1, y: 0.2, pixelPerfect: false }), 200, 200, null, [], 0);
const b = buildCameraInfo(pov({ x: 10.4, y: -0.3, pixelPerfect: false }), 200, 200, null, [], 1);
expect(Array.from(b.viewProjection)).not.toEqual(Array.from(a.viewProjection));
});
it('perspective POV builds without throwing and is non-degenerate', () => {
const cam = buildCameraInfo(
pov({ projection: ProjectionType.Perspective, fov: 60, near: 0.1, far: 100 }),
800,
600,
null,
[],
0,
);
expect(cam.viewProjection.some((v) => v !== 0)).toBe(true);
});
});
describe('cameraFrustumCorners', () => {
const camera = (over: Record<string, unknown> = {}) => ({
isActive: true,
projectionType: ProjectionType.Orthographic,
orthoSize: 300,
fov: 60,
nearPlane: 0.1,
farPlane: 1000,
viewport: { x: 0, y: 0, z: 1, w: 1 },
clearFlags: ClearFlags.ColorAndDepth,
priority: 0,
pixelPerfect: false,
cullingMask: 0xFFFFFFFF,
...over,
});
const transform = (over: Record<string, unknown> = {}) => ({
worldPosition: { x: 0, y: 0, z: 10 },
worldRotation: { x: 0, y: 0, z: 0, w: 1 },
...over,
});
type CamArg = Parameters<typeof cameraFrustumCorners>[0];
type TrArg = Parameters<typeof cameraFrustumCorners>[1];
const corners = (c: ReturnType<typeof camera>, t: ReturnType<typeof transform>,
w = 800, h = 600) =>
cameraFrustumCorners(c as unknown as CamArg, t as unknown as TrArg, w, h, null,
new Float32Array(24));
it('frames the authored ortho rect, aspect included', () => {
// orthoSize is the half-HEIGHT; 800x600 makes the half-width 400.
const c = corners(camera(), transform());
expect(c[0]).toBeCloseTo(-400, 3);
expect(c[1]).toBeCloseTo(-300, 3);
expect(c[6]).toBeCloseTo(400, 3); // near top-right
expect(c[7]).toBeCloseTo(300, 3);
});
it('follows the camera, and its tilt with it', () => {
const moved = corners(camera(), transform({ worldPosition: { x: 100, y: 50, z: 10 } }));
expect(moved[0]).toBeCloseTo(-300, 3);
expect(moved[1]).toBeCloseTo(-250, 3);
// Pitched 90° about X the camera looks along -Y, so its frame leaves the
// z = 0 plane entirely — the corners' z spread rather than their x.
const s = Math.sin(Math.PI / 4);
const pitched = corners(camera(), transform({ worldRotation: { x: s, y: 0, z: 0, w: s } }));
const zs = [pitched[2]!, pitched[5]!, pitched[8]!, pitched[11]!];
expect(Math.max(...zs) - Math.min(...zs)).toBeGreaterThan(500);
});
it('is a real perspective volume when the camera says so', () => {
const c = corners(camera({ projectionType: ProjectionType.Perspective, fov: 90 }),
transform());
// 90° fov: the near face's half-height is its distance from the eye.
const nearHalfH = Math.abs(c[7]!);
const farHalfH = Math.abs(c[19]!);
expect(nearHalfH).toBeCloseTo(0.1, 3);
expect(farHalfH / nearHalfH).toBeCloseTo(1000 / 0.1, -1); // float32 ratio
});
});