Normalize shared world-to-screen scale between Asteroids runtime and Collision Inspector V2 - PR_26139_011-shared-world-scale-normalization

Author: DavidQ

docs/dev/reports/PR_26139_011-shared-world-scale-normalization_report.md

@@ -0,0 +1,51 @@
+# PR_26139_011-shared-world-scale-normalization
+
+## Scope
+- Added a shared canonical world/screen transform helper in `src/engine/rendering/WorldScreenTransform.js`.
+- Kept Asteroids runtime as the source of truth: object world coordinates map 1:1 to canvas pixels at `CANONICAL_WORLD_TO_SCREEN_SCALE = 1`.
+- Moved runtime object render translate/rotate/scale composition in `ObjectVectorRuntimeAssetService` through the shared helper while preserving prior instance scale semantics.
+- Updated Collision Inspector V2 to use the shared helper for viewport sizing, canvas CSS sizing, pointer-to-world conversion, and zoom transform composition.
+- Kept Collision Inspector zoom as additional user zoom only.
+- Kept Object Vector Studio V2 as an editor surface with editor viewport zoom only; added status text that explicitly separates editor zoom from runtime/world scale.
+- Preserved intentional asteroid instance scale tuning, ship flame flicker behavior, manifest geometry SSoT, and manifest-only object rendering.
+
+## Prior Reference
+- Read `docs/dev/PROJECT_INSTRUCTIONS.md`.
+- Used current PR_26139_010 implementation and `docs/dev/reports/PR_26139_010-collision-inspector-usability-polish_report.md` as the available prior reference.
+- Requested `docs/dev/reports/PR_26139_010-size-scale-differences_report.md` was not present in this workspace.
+
+## Scale Normalization Rule
+- Asteroids runtime: canonical world scale is `1 world unit = 1 canvas pixel`; per-object gameplay/art tuning remains `options.scale`.
+- Collision Inspector V2: uses the same canonical world-to-screen transform and manifest screen dimensions; `collisionZoomInput` applies user zoom after canonical world scaling.
+- Object Vector Studio V2: uses editor-only viewport/grid zoom for authoring; it does not apply runtime/world scale to the editor work surface.
+
+## Validation
+- PASS: `node --check src/engine/rendering/WorldScreenTransform.js`
+- PASS: `node --check src/engine/rendering/ObjectVectorRuntimeAssetService.js`
+- PASS: `node --check tools/collision-inspector-v2/js/CollisionInspectorV2App.js`
+- PASS: `node --check tools/collision-inspector-v2/js/CollisionInspectorV2Controls.js`
+- PASS: `node --check tools/collision-inspector-v2/js/CollisionInspectorV2Renderer.js`
+- PASS: `node --check tools/object-vector-studio-v2/js/ToolStarterApp.js`
+- PASS: `node --check tests/playwright/tools/CollisionInspectorV2.spec.mjs`
+- PASS: `npx playwright test tests/playwright/tools/CollisionInspectorV2.spec.mjs --project=playwright --workers=1 --reporter=list`
+  - `4 passed`
+  - Validates Asteroids runtime canvas scale and Collision Inspector canvas scale.
+  - Validates same manifest ship physical size between Asteroids runtime object rendering and Collision Inspector at zoom `1.0`, allowing stroke/antialias bounds tolerance.
+  - Validates Collision Inspector zoom remains additional user zoom up to `5x`.
+  - Validates Object Vector Studio V2 editor zoom changes without changing shared runtime scale.
+  - Validates Workspace Manager V2 launch path still loads Asteroids objects.
+- PASS: `npm run build:manifest`
+  - This repo does not define a plain `npm run build`; `build:manifest` is the available build script.
+  - Removed generated `docs/build` output after validation.
+- PASS: `git diff --check`
+  - Only existing line-ending conversion warnings were reported.
+- PASS: Playwright V8 coverage report generated at `docs/dev/reports/playwright_v8_coverage_report.txt`.
+
+## Full Samples Smoke Test
+- Skipped. This PR is limited to shared scale transform wiring plus targeted Collision Inspector/Object Vector Studio validation.
+
+## Manual Test Notes
+- Open `tools/collision-inspector-v2/index.html?manifestPath=/games/Asteroids/game.manifest.json`.
+- Verify the ship appears the same physical size as Asteroids runtime at Collision Inspector zoom `1.0`.
+- Increase Collision Inspector zoom to `5x`; expected result is zoomed inspection only, with unchanged collision/world coordinates.
+- Open Object Vector Studio V2 and use its zoom controls; expected result is editor viewport zoom only, not runtime/world scale changes.

src/engine/rendering/ObjectVectorRuntimeAssetService.js

@@ -1,3 +1,5 @@
+import { createWorldScreenTransform } from "./WorldScreenTransform.js";
+
 const DEFAULT_SCHEMA_URL = new URL("../../../tools/schemas/tools/object-vector-studio-v2.schema.json", import.meta.url);
 const OBJECT_VECTOR_TOOL_ID = "object-vector-studio-v2";
 
@@ -865,11 +867,13 @@ export class ObjectVectorRuntimeAssetService {
 
   drawObjectToCanvas(context, object, frame, options = {}) {
     try {
+      const renderTransform = createWorldScreenTransform({
+        worldScale: options.worldScale
+      }).objectRenderOptions(options);
       context.save();
-      context.translate(options.x || 0, options.y || 0);
-      context.rotate(options.rotation || 0);
-      const scale = Number.isFinite(options.scale) ? options.scale : 1;
-      context.scale(scale, scale);
+      context.translate(renderTransform.x, renderTransform.y);
+      context.rotate(renderTransform.rotation);
+      context.scale(renderTransform.scale, renderTransform.scale);
       let renderedShapes = 0;
       const transformOrigin = objectTransformOrigin(object);
       sortedShapes(object).forEach((shape, shapeIndex) => {

src/engine/rendering/WorldScreenTransform.js

@@ -0,0 +1,79 @@
+export const CANONICAL_WORLD_TO_SCREEN_SCALE = 1;
+
+function finiteNumber(value, fallback = 0) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}
+
+function positiveInteger(value, fallback = 1) {
+  const number = Math.floor(Number(value));
+  return Number.isFinite(number) && number > 0 ? number : fallback;
+}
+
+function positiveScale(value, fallback = 1) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : fallback;
+}
+
+export function createWorldScreenTransform({
+  screenHeight = 1,
+  screenWidth = 1,
+  userZoom = 1,
+  worldScale = CANONICAL_WORLD_TO_SCREEN_SCALE
+} = {}) {
+  const resolvedScreenHeight = positiveInteger(screenHeight);
+  const resolvedScreenWidth = positiveInteger(screenWidth);
+  const resolvedUserZoom = positiveScale(userZoom);
+  const resolvedWorldScale = positiveScale(worldScale, CANONICAL_WORLD_TO_SCREEN_SCALE);
+  const center = Object.freeze({
+    x: resolvedScreenWidth / 2,
+    y: resolvedScreenHeight / 2
+  });
+
+  return Object.freeze({
+    center,
+    cssAspectRatio: `${resolvedScreenWidth} / ${resolvedScreenHeight}`,
+    cssHeight: resolvedScreenHeight * resolvedWorldScale,
+    cssWidth: resolvedScreenWidth * resolvedWorldScale,
+    screenHeight: resolvedScreenHeight,
+    screenWidth: resolvedScreenWidth,
+    userZoom: resolvedUserZoom,
+    worldScale: resolvedWorldScale,
+    applyUserZoom(context) {
+      if (resolvedUserZoom === 1) {
+        return;
+      }
+      context.translate(center.x, center.y);
+      context.scale(resolvedUserZoom, resolvedUserZoom);
+      context.translate(-center.x, -center.y);
+    },
+    applyWorldToScreen(context) {
+      if (resolvedWorldScale === 1) {
+        return;
+      }
+      context.scale(resolvedWorldScale, resolvedWorldScale);
+    },
+    clientPointToScreenPoint(event, rect) {
+      const rectWidth = positiveScale(rect?.width);
+      const rectHeight = positiveScale(rect?.height);
+      return {
+        x: ((finiteNumber(event?.clientX) - finiteNumber(rect?.left)) / rectWidth) * resolvedScreenWidth,
+        y: ((finiteNumber(event?.clientY) - finiteNumber(rect?.top)) / rectHeight) * resolvedScreenHeight
+      };
+    },
+    objectRenderOptions(options = {}) {
+      return {
+        rotation: options.rotation || 0,
+        scale: (Number.isFinite(options.scale) ? options.scale : 1) * resolvedWorldScale,
+        x: (options.x || 0) * resolvedWorldScale,
+        y: (options.y || 0) * resolvedWorldScale
+      };
+    },
+    screenPointToWorldWithUserZoom(point) {
+      return {
+        x: ((finiteNumber(point?.x) - center.x) / resolvedUserZoom + center.x) / resolvedWorldScale,
+        y: ((finiteNumber(point?.y) - center.y) / resolvedUserZoom + center.y) / resolvedWorldScale
+      };
+    }
+  });
+}

src/engine/rendering/index.js

@@ -10,3 +10,4 @@ export { default as ResolutionScaler } from './ResolutionScaler.js';
 export { renderSpriteReadyEntities } from './SpriteRenderSystem.js';
 export { renderByLayers } from './LayeredRenderSystem.js';
 export { transformPoints, drawVectorShape } from './VectorDrawing.js';
+export { CANONICAL_WORLD_TO_SCREEN_SCALE, createWorldScreenTransform } from './WorldScreenTransform.js';

tests/playwright/tools/CollisionInspectorV2.spec.mjs

@@ -47,6 +47,67 @@ async function canvasSignature(page) {
   });
 }
 
+async function runtimeObjectPixelBounds(page, objectId, instance) {
+  return page.evaluate(async ({ instance, objectId }) => {
+    const { ObjectVectorRuntimeAssetService } = await import("/src/engine/rendering/index.js");
+    const runtime = new ObjectVectorRuntimeAssetService({
+      logger: {
+        error() {},
+        info() {},
+        warn() {}
+      }
+    });
+    const assetSet = await runtime.loadFromManifest("/games/Asteroids/game.manifest.json", {
+      sourceLabel: "scale validation"
+    });
+    if (!assetSet) {
+      throw new Error("Asteroids object-vector manifest failed to load for scale validation.");
+    }
+
+    const canvas = document.createElement("canvas");
+    canvas.width = 960;
+    canvas.height = 720;
+    const context = canvas.getContext("2d");
+    const result = runtime.renderObject({ ctx: context }, assetSet, {
+      elapsedMs: 0,
+      objectId,
+      rotation: instance.rotation,
+      scale: instance.scale,
+      x: instance.x,
+      y: instance.y
+    });
+    if (!result.ok) {
+      throw new Error(`Runtime object render failed for ${objectId}.`);
+    }
+
+    const data = context.getImageData(0, 0, canvas.width, canvas.height).data;
+    let maxX = -1;
+    let maxY = -1;
+    let minX = canvas.width;
+    let minY = canvas.height;
+    for (let y = 0; y < canvas.height; y += 1) {
+      for (let x = 0; x < canvas.width; x += 1) {
+        if (data[(y * canvas.width + x) * 4 + 3] <= 0) {
+          continue;
+        }
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+      }
+    }
+    if (maxX < minX || maxY < minY) {
+      throw new Error(`Runtime object render produced no visible pixels for ${objectId}.`);
+    }
+    return {
+      height: maxY - minY + 1,
+      width: maxX - minX + 1,
+      x: minX,
+      y: minY
+    };
+  }, { instance, objectId });
+}
+
 test.describe("Collision Inspector V2", () => {
   test("loads a game manifest and reports live vector, pixel, bounds, and hybrid collisions", async ({ page }) => {
     const server = await startRepoServer();
@@ -116,10 +177,19 @@ test.describe("Collision Inspector V2", () => {
       expect(collisionInspectorScale.scaleX).toBeCloseTo(1, 2);
       expect(collisionInspectorScale.scaleY).toBeCloseTo(1, 2);
       const runtimeRenderSource = await readFile(join(server.repoRoot, "src", "engine", "rendering", "ObjectVectorRuntimeAssetService.js"), "utf8");
+      const worldScreenSource = await readFile(join(server.repoRoot, "src", "engine", "rendering", "WorldScreenTransform.js"), "utf8");
+      const collisionControlsSource = await readFile(join(server.repoRoot, "tools", "collision-inspector-v2", "js", "CollisionInspectorV2Controls.js"), "utf8");
+      const collisionRendererSource = await readFile(join(server.repoRoot, "tools", "collision-inspector-v2", "js", "CollisionInspectorV2Renderer.js"), "utf8");
       const objectVectorStudioSource = await readFile(join(server.repoRoot, "tools", "object-vector-studio-v2", "js", "ToolStarterApp.js"), "utf8");
-      expect(runtimeRenderSource).toContain("const scale = Number.isFinite(options.scale) ? options.scale : 1;");
-      expect(runtimeRenderSource).toContain("context.scale(scale, scale);");
+      expect(worldScreenSource).toContain("export const CANONICAL_WORLD_TO_SCREEN_SCALE = 1;");
+      expect(worldScreenSource).toContain("objectRenderOptions(options = {})");
+      expect(runtimeRenderSource).toContain("createWorldScreenTransform");
+      expect(runtimeRenderSource).toContain(".objectRenderOptions(options)");
+      expect(collisionControlsSource).toContain("createWorldScreenTransform");
+      expect(collisionRendererSource).toContain("createWorldScreenTransform");
+      expect(collisionRendererSource).toContain("screenPointToWorldWithUserZoom");
       expect(objectVectorStudioSource).toContain("const OBJECT_PREVIEW_DRAWING_SCALE = GRID_STEP;");
+      expect(objectVectorStudioSource).toContain("CANONICAL_WORLD_TO_SCREEN_SCALE");
       expect(objectVectorStudioSource).toContain("point.x / OBJECT_PREVIEW_DRAWING_SCALE");
       const asteroidsPage = await page.context().newPage();
       try {
@@ -147,6 +217,15 @@ test.describe("Collision Inspector V2", () => {
       await expect(page.locator("#overlapState")).toHaveText("false");
       await expect(page.locator("#originState")).toHaveText("Origins:\nA 360.000,320.000\nB 500.000,320.000");
       await expect(page.locator("#rotationState")).toHaveText("A 0 / B 0");
+      const scaleMatchSummary = await readCollisionSummary(page);
+      const runtimeShipBounds = await runtimeObjectPixelBounds(page, "object.asteroids.ship", {
+        rotation: 0,
+        scale: 1,
+        x: 360,
+        y: 320
+      });
+      expect(Math.abs(runtimeShipBounds.width - scaleMatchSummary.bounds.objectA.width)).toBeLessThanOrEqual(10);
+      expect(Math.abs(runtimeShipBounds.height - scaleMatchSummary.bounds.objectA.height)).toBeLessThanOrEqual(10);
       await expect(page.locator("#collisionSummary")).toContainText('"enginePath": "src/engine/collision/objectVector.js"');
       await expect(page.locator("#collisionSummary")).toContainText('"objectOrigins"');
       await expect(page.locator("#collisionSummary")).toContainText('"recommendedMode": "vector"');
@@ -324,6 +403,39 @@ test.describe("Collision Inspector V2", () => {
     }
   });
 
+  test("keeps Object Vector Studio V2 zoom editor-only against shared world scale", async ({ page }) => {
+    const server = await startRepoServer();
+    const pageErrors = [];
+    page.on("pageerror", (error) => {
+      pageErrors.push(error.message);
+    });
+
+    await coverageReporter.start(page);
+    try {
+      await page.goto(`${server.baseUrl}/tools/object-vector-studio-v2/index.html`, { waitUntil: "networkidle" });
+      await expect(page.locator("#statusLog")).toHaveValue(/Object Vector Studio V2 editor zoom is viewport-only; runtime\/world scale remains 1:1/);
+      const initialZoom = await page.evaluate(() => window.__objectVectorStudioV2App.viewport.zoom);
+      const sharedScale = await page.evaluate(async () => {
+        const { CANONICAL_WORLD_TO_SCREEN_SCALE } = await import("/src/engine/rendering/index.js");
+        return CANONICAL_WORLD_TO_SCREEN_SCALE;
+      });
+      expect(sharedScale).toBe(1);
+      await page.locator("#objectVectorStudioV2ZoomInButton").click();
+      const editorZoom = await page.evaluate(() => window.__objectVectorStudioV2App.viewport.zoom);
+      expect(editorZoom).toBeGreaterThan(initialZoom);
+      const sharedScaleAfterZoom = await page.evaluate(async () => {
+        const { CANONICAL_WORLD_TO_SCREEN_SCALE } = await import("/src/engine/rendering/index.js");
+        return CANONICAL_WORLD_TO_SCREEN_SCALE;
+      });
+      expect(sharedScaleAfterZoom).toBe(1);
+      await expect(page.locator("#statusLog")).toHaveValue(/Viewport zoom set/);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await coverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("loads Asteroids Object Vector objects from a Workspace Manager V2 manifest context", async ({ page }) => {
     const server = await startRepoServer();
     const pageErrors = [];

tools/collision-inspector-v2/js/CollisionInspectorV2App.js

@@ -4,6 +4,7 @@ import {
   OBJECT_VECTOR_COLLISION_MODE_LABELS,
   recommendObjectVectorCollisionMode
 } from "../../../src/engine/collision/index.js";
+import { CANONICAL_WORLD_TO_SCREEN_SCALE } from "../../../src/engine/rendering/index.js";
 import { resolveManifestScreenDimensions } from "../../../src/tools/common/GameManifestLoader.js";
 import {
   clone,
@@ -60,6 +61,7 @@ export class CollisionInspectorV2App {
     this.controls.setLaunchMode(this.isWorkspaceLaunch());
     this.controls.setZoom(this.zoom);
     this.logger.write("INFO Collision Inspector V2 ready.");
+    this.logger.write(`INFO Shared world-to-screen scale is ${CANONICAL_WORLD_TO_SCREEN_SCALE}:1; Collision Inspector zoom is additional user zoom only.`);
     await this.loadInitialManifest();
     if (this.hasRenderableManifest()) {
       this.evaluateAndRender();

tools/collision-inspector-v2/js/CollisionInspectorV2Controls.js

@@ -1,3 +1,4 @@
+import { createWorldScreenTransform } from "../../../src/engine/rendering/index.js";
 import {
   labelForObject,
   numberValue,
@@ -131,11 +132,15 @@ export class CollisionInspectorV2Controls {
   }
 
   setViewportSize(width, height) {
-    this.elements.canvas.setAttribute("width", String(Math.max(1, Math.floor(numberValue(width, 1)))));
-    this.elements.canvas.setAttribute("height", String(Math.max(1, Math.floor(numberValue(height, 1)))));
-    this.elements.canvas.style.setProperty("--collision-inspector-aspect-ratio", `${this.elements.canvas.width} / ${this.elements.canvas.height}`);
-    this.elements.canvas.style.setProperty("--collision-inspector-screen-width", `${this.elements.canvas.width}px`);
-    this.elements.canvas.style.setProperty("--collision-inspector-screen-height", `${this.elements.canvas.height}px`);
+    const transform = createWorldScreenTransform({
+      screenHeight: height,
+      screenWidth: width
+    });
+    this.elements.canvas.setAttribute("width", String(transform.screenWidth));
+    this.elements.canvas.setAttribute("height", String(transform.screenHeight));
+    this.elements.canvas.style.setProperty("--collision-inspector-aspect-ratio", transform.cssAspectRatio);
+    this.elements.canvas.style.setProperty("--collision-inspector-screen-width", `${transform.cssWidth}px`);
+    this.elements.canvas.style.setProperty("--collision-inspector-screen-height", `${transform.cssHeight}px`);
   }
 
   syncResult(result) {