Skip to content

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.

feat(camera): pixel-perfect camera snapping (Orthographic)

yhh5942e0b75e26
diff --git a/desktop/public/scenes/pixel-perfect.esscene b/desktop/public/scenes/pixel-perfect.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.snap
index 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.ts
index 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.cpp
index 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::st
if (!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::st
if (!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.cpp
index 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 drift
static_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.hpp
index 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;
};