Polish real gameplay sample into a complete mini-game with UI, feedback, and full game loop.

PR: BUILD_PR_LEVEL_17_40_SAMPLE_1710_REAL_GAMEPLAY_POLISH

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,3 +1,3 @@
 MODEL: GPT-5.3-codex
 REASONING: high
-COMMAND: Create Sample 1709 Movement Models Lab using existing engine systems only. Demonstrate direct x/y movement, rotation/tank controls, and optionally weighted movement if already supportable. Add camera follow, visible mode labels, register the sample in samples/index.html, and package the repo-structured result to <project folder>/tmp/BUILD_PR_LEVEL_17_39_SAMPLE_1709_MOVEMENT_MODELS_LAB.zip
+COMMAND: Polish Sample 1708 into a complete mini-game with feedback, UI, and full game loop using existing systems only, then package to <project folder>/tmp/BUILD_PR_LEVEL_17_40_SAMPLE_1710_REAL_GAMEPLAY_POLISH.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1,3 +1,3 @@
-Add Sample 1709 Movement Models Lab to compare direct movement, tank controls, and optional weighted movement with camera follow and visible mode labels.
+Polish real gameplay sample into a complete mini-game with UI, feedback, and full game loop.
 
-PR: BUILD_PR_LEVEL_17_39_SAMPLE_1709_MOVEMENT_MODELS_LAB
+PR: BUILD_PR_LEVEL_17_40_SAMPLE_1710_REAL_GAMEPLAY_POLISH

docs/dev/reports/validation_checklist.txt

@@ -1,7 +1,5 @@
-- [ ] sample loads from samples/index.html
-- [ ] direct x/y movement works
-- [ ] tank/rotation movement works
-- [ ] optional weighted movement works if implemented
-- [ ] camera follows correctly in all active modes
-- [ ] active mode label/instructions visible
+- [ ] game loop complete
+- [ ] score visible
+- [ ] restart works
+- [ ] debug panels intact
 - [ ] no console errors

docs/pr/BUILD_PR_LEVEL_17_40_SAMPLE_1710_REAL_GAMEPLAY_POLISH.md

@@ -0,0 +1,31 @@
+# BUILD_PR_LEVEL_17_40_SAMPLE_1710_REAL_GAMEPLAY_POLISH
+
+## Purpose
+Polish Sample `1708` into a complete mini-game experience using existing systems only.
+
+## Source of Truth
+- `docs/pr/PLAN_PR_LEVEL_17_40_SAMPLE_1710_REAL_GAMEPLAY_POLISH.md`
+- existing sample implementation in `samples/phase-17/1708/`
+
+## Exact Build Target
+1. Polish `samples/phase-17/1708/RealGameplayMiniGameScene.js` with:
+   - stronger visual feedback for player events (hit/collect/match state)
+   - complete state flow (`ready` -> `running` -> `won|lost`)
+   - restart path and clear instructions
+   - improved HUD/readability while preserving existing controls
+2. Keep standard 3D debug camera/collision panel integration working.
+3. Update targeted runtime validation to verify the full loop and debug-panel output.
+
+## Constraints
+- use existing engine systems only
+- no engine-core changes
+- keep scope to sample `1708` polish and targeted validation only
+
+## Validation
+- polished sample state flow is testable end-to-end
+- debug panels still emit visible lines
+- no runtime errors in targeted test execution
+
+## Packaging Rule
+Package only this PR's created/modified files into:
+`tmp/BUILD_PR_LEVEL_17_40_SAMPLE_1710_REAL_GAMEPLAY_POLISH.zip`

docs/pr/PLAN_PR_LEVEL_17_40_SAMPLE_1710_REAL_GAMEPLAY_POLISH.md

@@ -0,0 +1,15 @@
+# PLAN_PR_LEVEL_17_40_SAMPLE_1710_REAL_GAMEPLAY_POLISH
+
+## Purpose
+Polish Sample 1708 into a complete, presentable mini-game.
+
+## Scope
+Enhance gameplay clarity, feedback, and completeness.
+
+## Focus
+- visual polish
+- feedback systems
+- game loop completeness
+
+## Out of Scope
+- new engine systems