Normalize Asteroids runtime object rendering to shared manifest object IDs - PR_26133_129-asteroids-manifest-runtime-normalization

Author: DavidQ

docs/dev/reports/PR_26133_129-asteroids-manifest-runtime-normalization_report.md

@@ -0,0 +1,56 @@
+# PR_26133_129 Asteroids Manifest Runtime Normalization
+
+## Summary
+- Normalized Asteroids gameplay/demo/attract object rendering to exact Object Vector Studio V2 manifest object IDs.
+- Removed the active tag-based runtime lookup module and stopped passing `tags`/`runtimeRole` options into Asteroids object rendering.
+- Updated gameplay collision/profile geometry to resolve by exact manifest object ID instead of tag-derived runtime keys.
+- Preserved ship flame flicker, asteroid scale tuning, and the PR_26133_128 non-object effect/UI draw systems.
+
+## Final Active Object IDs
+- Bullet: `object.asteroids.bullet`
+- Ship: `object.asteroids.ship`
+- Large asteroid: `object.asteroids.large-asteroid`
+- Medium asteroid: `object.asteroids.medium-asteroid`
+- Small asteroid: `object.asteroids.small-asteroid`
+- Large UFO: `object.asteroids.large-ufo`
+- Small UFO: `object.asteroids.small-ufo`
+
+## Removed Aliases And Indirect Lookup Paths
+- Deleted `games/Asteroids/game/asteroidsObjectTags.js`.
+- Removed active imports/usages of:
+  - `ASTEROIDS_RUNTIME_OBJECT_TAGS`
+  - `ASTEROID_SIZE_RUNTIME_OBJECT_KEYS`
+  - `runtimeObjectTagOptions`
+  - `resolveAsteroidsTaggedObject`
+  - `validateAsteroidsRuntimeObjectTags`
+  - `objectsByKey`
+- Removed tag/runtime-role options from gameplay/demo/attract render calls.
+- Replaced runtime cache expectations with direct object-ID cache messages.
+- Replaced runtime object validation with exact required object ID validation.
+
+## Remaining Intentional Non-Object Draw Systems
+- Starfield background pixels: procedural background effect.
+- HUD/menu/high-score text: UI text.
+- Attract text panels and demo trail pixels: UI/effect drawing.
+- Pause and initials overlays: modal UI.
+- Particle effects: transient randomized effects.
+- Ship debris fragments: runtime destruction effect using manifest-derived ship hull points from PR_26133_128.
+
+## Validation
+- PASS: targeted Asteroids node validation:
+  - `AsteroidsValidation`
+  - `AsteroidsPresentation`
+  - `AsteroidsVectorTransforms`
+  - `AsteroidsPlatformDemo`
+  - `AsteroidsAssetReferenceAdoption`
+- PASS: targeted Workspace Manager V2/Asteroids Playwright validation:
+  - `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list -g "loads Object Vector Studio V2 runtime assets into Asteroids gameplay rendering"`
+- PASS: `git diff --check`
+- Playwright impacted: Yes. This PR changes Asteroids runtime object lookup/render behavior and validates Asteroids launch, attract/demo object rendering, gameplay object rendering, and bullet rotation via the targeted browser slice.
+- Full samples smoke test skipped as requested; this PR only touches Asteroids runtime normalization.
+
+## Manual Validation
+- Open `/games/Asteroids/index.html`.
+- Let attract/demo run; expected: ship, UFO, and asteroids render through Object Vector Studio V2 manifest object IDs.
+- Start gameplay; expected: ship, bullets, asteroids, UFOs, and life icons render from the same manifest object renderer path.
+- Fire bullets at multiple ship angles; expected: `object.asteroids.bullet` preserves manifest styling and rotates with the shot direction.

games/Asteroids/game/AsteroidsAttractAdapter.js

@@ -7,21 +7,6 @@ AsteroidsAttractAdapter.js
 import { clamp } from '../../../src/shared/utils/mathUtils.js';
 import { ASTEROIDS_OBJECT_GEOMETRY_IDS } from './asteroidsObjectGeometryManifest.js';
 
-const ASTEROID_RENDER_BINDINGS = Object.freeze({
-  large: Object.freeze({
-    objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.asteroidLarge,
-    objectKey: 'asteroidLarge',
-  }),
-  medium: Object.freeze({
-    objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.asteroidMedium,
-    objectKey: 'asteroidMedium',
-  }),
-  small: Object.freeze({
-    objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.asteroidSmall,
-    objectKey: 'asteroidSmall',
-  }),
-});
-
 function estimateTextWidth(text, fontPx) {
   return String(text ?? '').length * (fontPx * 0.62);
 }
@@ -104,17 +89,15 @@ export default class AsteroidsAttractAdapter {
     return clamp(timing.alpha, 0, 1);
   }
 
-  drawManifestAsteroid(renderer, sizeKey, options = {}) {
-    const binding = ASTEROID_RENDER_BINDINGS[sizeKey];
-    if (!binding) {
+  drawManifestAsteroid(renderer, objectId, options = {}) {
+    if (!objectId) {
       return;
     }
 
     this.scene?.drawObjectVectorAsset?.(renderer, 'asteroids', {
-      ...this.scene.objectVectorTagOptions(binding.objectKey),
       elapsedMs: this.scene.objectVectorPlaybackMs,
       fps: 12,
-      objectId: binding.objectId,
+      objectId,
       requireManifestBinding: true,
       stateId: 'active',
       ...options,
@@ -153,7 +136,6 @@ export default class AsteroidsAttractAdapter {
     }
 
     this.scene?.drawObjectVectorAsset?.(renderer, 'ship', {
-      ...this.scene.objectVectorTagOptions('ship'),
       elapsedMs: this.scene.objectVectorPlaybackMs,
       fps: 12,
       objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.ship,
@@ -164,16 +146,16 @@ export default class AsteroidsAttractAdapter {
       x: 328,
       y: 348,
     });
-    this.drawManifestAsteroid(renderer, 'large', {
+    this.drawManifestAsteroid(renderer, ASTEROIDS_OBJECT_GEOMETRY_IDS.asteroidLarge, {
       x: 632,
       y: 352,
     });
-    this.drawManifestAsteroid(renderer, 'medium', {
+    this.drawManifestAsteroid(renderer, ASTEROIDS_OBJECT_GEOMETRY_IDS.asteroidMedium, {
       rotation: 0.34,
       x: 698,
       y: 316,
     });
-    this.drawManifestAsteroid(renderer, 'small', {
+    this.drawManifestAsteroid(renderer, ASTEROIDS_OBJECT_GEOMETRY_IDS.asteroidSmall, {
       rotation: -0.46,
       x: 594,
       y: 306,
@@ -247,7 +229,6 @@ export default class AsteroidsAttractAdapter {
     const x = 480 + Math.cos(this.demoTime * 0.7) * 220;
     const y = 340 + Math.sin(this.demoTime * 1.1) * 130;
     this.scene?.drawObjectVectorAsset?.(renderer, 'ship', {
-      ...this.scene.objectVectorTagOptions('ship'),
       elapsedMs: this.scene.objectVectorPlaybackMs,
       fps: 12,
       objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.ship,
@@ -258,23 +239,22 @@ export default class AsteroidsAttractAdapter {
       y,
     });
 
-    this.drawManifestAsteroid(renderer, 'large', {
+    this.drawManifestAsteroid(renderer, ASTEROIDS_OBJECT_GEOMETRY_IDS.asteroidLarge, {
       rotation: this.demoTime * 0.25,
       x: 480 + Math.sin(this.demoTime * 0.5) * 250,
       y: 330 + Math.cos(this.demoTime * 0.9) * 120,
     });
-    this.drawManifestAsteroid(renderer, 'medium', {
+    this.drawManifestAsteroid(renderer, ASTEROIDS_OBJECT_GEOMETRY_IDS.asteroidMedium, {
       rotation: -this.demoTime * 0.31,
       x: 520 + Math.sin((this.demoTime * 0.78) + 1.4) * 190,
       y: 356 + Math.cos((this.demoTime * 0.64) + 0.7) * 96,
     });
-    this.drawManifestAsteroid(renderer, 'small', {
+    this.drawManifestAsteroid(renderer, ASTEROIDS_OBJECT_GEOMETRY_IDS.asteroidSmall, {
       rotation: this.demoTime * 0.42,
       x: 430 + Math.sin((this.demoTime * 0.92) + 2.2) * 154,
       y: 318 + Math.cos((this.demoTime * 0.72) + 2.7) * 78,
     });
     this.scene?.drawObjectVectorAsset?.(renderer, 'ufo', {
-      ...this.scene.objectVectorTagOptions('ufoLarge'),
       elapsedMs: this.scene.objectVectorPlaybackMs,
       fps: 12,
       objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.ufoLarge,

games/Asteroids/game/AsteroidsGameScene.js

@@ -15,10 +15,11 @@ import AsteroidsHighScoreService from '../systems/AsteroidsHighScoreService.js';
 import AsteroidsInitialsEntry from '../systems/AsteroidsInitialsEntry.js';
 import { createAsteroidGeometryProfilesFromObjectVectorAssets } from './asteroidObjectGeometry.js';
 import {
-  ASTEROID_SIZE_RUNTIME_OBJECT_KEYS,
-  runtimeObjectTagOptions,
-  validateAsteroidsRuntimeObjectTags
-} from './asteroidsObjectTags.js';
+  ASTEROIDS_OBJECT_GEOMETRY_IDS,
+  ASTEROIDS_ASTEROID_SIZE_OBJECT_IDS,
+  ASTEROIDS_UFO_TYPE_OBJECT_IDS,
+  validateAsteroidsRuntimeObjectIds
+} from './asteroidsObjectGeometryManifest.js';
 import {
   ASTEROIDS_GAME_OVER_AUTO_EXIT_SECONDS, ASTEROIDS_GAME_OVER_RETURN_MODE
 } from "../rules/flowRules.js";
@@ -89,16 +90,16 @@ export default class AsteroidsGameScene extends Scene {
     this.objectVectorAssets = options.objectVectorAssets || null;
     this.objectVectorRuntime = options.objectVectorRuntime || null;
     this.objectGeometry = options.objectGeometry || null;
-    if (!this.objectGeometry?.objectsById || !this.objectGeometry?.objectsByKey) {
+    if (!this.objectGeometry?.objectsById) {
       const message = 'Asteroids Object Vector manifest validation failed: object geometry was not loaded from game.manifest.json.';
       console.error(message);
       throw new Error(message);
     }
     this.objectVectorRuntimeObjectValidation = this.objectVectorAssets
-      ? validateAsteroidsRuntimeObjectTags([...this.objectVectorAssets.objectsById.values()], {
+      ? validateAsteroidsRuntimeObjectIds(this.objectVectorAssets.objectsById, {
         logger: this.objectVectorRuntime,
       })
-      : { errors: [], objectsByKey: {}, ok: false, warnings: [] };
+      : { errors: [], objectIds: [], ok: false, warnings: [] };
     if (this.objectVectorAssets && !this.objectVectorRuntimeObjectValidation.ok) {
       const message = validationFailureMessage(this.objectVectorRuntimeObjectValidation);
       this.objectVectorRuntime?.log?.('FAIL', message, {
@@ -737,12 +738,11 @@ export default class AsteroidsGameScene extends Scene {
     }
 
     this.world.asteroids.forEach((asteroid) => {
-      const objectKey = ASTEROID_SIZE_RUNTIME_OBJECT_KEYS[asteroid.size];
+      const objectId = ASTEROIDS_ASTEROID_SIZE_OBJECT_IDS[asteroid.size] || "";
       this.drawObjectVectorAsset(renderer, "asteroids", {
-        ...this.objectVectorTagOptions(objectKey),
         elapsedMs: this.objectVectorPlaybackMs,
         fps: 12,
-        objectId: this.objectVectorRuntimeObjectValidation.objectsByKey[objectKey]?.id || "",
+        objectId,
         requireManifestBinding: true,
         rotation: asteroid.angle,
         stateId: "active",
@@ -752,12 +752,11 @@ export default class AsteroidsGameScene extends Scene {
     });
 
     if (this.world.ufo) {
-      const objectKey = this.world.ufo.type === "small" ? "ufoSmall" : "ufoLarge";
+      const objectId = ASTEROIDS_UFO_TYPE_OBJECT_IDS[this.world.ufo.type] || ASTEROIDS_OBJECT_GEOMETRY_IDS.ufoLarge;
       this.drawObjectVectorAsset(renderer, "ufo", {
-        ...this.objectVectorTagOptions(objectKey),
         elapsedMs: this.objectVectorPlaybackMs,
         fps: 12,
-        objectId: this.objectVectorRuntimeObjectValidation.objectsByKey[objectKey]?.id || "",
+        objectId,
         requireManifestBinding: true,
         stateId: "active",
         x: this.world.ufo.x,
@@ -767,8 +766,7 @@ export default class AsteroidsGameScene extends Scene {
 
     this.world.bullets.forEach((bullet) => {
       this.drawObjectVectorAsset(renderer, "bullet", {
-        ...this.objectVectorTagOptions("bullet"),
-        objectId: this.objectVectorRuntimeObjectValidation.objectsByKey.bullet?.id || "",
+        objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.bullet,
         requireManifestBinding: true,
         rotation: bullet.angle,
         stateId: "active",
@@ -779,8 +777,7 @@ export default class AsteroidsGameScene extends Scene {
 
     this.world.ufoBullets.forEach((bullet) => {
       this.drawObjectVectorAsset(renderer, "bullet", {
-        ...this.objectVectorTagOptions("bullet"),
-        objectId: this.objectVectorRuntimeObjectValidation.objectsByKey.bullet?.id || "",
+        objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.bullet,
         requireManifestBinding: true,
         rotation: bullet.angle,
         stateId: "active",
@@ -793,10 +790,9 @@ export default class AsteroidsGameScene extends Scene {
 
     if (this.world.shipActive && !this.session.isTurnIntroActive() && this.session.mode !== 'menu') {
       this.drawObjectVectorAsset(renderer, "ship", {
-        ...this.objectVectorTagOptions("ship"),
         elapsedMs: this.objectVectorPlaybackMs,
         fps: 12,
-        objectId: this.objectVectorRuntimeObjectValidation.objectsByKey.ship?.id || "",
+        objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.ship,
         requireManifestBinding: true,
         rotation: this.world.ship.angle,
         stateId: this.world.ship.thrusting && this.session.mode === 'playing' ? "move" : "idle",
@@ -872,10 +868,6 @@ export default class AsteroidsGameScene extends Scene {
     this.publishObjectVectorRuntimeDiagnostics();
   }
 
-  objectVectorTagOptions(objectKey) {
-    return runtimeObjectTagOptions(objectKey);
-  }
-
   drawLives(renderer, centerX, y, lives) {
     if (!lives) {
       return;
@@ -884,10 +876,9 @@ export default class AsteroidsGameScene extends Scene {
     const startX = centerX - ((lives - 1) * LIFE_SPACING) / 2;
     Array.from({ length: lives }).forEach((_, index) => {
       this.drawObjectVectorAsset(renderer, "shipLife", {
-        ...this.objectVectorTagOptions("ship"),
         elapsedMs: this.objectVectorPlaybackMs,
         fps: 12,
-        objectId: this.objectVectorRuntimeObjectValidation.objectsByKey.ship?.id || "",
+        objectId: ASTEROIDS_OBJECT_GEOMETRY_IDS.ship,
         requireManifestBinding: true,
         rotation: -Math.PI / 2,
         scale: 1.05,
@@ -900,12 +891,12 @@ export default class AsteroidsGameScene extends Scene {
 
   drawObjectVectorAsset(renderer, renderKey, options) {
     if (!this.objectVectorRuntime || !this.objectVectorAssets) {
-      this.recordObjectVectorRenderFailure(renderKey, options.assetId || options.objectId || options.runtimeRole, "validated Object Vector runtime assets are not loaded");
+      this.recordObjectVectorRenderFailure(renderKey, options.assetId || options.objectId, "validated Object Vector runtime assets are not loaded");
       return false;
     }
     const result = this.objectVectorRuntime.renderObject(renderer, this.objectVectorAssets, options);
     if (!result.ok) {
-      this.recordObjectVectorRenderFailure(renderKey, options.assetId || options.objectId || options.runtimeRole, "runtime render returned failed result");
+      this.recordObjectVectorRenderFailure(renderKey, options.assetId || options.objectId, "runtime render returned failed result");
       return false;
     }
     this.objectVectorRenderCounts[renderKey] = (this.objectVectorRenderCounts[renderKey] || 0) + 1;

games/Asteroids/game/AsteroidsWorld.js

@@ -13,6 +13,7 @@ import { distance } from '../../../src/shared/utils/mathUtils.js';
 import { randomRange } from '../utils/math.js';
 import { sanitizeFiniteNumber, sanitizePositiveNumber } from '../../../src/shared/math/numberNormalization.js';
 import {
+  ASTEROIDS_OBJECT_GEOMETRY_IDS,
   requireAsteroidsObjectGeometryPoints,
 } from './asteroidsObjectGeometryManifest.js';
 
@@ -149,11 +150,11 @@ export default class AsteroidsWorld {
     if (!this.objectGeometry?.objectsById) {
       throw new Error('AsteroidsWorld requires manifest-loaded Object Vector geometry for ship, UFO, asteroid, and bullet gameplay geometry.');
     }
-    this.bulletCollisionPoints = requireAsteroidsObjectGeometryPoints(this.objectGeometry, 'bullet', 'bullet object geometry');
-    this.shipCollisionPoints = requireAsteroidsObjectGeometryPoints(this.objectGeometry, 'ship', 'ship object geometry');
+    this.bulletCollisionPoints = requireAsteroidsObjectGeometryPoints(this.objectGeometry, ASTEROIDS_OBJECT_GEOMETRY_IDS.bullet, 'bullet object geometry');
+    this.shipCollisionPoints = requireAsteroidsObjectGeometryPoints(this.objectGeometry, ASTEROIDS_OBJECT_GEOMETRY_IDS.ship, 'ship object geometry');
     this.ufoCollisionPoints = {
-      large: requireAsteroidsObjectGeometryPoints(this.objectGeometry, 'ufoLarge', 'large UFO object geometry'),
-      small: requireAsteroidsObjectGeometryPoints(this.objectGeometry, 'ufoSmall', 'small UFO object geometry'),
+      large: requireAsteroidsObjectGeometryPoints(this.objectGeometry, ASTEROIDS_OBJECT_GEOMETRY_IDS.ufoLarge, 'large UFO object geometry'),
+      small: requireAsteroidsObjectGeometryPoints(this.objectGeometry, ASTEROIDS_OBJECT_GEOMETRY_IDS.ufoSmall, 'small UFO object geometry'),
     };
     this.rng = typeof rng === 'function' ? rng : Math.random;
     this.bounds = sanitizeBounds(bounds);

games/Asteroids/game/asteroidObjectGeometry.js

@@ -1,7 +1,6 @@
 import {
-  ASTEROID_SIZE_RUNTIME_OBJECT_KEYS,
-  resolveAsteroidsTaggedObject,
-} from './asteroidsObjectTags.js';
+  ASTEROIDS_ASTEROID_SIZE_OBJECT_IDS,
+} from './asteroidsObjectGeometryManifest.js';
 
 const ASTEROID_SIZE_LABELS = Object.freeze({
   1: 'SML',
@@ -61,13 +60,36 @@ function extractPrimaryPolygonPoints(object) {
   return asArray(shape?.geometry?.points).map(cleanPoint);
 }
 
+function logProfileFailure(logger, message, details = {}) {
+  if (!logger) {
+    return;
+  }
+  if (typeof logger.log === 'function') {
+    logger.log('FAIL', message, details);
+    return;
+  }
+  logger.error?.(message, details);
+}
+
 function createProfilesFromObjects(objects, options = {}) {
   const profiles = {};
+  const objectsById = new Map(asArray(objects).map((object) => [object?.id, object]).filter(([id]) => id));
 
-  Object.entries(ASTEROID_SIZE_RUNTIME_OBJECT_KEYS).forEach(([size, objectKey]) => {
-    const object = resolveAsteroidsTaggedObject(objects, objectKey, options);
+  Object.entries(ASTEROIDS_ASTEROID_SIZE_OBJECT_IDS).forEach(([size, objectId]) => {
+    const object = objectsById.get(objectId);
+    if (!object) {
+      logProfileFailure(options.logger, `Asteroids asteroid geometry profile ${objectId} is missing from Object Vector manifest objects.`, {
+        objectId,
+        size,
+      });
+      return;
+    }
     const points = centerPoints(extractPrimaryPolygonPoints(object));
     if (points.length < 3) {
+      logProfileFailure(options.logger, `Asteroids asteroid geometry profile ${objectId} must contain visible polygon geometry with at least 3 points.`, {
+        objectId,
+        size,
+      });
       return;
     }
     const sizeId = Number(size);