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.

fix(engine): correct the pixelsPerUnit doctrine at its source

esengine9f383a89db14
diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.ts
index bd965335b..656510add 100644
--- a/sdk/src/component.generated.ts
+++ b/sdk/src/component.generated.ts
@@ -149,7 +149,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
colorFields: ['backgroundColor'],
animatableFields: [],
fields: {
- pixelsPerUnit: { min: 1, tooltip: "Texture pixels mapped to one world unit." },
+ pixelsPerUnit: { min: 1, tooltip: "World pixels per physics meter (Box2D + tile collider scale)." },
scaleMode: { enum: [{ label: 'FixedWidth', value: 0 }, { label: 'FixedHeight', value: 1 }, { label: 'Expand', value: 2 }, { label: 'Shrink', value: 3 }, { label: 'Match', value: 4 }], tooltip: "How the canvas adapts the design resolution to the screen." },
matchWidthOrHeight: { min: 0, max: 1, slider: true, tooltip: "0 matches width, 1 matches height (Match mode only)." },
},
diff --git a/sdk/src/preview/PreviewPlugin.ts b/sdk/src/preview/PreviewPlugin.ts
index 7cd8c3137..bbb04c56e 100644
--- a/sdk/src/preview/PreviewPlugin.ts
+++ b/sdk/src/preview/PreviewPlugin.ts
@@ -9,7 +9,7 @@ import type { App, Plugin } from '../app';
import type { SceneData } from '../scene';
import { loadRuntimeScene } from '../runtimeLoader';
import { Transform, Camera, Canvas, ProjectionType, ClearFlags, type TransformData, type CameraData, type CanvasData } from '../component';
-import { DEFAULT_DESIGN_WIDTH, DEFAULT_DESIGN_HEIGHT, DEFAULT_PIXELS_PER_UNIT } from '../defaults';
+import { DEFAULT_DESIGN_WIDTH, DEFAULT_DESIGN_HEIGHT } from '../defaults';
import { platformFetch } from '../platform';
import { SceneManager } from '../sceneManager';
import { HttpBackend } from '../asset/Backend';
@@ -122,8 +122,10 @@ export class PreviewPlugin implements Plugin {
for (const entity of canvasEntities) {
const canvas = world.get(entity, Canvas) as CanvasData;
if (canvas.designResolution) {
- const ppu = canvas.pixelsPerUnit || DEFAULT_PIXELS_PER_UNIT;
- orthoSize = (canvas.designResolution.y / 2) / ppu;
+ // World units are design pixels (editor cameras author orthoSize
+ // = designResolution.y / 2); pixelsPerUnit is the physics meter
+ // scale and has no bearing on the camera fit.
+ orthoSize = canvas.designResolution.y / 2;
aspectRatio = canvas.designResolution.x / canvas.designResolution.y;
break;
}
diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
index d445e742d..488cccf3b 100644
--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
@@ -98,7 +98,7 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho
},
"pixelsPerUnit": {
"min": 1,
- "tooltip": "Texture pixels mapped to one world unit.",
+ "tooltip": "World pixels per physics meter (Box2D + tile collider scale).",
},
"scaleMode": {
"enum": [
diff --git a/src/esengine/ecs/components/Canvas.hpp b/src/esengine/ecs/components/Canvas.hpp
index ea3aebb82..64cab46d9 100644
--- a/src/esengine/ecs/components/Canvas.hpp
+++ b/src/esengine/ecs/components/Canvas.hpp
@@ -61,9 +61,11 @@ enum class CanvasScaleMode : u8 {
*
* Workflow:
* 1. Artist creates assets at design resolution (e.g., 1920x1080)
- * 2. A 100x200 pixel sprite becomes 1x2 world units (at PPU=100)
- * 3. Camera orthoSize is calculated from design resolution and PPU
- * 4. At runtime, scaling adjusts for actual screen resolution
+ * 2. World units are design pixels: a 100x200 texture spawns a 100x200 sprite,
+ * and the default scene camera shows designResolution.y world units of height
+ * (orthoSize = designResolution.y / 2)
+ * 3. pixelsPerUnit is the physics scale: world pixels per Box2D meter
+ * 4. At runtime, scaleMode fits the design resolution to the actual screen
*/
ES_COMPONENT()
struct Canvas {
@@ -71,8 +73,8 @@ struct Canvas {
ES_PROPERTY()
glm::uvec2 designResolution{1920, 1080};
- /** @brief Pixels per world unit (e.g., 100 means 100px = 1 unit) */
- ES_PROPERTY(min=1, tooltip="Texture pixels mapped to one world unit.")
+ /** @brief World pixels per physics meter (e.g., 100 means 100px = 1 Box2D meter) */
+ ES_PROPERTY(min=1, tooltip="World pixels per physics meter (Box2D + tile collider scale).")
f32 pixelsPerUnit{100.0f};
/** @brief Scaling mode for different screen resolutions */