Move background render order into shared engine pipeline with game custom draw callback - PR_26133_111-engine-background-render-pipeline

DavidQ · DavidQ · commit 76ee16fdc2c1 · 2026-05-18T18:32:52.000-04:00
diff --git a/docs/dev/reports/PR_26133_111-engine-background-render-pipeline_report.md b/docs/dev/reports/PR_26133_111-engine-background-render-pipeline_report.md
@@ -0,0 +1,48 @@
+# PR_26133_111-engine-background-render-pipeline Report
+
+## Summary
+- Read `docs/dev/PROJECT_INSTRUCTIONS.md` before implementation.
+- Used available `PR_26133_110-collision-inspector-and-background-flow_report.md` and existing `codex_review.diff` references as prior context; no `PR_26133_110` delta ZIP was present under `tmp/`.
+- Moved shared frame rendering into `Engine.renderFrame()` with `Engine.renderBackgroundPipeline()` ordering: clear, background color, custom background callback, runtime overlay sync, background image, then scene/game objects.
+- Added optional `customBackgroundCallback` wiring on the engine and scene without hardcoding Asteroids into shared engine code.
+- Moved Asteroids starfield drawing from the legacy scene background-effects hook into `scene.customBackgroundCallback`.
+- Kept existing Asset Manager background color wiring and the `assets.color.background.game` key unchanged.
+
+## Changed Files
+- `src/engine/core/Engine.js`
+- `games/Asteroids/game/AsteroidsGameScene.js`
+- `tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
+- `docs/dev/reports/PR_26133_111-engine-background-render-pipeline_report.md`
+
+## Pre-Existing Dirty Files
+- `games/Asteroids/game.manifest.json` was already modified before this BUILD and was not edited for this PR.
+
+## Validation
+- PASS: `node --check src/engine/core/Engine.js`
+- PASS: `node --check games/Asteroids/game/AsteroidsGameScene.js`
+- PASS: `node --check tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
+- PASS: `git diff --check -- src/engine/core/Engine.js games/Asteroids/game/AsteroidsGameScene.js tests/playwright/tools/WorkspaceManagerV2.spec.mjs` (line-ending warnings only)
+- PASS: `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"` (1 passed)
+- PASS: targeted background render-order validation in the Asteroids runtime test asserted `clear`, `background-color`, `custom-background`, `overlay`, `background-image`, `game-objects`.
+- PASS: targeted Asteroids custom background callback validation asserted `scene.customBackgroundCallback` exists and draws starfield rects.
+- PASS: `npm run test:workspace-v2` (56 passed)
+- PASS: Playwright V8 coverage reports regenerated at `docs/dev/reports/playwright_v8_coverage_report.txt` and `docs/dev/reports/coverage_changed_js_guardrail.txt`.
+
+## Playwright
+- Playwright impacted: Yes.
+- Validated shared engine render ordering, Asteroids custom background callback wiring, Workspace V2 behavior, runtime asset loading, fullscreen bezel state, and existing workspace/tool regressions.
+- Expected pass behavior: the shared renderer preserves the requested stage order and Workspace V2 passes.
+- Expected fail behavior: tests fail if the starfield remains outside the custom callback, background image renders before overlay, game objects render before background stages, or Workspace V2 regressions appear.
+
+## Full Samples Smoke
+- Skipped full samples smoke test by request.
+- Reason: this PR changes shared render sequencing but is covered by the targeted Asteroids runtime validation and `npm run test:workspace-v2`; sample JSON launch validation remains out-of-scope until sample alignment.
+
+## Manual Validation
+1. Open `games/Asteroids/index.html`.
+2. Wait for boot completion.
+3. Start gameplay.
+4. Expected: the canvas clears, background color resolves from `assets.color.background.game`, Asteroids starfield renders through the custom background callback, the runtime overlay remains synchronized, the gameplay background image draws before game objects, and gameplay objects remain visible/interactive.
+
+## ZIP
+- Output path: `tmp/PR_26133_111-engine-background-render-pipeline_delta.zip`
diff --git a/games/Asteroids/game.manifest.json b/games/Asteroids/game.manifest.json
@@ -224,12 +224,12 @@
               "locked": false,
               "geometry": {
                 "point1": {
-                  "x": -7,
-                  "y": 16
+                  "x": -3,
+                  "y": 7
                 },
                 "point2": {
-                  "x": -0.079,
-                  "y": 19.96
+                  "x": 0,
+                  "y": 9
                 }
               },
               "style": {
@@ -254,12 +254,12 @@
               "locked": false,
               "geometry": {
                 "point1": {
-                  "x": 7,
-                  "y": 16
+                  "x": 3,
+                  "y": 7
                 },
                 "point2": {
-                  "x": -0.079,
-                  "y": 19.96
+                  "x": 0,
+                  "y": 9
                 }
               },
               "style": {
@@ -286,23 +286,19 @@
                 "points": [
                   {
                     "x": 0,
-                    "y": -24
-                  },
-                  {
-                    "x": 21,
-                    "y": 24
+                    "y": -16
                   },
                   {
-                    "x": 7,
-                    "y": 16
+                    "x": 9,
+                    "y": 10
                   },
                   {
-                    "x": -7,
-                    "y": 16
+                    "x": 0,
+                    "y": 5
                   },
                   {
-                    "x": -21,
-                    "y": 24
+                    "x": -9,
+                    "y": 10
                   }
                 ]
               },
@@ -316,7 +312,6 @@
                   false,
                   false,
                   false,
-                  false,
                   false
                 ],
                 "startPointStyle": "square",
@@ -339,11 +334,11 @@
               "geometry": {
                 "point1": {
                   "x": 0,
-                  "y": 24
+                  "y": 10
                 },
                 "point2": {
-                  "x": -7,
-                  "y": 16
+                  "x": -3,
+                  "y": 7
                 }
               },
               "style": {
@@ -368,12 +363,12 @@
               "locked": false,
               "geometry": {
                 "point1": {
-                  "x": 7,
-                  "y": 16
+                  "x": 3,
+                  "y": 7
                 },
                 "point2": {
                   "x": 0,
-                  "y": 24
+                  "y": 10
                 }
               },
               "style": {
@@ -472,7 +467,14 @@
                   "shapeOverrides": [
                     {
                       "visible": true,
-                      "shapeIndex": 0
+                      "shapeIndex": 0,
+                      "transform": {
+                        "rotation": 0,
+                        "scaleX": 1,
+                        "scaleY": 1,
+                        "x": 0,
+                        "y": 0
+                      }
                     },
                     {
                       "shapeIndex": 4,
@@ -495,6 +497,28 @@
                         "y": 0
                       },
                       "visible": false
+                    },
+                    {
+                      "shapeIndex": 1,
+                      "transform": {
+                        "rotation": 0,
+                        "scaleX": 1,
+                        "scaleY": 1,
+                        "x": 0,
+                        "y": 0
+                      },
+                      "visible": true
+                    },
+                    {
+                      "shapeIndex": 2,
+                      "transform": {
+                        "rotation": 0,
+                        "scaleX": 1,
+                        "scaleY": 1,
+                        "x": 0,
+                        "y": 0
+                      },
+                      "visible": true
                     }
                   ]
                 },
@@ -597,7 +621,7 @@
           ],
           "objectOrigin": {
             "x": 0,
-            "y": 0
+            "y": -3
           }
         },
         {
diff --git a/games/Asteroids/game/AsteroidsGameScene.js b/games/Asteroids/game/AsteroidsGameScene.js
@@ -181,6 +181,11 @@ export default class AsteroidsGameScene extends Scene {
     this.debugFrame = 0;
     this.debugEventLimit = 40;
     this.debugEvents = [];
+    this.customBackgroundCallback = (renderer) => {
+      this.world.starfield.forEach((star) => {
+        renderer.drawRect(star.x, star.y, star.size, star.size, '#94a3b8');
+      });
+    };
     this.lastThrusting = false;
     this.lastRotateDirection = 0;
     this.lastMode = this.session.mode;
@@ -729,12 +734,6 @@ export default class AsteroidsGameScene extends Scene {
     this.lastPPressed = pPressed;
   }
 
-  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);
diff --git a/src/engine/core/Engine.js b/src/engine/core/Engine.js
@@ -36,6 +36,7 @@ export default class Engine {
     fullscreen = null,
     backgroundColorLayer = null,
     backgroundImageLayer = null,
+    customBackgroundCallback = null,
     fullscreenBezelLayer = null,
     audio = null,
     logger = null,
@@ -76,6 +77,9 @@ export default class Engine {
     this.backgroundImageLayer = backgroundImageLayer || new backgroundImage({
       documentRef: this.documentRef
     });
+    this.customBackgroundCallback = typeof customBackgroundCallback === 'function'
+      ? customBackgroundCallback
+      : null;
     this.fullscreenBezelLayer = fullscreenBezelLayer || new fullscreenBezel({
       canvas,
       host: this.fullscreenTarget,
@@ -274,6 +278,60 @@ export default class Engine {
     }
   }
 
+  setCustomBackgroundCallback(callback) {
+    this.customBackgroundCallback = typeof callback === 'function' ? callback : null;
+  }
+
+  renderCustomBackground() {
+    if (typeof this.customBackgroundCallback === 'function') {
+      try {
+        return this.customBackgroundCallback(this.renderer, { scene: this.scene, engine: this });
+      } catch (error) {
+        this.trackRuntimeError('engine.customBackgroundCallback', error, { severity: 'error' });
+        throw error;
+      }
+    }
+
+    if (this.scene && typeof this.scene.customBackgroundCallback === 'function') {
+      try {
+        return this.scene.customBackgroundCallback(this.renderer, { scene: this.scene, engine: this });
+      } catch (error) {
+        this.trackRuntimeError('scene.customBackgroundCallback', error, { severity: 'error' });
+        throw error;
+      }
+    }
+
+    return null;
+  }
+
+  syncRuntimeOverlay() {
+    const fullscreenActive = this.fullscreen?.getState?.().active === true;
+    const fullscreenElement = this.fullscreen?.documentRef?.fullscreenElement
+      || this.documentRef?.fullscreenElement
+      || null;
+    return this.fullscreenBezelLayer?.sync?.({ fullscreenActive, fullscreenElement }) || null;
+  }
+
+  renderBackgroundPipeline() {
+    this.renderer.clear();
+    this.backgroundColorLayer?.render?.(this.renderer, { scene: this.scene, engine: this });
+    this.renderCustomBackground();
+    this.syncRuntimeOverlay();
+    this.backgroundImageLayer?.render?.(this.renderer, { scene: this.scene, engine: this });
+  }
+
+  renderFrame() {
+    this.renderBackgroundPipeline();
+    if (this.scene && typeof this.scene.render === 'function') {
+      try {
+        this.scene.render(this.renderer, this);
+      } catch (error) {
+        this.trackRuntimeError('scene.render', error, { severity: 'error' });
+        throw error;
+      }
+    }
+  }
+
   tick(now) {
     const { deltaMs, deltaSeconds } = this.frameClock.tick(now);
     const frameStart = performance.now();
@@ -325,30 +383,7 @@ export default class Engine {
     updateDurationMs = performance.now() - updateStart;
 
     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 {
-        this.scene.render(this.renderer, this);
-      } catch (error) {
-        this.trackRuntimeError('scene.render', error, { severity: 'error' });
-        throw error;
-      }
-    }
-    const fullscreenActive = this.fullscreen?.getState?.().active === true;
-    const fullscreenElement = this.fullscreen?.documentRef?.fullscreenElement
-      || this.documentRef?.fullscreenElement
-      || null;
-    this.fullscreenBezelLayer?.sync?.({ fullscreenActive, fullscreenElement });
+    this.renderFrame();
     renderDurationMs = performance.now() - renderStart;
 
     const frameData = {
diff --git a/tests/playwright/tools/WorkspaceManagerV2.spec.mjs b/tests/playwright/tools/WorkspaceManagerV2.spec.mjs
