Skip to content

Commit 5449506

Browse files
author
DavidQ
committed
Finish Asteroids engine-owned background/bezel layering and manifest-only chrome loading - PR 11.89
1 parent f855626 commit 5449506

5 files changed

Lines changed: 293 additions & 17 deletions

‎docs/dev/codex_commands.md‎

Lines changed: 12 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,21 @@
1-
# Codex Commands — PR 11.88
1+
# Codex command
22

3-
Model: GPT-5.4
4-
Reasoning: high
3+
Run from repo root:
54

65
```powershell
7-
codex --model gpt-5.4 --reasoning high "Apply PR 11.88 from docs/pr/PR_11_88_ENGINE_OWNED_GAME_CHROME_AND_LAYERING.md. Fix all listed engine-owned chrome/layering issues in one pass. Keep scope targeted. Do not add wrappers, aliases, fallback assets, or guessed chrome paths. Update Asteroids manifest assets, enforce manifest-only bezel/background loading, ensure manifest backgrounds draw in all states, remove opaque game-level fills that hide engine backgrounds, preserve gameplay rendering, and write validation notes to docs/dev/reports/pr_11_88_validation.md."
6+
codex exec --model gpt-5.4-codex --reasoning high --sandbox workspace-write --ask-for-approval never @docs/pr/BUILD_PR_LEVEL_11_89_ASTEROIDS_ENGINE_RENDER_OWNERSHIP_STABILIZATION.md
87
```
98

10-
## Required report
11-
Codex must create:
9+
## Required output from Codex
10+
Codex must create a ZIP artifact at:
1211

1312
```text
14-
docs/dev/reports/pr_11_88_validation.md
13+
C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\tmp\PR_11_89_ASTEROIDS_ENGINE_RENDER_OWNERSHIP_STABILIZATION.zip
1514
```
1615

17-
Report must include:
18-
19-
- files changed
20-
- manifest chrome asset declarations verified
21-
- guessed chrome path search results
22-
- background visible states checked
23-
- console 404 check result
24-
- `src/engine/utils/` search result
25-
- whether full sample suite was skipped and why
16+
The ZIP must include changed repo files and:
17+
- docs/pr/PLAN_PR_LEVEL_11_89_ASTEROIDS_ENGINE_RENDER_OWNERSHIP_STABILIZATION.md
18+
- docs/pr/BUILD_PR_LEVEL_11_89_ASTEROIDS_ENGINE_RENDER_OWNERSHIP_STABILIZATION.md
19+
- docs/dev/reports/pr_11_89_asteroids_engine_render_ownership_report.md
20+
- docs/dev/codex_commands.md
21+
- docs/dev/commit_comment.txt

‎docs/dev/commit_comment.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Enforce engine-owned game chrome and manifest-only background/bezel loading - PR 11.88
1+
Finish Asteroids engine-owned background/bezel layering and manifest-only chrome loading - PR 11.89

‎docs/dev/reports/pr_11_89_asteroids_engine_render_ownership_report.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# PR 11.89 - Asteroids Engine Render Ownership Stabilization
2+
3+
## Scope and Source of Truth
4+
- BUILD doc: `docs/pr/BUILD_PR_LEVEL_11_89_ASTEROIDS_ENGINE_RENDER_OWNERSHIP_STABILIZATION.md`
5+
- PLAN doc: `docs/pr/PLAN_PR_LEVEL_11_89_ASTEROIDS_ENGINE_RENDER_OWNERSHIP_STABILIZATION.md`
6+
7+
## Files Inspected
8+
- `games/Asteroids/index.js`
9+
- `games/Asteroids/game.manifest.json`
10+
- `games/Asteroids/game/AsteroidsGameScene.js`
11+
- `games/Asteroids/game/AsteroidsAttractAdapter.js`
12+
- `games/Asteroids/game/FullscreenBezelOverlay.js`
13+
- `src/engine/runtime/backgroundImage.js`
14+
- `src/engine/runtime/gameImageConvention.js`
15+
- `src/engine/runtime/fullscreenBezel.js`
16+
- `scripts/run-node-tests.mjs`
17+
18+
## Baseline Search Findings (Before Fix)
19+
20+
### Command
21+
`Select-String -Path .\games\Asteroids\**\*.js -Pattern "clearRect|fillRect|drawRect|background|bezel|chrome|overlay|rgba|globalAlpha" -CaseSensitive:$false`
22+
23+
### Result (high-signal)
24+
- `games/Asteroids/game/AsteroidsGameScene.js`: full-canvas draws are translucent when manifest background present (`rgba(...,0.22)`), opaque fallback only when manifest background unavailable.
25+
- `games/Asteroids/game/AsteroidsAttractAdapter.js`: attract overlay uses translucent fill when manifest background present (`rgba(...,0.36)`), stronger dim only when background unavailable.
26+
- `games/Asteroids/game/FullscreenBezelOverlay.js`: resolves bezel by asset id (`image.asteroids.bezel`), not guessed image path.
27+
28+
### Command
29+
`Select-String -Path .\games\Asteroids\**\*.* -Pattern "bezel.png|background.png|bezel1.png|deluxe.png|image.asteroids.bezel|image.asteroids.background" -CaseSensitive:$false`
30+
31+
### Result (high-signal)
32+
- Found `image.asteroids.bezel` id usage in `FullscreenBezelOverlay.js`.
33+
- Manifest initially still referenced `/games/Asteroids/assets/images/bezel.png` (required correction to `bezel1.png`).
34+
35+
### Command
36+
`Select-String -Path .\src\**\*.js, .\games\**\*.js -Pattern "/games/.*/assets/images/bezel.png|/games/.*/assets/images/background.png" -CaseSensitive:$false`
37+
38+
### Result
39+
- No matches in active source JS.
40+
41+
### Command
42+
`Select-String -Path .\games\Asteroids\game.manifest.json -Pattern "asset-browser|stretchOverride|image.asteroids.bezel|image.asteroids.background|bezel1.png|deluxe.png" -CaseSensitive:$false`
43+
44+
### Result (baseline)
45+
- `image.asteroids.bezel` present with `stretchOverride.uniformEdgeStretchPx = 10`.
46+
- `image.asteroids.background` present and points to `deluxe.png`.
47+
- Bezel path required correction from `bezel.png` to `bezel1.png`.
48+
49+
## Changes Made
50+
1. Updated manifest bezel path:
51+
- `games/Asteroids/game.manifest.json`
52+
- `image.asteroids.bezel.path`
53+
- from: `/games/Asteroids/assets/images/bezel.png`
54+
- to: `/games/Asteroids/assets/images/bezel1.png`
55+
56+
2. Renamed asset file to match manifest declaration:
57+
- from: `games/Asteroids/assets/images/bezel.png`
58+
- to: `games/Asteroids/assets/images/bezel1.png`
59+
60+
## Manifest Correction Verification (After Fix)
61+
- `image.asteroids.bezel.path = /games/Asteroids/assets/images/bezel1.png`
62+
- `image.asteroids.bezel.stretchOverride.uniformEdgeStretchPx = 10`
63+
- `image.asteroids.background.path = /games/Asteroids/assets/images/deluxe.png`
64+
- No duplicate `asset-browser.assets.bezel.stretchOverride` block introduced.
65+
66+
## Remaining Full-Screen Fills and Why Safe
67+
- `AsteroidsGameScene` base full-canvas fill is translucent (`rgba(2, 6, 23, 0.22)`) when manifest background exists.
68+
- `AsteroidsAttractAdapter` full-canvas dim is translucent (`rgba(2, 6, 23, 0.36)`) when manifest background exists.
69+
- `PAUSE_OVERLAY_COLOR` and initials entry overlays are translucent and intentionally preserve background visibility/readability.
70+
- Opaque fallback clears remain only for no-background conditions and are not persistent suppression of a declared manifest background.
71+
72+
## Before/After Guessed-Path Search
73+
74+
### Before
75+
- JS source guessed path search (`/games/.*/assets/images/bezel.png|background.png`): 0 matches.
76+
- Manifest bezel path was still `bezel.png` (not guessed runtime behavior, but mismatched required asset name).
77+
78+
### After
79+
- JS source guessed path search: 0 matches.
80+
- Manifest now uses required `bezel1.png` path and existing `deluxe.png` background path.
81+
82+
## Before/After `src/engine/utils/` Search
83+
84+
### Command
85+
`Select-String -Path .\src\**\*.js, .\games\**\*.js -Pattern "src/engine/utils/|/src/engine/utils/" -CaseSensitive:$false`
86+
87+
### Result
88+
- Before: 0 matches
89+
- After: 0 matches
90+
91+
## Validation Commands Run
92+
1. Required command from BUILD:
93+
- `npm test -- --runInBand`
94+
- Result: **failed during pretest guard** (`checkSharedExtractionGuard`) with existing repository-wide baseline violations unrelated to this PR's manifest/render ownership scope.
95+
96+
2. Supported targeted runtime validation (used per BUILD fallback guidance):
97+
- `npm run test:launch-smoke:games`
98+
- Result: **PASS (12/12)**, including `Asteroids` and `SolarSystem`.
99+
100+
## Manual/Browser Checklist Documentation
101+
- Workspace Manager launch + multi-state visual verification was not executed interactively in this CLI session.
102+
- Evidence used:
103+
- Source-level ownership verification in Asteroids render paths.
104+
- Manifest path correction verification.
105+
- Automated game launch smoke pass across all games with no launch failures.
106+
- Console 404 proxy check from smoke run:
107+
- No failing entries reported for Asteroids/SolarSystem.
108+
109+
## Full Samples Suite
110+
- Skipped intentionally.
111+
- Reason: BUILD directs targeted validation only; this PR is scoped to Asteroids manifest/chrome/render ownership stabilization and does not modify broad sample framework behavior.

‎docs/pr/BUILD_PR_LEVEL_11_89_ASTEROIDS_ENGINE_RENDER_OWNERSHIP_STABILIZATION.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# BUILD_PR_LEVEL_11_89_ASTEROIDS_ENGINE_RENDER_OWNERSHIP_STABILIZATION
2+
3+
## Codex Task
4+
Implement PLAN_PR_LEVEL_11_89_ASTEROIDS_ENGINE_RENDER_OWNERSHIP_STABILIZATION.
5+
6+
## Execution mode
7+
Correctness-first stabilization. Do not rush. Inspect before editing.
8+
9+
## Required steps
10+
11+
### 1. Baseline search
12+
Run searches and save findings to:
13+
`docs/dev/reports/pr_11_89_asteroids_engine_render_ownership_report.md`
14+
15+
Required searches:
16+
```powershell
17+
Select-String -Path .\games\Asteroids\**\*.js -Pattern "clearRect|fillRect|drawRect|background|bezel|chrome|overlay|rgba|globalAlpha" -CaseSensitive:$false
18+
Select-String -Path .\games\Asteroids\**\*.* -Pattern "bezel.png|background.png|bezel1.png|deluxe.png|image.asteroids.bezel|image.asteroids.background" -CaseSensitive:$false
19+
Select-String -Path .\src\**\*.js,.\games\**\*.js -Pattern "/games/.*/assets/images/bezel.png|/games/.*/assets/images/background.png" -CaseSensitive:$false
20+
Select-String -Path .\games\Asteroids\game.manifest.json -Pattern "asset-browser|stretchOverride|image.asteroids.bezel|image.asteroids.background|bezel1.png|deluxe.png" -CaseSensitive:$false
21+
```
22+
23+
### 2. Manifest correction
24+
Update `games/Asteroids/game.manifest.json` so:
25+
- `image.asteroids.bezel` path is `/games/Asteroids/assets/images/bezel1.png`
26+
- `image.asteroids.background` path is `/games/Asteroids/assets/images/deluxe.png`
27+
- `image.asteroids.bezel` includes:
28+
```json
29+
"stretchOverride": {
30+
"uniformEdgeStretchPx": 10
31+
}
32+
```
33+
- no duplicate bezel stretch config exists under `asset-browser.assets.bezel`
34+
35+
### 3. Engine-owned background
36+
Ensure the engine draws declared background in all states:
37+
- menu
38+
- attract
39+
- pause
40+
- gameplay
41+
42+
Remove or correct any Asteroids mode gate that prevents declared background rendering.
43+
44+
### 4. No opaque game suppression
45+
Find any Asteroids full-canvas clear/fill/overlay after background rendering.
46+
- Remove clear/fill if it duplicates engine clear.
47+
- Convert required dim overlays to transparent overlays that keep background visible.
48+
- Do not allow full opacity over the entire canvas unless it is an explicit gameplay flash/effect and not persistent.
49+
50+
### 5. Manifest-only chrome source
51+
Remove all guessed/fallback loading of chrome paths:
52+
- `bezel.png`
53+
- `background.png`
54+
- any derived `/games/<Game>/assets/images/bezel.png`
55+
- any derived `/games/<Game>/assets/images/background.png`
56+
57+
Chrome assets must be loaded only if declared in manifest. Missing optional chrome renders safe empty state with no network request.
58+
59+
### 6. Import/path verification
60+
Do not leave broken imports or stale references introduced by previous PRs.
61+
Run:
62+
```powershell
63+
Select-String -Path .\src\**\*.js,.\games\**\*.js -Pattern "src/engine/utils/|/src/engine/utils/" -CaseSensitive:$false
64+
```
65+
Expected: zero results, unless the occurrence is inside a report/documentation file. Do not alter unrelated docs.
66+
67+
### 7. Targeted validation
68+
Run only targeted validation; do not run full samples suite.
69+
70+
Required:
71+
```powershell
72+
npm test -- --runInBand
73+
```
74+
If the repo does not support this exact command, document the supported targeted command used instead.
75+
76+
Manual/browser validation checklist to document:
77+
- Open Workspace Manager.
78+
- Launch Asteroids.
79+
- Confirm no 404s for bezel/background.
80+
- Confirm background visible in menu.
81+
- Confirm background visible in attract.
82+
- Confirm background visible in pause.
83+
- Confirm background visible in gameplay.
84+
- Confirm bezel visible.
85+
- Confirm bezel stretch uses manifest override.
86+
87+
### 8. Report
88+
Create:
89+
`docs/dev/reports/pr_11_89_asteroids_engine_render_ownership_report.md`
90+
91+
Include:
92+
- files inspected
93+
- changes made
94+
- remaining full-screen fills, if any, and why they are safe
95+
- before/after guessed-path search result
96+
- before/after `src/engine/utils/` search result
97+
- validation commands run
98+
- whether full samples test was skipped and why
99+
100+
## Roadmap
101+
If touching roadmap, status-only updates only. Do not rewrite roadmap text.

‎docs/pr/PLAN_PR_LEVEL_11_89_ASTEROIDS_ENGINE_RENDER_OWNERSHIP_STABILIZATION.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# PLAN_PR_LEVEL_11_89_ASTEROIDS_ENGINE_RENDER_OWNERSHIP_STABILIZATION
2+
3+
## Purpose
4+
Finish the Asteroids engine-alignment work correctly, not quickly.
5+
6+
Asteroids must use the engine for engine-owned responsibilities and must not override or obscure engine chrome/layering behavior.
7+
8+
## Scope
9+
This PR audits and fixes Asteroids render ownership only.
10+
11+
Engine-owned:
12+
- frame clear behavior
13+
- manifest-only background loading
14+
- manifest-only bezel loading
15+
- background draw order
16+
- bezel draw order
17+
- chrome layering
18+
- optional empty-state behavior when manifest chrome is absent
19+
20+
Asteroids-owned:
21+
- gameplay entities
22+
- score/lives/game-specific HUD
23+
- game-specific vector drawing
24+
- gameplay state transitions
25+
26+
## Required audit targets
27+
Codex must inspect at minimum:
28+
- games/Asteroids/index.js
29+
- games/Asteroids/game.manifest.json
30+
- games/Asteroids/src/AsteroidsGameScene.js
31+
- games/Asteroids/src/AsteroidsAttractAdapter.js
32+
- any Asteroids file matching background, bezel, chrome, clear, fillRect, drawRect, overlay
33+
- engine background/chrome modules touched by PR 11.83 through PR 11.88
34+
- any manifest/chrome asset loader used by Asteroids
35+
36+
## Required fixes
37+
1. Asteroids must not hardcode or guess bezel/background asset paths.
38+
2. Asteroids must not load `/games/Asteroids/assets/images/bezel.png`.
39+
3. Asteroids must not load `/games/Asteroids/assets/images/background.png`.
40+
4. Asteroids must not load `/games/SolarSystem/assets/images/bezel.png` or `/background.png`.
41+
5. Background and bezel must come only from `game.manifest.json`.
42+
6. Asteroids must not gate engine background visibility by mode.
43+
7. Background must be visible in menu, attract, pause, and gameplay when declared in manifest.
44+
8. Asteroids must not clear the full canvas after the engine background is drawn.
45+
9. Asteroids must not draw a full-screen opaque fill that hides a manifest background.
46+
10. Any menu/attract/pause dimming must be transparent and must preserve visible background.
47+
11. Bezel stretch override must live only on `image.*.bezel` manifest entries, not under asset-browser duplicate config.
48+
12. Asteroids manifest must declare:
49+
- `image.asteroids.bezel.path` = `/games/Asteroids/assets/images/bezel1.png`
50+
- `image.asteroids.background.path` = `/games/Asteroids/assets/images/deluxe.png`
51+
- `image.asteroids.bezel.stretchOverride.uniformEdgeStretchPx` = `10`
52+
53+
## Explicit non-goals
54+
- Do not refactor gameplay logic.
55+
- Do not convert Asteroids audio unless directly required for render correctness.
56+
- Do not touch unrelated games except shared engine code required to enforce manifest-only chrome loading.
57+
- Do not add fallback/default chrome assets.
58+
- Do not create aliases or shims.
59+
- Do not use hardcoded asset paths outside manifests.
60+
61+
## Acceptance
62+
- No browser 404s for guessed bezel/background paths.
63+
- Asteroids background is visible in menu, attract, pause, and gameplay.
64+
- Asteroids bezel is visible and uses manifest stretch override.
65+
- No full-screen opaque fills hide the background.
66+
- No game-level background ownership remains.
67+
- Manifest is the single source of truth for Asteroids chrome assets.
68+
- Targeted validation report documents exact files inspected and exact checks performed.

0 commit comments

Comments
 (0)