Resolve Asteroids background image from Asset Manager manifest instead of hardcoded path - PR_26139_015-manifest-background-asset-resolution

Author: DavidQ

docs/dev/reports/PR_26139_015-manifest-background-asset-resolution_report.md

@@ -0,0 +1,63 @@
+# PR_26139_015-manifest-background-asset-resolution Report
+
+## Summary
+
+- Removed the Asteroids background image convention fallback so the runtime no longer guesses `assets/images/background.png`.
+- Background image resolution now selects only an `asset-manager-v2` image asset with `role: "background"`.
+- Background image loading waits for manifest resolution; when the optional background role is absent, the layer stays unavailable and does not create an image request.
+- Removed the stale gameplay-only background image gate so the shared background image layer renders behind menu, attract, and gameplay screens once ready.
+- Existing shared background render order remains: clear, background color, custom background callback, overlay, background image, game objects.
+
+## Files Changed
+
+- `src/engine/runtime/gameImageConvention.js`
+- `src/engine/runtime/backgroundImage.js`
+- `tests/core/BackgroundImageAndFullscreenBezel.test.mjs`
+- `tests/playwright/tools/AsteroidsBackgroundAssetResolution.spec.mjs`
+- `docs/dev/reports/PR_26139_015-manifest-background-asset-resolution_report.md`
+
+## Background Asset Resolution
+
+- Active background image source: `tools.asset-manager-v2.assets[*]` with `type: "image"` and `role: "background"`.
+- Current Asteroids manifest result: `/games/Asteroids/assets/images/deluxe.png`.
+- The deluxe filename is not hardcoded; it is discovered from the manifest asset entry.
+- If no Asset Manager background image role exists, `backgroundImageLayer.getState()` reports `path: ""` and `status: "unavailable"`.
+- No fallback/default background image path is produced.
+- The background image layer no longer suppresses rendering based on scene mode.
+
+## Validation
+
+- PASS: `node --check src/engine/runtime/gameImageConvention.js`
+- PASS: `node --check src/engine/runtime/backgroundImage.js`
+- PASS: `node --check tests/playwright/tools/AsteroidsBackgroundAssetResolution.spec.mjs`
+- PASS: targeted Node manifest/background absence validation
+- PASS: `npm run build:manifest`
+- PASS: `npx playwright test tests/playwright/tools/AsteroidsBackgroundAssetResolution.spec.mjs --project=playwright --workers=1 --reporter=list`
+  - 2 passed.
+  - Verified no request for `/games/Asteroids/assets/images/background.png`.
+  - Verified `/games/Asteroids/assets/images/deluxe.png` loads from the Asset Manager `role: "background"` asset.
+  - Verified the loaded background image changes the Asteroids menu canvas pixels from the manifest background color.
+  - Verified removing the background image role causes no deluxe/background image request, no 404, and the game still boots.
+- PASS: `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list --grep "loads Object Vector Studio V2 runtime assets into Asteroids gameplay rendering"`
+  - 1 passed.
+  - Verified background render order remains clear, background color, custom background callback, overlay, background image, game objects.
+- WARN: `npm run test:workspace-v2`
+  - 54 passed, 2 failed.
+  - Existing unrelated failures:
+    - `validates optional Text to Speech V2 schema contract through Workspace Manager V2 schema`
+    - `tracks Object Vector Studio V2 dirty state through persisted edits and save outcomes`
+- PASS: `git diff --check`
+  - Git emitted the existing line-ending normalization warning for `tests/core/BackgroundImageAndFullscreenBezel.test.mjs`; command exit code was 0.
+
+## Manual Validation
+
+1. Open `games/Asteroids/index.html`.
+2. Confirm the game boots without a request for `/games/Asteroids/assets/images/background.png`.
+3. Confirm the background image is visible on the initial Asteroids menu screen.
+4. Confirm the runtime background image path is `/games/Asteroids/assets/images/deluxe.png` only because the Asteroids manifest has an Asset Manager image asset with `role: "background"`.
+5. Temporarily remove that background image role from the manifest and reload.
+6. Confirm the game still boots, the background image layer is unavailable, and no missing background image request appears.
+
+## Full Samples Smoke
+
+- Skipped as requested; this PR changes the Asteroids/runtime background asset path only and does not broadly change sample loading.

src/engine/runtime/backgroundImage.js

@@ -4,29 +4,6 @@ import {
   resolveRuntimeAssetUrl
 } from "./gameImageConvention.js";
 
-const NON_GAMEPLAY_MODE_TOKENS = Object.freeze([
-  "menu",
-  "title",
-  "attract",
-  "select-player",
-  "player-select",
-  "intro",
-  "splash",
-  "game-over",
-  "credits",
-  "pause"
-]);
-
-const GAMEPLAY_MODE_TOKENS = Object.freeze([
-  "playing",
-  "gameplay",
-  "in-game",
-  "ingame",
-  "combat",
-  "runtime",
-  "active"
-]);
-
 function createLayerState(path) {
   return {
     path,
@@ -54,30 +31,6 @@ function drawFullscreenImage(renderer, image) {
   return true;
 }
 
-function toModeText(value) {
-  return typeof value === "string" ? value.trim().toLowerCase() : "";
-}
-
-function sceneModeCandidates(scene) {
-  if (!scene || typeof scene !== "object") {
-    return [];
-  }
-
-  return [
-    scene.mode,
-    scene.state,
-    scene.status,
-    scene.screen,
-    scene.view,
-    scene.phase,
-    scene.session?.mode,
-    scene.session?.state,
-    scene.session?.status
-  ]
-    .map(toModeText)
-    .filter(Boolean);
-}
-
 export default class backgroundImage {
   constructor(options = {}) {
     this.documentRef = options.documentRef || globalThis.document || null;
@@ -88,6 +41,9 @@ export default class backgroundImage {
     this.gameId = resolved.gameId;
     this.manifestPath = resolved.manifestPath;
     this.layer = createLayerState(resolved.backgroundPath);
+    this.manifestPayload = options.manifestPayload && typeof options.manifestPayload === "object" && !Array.isArray(options.manifestPayload)
+      ? options.manifestPayload
+      : null;
     this.imageFactory = typeof options.imageFactory === "function"
       ? options.imageFactory
       : (typeof Image === "function" ? () => new Image() : null);
@@ -116,7 +72,8 @@ export default class backgroundImage {
     this.manifestResolvePromise = resolveManifestChromeAssetPaths({
       gameId: this.gameId,
       manifestPath: this.manifestPath,
-      documentRef: this.documentRef
+      documentRef: this.documentRef,
+      manifestPayload: this.manifestPayload
     })
       .then((resolved) => {
         this.gameId = resolved.gameId || this.gameId;
@@ -134,45 +91,14 @@ export default class backgroundImage {
       });
   }
 
-  isGameplayState(scene) {
-    if (!scene || typeof scene !== "object") {
-      return true;
-    }
-
-    if (typeof scene.isGameplayStateActive === "function") {
-      const explicit = scene.isGameplayStateActive();
-      if (typeof explicit === "boolean") {
-        return explicit;
-      }
-    }
-    if (typeof scene.isGameplayStateActive === "boolean") {
-      return scene.isGameplayStateActive;
-    }
-
-    const modes = sceneModeCandidates(scene);
-    for (const mode of modes) {
-      if (NON_GAMEPLAY_MODE_TOKENS.some((token) => mode.includes(token))) {
-        return false;
-      }
-      if (GAMEPLAY_MODE_TOKENS.some((token) => mode.includes(token))) {
-        return true;
-      }
-    }
-
-    if (scene.attractController?.active === true) {
-      return false;
-    }
-
-    return true;
-  }
-
   ensureLoaded() {
     this.ensureManifestResolved();
 
+    if (!this.manifestResolved) {
+      return;
+    }
     if (!this.layer.path) {
-      if (this.manifestResolved) {
-        this.layer.status = "unavailable";
-      }
+      this.layer.status = "unavailable";
       return;
     }
     if (this.layer.status === "ready" || this.layer.status === "missing" || this.layer.status === "loading") {
@@ -213,13 +139,6 @@ export default class backgroundImage {
 
   render(renderer, options = {}) {
     this.ensureLoaded();
-    if (!this.isGameplayState(options.scene)) {
-      return {
-        drawn: false,
-        reason: "non-gameplay-state",
-        path: this.layer.path
-      };
-    }
     if (this.layer.status !== "ready" || !this.layer.image) {
       return {
         drawn: false,

src/engine/runtime/gameImageConvention.js

@@ -66,7 +66,7 @@ function resolveManifestRelativePath(pathValue, manifestPath) {
   return `${baseFolder}/${normalized.replace(/^\/+/, "")}`;
 }
 
-function normalizeAssetEntry(rawEntry, fallbackId = "", manifestPath = "") {
+function normalizeAssetEntry(rawEntry, fallbackId = "", manifestPath = "", sourceToolId = "") {
   const entry = toObject(rawEntry);
   const path = resolveManifestRelativePath(entry.path || entry.runtimePath || entry.href, manifestPath);
   if (!path) {
@@ -77,6 +77,7 @@ function normalizeAssetEntry(rawEntry, fallbackId = "", manifestPath = "") {
     kind: safeText(entry.kind, "").toLowerCase(),
     path,
     role: safeText(entry.role, "").toLowerCase(),
+    sourceToolId: safeText(sourceToolId, "").toLowerCase(),
     type: safeText(entry.type, "").toLowerCase()
   };
 }
@@ -127,12 +128,12 @@ function collectImageEntriesFromManifest(manifestPayload, { manifestPath = "" }
 
   const assetBrowserAssets = toObject(payload?.tools?.["asset-browser"]?.assets);
   Object.entries(assetBrowserAssets).forEach(([assetId, rawEntry]) => {
-    pushEntry(normalizeAssetEntry(rawEntry, assetId, manifestPath));
+    pushEntry(normalizeAssetEntry(rawEntry, assetId, manifestPath, "asset-browser"));
   });
 
   const assetManagerAssets = toObject(payload?.tools?.["asset-manager-v2"]?.assets);
   Object.entries(assetManagerAssets).forEach(([assetId, rawEntry]) => {
-    pushEntry(normalizeAssetEntry(rawEntry, assetId, manifestPath));
+    pushEntry(normalizeAssetEntry(rawEntry, assetId, manifestPath, "asset-manager-v2"));
   });
 
   return entries;
@@ -186,6 +187,17 @@ function chooseGameBackgroundColor(entries) {
     || null;
 }
 
+function chooseAssetManagerBackgroundImagePath(entries) {
+  const normalizedEntries = Array.isArray(entries) ? entries : [];
+  const backgroundAsset = normalizedEntries.find((entry) => (
+    entry?.sourceToolId === "asset-manager-v2"
+    && entry?.type === "image"
+    && entry?.role === "background"
+    && safeText(entry?.path, "")
+  ));
+  return backgroundAsset?.path || "";
+}
+
 const manifestCache = new Map();
 
 async function readManifestPayload(manifestPath, documentRef = null) {
@@ -261,7 +273,7 @@ export function resolveGameImageConventionPaths(options = {}) {
     backgroundColorHex: "",
     backgroundColorName: "",
     backgroundColorPath: "",
-    backgroundPath: gameId ? `games/${gameId}/assets/images/background.png` : "",
+    backgroundPath: "",
     bezelPath: gameId ? `games/${gameId}/assets/images/bezel.png` : ""
   };
 }
@@ -288,7 +300,7 @@ export async function resolveManifestChromeAssetPaths(options = {}) {
     backgroundColorHex: backgroundColor?.hex || "",
     backgroundColorName: backgroundColor?.name || "",
     backgroundColorPath: backgroundColor?.path || "",
-    backgroundPath: chooseSemanticImagePath(imageEntries, "background"),
+    backgroundPath: chooseAssetManagerBackgroundImagePath(imageEntries),
     bezelPath: chooseSemanticImagePath(imageEntries, "bezel")
   };
 }