Add Collision Inspector V2 and wire existing background color into render flow - PR_26133_110-collision-inspector-and-background-flow

Author: DavidQ

games/Asteroids/game.manifest.json

@@ -89,6 +89,19 @@
       "name": "Asteroids Asset Manager V2 Registry",
       "source": "manifest",
       "assets": {
+        "assets.color.background.game": {
+          "path": "palette://workspace/space-black",
+          "type": "color",
+          "kind": "hex",
+          "role": "background",
+          "source": "manifest",
+          "color": {
+            "hex": "#020617",
+            "name": "Space Black",
+            "symbol": "!",
+            "source": "manifest"
+          }
+        },
         "assets.audio.music.beat-1": {
           "path": "assets/audio/beat1.wav",
           "type": "audio",
@@ -176,6 +189,16 @@
             "uniformEdgeStretchPx": 10
           }
         },
+        "assets.image.background.deluxe": {
+          "path": "assets/images/deluxe.png",
+          "type": "image",
+          "kind": "png",
+          "role": "background",
+          "source": "manifest",
+          "stretchOverride": {
+            "uniformEdgeStretchPx": 0
+          }
+        },
         "assets.image.preview.preview": {
           "path": "assets/images/preview.png",
           "type": "image",

games/Asteroids/game/AsteroidsGameScene.js

@@ -729,12 +729,15 @@ export default class AsteroidsGameScene extends Scene {
     this.lastPPressed = pPressed;
   }
 
-  render(renderer, engine) {
-    const leaderboardTopScore = this.highScoreService.getTopScore(this.highScoreRows);
-    const liveHudHighScore = Math.max(this.session.highScore, leaderboardTopScore);
+  renderBackgroundEffects(renderer) {
     this.world.starfield.forEach((star) => {
       renderer.drawRect(star.x, star.y, star.size, star.size, '#94a3b8');
     });
+  }
+
+  render(renderer, engine) {
+    const leaderboardTopScore = this.highScoreService.getTopScore(this.highScoreRows);
+    const liveHudHighScore = Math.max(this.session.highScore, leaderboardTopScore);
 
     if (this.session.mode !== 'menu') {
       const flashOn = this.session.isTurnIntroActive()

src/engine/core/Engine.js

@@ -11,6 +11,7 @@ import FixedTicker from './FixedTicker.js';
 import EventBus from '../events/EventBus.js';
 import { Camera3D } from '../camera/index.js';
 import {
+  backgroundColor,
   backgroundImage,
   fullscreenBezel,
   FullscreenService,
@@ -33,6 +34,7 @@ export default class Engine {
     frameClock = null,
     fixedTicker = null,
     fullscreen = null,
+    backgroundColorLayer = null,
     backgroundImageLayer = null,
     fullscreenBezelLayer = null,
     audio = null,
@@ -68,6 +70,9 @@ export default class Engine {
       documentRef: this.documentRef,
       target: this.fullscreenTarget,
     });
+    this.backgroundColorLayer = backgroundColorLayer || new backgroundColor({
+      documentRef: this.documentRef
+    });
     this.backgroundImageLayer = backgroundImageLayer || new backgroundImage({
       documentRef: this.documentRef
     });
@@ -321,6 +326,15 @@ export default class Engine {
 
     const renderStart = performance.now();
     this.renderer.clear();
+    this.backgroundColorLayer?.render?.(this.renderer, { scene: this.scene, engine: this });
+    if (this.scene && typeof this.scene.renderBackgroundEffects === 'function') {
+      try {
+        this.scene.renderBackgroundEffects(this.renderer, this);
+      } catch (error) {
+        this.trackRuntimeError('scene.renderBackgroundEffects', error, { severity: 'error' });
+        throw error;
+      }
+    }
     this.backgroundImageLayer?.render?.(this.renderer, { scene: this.scene, engine: this });
     if (this.scene && typeof this.scene.render === 'function') {
       try {

src/engine/runtime/backgroundColor.js

@@ -0,0 +1,115 @@
+import {
+  resolveGameImageConventionPaths,
+  resolveManifestChromeAssetPaths
+} from "./gameImageConvention.js";
+
+const COLOR_HEX_PATTERN = /^#([0-9a-f]{6}|[0-9a-f]{8})$/i;
+
+function createLayerState({ assetId = "", hex = "", name = "", path = "" } = {}) {
+  return {
+    assetId,
+    hex,
+    name,
+    path,
+    status: hex ? "ready" : "unavailable"
+  };
+}
+
+function normalizeHex(value) {
+  const color = typeof value === "string" ? value.trim() : "";
+  return COLOR_HEX_PATTERN.test(color) ? color : "";
+}
+
+export default class backgroundColor {
+  constructor(options = {}) {
+    this.documentRef = options.documentRef || globalThis.document || null;
+    const resolved = resolveGameImageConventionPaths({
+      gameId: options.gameId,
+      documentRef: this.documentRef,
+      manifestPath: options.manifestPath
+    });
+    this.gameId = resolved.gameId;
+    this.manifestPath = resolved.manifestPath;
+    this.layer = createLayerState({
+      assetId: resolved.backgroundColorAssetId,
+      hex: normalizeHex(resolved.backgroundColorHex),
+      name: resolved.backgroundColorName,
+      path: resolved.backgroundColorPath
+    });
+    this.manifestResolved = false;
+    this.manifestResolvePromise = null;
+  }
+
+  getState() {
+    return {
+      gameId: this.gameId,
+      manifestPath: this.manifestPath,
+      manifestResolved: this.manifestResolved,
+      assetId: this.layer.assetId,
+      hex: this.layer.hex,
+      name: this.layer.name,
+      path: this.layer.path,
+      status: this.layer.status
+    };
+  }
+
+  ensureManifestResolved() {
+    if (this.manifestResolved || this.manifestResolvePromise) {
+      return;
+    }
+
+    this.manifestResolvePromise = resolveManifestChromeAssetPaths({
+      gameId: this.gameId,
+      manifestPath: this.manifestPath,
+      documentRef: this.documentRef
+    })
+      .then((resolved) => {
+        this.gameId = resolved.gameId || this.gameId;
+        this.manifestPath = resolved.manifestPath || this.manifestPath;
+        const hex = normalizeHex(resolved.backgroundColorHex);
+        this.layer = createLayerState({
+          assetId: resolved.backgroundColorAssetId,
+          hex,
+          name: resolved.backgroundColorName,
+          path: resolved.backgroundColorPath
+        });
+      })
+      .catch(() => {
+        this.layer = createLayerState();
+      })
+      .finally(() => {
+        this.manifestResolved = true;
+        this.manifestResolvePromise = null;
+      });
+  }
+
+  render(renderer) {
+    this.ensureManifestResolved();
+    if (!this.layer.hex) {
+      return {
+        drawn: false,
+        reason: this.layer.status,
+        assetId: this.layer.assetId
+      };
+    }
+
+    const canvasSize = renderer?.getCanvasSize?.() || { width: 0, height: 0 };
+    const width = Number(canvasSize.width) > 0 ? Number(canvasSize.width) : 0;
+    const height = Number(canvasSize.height) > 0 ? Number(canvasSize.height) : 0;
+    if (width <= 0 || height <= 0 || typeof renderer?.drawRect !== "function") {
+      return {
+        drawn: false,
+        reason: "renderer-unavailable",
+        assetId: this.layer.assetId
+      };
+    }
+
+    renderer.drawRect(0, 0, width, height, this.layer.hex);
+    return {
+      drawn: true,
+      reason: "drawn",
+      assetId: this.layer.assetId,
+      hex: this.layer.hex
+    };
+  }
+}

src/engine/runtime/backgroundImage.js

@@ -213,6 +213,13 @@ 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

@@ -81,6 +81,24 @@ function normalizeAssetEntry(rawEntry, fallbackId = "", manifestPath = "") {
   };
 }
 
+function normalizeColorEntry(rawEntry, fallbackId = "") {
+  const entry = toObject(rawEntry);
+  const color = toObject(entry.color);
+  const hex = safeText(color.hex, "");
+  if (!hex) {
+    return null;
+  }
+  return {
+    id: safeText(entry.id, "") || safeText(fallbackId, ""),
+    hex,
+    kind: safeText(entry.kind, "").toLowerCase(),
+    name: safeText(color.name, ""),
+    path: safeText(entry.path || entry.runtimePath || entry.href, ""),
+    role: safeText(entry.role, "").toLowerCase(),
+    type: safeText(entry.type, "").toLowerCase()
+  };
+}
+
 function collectImageEntriesFromManifest(manifestPayload, { manifestPath = "" } = {}) {
   const payload = toObject(manifestPayload);
   const entries = [];
@@ -115,6 +133,19 @@ function collectImageEntriesFromManifest(manifestPayload, { manifestPath = "" }
   return entries;
 }
 
+function collectColorEntriesFromManifest(manifestPayload) {
+  const payload = toObject(manifestPayload);
+  const entries = [];
+  const assetManagerAssets = toObject(payload?.tools?.["asset-manager-v2"]?.assets);
+  Object.entries(assetManagerAssets).forEach(([assetId, rawEntry]) => {
+    const entry = normalizeColorEntry(rawEntry, assetId);
+    if (entry?.type === "color") {
+      entries.push(entry);
+    }
+  });
+  return entries;
+}
+
 function chooseSemanticImagePath(entries, semanticToken) {
   const token = safeText(semanticToken, "").toLowerCase();
   if (!token) {
@@ -143,6 +174,13 @@ function chooseSemanticImagePath(entries, semanticToken) {
   return "";
 }
 
+function chooseGameBackgroundColor(entries) {
+  const normalizedEntries = Array.isArray(entries) ? entries : [];
+  return normalizedEntries.find((entry) => entry.id === "assets.color.background.game")
+    || normalizedEntries.find((entry) => entry.role === "background" && entry.id.includes(".background.game"))
+    || null;
+}
+
 const manifestCache = new Map();
 
 async function readManifestPayload(manifestPath, documentRef = null) {
@@ -214,8 +252,12 @@ export function resolveGameImageConventionPaths(options = {}) {
   return {
     gameId,
     manifestPath,
-    backgroundPath: "",
-    bezelPath: ""
+    backgroundColorAssetId: "",
+    backgroundColorHex: "",
+    backgroundColorName: "",
+    backgroundColorPath: "",
+    backgroundPath: gameId ? `games/${gameId}/assets/images/background.png` : "",
+    bezelPath: gameId ? `games/${gameId}/assets/images/bezel.png` : ""
   };
 }
 
@@ -228,16 +270,19 @@ export async function resolveManifestChromeAssetPaths(options = {}) {
   if (!manifestPayload) {
     return {
       ...base,
-      backgroundPath: "",
-      bezelPath: "",
       manifestPayload: null
     };
   }
 
   const imageEntries = collectImageEntriesFromManifest(manifestPayload, { manifestPath: base.manifestPath });
+  const backgroundColor = chooseGameBackgroundColor(collectColorEntriesFromManifest(manifestPayload));
   return {
     ...base,
     manifestPayload,
+    backgroundColorAssetId: backgroundColor?.id || "",
+    backgroundColorHex: backgroundColor?.hex || "",
+    backgroundColorName: backgroundColor?.name || "",
+    backgroundColorPath: backgroundColor?.path || "",
     backgroundPath: chooseSemanticImagePath(imageEntries, "background"),
     bezelPath: chooseSemanticImagePath(imageEntries, "bezel")
   };

src/engine/runtime/index.js

@@ -7,6 +7,7 @@ index.js
 export { default as MobileRuntimeTweaks } from './MobileRuntimeTweaks.js';
 export { default as FullscreenService } from './FullscreenService.js';
 export { default as BrowserDownloadService } from './BrowserDownloadService.js';
+export { default as backgroundColor } from './backgroundColor.js';
 export { default as backgroundImage } from './backgroundImage.js';
 export { default as fullscreenBezel, resolvePreferredFullscreenTarget } from './fullscreenBezel.js';
 export { resolveGameImageConventionPaths } from './gameImageConvention.js';

tests/playwright/tools/AssetManagerV2.spec.mjs

@@ -1103,6 +1103,11 @@ test.describe("Asset Manager V2", () => {
       await expect(page.locator("#assetPathInput")).toHaveValue("palette://workspace/signal-violet");
       await expect(page.locator("#statusLog")).toHaveValue(/FAIL Selected color validation failed: Color usage is required for color assets\./);
       await expect(page.locator("#addAssetButton")).toBeDisabled();
+      await page.locator("#assetRoleSelect").selectOption("background");
+      await page.locator("#assetUsageInput").fill("game");
+      await expect(page.locator("#assetIdInput")).toHaveValue("assets.color.background.game");
+      await expect(page.locator("#assetUsageField")).toHaveCount(1);
+      await page.locator("#assetRoleSelect").selectOption("hud");
       await page.locator("#assetUsageInput").fill("Menu Highlight");
       await expect(page.locator("#assetIdInput")).toHaveValue("assets.color.hud.menu-highlight.signal-violet");
       await expect(page.locator("#assetPathInput")).toHaveValue("palette://workspace/signal-violet");
@@ -1257,7 +1262,7 @@ test.describe("Asset Manager V2", () => {
     });
 
     try {
-      await expect(page.locator("#workspaceToolTiles [data-workspace-tool-id]")).toHaveCount(4);
+      await expect(page.locator("#workspaceToolTiles [data-workspace-tool-id]")).toHaveCount(7);
       await expect(page.locator('[data-workspace-tool-id="workspace-manager-v2"]')).toHaveCount(0);
       await page.locator("#activeGameSelect").selectOption("Asteroids");
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"gameRoot": "games\/Asteroids\/"/);
@@ -1278,14 +1283,14 @@ test.describe("Asset Manager V2", () => {
       await expect(page.locator("#returnToWorkspaceButton")).toBeEnabled();
       await expect(page.locator("#workspaceInsertAssetsButton")).toHaveCount(0);
       await expect(page.locator("#workspaceCopyManifestButton")).toHaveCount(0);
-      await expect(page.locator("#statusLog")).toHaveValue(/Workspace Manager V2 loaded 14 validated assets from tools\.asset-manager-v2\.assets/);
+      await expect(page.locator("#statusLog")).toHaveValue(/Workspace Manager V2 loaded 15 validated assets from tools\.asset-manager-v2\.assets/);
       await expect(page.locator("#statusLog")).toHaveValue(/Workspace Manager V2 loaded \d+ palette colors from active palette context/);
       const hostContextId = await page.evaluate(() => new URL(window.location.href).searchParams.get("hostContextId"));
       const initialAssetCount = await page.evaluate((id) => {
         const context = JSON.parse(sessionStorage.getItem(id));
         return Object.keys(context.tools["asset-manager-v2"].assets).length;
       }, hostContextId);
-      expect(initialAssetCount).toBe(14);
+      expect(initialAssetCount).toBe(15);
       const workspacePreviewContext = await page.evaluate(async () => {
         const { WorkspaceBridge } = await import("/tools/asset-manager-v2/js/services/WorkspaceBridge.js");
         return new WorkspaceBridge({ windowRef: window }).readWorkspacePreviewContext();
@@ -1478,18 +1483,25 @@ test.describe("Asset Manager V2", () => {
       const assetManagerCard = page.locator(".tools-platform-card").filter({
         has: page.locator("h3 a", { hasText: "Asset Manager V2" })
       });
+      const collisionInspectorLink = page.locator(".tools-platform-card h3 a", { hasText: "Collision Inspector V2" });
+      const collisionInspectorCard = page.locator(".tools-platform-card").filter({
+        has: page.locator("h3 a", { hasText: "Collision Inspector V2" })
+      });
       await expect(assetManagerLink).toBeVisible();
       await expect(assetManagerLink).toHaveAttribute("href", "/tools/asset-manager-v2/index.html");
       await expect(assetManagerCard).toContainText("Schema Validated");
+      await expect(collisionInspectorLink).toBeVisible();
+      await expect(collisionInspectorLink).toHaveAttribute("href", "/tools/collision-inspector-v2/index.html");
+      await expect(collisionInspectorCard).toContainText("Manifest-driven collision QA");
       const plannedToolNames = await page.locator("[data-planned-tools-grid] h3").allTextContents();
       for (const plannedToolName of [
         "Asset Manager V2",
         "Animation / Flipbook Editor",
-        "Audio / SFX Playground",
-        "Collision / Hitbox Editor"
+        "Audio / SFX Playground"
       ]) {
         expect(plannedToolNames).toContain(plannedToolName);
       }
+      expect(plannedToolNames).not.toContain("Collision / Hitbox Editor");
       expect(pageErrors).toEqual([]);
     } finally {
       await coverageReporter.stop(page);