Resolve Asteroids runtime objects from manifest metadata instead of fragile object IDs - PR_26133_034-asteroids-runtime-object-resolution-by-tags

Author: DavidQ

docs/dev/reports/asteroids_runtime_object_resolution_report.md

@@ -0,0 +1,40 @@
+# PR_26133_034 Asteroids Runtime Object Resolution Report
+
+Date: 2026-05-14
+
+## Scope
+
+This change makes Asteroids runtime Object Vector lookup role/tag driven so duplicated or recreated objects can keep rendering even when their object ids change.
+
+## Runtime Resolution
+
+- Added Asteroids runtime role metadata for ship, large/medium/small asteroids, and large/small UFOs.
+- Asteroids rendering now passes `runtimeRole` and required tags into the Object Vector runtime instead of selecting ship/UFO/asteroids with scene-local hardcoded object ids.
+- Asteroid collision profiles now resolve asteroid objects by role tags before extracting polygon geometry.
+- Explicit `game.gameData.objectVectorRuntime.objectIds` values are preserved as optional binding hints, but tag matches win when a binding points at a stale or old object.
+- Multiple tag matches are ranked by non-old candidates first, then newest manifest order, and an actionable warning lists candidates and the selected object.
+
+## Required Tags
+
+- Large asteroid: `["asteroid", "large"]`
+- Medium asteroid: `["asteroid", "medium"]`
+- Small asteroid: `["asteroid", "small"]`
+- Ship: `["player", "ship"]`
+- Large UFO: `["ufo", "large"]`
+- Small UFO: `["ufo", "small"]`
+
+## Manifest Data
+
+- Current Asteroids manifest object metadata already contains the required tags for all runtime roles.
+- No renamed old Medium Asteroid entry is present in the current manifest data.
+- Targeted tests construct a recreated Medium Asteroid with id `object.asteroids.asteroid.medium-recreated` and an old stale medium candidate to verify the active tag-correct object is selected.
+- No vector-map-editor fallback geometry was added or restored.
+
+## Validation
+
+- PASS - `npm run test:workspace-v2` -> 49 passed.
+- PASS - targeted Asteroids Asset Reference Adoption test for recreated/stale medium asteroid collision profile selection.
+- PASS - targeted Asteroids Platform Demo test for Object Vector runtime tag resolution and stale explicit binding warning.
+- PASS - targeted Asteroids collision timing/stress checks.
+- PASS - targeted Asteroids validation smoke.
+- PASS - targeted Asteroids manifest Object Vector runtime validation loaded 6 objects and resolved medium asteroid by tags.

docs/dev/reports/playwright_v8_coverage_report.md

@@ -1,6 +1,6 @@
-# PR_26133_033 Playwright V8 Coverage Report
+# PR_26133_034 Playwright V8 Coverage Report
 
-Task: PR_26133_033-asteroids-collision-and-object-vector-schema-defaults
+Task: PR_26133_034-asteroids-runtime-object-resolution-by-tags
 Date: 2026-05-14
 
 ## Result
@@ -26,10 +26,7 @@ PASS - Coverage reporting was generated during `npm run test:workspace-v2`.
 ## Changed Runtime JS Coverage
 
 ```text
-(83%) tools/object-vector-studio-v2/js/bootstrap.js - executed lines 109/109; executed functions 5/6
-(93%) tools/object-vector-studio-v2/js/ToolStarterApp.js - executed lines 4333/4333; executed functions 453/485
-(95%) tools/object-vector-studio-v2/js/services/ObjectVectorStudioV2SchemaService.js - executed lines 453/453; executed functions 55/58
-(98%) src/engine/rendering/ObjectVectorRuntimeAssetService.js - executed lines 915/915; executed functions 107/109
+(97%) src/engine/rendering/ObjectVectorRuntimeAssetService.js - executed lines 1056/1056; executed functions 123/127
 ```
 
 ## Guardrail
@@ -40,4 +37,4 @@ PASS - Coverage reporting was generated during `npm run test:workspace-v2`.
 
 ## PR-Specific Note
 
-The Workspace V2 run exercised Object Vector Studio V2 launch, schema loading, schema-driven shape creation, generated Asteroids object-vector payload validation, and Asteroids runtime object-vector loading. Coverage remains advisory only.
+The Workspace V2 run exercised Asteroids gameplay Object Vector runtime loading and rendering with role/tag cache diagnostics, plus Object Vector Studio V2 launch/save flows. Coverage remains advisory only.

docs/dev/reports/playwright_workspace_v2_results.md

@@ -1,6 +1,6 @@
-# PR_26133_033 Workspace V2 Playwright Results
+# PR_26133_034 Workspace V2 Playwright Results
 
-Task: PR_26133_033-asteroids-collision-and-object-vector-schema-defaults
+Task: PR_26133_034-asteroids-runtime-object-resolution-by-tags
 Date: 2026-05-14
 
 ## Result
@@ -14,16 +14,17 @@ PASS - `npm run test:workspace-v2` completed successfully.
 
 ## PR-Specific Coverage
 
-- Object Vector Studio V2 schema defaults are present in the game manifest schema and the standalone tool schema.
-- New rectangle creation was verified against schema-cloned geometry/style/transform defaults.
-- Workspace Manager V2 generated the Asteroids Object Vector payload without `assetLibrary` and with `objects[*].tags` present.
-- Launching Object Vector Studio V2 for Asteroids from Workspace Manager V2 loaded 6 objects and validated the payload.
-- Dirty-state and save validation still pass after the generated manifest cleanup.
+- Asteroids gameplay rendering now resolves Object Vector runtime objects through role/tag options for ship, UFO, and asteroid roles.
+- Workspace V2 runtime rendering test was updated to expect role-based cache diagnostics for ship and small UFO.
+- Object Vector Studio V2 still loads the Asteroids object payload from `games/Asteroids/game.manifest.json`.
+- Asteroids manifest runtime validation confirmed the current large, medium, and small asteroid objects expose the required tag metadata.
 
 ## Additional Validation
 
-PASS - Targeted Asteroids collision checks covered ship/asteroid, bullet/asteroid, UFO/asteroid, UFO bullet/asteroid, ship bullet/UFO bullet crossfire, and ship/UFO crash cases.
+PASS - Targeted recreated Medium Asteroid resolution tests confirmed `["asteroid", "medium"]` tags select the recreated object even when an explicit stale medium object id is present.
+
+PASS - Targeted Asteroids collision timing/stress checks still load asteroid collision profiles from Object Vector Studio V2 geometry.
 
 PASS - Targeted Asteroids validation smoke completed.
 
-PASS - Node schema validation reported `games/Asteroids/game.manifest.json` and the generated workspace manifest as schema-valid.
+PASS - Targeted Asteroids manifest Object Vector runtime validation loaded 6 objects and resolved the current medium asteroid by tags.

games/Asteroids/game.manifest.json

@@ -490,8 +490,8 @@
               ]
             },
             {
-              "id": "object.asteroids.asteroid.medium",
-              "name": "Medium Asteroid",
+              "id": "object.asteroids.medium-asteroid-1",
+              "name": "Medium Asteroid 1",
               "shapes": [
                 {
                   "tool": "polygon",
@@ -812,6 +812,106 @@
                 "ufo",
                 "small"
               ]
+            },
+            {
+              "id": "object.asteroids.medium-asteroid",
+              "name": "Medium Asteroid",
+              "shapes": [
+                {
+                  "tool": "polygon",
+                  "order": 0,
+                  "visible": true,
+                  "locked": false,
+                  "geometry": {
+                    "points": [
+                      {
+                        "x": 10,
+                        "y": 40
+                      },
+                      {
+                        "x": 50,
+                        "y": 20
+                      },
+                      {
+                        "x": 45,
+                        "y": 5
+                      },
+                      {
+                        "x": 25,
+                        "y": -10
+                      },
+                      {
+                        "x": 50,
+                        "y": -35
+                      },
+                      {
+                        "x": 30,
+                        "y": -45
+                      },
+                      {
+                        "x": 10,
+                        "y": -38
+                      },
+                      {
+                        "x": -20,
+                        "y": -45
+                      },
+                      {
+                        "x": -43,
+                        "y": -18
+                      },
+                      {
+                        "x": -43,
+                        "y": 20
+                      },
+                      {
+                        "x": -25,
+                        "y": 20
+                      },
+                      {
+                        "x": -25,
+                        "y": 40
+                      }
+                    ]
+                  },
+                  "style": {
+                    "fill": "transparent",
+                    "stroke": "#CBD5E1",
+                    "strokeWidth": 2,
+                    "fillOpacity": 1,
+                    "strokeOpacity": 1
+                  },
+                  "transform": {
+                    "x": 0,
+                    "y": 0,
+                    "rotation": 0,
+                    "scaleX": 1,
+                    "scaleY": 1,
+                    "origin": {
+                      "x": -1,
+                      "y": 1
+                    }
+                  }
+                }
+              ],
+              "states": [
+                {
+                  "id": "active",
+                  "name": "Active",
+                  "frames": [
+                    {
+                      "id": "active-frame-1",
+                      "order": 0,
+                      "durationFrames": 1,
+                      "shapeOverrides": []
+                    }
+                  ]
+                }
+              ],
+              "tags": [
+                "asteroid",
+                "large"
+              ]
             }
           ]
         },

games/Asteroids/game/AsteroidsGameScene.js

@@ -13,10 +13,11 @@ import ShipDebrisSystem from '../systems/ShipDebrisSystem.js';
 import AsteroidsAttractAdapter from './AsteroidsAttractAdapter.js';
 import AsteroidsHighScoreService from '../systems/AsteroidsHighScoreService.js';
 import AsteroidsInitialsEntry from '../systems/AsteroidsInitialsEntry.js';
+import { createAsteroidGeometryProfilesFromObjectVectorAssets } from './asteroidObjectGeometry.js';
 import {
-  ASTEROID_OBJECT_VECTOR_OBJECT_IDS,
-  createAsteroidGeometryProfilesFromObjectVectorAssets
-} from './asteroidObjectGeometry.js';
+  ASTEROID_SIZE_RUNTIME_ROLES,
+  runtimeObjectRoleOptions
+} from './asteroidsObjectVectorRoles.js';
 import {
   ASTEROIDS_GAME_OVER_AUTO_EXIT_SECONDS, ASTEROIDS_GAME_OVER_RETURN_MODE
 } from "../rules/flowRules.js";
@@ -29,11 +30,6 @@ const SCORE_TWO_X = 824;
 const LIFE_SPACING = 22;
 const PAUSE_OVERLAY_COLOR = 'rgba(2, 6, 23, 0.58)';
 const INITIALS_OVERLAY_COLOR = 'rgba(1, 6, 19, 0.62)';
-const UFO_OBJECT_VECTOR_OBJECT_IDS = Object.freeze({
-  large: "object.asteroids.ufo.large",
-  small: "object.asteroids.ufo.small",
-});
-const SHIP_OBJECT_VECTOR_OBJECT_ID = "object.asteroids.ship";
 const LIFE_ICON_POINTS = [
   [14, 0],
   [-10, -8],
@@ -114,8 +110,11 @@ export default class AsteroidsGameScene extends Scene {
     this.devConsoleIntegration = options.devConsoleIntegration || null;
     this.objectVectorAssets = options.objectVectorAssets || null;
     this.objectVectorRuntime = options.objectVectorRuntime || null;
+    this.objectVectorRuntimeBindings = this.objectVectorAssets?.runtimeBindings || {};
     this.asteroidGeometryProfiles = options.asteroidGeometryProfiles
-      || createAsteroidGeometryProfilesFromObjectVectorAssets(this.objectVectorAssets);
+      || createAsteroidGeometryProfilesFromObjectVectorAssets(this.objectVectorAssets, {
+        logger: this.objectVectorRuntime,
+      });
     this.objectVectorPlaybackMs = 0;
     this.objectVectorRenderCounts = {
       asteroids: 0,
@@ -735,10 +734,11 @@ export default class AsteroidsGameScene extends Scene {
     }
 
     this.world.asteroids.forEach((asteroid) => {
+      const roleId = ASTEROID_SIZE_RUNTIME_ROLES[asteroid.size];
       this.drawObjectVectorAsset(renderer, "asteroids", {
+        ...this.objectVectorRoleOptions(roleId),
         elapsedMs: this.objectVectorPlaybackMs,
         fps: 12,
-        objectId: ASTEROID_OBJECT_VECTOR_OBJECT_IDS[asteroid.size],
         rotation: asteroid.angle,
         stateId: "active",
         x: asteroid.x,
@@ -747,10 +747,11 @@ export default class AsteroidsGameScene extends Scene {
     });
 
     if (this.world.ufo) {
+      const roleId = this.world.ufo.type === "small" ? "ufoSmall" : "ufoLarge";
       this.drawObjectVectorAsset(renderer, "ufo", {
+        ...this.objectVectorRoleOptions(roleId),
         elapsedMs: this.objectVectorPlaybackMs,
         fps: 12,
-        objectId: UFO_OBJECT_VECTOR_OBJECT_IDS[this.world.ufo.type],
         stateId: "active",
         x: this.world.ufo.x,
         y: this.world.ufo.y,
@@ -769,9 +770,9 @@ export default class AsteroidsGameScene extends Scene {
 
     if (this.world.shipActive && !this.session.isTurnIntroActive() && this.session.mode !== 'menu') {
       this.drawObjectVectorAsset(renderer, "ship", {
+        ...this.objectVectorRoleOptions("ship"),
         elapsedMs: this.objectVectorPlaybackMs,
         fps: 12,
-        objectId: SHIP_OBJECT_VECTOR_OBJECT_ID,
         rotation: this.world.ship.angle + Math.PI / 2,
         stateId: this.world.ship.thrusting && this.session.mode === 'playing' ? "thrust" : "idle",
         x: this.world.ship.x,
@@ -846,14 +847,18 @@ export default class AsteroidsGameScene extends Scene {
     this.publishObjectVectorRuntimeDiagnostics();
   }
 
+  objectVectorRoleOptions(roleId) {
+    return runtimeObjectRoleOptions(roleId, this.objectVectorRuntimeBindings);
+  }
+
   drawObjectVectorAsset(renderer, renderKey, options) {
     if (!this.objectVectorRuntime || !this.objectVectorAssets) {
-      this.recordObjectVectorRenderFailure(renderKey, options.assetId || options.objectId, "validated Object Vector runtime assets are not loaded");
+      this.recordObjectVectorRenderFailure(renderKey, options.assetId || options.objectId || options.runtimeRole, "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, "runtime render returned failed result");
+      this.recordObjectVectorRenderFailure(renderKey, options.assetId || options.objectId || options.runtimeRole, "runtime render returned failed result");
       return false;
     }
     this.objectVectorRenderCounts[renderKey] = (this.objectVectorRenderCounts[renderKey] || 0) + 1;

games/Asteroids/game/asteroidObjectGeometry.js

@@ -1,8 +1,7 @@
-export const ASTEROID_OBJECT_VECTOR_OBJECT_IDS = Object.freeze({
-  1: 'object.asteroids.asteroid.small',
-  2: 'object.asteroids.asteroid.medium',
-  3: 'object.asteroids.asteroid.large',
-});
+import {
+  ASTEROID_SIZE_RUNTIME_ROLES,
+  resolveAsteroidsObjectVectorRole,
+} from './asteroidsObjectVectorRoles.js';
 
 const ASTEROID_SIZE_LABELS = Object.freeze({
   1: 'SML',
@@ -66,20 +65,20 @@ function extractPrimaryPolygonPoints(object) {
   return asArray(shape?.geometry?.points).map(cleanPoint);
 }
 
-function createProfilesFromObjects(objects) {
-  const objectById = new Map(asArray(objects).map((object) => [object?.id, object]));
+function createProfilesFromObjects(objects, options = {}) {
   const profiles = {};
 
-  Object.entries(ASTEROID_OBJECT_VECTOR_OBJECT_IDS).forEach(([size, objectId]) => {
-    const points = centerPoints(extractPrimaryPolygonPoints(objectById.get(objectId)));
+  Object.entries(ASTEROID_SIZE_RUNTIME_ROLES).forEach(([size, roleId]) => {
+    const object = resolveAsteroidsObjectVectorRole(objects, roleId, options);
+    const points = centerPoints(extractPrimaryPolygonPoints(object));
     if (points.length < 3) {
       return;
     }
     const sizeId = Number(size);
     profiles[sizeId] = {
       id: sizeId,
       label: ASTEROID_SIZE_LABELS[sizeId] || String(sizeId),
-      objectId,
+      objectId: object.id,
       points,
       radius: maxRadius(points),
     };
@@ -88,13 +87,16 @@ function createProfilesFromObjects(objects) {
   return profiles;
 }
 
-export function createAsteroidGeometryProfilesFromObjectVectorPayload(payload) {
-  return createProfilesFromObjects(asRecord(payload).objects);
+export function createAsteroidGeometryProfilesFromObjectVectorPayload(payload, options = {}) {
+  return createProfilesFromObjects(asRecord(payload).objects, options);
 }
 
-export function createAsteroidGeometryProfilesFromObjectVectorAssets(assetSet) {
+export function createAsteroidGeometryProfilesFromObjectVectorAssets(assetSet, options = {}) {
   if (assetSet?.objectsById instanceof Map) {
-    return createProfilesFromObjects([...assetSet.objectsById.values()]);
+    return createProfilesFromObjects([...assetSet.objectsById.values()], {
+      runtimeBindings: asRecord(assetSet.runtimeBindings),
+      ...options,
+    });
   }
-  return createAsteroidGeometryProfilesFromObjectVectorPayload(assetSet?.payload);
+  return createAsteroidGeometryProfilesFromObjectVectorPayload(assetSet?.payload, options);
 }