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
fix(engine): correct the pixelsPerUnit doctrine at its source
esengine9f383a89db14
diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.tsindex 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.tsindex 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.snapindex 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.hppindex 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 */