Autodiscover and autodraw fullscreen bezel and background images

BUILD_PR_LEVEL_10_16_AUTODISCOVER_FULLSCREEN_BEZEL_AND_BACKGROUND

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,49 +2,46 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create `BUILD_PR_LEVEL_10_15_TEMPLATE_ASSET_STRUCTURE_AND_FULLSCREEN_BEZEL_FOUNDATION` as one small bundled PR with exactly these changes:
-
-1. Normalize `games/_template/assets/` to match the current Asteroids asset directory structure:
-   - audio/
-   - fonts/
-   - images/
-   - palettes/
-   - parallax/
-   - parallax/data/.gitkeep
-   - sprites/
-   - sprites/data/.gitkeep
-   - tilemaps/
-   - tilemaps/data/.gitkeep
-   - tilesets/
-   - vectors/
-   - vectors/data/.gitkeep
-   - preserve `.gitkeep` where needed
-   - do NOT copy Asteroids-specific content into `_template`
-
-2. Add a minimal fullscreen bezel foundation that is clearly NOT Parallax:
-   - use Asteroids `games/Asteroids/assets/images/bezel.png` as the first candidate asset
-   - bezel only applies in fullscreen mode
-   - bezel is screen-space, not world-space
-   - implement as a dedicated explicit surface/class/module name such as `FullscreenBezelOverlay` or equivalent clear name
-   - support draw mode contract with:
-     - default `overlay` (draw last)
-     - optional `underlay` support point for future use
-   - keep scope minimal and engine-safe
-
-3. Add/update focused tests or validation coverage for:
-   - `_template` directory scaffold exists
-   - bezel path/contract resolves correctly
-   - fullscreen-only gating is covered
-   - no Parallax coupling is introduced
-
-4. Update roadmap status only by adding the bezel foundation item in the appropriate high-level roadmap area without rewriting unrelated roadmap text.
-
-5. Final packaging step is REQUIRED:
+Create `BUILD_PR_LEVEL_10_16_AUTODISCOVER_FULLSCREEN_BEZEL_AND_BACKGROUND` as one small testable PR.
+
+Implement convention-based autodiscovery and autodraw for these optional files:
+
+- `games/<gameId>/assets/images/background.png`
+- `games/<gameId>/assets/images/bezel.png`
+
+Requirements:
+1. `background.png`
+   - if present, draw automatically
+   - draw before game/world content
+   - no user-added game code required
+
+2. `bezel.png`
+   - if present, draw automatically
+   - only draw in fullscreen mode
+   - draw in screen space
+   - draw after gameplay/HUD by default
+   - no user-added game code required
+
+3. Architecture rules
+   - do NOT use Parallax for bezel
+   - keep implementation minimal and shared where appropriate
+   - do not require explicit per-game registration
+   - do not break games that do not have these files
+
+4. Validation
+   - add/update focused tests or validation coverage for:
+     - autodetect present file
+     - no-op when file missing
+     - fullscreen gating for bezel
+     - background draw-before-world behavior
+   - verify Asteroids bezel candidate works from:
+     `games/Asteroids/assets/images/bezel.png`
+
+5. Final packaging step is REQUIRED
    - package ALL changed files into this exact repo-structured ZIP:
-     `<project folder>/tmp/BUILD_PR_LEVEL_10_15_TEMPLATE_ASSET_STRUCTURE_AND_FULLSCREEN_BEZEL_FOUNDATION.zip`
+     `<project folder>/tmp/BUILD_PR_LEVEL_10_16_AUTODISCOVER_FULLSCREEN_BEZEL_AND_BACKGROUND.zip`
 
 Hard rules:
 - no commit-only result
 - no missing ZIP
-- no repo-wide unrelated edits
-- keep changes surgical
+- no unrelated repo changes

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,2 @@
-Normalize _template asset structure and add fullscreen bezel foundation
-BUILD_PR_LEVEL_10_15_TEMPLATE_ASSET_STRUCTURE_AND_FULLSCREEN_BEZEL_FOUNDATION
+Autodiscover and autodraw fullscreen bezel and background images
+BUILD_PR_LEVEL_10_16_AUTODISCOVER_FULLSCREEN_BEZEL_AND_BACKGROUND

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-BUILD_PR_LEVEL_10_16_ASTEROIDS_FULLSCREEN_BEZEL_IMPLEMENTATION_CANDIDATE
+BUILD_PR_LEVEL_10_17_AUTODISCOVER_IMAGE_RENDER_VALIDATION

docs/dev/reports/change_summary.txt

@@ -1,4 +1,5 @@
-- Bundled _template asset scaffold normalization with fullscreen bezel foundation
-- Declared bezel as dedicated screen-space overlay, not Parallax
-- Set Asteroids bezel.png as first candidate asset
-- Enforced required Codex ZIP packaging output
+- Added zero-config autodiscovery direction for background.png and bezel.png
+- Background draws automatically before world render
+- Bezel draws automatically in fullscreen after gameplay/HUD
+- No per-game user code required
+- Codex ZIP output explicitly required

docs/dev/reports/validation_checklist.txt

@@ -1,8 +1,6 @@
-- `_template` asset folders match Asteroids structure
-- `.gitkeep` files preserved where needed
-- No Asteroids-specific content copied into `_template`
-- Bezel is fullscreen-only
-- Bezel is screen-space, not camera/parallax space
-- Default draw mode is overlay, with explicit future underlay hook
-- Focused validation/tests added
-- Output ZIP created at `<project folder>/tmp/BUILD_PR_LEVEL_10_15_TEMPLATE_ASSET_STRUCTURE_AND_FULLSCREEN_BEZEL_FOUNDATION.zip`
+- `background.png` autodetects and draws without manual wiring
+- `bezel.png` autodetects and draws without manual wiring
+- Bezel only renders in fullscreen
+- Missing files cause no runtime failure
+- Asteroids bezel candidate is covered
+- Output ZIP created at `<project folder>/tmp/BUILD_PR_LEVEL_10_16_AUTODISCOVER_FULLSCREEN_BEZEL_AND_BACKGROUND.zip`

docs/pr/BUILD_PR_LEVEL_10_16_AUTODISCOVER_FULLSCREEN_BEZEL_AND_BACKGROUND.md

@@ -0,0 +1,69 @@
+# BUILD_PR_LEVEL_10_16_AUTODISCOVER_FULLSCREEN_BEZEL_AND_BACKGROUND
+
+## Purpose
+Implement zero-config asset autodiscovery for fullscreen bezel and optional background image rendering.
+
+## Problem
+The bezel is not showing, and the current direction still relies too much on explicit setup.
+If a game already has:
+- `assets/images/bezel.png`
+- or `assets/images/background.png`
+
+the runtime should detect and draw them automatically with no game-specific user code.
+
+## Scope
+
+### Automatic discovery rules
+For each game, autodetect these optional image assets under:
+`games/<gameId>/assets/images/`
+
+Recognized filenames:
+- `bezel.png`
+- `background.png`
+
+No additional game wiring should be required.
+
+### Render behavior
+
+#### Background
+If `background.png` exists:
+- draw automatically
+- treat as screen-sized image content
+- draw before world/gameplay
+- keep behavior minimal and stable
+- no camera/parallax dependency unless separately designed later
+
+#### Bezel
+If `bezel.png` exists:
+- draw automatically
+- bezel should only render in fullscreen mode
+- bezel is screen-space only
+- draw after gameplay/HUD by default
+- no user-added per-game code required
+
+### Render order
+Default order:
+1. optional autodiscovered `background.png`
+2. game/world render
+3. HUD/overlay as currently defined
+4. optional autodiscovered fullscreen `bezel.png`
+
+### Architectural rules
+- Do not route bezel through Parallax
+- Do not require per-game bootstrap code to enable bezel/background autodraw
+- Keep detection convention-based and minimal
+- Keep scope engine-safe and surgical
+- Prefer a small shared image-discovery/render helper if needed
+
+## Testable Outcome
+- If `games/Asteroids/assets/images/bezel.png` exists, bezel appears automatically in fullscreen
+- If `games/<gameId>/assets/images/background.png` exists, background appears automatically
+- Games without either file continue to run without error
+- No manual game code required to enable either behavior
+- PR returns repo-structured ZIP at:
+  `<project folder>/tmp/BUILD_PR_LEVEL_10_16_AUTODISCOVER_FULLSCREEN_BEZEL_AND_BACKGROUND.zip`
+
+## Non-Goals
+- No generalized layered art system
+- No editor changes
+- No parallax/background system redesign

games/Asteroids/game/AsteroidsGameScene.js

@@ -13,7 +13,6 @@ import ShipDebrisSystem from '../systems/ShipDebrisSystem.js';
 import AsteroidsAttractAdapter from './AsteroidsAttractAdapter.js';
 import AsteroidsHighScoreService from '../systems/AsteroidsHighScoreService.js';
 import AsteroidsInitialsEntry from '../systems/AsteroidsInitialsEntry.js';
-import FullscreenBezelOverlay from './FullscreenBezelOverlay.js';
 import {
   ASTEROIDS_GAME_OVER_AUTO_EXIT_SECONDS, ASTEROIDS_GAME_OVER_RETURN_MODE } from "../rules/flowRules.js";
 import { ASTEROIDS_GAME_OVER_RETURN_STATUS } from "../rules/flowContent.js";
@@ -135,8 +134,6 @@ export default class AsteroidsGameScene extends Scene {
     this.beatTimer = 0;
     this.nextBeatId = 'beat1';
     this.scoreFlashTime = 0;
-    this.isFullscreenActive = false;
-    this.fullscreenBezelOverlay = new FullscreenBezelOverlay();
     this.initialsEntry = new AsteroidsInitialsEntry();
     this.attractAdapter = new AsteroidsAttractAdapter({ scene: this });
     this.currentInput = null;
@@ -495,7 +492,6 @@ export default class AsteroidsGameScene extends Scene {
   update(dtSeconds, engine) {
     this.debugFrame += 1;
     this.currentInput = engine.input ?? null;
-    this.isFullscreenActive = engine?.fullscreen?.getState?.().active === true;
     const enterPressed = engine.input?.isDown('Enter');
     const onePressed = engine.input?.isDown('Digit1');
     const twoPressed = engine.input?.isDown('Digit2');
@@ -698,10 +694,6 @@ export default class AsteroidsGameScene extends Scene {
     this.world.starfield.forEach((star) => {
       renderer.drawRect(star.x, star.y, star.size, star.size, '#94a3b8');
     });
-    this.fullscreenBezelOverlay.render(renderer, {
-      fullscreenActive: this.isFullscreenActive,
-      stage: 'underlay',
-    });
 
     if (this.session.mode !== 'menu') {
       const flashOn = this.session.isTurnIntroActive()
@@ -824,11 +816,6 @@ export default class AsteroidsGameScene extends Scene {
       });
     }
 
-    this.fullscreenBezelOverlay.render(renderer, {
-      fullscreenActive: this.isFullscreenActive,
-      stage: 'overlay',
-    });
-
     if (this.devConsoleIntegration) {
       this.devConsoleIntegration.render(renderer, {
         worldStages: ['parallax', 'entities', 'sprite-effects', 'vector-overlay'],

src/engine/core/Engine.js

@@ -9,7 +9,7 @@ import RuntimeMetrics from './RuntimeMetrics.js';
 import FrameClock from './FrameClock.js';
 import FixedTicker from './FixedTicker.js';
 import EventBus from '../events/EventBus.js';
-import { FullscreenService } from '../runtime/index.js';
+import { AutoDiscoveredGameImageLayers, FullscreenService } from '../runtime/index.js';
 import { AudioService } from '../audio/index.js';
 import { Logger } from '../logging/index.js';
 import { SettingsSystem } from '../release/index.js';
@@ -26,6 +26,7 @@ export default class Engine {
     frameClock = null,
     fixedTicker = null,
     fullscreen = null,
+    autoImageLayers = null,
     audio = null,
     logger = null,
   } = {}) {
@@ -51,6 +52,9 @@ export default class Engine {
       documentRef: globalThis.document ?? null,
       target: canvas,
     });
+    this.autoImageLayers = autoImageLayers || new AutoDiscoveredGameImageLayers({
+      documentRef: globalThis.document ?? null
+    });
     this.audio = audio || new AudioService();
     this.logger = logger || new Logger({ channel: 'engine' });
     this.settings = new SettingsSystem({
@@ -145,9 +149,12 @@ export default class Engine {
     updateDurationMs = performance.now() - updateStart;
 
     const renderStart = performance.now();
+    this.autoImageLayers?.renderBackground?.(this.renderer);
     if (this.scene && typeof this.scene.render === 'function') {
       this.scene.render(this.renderer, this);
     }
+    const fullscreenActive = this.fullscreen?.getState?.().active === true;
+    this.autoImageLayers?.renderBezel?.(this.renderer, { fullscreenActive });
     renderDurationMs = performance.now() - renderStart;
 
     this.metrics.recordFrame({