Normalize shared orientation transforms between Asteroids runtime and Collision Inspector V2 - PR_26139_012-collision-orientation-runtime-alignment

Author: DavidQ

docs/dev/reports/PR_26139_012-collision-orientation-runtime-alignment_report.md

@@ -0,0 +1,55 @@
+# PR_26139_012-collision-orientation-runtime-alignment
+
+## Scope
+- Added `src/engine/rendering/OrientationTransform.js` beside the shared world/screen scale helper.
+- Routed Object Vector runtime shape transforms, SVG transform output, shared collision geometry, Collision Inspector V2 heading guides, and Object Vector Studio V2 preview point transforms through the shared orientation helper.
+- Kept Asteroids runtime heading as radians and made Asteroids object render calls explicit with `rotationUnit: 'radians'`.
+- Kept Collision Inspector V2 rotate controls in degrees and made inspector instances explicit with `rotationUnit: "degrees"`.
+- Preserved manifest geometry as the SSoT, intentional asteroid scale tuning, and ship flame flicker behavior.
+
+## Orientation Contract
+- Runtime object instance rotation uses radians unless a caller explicitly provides `rotationUnit`.
+- Manifest shape transforms remain degrees.
+- Collision Inspector V2 UI rotation remains degrees, then converts through the shared helper before collision/heading rendering.
+- Object Vector Studio V2 remains an editor surface; its preview shape transforms call the same helper for SVG transforms, point transforms, inverse point transforms, origin normalization, and rotation normalization.
+- Object instance `x/y` remains the Asteroids runtime source-of-truth world position for the object's local coordinate origin. Manifest `objectOrigin` is transformed through the same runtime orientation path for diagnostics and inspector origin markers.
+
+## Validation
+- PASS: `node --check src/engine/rendering/OrientationTransform.js`
+- PASS: `node --check src/engine/rendering/WorldScreenTransform.js`
+- PASS: `node --check src/engine/rendering/ObjectVectorRuntimeAssetService.js`
+- PASS: `node --check src/engine/collision/objectVector.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 games/Asteroids/game/AsteroidsGameScene.js`
+- PASS: `node --check games/Asteroids/game/AsteroidsAttractAdapter.js`
+- PASS: `node --check games/Asteroids/entities/Ufo.js`
+- PASS: `node --check tests/games/AsteroidsPresentation.test.mjs`
+- PASS: `node --check tests/playwright/tools/CollisionInspectorV2.spec.mjs`
+- PASS: `node --input-type=module -e "import('./tests/games/AsteroidsPresentation.test.mjs').then((module) => module.run())"`
+  - Validates Asteroids gameplay, attract, UFO, ship, asteroid, and bullet render calls use manifest object IDs and the runtime radians convention.
+- PASS: `node --input-type=module -e "import('./tests/final/PrecisionCollisionSystems.test.mjs').then((module) => module.run())"`
+  - Validates shared collision transform behavior still matches existing radians expectations.
+- PASS: `npx playwright test tests/playwright/tools/CollisionInspectorV2.spec.mjs --project=playwright --workers=1 --reporter=list`
+  - `4 passed`
+  - Validates Collision Inspector V2 layout and shared collision path.
+  - Validates runtime render bounds and shared collision bounds align for ship, asteroid, UFO, and bullet orientation samples.
+  - Validates bullet transformed points differ at `0`, `90`, `180`, and `270` degree headings while resolving through the same runtime/collision helper.
+  - Validates inspector heading guides use explicit rotation units.
+  - Validates Object Vector Studio V2 preview transforms match the shared orientation helper.
+- PASS: `npm run build:manifest`
+  - Available repo build script wrote `docs/build/sample-manifest.json`; generated output was removed 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 orientation/runtime alignment and targeted Collision Inspector V2, Object Vector Studio V2, and Asteroids orientation validation.
+
+## Manual Test Notes
+- Open `tools/collision-inspector-v2/index.html?manifestPath=/games/Asteroids/game.manifest.json`.
+- Select ship, bullet, asteroid, and UFO objects and rotate A/B; expected result is heading guides, origins, transformed points, and collision results updating consistently.
+- Launch `games/Asteroids/index.html`, fire bullets at several ship headings, and verify bullet render direction and collision behavior track the ship heading.
+- Open Object Vector Studio V2 and rotate/edit object geometry; expected result is unchanged editor zoom behavior with preview transforms matching runtime/collision orientation math.

games/Asteroids/entities/Ufo.js

@@ -111,6 +111,8 @@ export default class Ufo {
 
   getCollisionPolygon() {
     return transformCollisionPoints(this.collisionPoints, {
+      rotation: 0,
+      rotationUnit: 'radians',
       x: this.x,
       y: this.y,
     });

games/Asteroids/game/AsteroidsAttractAdapter.js

@@ -99,6 +99,7 @@ export default class AsteroidsAttractAdapter {
       fps: 12,
       objectId,
       requireManifestBinding: true,
+      rotationUnit: 'radians',
       stateId: 'active',
       ...options,
     });
@@ -141,6 +142,7 @@ export default class AsteroidsAttractAdapter {
       objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.ship,
       requireManifestBinding: true,
       rotation: -0.28,
+      rotationUnit: 'radians',
       scale: 1.1,
       stateId: 'idle',
       x: 328,
@@ -234,6 +236,7 @@ export default class AsteroidsAttractAdapter {
       objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.ship,
       requireManifestBinding: true,
       rotation: Math.sin(this.demoTime * 0.9) * 1.2,
+      rotationUnit: 'radians',
       stateId: 'idle',
       x,
       y,
@@ -259,6 +262,8 @@ export default class AsteroidsAttractAdapter {
       fps: 12,
       objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.ufoLarge,
       requireManifestBinding: true,
+      rotation: 0,
+      rotationUnit: 'radians',
       stateId: 'active',
       x: 480 + Math.cos(this.demoTime * 0.43) * 280,
       y: 284,

games/Asteroids/game/AsteroidsGameScene.js

@@ -760,6 +760,7 @@ export default class AsteroidsGameScene extends Scene {
         objectId,
         requireManifestBinding: true,
         rotation: asteroid.angle,
+        rotationUnit: 'radians',
         stateId: "active",
         x: asteroid.x,
         y: asteroid.y,
@@ -773,6 +774,8 @@ export default class AsteroidsGameScene extends Scene {
         fps: 12,
         objectId,
         requireManifestBinding: true,
+        rotation: 0,
+        rotationUnit: 'radians',
         stateId: "active",
         x: this.world.ufo.x,
         y: this.world.ufo.y,
@@ -784,6 +787,7 @@ export default class AsteroidsGameScene extends Scene {
         objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.bullet,
         requireManifestBinding: true,
         rotation: bullet.angle,
+        rotationUnit: 'radians',
         stateId: "active",
         x: bullet.x,
         y: bullet.y,
@@ -795,6 +799,7 @@ export default class AsteroidsGameScene extends Scene {
         objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.bullet,
         requireManifestBinding: true,
         rotation: bullet.angle,
+        rotationUnit: 'radians',
         stateId: "active",
         x: bullet.x,
         y: bullet.y,
@@ -810,6 +815,7 @@ export default class AsteroidsGameScene extends Scene {
         objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.ship,
         requireManifestBinding: true,
         rotation: this.world.ship.angle,
+        rotationUnit: 'radians',
         stateId: this.world.ship.thrusting && this.session.mode === 'playing' ? "move" : "idle",
         x: this.world.ship.x,
         y: this.world.ship.y,
@@ -896,6 +902,7 @@ export default class AsteroidsGameScene extends Scene {
         objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.ship,
         requireManifestBinding: true,
         rotation: -Math.PI / 2,
+        rotationUnit: 'radians',
         scale: 1.05,
         stateId: "idle",
         x: startX + index * LIFE_SPACING,

src/engine/collision/objectVector.js

@@ -7,6 +7,13 @@ objectVector.js
 import { isColliding } from './aabb.js';
 import { arePolygonsColliding, getPolygonBounds, isPointInPolygon } from './polygon.js';
 import { areMasksColliding, createRasterMask } from './raster.js';
+import {
+  normalizeObjectVectorOrigin,
+  normalizeObjectVectorTransform,
+  transformObjectVectorInstancePoint,
+  transformObjectVectorShapePoint,
+  transformRuntimeOrientedPoints,
+} from '../rendering/OrientationTransform.js';
 
 export const OBJECT_VECTOR_COLLISION_ENGINE_PATH = 'src/engine/collision/objectVector.js';
 export const OBJECT_VECTOR_COLLISION_MODES = Object.freeze(['bounds', 'vector', 'pixel-sprite', 'hybrid']);
@@ -80,21 +87,11 @@ function firstObjectFrame(object, preferredStateIds = ['active', 'idle']) {
 }
 
 function shapeTransform(shape) {
-  const transform = isRecord(shape?.transform) ? shape.transform : {};
-  return {
-    rotation: numberValue(transform.rotation),
-    scaleX: numberValue(transform.scaleX, 1),
-    scaleY: numberValue(transform.scaleY, 1),
-    x: numberValue(transform.x),
-    y: numberValue(transform.y),
-  };
+  return normalizeObjectVectorTransform(shape?.transform);
 }
 
 export function getObjectVectorOrigin(object) {
-  return {
-    x: numberValue(object?.objectOrigin?.x),
-    y: numberValue(object?.objectOrigin?.y),
-  };
+  return normalizeObjectVectorOrigin(object?.objectOrigin);
 }
 
 function effectiveShapeForFrame(shape, frame, shapeIndex) {
@@ -193,31 +190,8 @@ function shapeLocalPolygons(shape) {
   return [];
 }
 
-function transformShapePoint(point, transform, origin) {
-  const radians = (transform.rotation * Math.PI) / 180;
-  const scaledX = (point.x - origin.x) * transform.scaleX;
-  const scaledY = (point.y - origin.y) * transform.scaleY;
-  const rotatedX = scaledX * Math.cos(radians) - scaledY * Math.sin(radians);
-  const rotatedY = scaledX * Math.sin(radians) + scaledY * Math.cos(radians);
-  return {
-    x: rotatedX + origin.x + transform.x,
-    y: rotatedY + origin.y + transform.y,
-  };
-}
-
-function rotationRadians(value, unit = 'degrees') {
-  const rotation = numberValue(value);
-  return unit === 'radians' ? rotation : (rotation * Math.PI) / 180;
-}
-
-function transformInstancePoint(point, origin, instance) {
-  const radians = rotationRadians(instance?.rotation, instance?.rotationUnit || 'degrees');
-  const dx = point.x - origin.x;
-  const dy = point.y - origin.y;
-  return {
-    x: (dx * Math.cos(radians) - dy * Math.sin(radians)) + origin.x + numberValue(instance?.x),
-    y: (dx * Math.sin(radians) + dy * Math.cos(radians)) + origin.y + numberValue(instance?.y),
-  };
+function transformInstancePoint(point, instance) {
+  return transformObjectVectorInstancePoint(point, instance, { rotationUnit: 'degrees' });
 }
 
 export function transformCollisionPoints(points, {
@@ -229,13 +203,15 @@ export function transformCollisionPoints(points, {
   scaleX = scale,
   scaleY = scale,
 } = {}) {
-  const radians = rotationRadians(rotation, rotationUnit);
-  const safeScaleX = numberValue(scaleX, 1);
-  const safeScaleY = numberValue(scaleY, 1);
-  return normalizePoints(points).map((point) => ({
-    x: numberValue(x) + ((point.x * safeScaleX) * Math.cos(radians)) - ((point.y * safeScaleY) * Math.sin(radians)),
-    y: numberValue(y) + ((point.x * safeScaleX) * Math.sin(radians)) + ((point.y * safeScaleY) * Math.cos(radians)),
-  }));
+  return transformRuntimeOrientedPoints(normalizePoints(points), {
+    rotation,
+    rotationUnit,
+    scale,
+    scaleX,
+    scaleY,
+    x,
+    y,
+  });
 }
 
 function boundsFromPoints(points) {
@@ -301,7 +277,7 @@ export function getObjectVectorCollisionOutlinePoints(object, options = {}) {
     return tool === 'polygon' || tool === 'polyline';
   }) || visibleEffectiveShapes(object, options).find((candidate) => shapeTool(candidate) === 'line');
   const transform = shapeTransform(shape);
-  return shapeLocalOutlinePoints(shape).map((point) => transformShapePoint(point, transform, origin));
+  return shapeLocalOutlinePoints(shape).map((point) => transformObjectVectorShapePoint(point, transform, origin));
 }
 
 export function createObjectVectorCollisionGeometry(object, instance = {}, options = {}) {
@@ -310,7 +286,7 @@ export function createObjectVectorCollisionGeometry(object, instance = {}, optio
     .flatMap((shape) => {
       const transform = shapeTransform(shape);
       return shapeLocalPolygons(shape)
-        .map((polygon) => polygon.map((point) => transformInstancePoint(transformShapePoint(point, transform, origin), origin, instance)))
+        .map((polygon) => polygon.map((point) => transformInstancePoint(transformObjectVectorShapePoint(point, transform, origin), instance)))
         .filter((polygon) => polygon.length >= 3);
     });
   const bounds = boundsFromPolygons(polygons);
@@ -322,7 +298,7 @@ export function createObjectVectorCollisionGeometry(object, instance = {}, optio
     mask: maskFromPolygons(polygons, bounds, maskCellSize),
     object,
     origin,
-    originWorld: object ? transformInstancePoint(origin, origin, instance) : { x: 0, y: 0 },
+    originWorld: object ? transformInstancePoint(origin, instance) : { x: 0, y: 0 },
     polygons,
     shapeRotations: [...new Set(visibleEffectiveShapes(object, options).map((shape) => shapeTransform(shape).rotation))],
     transformedPoints: polygons.flat(),

src/engine/rendering/ObjectVectorRuntimeAssetService.js

@@ -1,3 +1,9 @@
+import {
+  applyObjectVectorCanvasTransform,
+  normalizeObjectVectorOrigin,
+  normalizeObjectVectorTransform,
+  objectVectorSvgTransformAttribute
+} from "./OrientationTransform.js";
 import { createWorldScreenTransform } from "./WorldScreenTransform.js";
 
 const DEFAULT_SCHEMA_URL = new URL("../../../tools/schemas/tools/object-vector-studio-v2.schema.json", import.meta.url);
@@ -119,30 +125,11 @@ function shapeGeometryTool(shape) {
 }
 
 function shapeTransform(shape) {
-  const transform = shape.transform || {
-    rotation: 0,
-    scaleX: 1,
-    scaleY: 1,
-    x: 0,
-    y: 0
-  };
-  return {
-    rotation: Number(transform.rotation ?? 0),
-    scaleX: Number(transform.scaleX ?? 1),
-    scaleY: Number(transform.scaleY ?? 1),
-    x: Number(transform.x ?? 0),
-    y: Number(transform.y ?? 0)
-  };
+  return normalizeObjectVectorTransform(shape?.transform);
 }
 
 function objectTransformOrigin(object) {
-  if (isPlainObject(object?.objectOrigin) && Number.isFinite(Number(object.objectOrigin.x)) && Number.isFinite(Number(object.objectOrigin.y))) {
-    return {
-      x: Number(object.objectOrigin.x),
-      y: Number(object.objectOrigin.y)
-    };
-  }
-  return { x: 0, y: 0 };
+  return normalizeObjectVectorOrigin(object?.objectOrigin);
 }
 
 function pointStyleValue(value) {
@@ -423,16 +410,6 @@ function effectiveShapeForFrame(shape, frame, shapeIndex) {
   return effective;
 }
 
-function svgTransformAttribute(transform, origin = { x: 0, y: 0 }) {
-  return [
-    `translate(${transform.x} ${transform.y})`,
-    `translate(${origin.x} ${origin.y})`,
-    `rotate(${transform.rotation})`,
-    `scale(${transform.scaleX} ${transform.scaleY})`,
-    `translate(${-origin.x} ${-origin.y})`
-  ].join(" ");
-}
-
 export class ObjectVectorRuntimeAssetService {
   constructor({ fetchRef = (...args) => fetch(...args), logger = console, schemaUrl = DEFAULT_SCHEMA_URL } = {}) {
     this.assetCache = new Map();
@@ -897,11 +874,7 @@ export class ObjectVectorRuntimeAssetService {
     const transform = shapeTransform(shape);
     context.save();
     try {
-      context.translate(transform.x, transform.y);
-      context.translate(transformOrigin.x, transformOrigin.y);
-      context.rotate((transform.rotation * Math.PI) / 180);
-      context.scale(transform.scaleX, transform.scaleY);
-      context.translate(-transformOrigin.x, -transformOrigin.y);
+      applyObjectVectorCanvasTransform(context, transform, transformOrigin);
       context.lineWidth = shape.style.strokeWidth;
       context.lineCap = pointStyleValue(shape.style.strokeLinecap ?? shape.style.startPointStyle ?? shape.style.pointStyle);
       context.lineJoin = strokeLineJoinValue(shape.style.pointStyle ?? shape.style.strokeLinecap);
@@ -1014,7 +987,7 @@ export class ObjectVectorRuntimeAssetService {
   shapeToSvg(shape, transformOrigin = { x: 0, y: 0 }) {
     const lineCap = pointStyleValue(shape.style.strokeLinecap ?? shape.style.startPointStyle ?? shape.style.pointStyle);
     const lineJoin = strokeLineJoinValue(shape.style.pointStyle ?? shape.style.strokeLinecap);
-    const style = ` fill="${escapeXml(shape.style.fill)}" fill-opacity="${shape.style.fillOpacity}" stroke="${escapeXml(shape.style.stroke)}" stroke-opacity="${shape.style.strokeOpacity}" stroke-width="${shape.style.strokeWidth}" stroke-linecap="${lineCap}" stroke-linejoin="${lineJoin}" transform="${svgTransformAttribute(shapeTransform(shape), transformOrigin)}"`;
+    const style = ` fill="${escapeXml(shape.style.fill)}" fill-opacity="${shape.style.fillOpacity}" stroke="${escapeXml(shape.style.stroke)}" stroke-opacity="${shape.style.strokeOpacity}" stroke-width="${shape.style.strokeWidth}" stroke-linecap="${lineCap}" stroke-linejoin="${lineJoin}" transform="${objectVectorSvgTransformAttribute(shapeTransform(shape), transformOrigin)}"`;
     const geometryTool = shapeGeometryTool(shape);
     if (geometryTool === "rectangle") {
       const roundedPath = roundedPointPathCommands(shape, { closed: true });