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
feat(camera): pixel-perfect camera snapping (Orthographic)
yhh5942e0b75e26
diff --git a/desktop/public/scenes/pixel-perfect.esscene b/desktop/public/scenes/pixel-perfect.esscenenew file mode 100644index 000000000..dd1860989--- /dev/null+++ b/desktop/public/scenes/pixel-perfect.esscene@@ -0,0 +1,28 @@+{+ "version": "1.0",+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0.37, "y": -0.42, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0, "pixelPerfect": true } }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "Green",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ { "type": "Sprite", "data": { "size": { "x": 400, "y": 400 }, "color": { "r": 0, "g": 1, "b": 0, "a": 1 } } }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/pixel-perfect.textures.json b/desktop/public/scenes/pixel-perfect.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/pixel-perfect.textures.json@@ -0,0 +1 @@+{}diff --git a/sdk/src/camera/CameraDirector.ts b/sdk/src/camera/CameraDirector.tsindex 623d3511e..9fe6ea1f3 100644--- a/sdk/src/camera/CameraDirector.ts+++ b/sdk/src/camera/CameraDirector.ts@@ -58,6 +58,7 @@ export function lerpPOV(a: CameraPOV, b: CameraPOV, t: number): CameraPOV {viewport: b.viewport,clearFlags: b.clearFlags,priority: b.priority,+ pixelPerfect: t < 0.5 ? a.pixelPerfect : b.pixelPerfect, // discrete: flip at the midpoint};}diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.tsindex 4bc410b1f..30b0f2cd6 100644--- a/sdk/src/camera/CameraPlugin.ts+++ b/sdk/src/camera/CameraPlugin.ts@@ -119,6 +119,17 @@ export interface CameraPOV {viewport: { x: number; y: number; z: number; w: number };clearFlags: number;priority: number;+ pixelPerfect: boolean;+}++/**+ * Snap a world coordinate to the camera's pixel grid (one cell = one rendered pixel,+ * in world units). Rounding the camera position to this grid is what makes pixel-perfect+ * rendering stable — static sprites land on the same texels every frame instead of+ * shimmering as the camera drifts by sub-pixel amounts. worldPerPixel <= 0 is a no-op.+ */+export function snapToPixelGrid(value: number, worldPerPixel: number): number {+ return worldPerPixel > 0 ? Math.round(value / worldPerPixel) * worldPerPixel : value;}function readCameraPOV(@@ -142,6 +153,7 @@ function readCameraPOV(viewport: { x: camera.viewport.x, y: camera.viewport.y, z: camera.viewport.z, w: camera.viewport.w },clearFlags: camera.clearFlags,priority: camera.priority,+ pixelPerfect: camera.pixelPerfect,};}@@ -180,7 +192,20 @@ export function buildCameraInfo(projection = perspective(pov.fov * Math.PI / 180, aspect, pov.near, pov.far);}- const view = invertViewZ(pov.x, pov.y, pov.z, Math.cos(pov.rotation), Math.sin(pov.rotation));+ // Pixel-perfect: snap the camera onto the world-space pixel grid before building+ // the view, so static pixel art doesn't shimmer. Orthographic only (a perspective+ // pixel grid is ill-defined); snapped in world space, which is exact for the common+ // unrotated 2D case. The snapped position also drives cameraX/Y so screen↔world stays+ // consistent with what's rendered.+ let camX = pov.x;+ let camY = pov.y;+ if (pov.pixelPerfect && pov.projection === ProjectionType.Orthographic) {+ const worldPerPixel = (2 * halfH) / Math.max(pov.viewport.w * height, 1);+ camX = snapToPixelGrid(pov.x, worldPerPixel);+ camY = snapToPixelGrid(pov.y, worldPerPixel);+ }++ const view = invertViewZ(camX, camY, pov.z, Math.cos(pov.rotation), Math.sin(pov.rotation));const cam = acquireCameraInfo(pool, index);cam.entity = pov.entity;cam.viewProjection.set(multiply(projection, view));@@ -192,8 +217,8 @@ export function buildCameraInfo(cam.priority = pov.priority;cam.halfW = halfW;cam.halfH = halfH;- cam.cameraX = pov.x;- cam.cameraY = pov.y;+ cam.cameraX = camX;+ cam.cameraY = camY;return cam;}@@ -283,6 +308,7 @@ export function editorCameraInfo(viewport: { x: 0, y: 0, z: 1, w: 1 },clearFlags: ClearFlags.ColorAndDepth,priority: 0,+ pixelPerfect: false, // editor navigation pans/zooms freely — no pixel snapping};return buildCameraInfo(pov, width, height, null, pool, 0);}diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.tsindex 71a49e333..30d5f8406 100644--- a/sdk/src/component.generated.ts+++ b/sdk/src/component.generated.ts@@ -15,7 +15,7 @@ import type { Dimension, Padding, VisualState } from './wasm.generated';* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to* run on mismatch, because mismatched offsets read the wrong heap bytes.*/-export const ABI_LAYOUT_HASH = '124c9c3f323b74f1';+export const ABI_LAYOUT_HASH = '70f3953079450020';export interface AssetFieldMeta {field: string;@@ -88,6 +88,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {priority: 0,viewport: { x: 0, y: 0, z: 1, w: 1 },clearFlags: 3,+ pixelPerfect: false,},assetFields: [],entityFields: [],@@ -102,6 +103,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {aspectRatio: { advanced: true },priority: { step: 1, advanced: true },clearFlags: { tooltip: "Which buffers to clear before rendering this camera." },+ pixelPerfect: { tooltip: "Snap the camera to the pixel grid for crisp pixel-art (Orthographic).", advanced: true },},},Canvas: {@@ -648,6 +650,7 @@ export interface CameraData {priority: number;viewport: Vec4;clearFlags: number;+ pixelPerfect: boolean;}export interface CanvasData {diff --git a/sdk/src/ecs/ptrAccessors.generated.ts b/sdk/src/ecs/ptrAccessors.generated.tsindex 57232bd4b..2806794f2 100644--- a/sdk/src/ecs/ptrAccessors.generated.ts+++ b/sdk/src/ecs/ptrAccessors.generated.ts@@ -124,6 +124,7 @@ export interface CameraPtrData {priority: number;viewport: Vec4;clearFlags: number;+ pixelPerfect: boolean;}export function fillCamera(@@ -140,6 +141,7 @@ export function fillCamera(out.priority = u32[(ptr + 28) >> 2] | 0;const viewport_ = out.viewport; viewport_.x = f32[(ptr + 32) >> 2]; viewport_.y = f32[((ptr + 32) >> 2) + 1]; viewport_.z = f32[((ptr + 32) >> 2) + 2]; viewport_.w = f32[((ptr + 32) >> 2) + 3];out.clearFlags = u8[ptr + 48];+ out.pixelPerfect = u8[ptr + 49] !== 0;}export function writeCamera(@@ -156,6 +158,7 @@ export function writeCamera(u32[(ptr + 28) >> 2] = data.priority | 0;f32[(ptr + 32) >> 2] = data.viewport.x; f32[((ptr + 32) >> 2) + 1] = data.viewport.y; f32[((ptr + 32) >> 2) + 2] = data.viewport.z; f32[((ptr + 32) >> 2) + 3] = data.viewport.w;u8[ptr + 48] = data.clearFlags;+ u8[ptr + 49] = data.pixelPerfect ? 1 : 0;}export function createCameraData(): CameraPtrData {@@ -170,6 +173,7 @@ export function createCameraData(): CameraPtrData {priority: 0,viewport: { x: 0, y: 0, z: 0, w: 0 },clearFlags: 0,+ pixelPerfect: false,};}diff --git a/sdk/src/preview/PreviewPlugin.ts b/sdk/src/preview/PreviewPlugin.tsindex 5ae2b1757..5b0f4f6c2 100644--- a/sdk/src/preview/PreviewPlugin.ts+++ b/sdk/src/preview/PreviewPlugin.ts@@ -146,6 +146,7 @@ export class PreviewPlugin implements Plugin {aspectRatio,priority: 0,showFrustum: false,+ pixelPerfect: false,viewport: { x: 0, y: 0, z: 1, w: 1 },clearFlags: ClearFlags.ColorAndDepth,};diff --git a/sdk/src/ptrLayouts.generated.ts b/sdk/src/ptrLayouts.generated.tsindex 513d3bbf4..a3f0c0d42 100644--- a/sdk/src/ptrLayouts.generated.ts+++ b/sdk/src/ptrLayouts.generated.ts@@ -57,6 +57,7 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {{ name: 'priority', type: 'i32', offset: 28 },{ name: 'viewport', type: 'vec4', offset: 32 },{ name: 'clearFlags', type: 'u8', offset: 48 },+ { name: 'pixelPerfect', type: 'bool', offset: 49 },],},Canvas: {diff --git a/sdk/src/wasm.generated.ts b/sdk/src/wasm.generated.tsindex be548c91b..16be29b51 100644--- a/sdk/src/wasm.generated.ts+++ b/sdk/src/wasm.generated.ts@@ -187,6 +187,7 @@ export interface Camera {priority: number;viewport: Vec4;clearFlags: number;+ pixelPerfect: boolean;}export interface Canvas {diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snapindex 4dd8261ab..87801b078 100644--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap@@ -60,6 +60,10 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho"min": 0,"tooltip": "Half the visible height in world units (Orthographic).",},+ "pixelPerfect": {+ "advanced": true,+ "tooltip": "Snap the camera to the pixel grid for crisp pixel-art (Orthographic).",+ },"priority": {"advanced": true,"step": 1,diff --git a/sdk/tests/camera-pov.test.ts b/sdk/tests/camera-pov.test.tsindex eb821fdcc..392dda29e 100644--- a/sdk/tests/camera-pov.test.ts+++ b/sdk/tests/camera-pov.test.ts@@ -6,7 +6,7 @@* is the decoupling point a camera director will blend over (Phase C).*/import { describe, it, expect } from 'vitest';-import { buildCameraInfo, type CameraPOV } from '../src/camera/CameraPlugin';+import { buildCameraInfo, snapToPixelGrid, type CameraPOV } from '../src/camera/CameraPlugin';import { ProjectionType, ClearFlags } from '../src/component';function ndc(vp: Float32Array, x: number, y: number) {@@ -28,6 +28,7 @@ const pov = (over: Partial<CameraPOV>): CameraPOV => ({viewport: { x: 0, y: 0, z: 1, w: 1 },clearFlags: ClearFlags.ColorAndDepth,priority: 0,+ pixelPerfect: false,...over,});@@ -48,6 +49,30 @@ describe('camera POV → view-projection', () => {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 }),diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cppindex 15a3e7c85..8d8d77678 100644--- a/src/esengine/bindings/EditorAPI.generated.cpp+++ b/src/esengine/bindings/EditorAPI.generated.cpp@@ -2,10 +2,10 @@* @file EditorAPI.generated.cpp* @brief Auto-generated editor API with string-dispatched component access* @details Generated by EHT - DO NOT EDIT- * @schema_hash 4cdc83e88b77776d+ * @schema_hash 4ebe63d3ff723023*/-#define ES_EDITOR_API_SCHEMA_HASH "4cdc83e88b77776d"+#define ES_EDITOR_API_SCHEMA_HASH "4ebe63d3ff723023"#include <emscripten/bind.h>#include <string>@@ -128,7 +128,8 @@ std::string editor_getComponentSchema(const std::string& name) {{"key":"viewport.y","type":"float","group":"Camera"},{"key":"viewport.z","type":"float","group":"Camera"},{"key":"viewport.w","type":"float","group":"Camera"},- {"key":"clearFlags","type":"enum","group":"Camera","values":["Nothing","Color","Depth","ColorAndDepth"]}+ {"key":"clearFlags","type":"enum","group":"Camera","values":["Nothing","Color","Depth","ColorAndDepth"]},+ {"key":"pixelPerfect","type":"bool","group":"Camera"}])JSON";} else if (name == "Canvas") {return R"JSON([@@ -1626,6 +1627,7 @@ bool editor_setBool(Registry& reg, u32 e, const std::string& comp, const std::stif (!reg.has<esengine::ecs::Camera>(entity)) return false;auto& c = reg.get<esengine::ecs::Camera>(entity);if (field == "isActive") { c.isActive = value; }+ else if (field == "pixelPerfect") { c.pixelPerfect = value; }else { return false; }return true;} else if (comp == "CapsuleCollider") {@@ -1759,6 +1761,7 @@ bool editor_getBool(Registry& reg, u32 e, const std::string& comp, const std::stif (!reg.has<esengine::ecs::Camera>(entity)) return false;const auto& c = reg.get<esengine::ecs::Camera>(entity);if (field == "isActive") { return c.isActive; }+ else if (field == "pixelPerfect") { return c.pixelPerfect; }} else if (comp == "CapsuleCollider") {if (!reg.has<esengine::ecs::CapsuleCollider>(entity)) return false;const auto& c = reg.get<esengine::ecs::CapsuleCollider>(entity);diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex 58928ec9a..37429306f 100644--- a/src/esengine/bindings/WebBindings.generated.cpp+++ b/src/esengine/bindings/WebBindings.generated.cpp@@ -256,6 +256,7 @@ struct CameraJS {i32 priority;glm::vec4 viewport;i32 clearFlags;+ bool pixelPerfect;};esengine::ecs::Camera cameraFromJS(const CameraJS& js) {@@ -270,6 +271,7 @@ esengine::ecs::Camera cameraFromJS(const CameraJS& js) {c.priority = js.priority;c.viewport = js.viewport;c.clearFlags = static_cast<ClearFlags>(js.clearFlags);+ c.pixelPerfect = js.pixelPerfect;return c;}@@ -285,6 +287,7 @@ CameraJS cameraToJS(const esengine::ecs::Camera& c) {js.priority = c.priority;js.viewport = c.viewport;js.clearFlags = static_cast<i32>(c.clearFlags);+ js.pixelPerfect = c.pixelPerfect;return js;}@@ -849,7 +852,8 @@ EMSCRIPTEN_BINDINGS(esengine_components) {.field("isActive", &CameraJS::isActive).field("priority", &CameraJS::priority).field("viewport", &CameraJS::viewport)- .field("clearFlags", &CameraJS::clearFlags);+ .field("clearFlags", &CameraJS::clearFlags)+ .field("pixelPerfect", &CameraJS::pixelPerfect);value_object<CanvasJS>("Canvas").field("designResolution", &CanvasJS::designResolution)@@ -1756,6 +1760,7 @@ static_assert(offsetof(esengine::ecs::Camera, isActive) == 24, "ABI offset driftstatic_assert(offsetof(esengine::ecs::Camera, priority) == 28, "ABI offset drift: esengine::ecs::Camera.priority (EHT expected 28)");static_assert(offsetof(esengine::ecs::Camera, viewport) == 32, "ABI offset drift: esengine::ecs::Camera.viewport (EHT expected 32)");static_assert(offsetof(esengine::ecs::Camera, clearFlags) == 48, "ABI offset drift: esengine::ecs::Camera.clearFlags (EHT expected 48)");+static_assert(offsetof(esengine::ecs::Camera, pixelPerfect) == 49, "ABI offset drift: esengine::ecs::Camera.pixelPerfect (EHT expected 49)");static_assert(offsetof(esengine::ecs::Canvas, designResolution) == 0, "ABI offset drift: esengine::ecs::Canvas.designResolution (EHT expected 0)");static_assert(offsetof(esengine::ecs::Canvas, pixelsPerUnit) == 8, "ABI offset drift: esengine::ecs::Canvas.pixelsPerUnit (EHT expected 8)");static_assert(offsetof(esengine::ecs::Canvas, scaleMode) == 12, "ABI offset drift: esengine::ecs::Canvas.scaleMode (EHT expected 12)");@@ -1933,7 +1938,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif// ABI Hash -- runtime handshake against the SDK bundle// =============================================================================-static const char* kEsAbiLayoutHash = "124c9c3f323b74f1";+static const char* kEsAbiLayoutHash = "70f3953079450020";std::string esengineGetAbiLayoutHash() {return std::string(kEsAbiLayoutHash);diff --git a/src/esengine/ecs/components/Camera.hpp b/src/esengine/ecs/components/Camera.hppindex 4a6bd3732..2f28f5ec0 100644--- a/src/esengine/ecs/components/Camera.hpp+++ b/src/esengine/ecs/components/Camera.hpp@@ -109,6 +109,11 @@ struct Camera {ES_PROPERTY(flags, tooltip="Which buffers to clear before rendering this camera.")ClearFlags clearFlags{ClearFlags::ColorAndDepth};+ /** @brief Snap the camera to the world-space pixel grid (Orthographic) so static+ * pixel art renders crisp, without sub-pixel shimmer when the camera moves. */+ ES_PROPERTY(advanced, tooltip="Snap the camera to the pixel grid for crisp pixel-art (Orthographic).")+ bool pixelPerfect{false};+Camera() = default;};