Add advanced readability and camera enhancements to Phase 16 samples<BUILD_PR_LEVEL_17_15_ADVANCED_3D_SAMPLE_EXTENSIONS>

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -3,15 +3,19 @@ MODEL: GPT-5.3-codex
 REASONING: high
 
 COMMAND:
-Implement Sample 1608 dungeon crawler core loop.
+Add advanced but safe enhancements to Phase 16 samples.
+
+Focus:
+- camera mode toggle
+- simple shading/depth cues
+- debug overlay
 
 Rules:
 - smallest scoped change
+- sample-only
 - no zip output
-- sample only
 
 Validate:
-- movement works
-- collision blocks
-- interaction visible
+- features visibly work
+- no regressions
 - sanity + smoke pass

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-Add core dungeon crawler loop to Sample 1608<BUILD_PR_LEVEL_17_14_SAMPLE_1608_DUNGEON_CRAWLER_CORE_LOOP>
+Add advanced readability and camera enhancements to Phase 16 samples<BUILD_PR_LEVEL_17_15_ADVANCED_3D_SAMPLE_EXTENSIONS>

docs/dev/reports/change_summary.txt

@@ -1 +1 @@
-1608 now has a readable dungeon loop with movement, blocking collision, and interaction.
+Adds camera modes, shading cues, and debug overlays to improve 3D sample clarity.

docs/dev/reports/launch_smoke_report.md

@@ -1,9 +1,16 @@
 # Launch Smoke Report
 
-Generated: 2026-04-15T21:47:58.859Z
+Generated: 2026-04-15T21:59:22.383Z
 
-Filters: games=false, samples=true, tools=false, sampleRange=1608-1608
+Filters: games=false, samples=true, tools=false, sampleRange=1601-1608
 
 | Status | Type | Label | Path | Notes | Steps |
 | --- | --- | --- | --- | --- | --- |
+| PASS | sample | 1601 | samples\phase-16\1601\index.html |  | npm install --prefix ./tmp ws → npm run test:launch-smoke |
+| PASS | sample | 1602 | samples\phase-16\1602\index.html |  | npm install --prefix ./tmp ws → npm run test:launch-smoke |
+| PASS | sample | 1603 | samples\phase-16\1603\index.html |  | npm install --prefix ./tmp ws → npm run test:launch-smoke |
+| PASS | sample | 1604 | samples\phase-16\1604\index.html |  | npm install --prefix ./tmp ws → npm run test:launch-smoke |
+| PASS | sample | 1605 | samples\phase-16\1605\index.html |  | npm install --prefix ./tmp ws → npm run test:launch-smoke |
+| PASS | sample | 1606 | samples\phase-16\1606\index.html |  | npm install --prefix ./tmp ws → npm run test:launch-smoke |
+| PASS | sample | 1607 | samples\phase-16\1607\index.html |  | npm install --prefix ./tmp ws → npm run test:launch-smoke |
 | PASS | sample | 1608 | samples\phase-16\1608\index.html |  | npm install --prefix ./tmp ws → npm run test:launch-smoke |

docs/dev/reports/validation_checklist.txt

@@ -1,7 +1,6 @@
 
-[ ] movement works
-[ ] walls block
-[ ] interaction visible
-[ ] loop understandable
+[ ] camera toggle works
+[ ] shading improves readability
+[ ] debug overlay visible
 [ ] sanity pass
 [ ] smoke pass

docs/pr/BUILD_PR_LEVEL_17_15_ADVANCED_3D_SAMPLE_EXTENSIONS.md

@@ -0,0 +1,22 @@
+
+# BUILD PR: 17.15 Advanced 3D Sample Extensions
+
+## Purpose
+Extend Phase 16 samples with advanced but still safe, testable capabilities.
+
+## Scope
+- camera modes (follow, free look toggle)
+- simple lighting/shading hint (fake shading ok)
+- depth ordering clarity improvements
+- optional debug overlay (position, velocity)
+
+## Constraints
+- no engine changes
+- sample-only enhancements
+- no networking or 2D impact
+
+## Acceptance
+- camera mode toggle works
+- shading/depth improves readability
+- debug overlay optional and useful
+- sanity + smoke pass

samples/phase-16/1601/CubeExplorer3DScene.js

@@ -9,6 +9,13 @@ import { Theme, ThemeTokens } from '/src/engine/theme/index.js';
 import { drawFrame, drawPanel } from '/src/engine/debug/index.js';
 import { World } from '/src/engine/ecs/index.js';
 import { stepWorldPhysics3D } from '/src/engine/systems/index.js';
+import {
+  applyPhase16CameraMode,
+  createPhase16ViewState,
+  drawDepthBackdrop,
+  drawPhase16DebugOverlay,
+  stepPhase16ViewToggles,
+} from '../shared/threeDWireframe.js';
 
 const theme = new Theme(ThemeTokens);
 const BOX_EDGES = [
@@ -91,7 +98,10 @@ function drawWireBox(renderer, transform3D, size3D, cameraState, viewport, color
     if (!start || !end) {
       continue;
     }
-    renderer.drawLine(start.x, start.y, end.x, end.y, color, 2);
+    const edgeDepth = (start.depth + end.depth) * 0.5;
+    const depthT = clamp((edgeDepth - 3) / 40, 0, 1);
+    const edgeWidth = 2.2 - depthT * 1.1;
+    renderer.drawLine(start.x, start.y, end.x, end.y, color, Math.max(1, edgeWidth));
   }
 }
 
@@ -120,6 +130,7 @@ export default class CubeExplorer3DScene extends Scene {
       depth: 22,
     };
     this.lastPhysicsSummary = { movedEntities: 0, collisionCount: 0 };
+    this.viewState = createPhase16ViewState();
 
     this.playerId = this.world.createEntity();
     this.world.addComponent(this.playerId, 'transform3D', {
@@ -175,21 +186,29 @@ export default class CubeExplorer3DScene extends Scene {
     const cameraZ = playerTransform.z - Math.cos(this.cameraYaw) * orbitDistance;
     const cameraY = playerTransform.y + 4.8;
 
-    this.camera3D.setPosition({
-      x: cameraX,
-      y: cameraY,
-      z: cameraZ,
-    });
-    this.camera3D.setRotation({
-      x: this.cameraPitch,
-      y: this.cameraYaw,
-      z: 0,
+    const basePose = {
+      position: {
+        x: cameraX,
+        y: cameraY,
+        z: cameraZ,
+      },
+      rotation: {
+        x: this.cameraPitch,
+        y: this.cameraYaw,
+        z: 0,
+      },
+    };
+    applyPhase16CameraMode(this.camera3D, this.viewState, basePose, {
+      x: playerTransform.x + 0.8,
+      y: playerTransform.y + 0.8,
+      z: playerTransform.z + 0.8,
     });
   }
 
   step3DPhysics(dt, engine) {
     const velocity = this.world.requireComponent(this.playerId, 'velocity3D');
     const input = engine.input;
+    stepPhase16ViewToggles(this.viewState, input);
 
     velocity.x = 0;
     velocity.y = 0;
@@ -217,7 +236,7 @@ export default class CubeExplorer3DScene extends Scene {
     drawFrame(renderer, theme, [
       'Sample 1601 - 3D Cube Explorer',
       'Minimal 3D movement + AABB collision using an isolated physics loop',
-      'Move: W A S D | Vertical: R/F | Camera orbit: Arrow keys',
+      'Move: W A S D | Vertical: R/F | Camera orbit: Arrow keys | Camera: C | Debug: V',
       'Goal: navigate around blocking boxes while remaining inside world bounds',
     ]);
 
@@ -229,6 +248,7 @@ export default class CubeExplorer3DScene extends Scene {
       '#d8d5ff',
       2,
     );
+    drawDepthBackdrop(renderer, this.viewport);
 
     const cameraState = this.camera3D?.getState?.() ?? {
       position: { x: 0, y: 3, z: -8 },
@@ -277,12 +297,17 @@ export default class CubeExplorer3DScene extends Scene {
     });
 
     const player = this.world.requireComponent(this.playerId, 'transform3D');
-    drawPanel(renderer, 620, 34, 300, 126, '3D Runtime', [
+    drawPanel(renderer, 620, 34, 300, 156, '3D Runtime', [
       `Cube: x=${player.x.toFixed(2)} y=${player.y.toFixed(2)} z=${player.z.toFixed(2)}`,
       `Camera yaw: ${this.cameraYaw.toFixed(2)} pitch: ${this.cameraPitch.toFixed(2)}`,
       `Moved entities: ${this.lastPhysicsSummary.movedEntities}`,
       `Resolved collisions: ${this.lastPhysicsSummary.collisionCount}`,
       'Physics loop: stepWorldPhysics3D (MovementSystem + AABB)',
     ]);
+
+    drawPhase16DebugOverlay(renderer, this.viewport, this.viewState, [
+      `Yaw: ${this.cameraYaw.toFixed(2)} | Pitch: ${this.cameraPitch.toFixed(2)}`,
+      `Collisions/frame: ${this.lastPhysicsSummary.collisionCount}`,
+    ]);
   }
 }

samples/phase-16/1602/MazeRunner3DScene.js

@@ -10,7 +10,16 @@ import { drawFrame, drawPanel } from '/src/engine/debug/index.js';
 import { World } from '/src/engine/ecs/index.js';
 import { isAabbColliding3D } from '/src/engine/physics/index.js';
 import { stepWorldPhysics3D } from '/src/engine/systems/index.js';
-import { createProjectionViewport, drawGroundGrid, drawWireBox } from '../shared/threeDWireframe.js';
+import {
+  applyPhase16CameraMode,
+  createPhase16ViewState,
+  createProjectionViewport,
+  drawDepthBackdrop,
+  drawGroundGrid,
+  drawPhase16DebugOverlay,
+  drawWireBox,
+  stepPhase16ViewToggles,
+} from '../shared/threeDWireframe.js';
 
 const theme = new Theme(ThemeTokens);
 
@@ -44,6 +53,7 @@ export default class MazeRunner3DScene extends Scene {
     };
     this.goalReached = false;
     this.lastPhysicsSummary = { movedEntities: 0, collisionCount: 0 };
+    this.viewState = createPhase16ViewState();
 
     this.playerId = this.world.createEntity();
     this.world.addComponent(this.playerId, 'transform3D', {
@@ -109,20 +119,28 @@ export default class MazeRunner3DScene extends Scene {
     }
 
     const player = this.world.requireComponent(this.playerId, 'transform3D');
-    this.camera3D.setPosition({
-      x: player.x,
-      y: 10.2,
-      z: player.z - 10.6,
-    });
-    this.camera3D.setRotation({
-      x: -0.5,
-      y: 0,
-      z: 0,
+    const basePose = {
+      position: {
+        x: player.x,
+        y: 10.2,
+        z: player.z - 10.6,
+      },
+      rotation: {
+        x: -0.5,
+        y: 0,
+        z: 0,
+      },
+    };
+    applyPhase16CameraMode(this.camera3D, this.viewState, basePose, {
+      x: player.x + 0.55,
+      y: player.y + 0.55,
+      z: player.z + 0.55,
     });
   }
 
   step3DPhysics(dt, engine) {
     const input = engine.input;
+    stepPhase16ViewToggles(this.viewState, input);
     const velocity = this.world.requireComponent(this.playerId, 'velocity3D');
 
     const axisX = (input?.isDown('KeyD') ? 1 : 0) - (input?.isDown('KeyA') ? 1 : 0);
@@ -157,11 +175,12 @@ export default class MazeRunner3DScene extends Scene {
     drawFrame(renderer, theme, [
       'Sample 1602 - 3D Maze Runner',
       'Navigate through a 3D maze while physics keeps the cube outside wall bounds.',
-      'Move: W A S D',
+      'Move: W A S D | Camera: C | Debug: V',
       this.goalReached ? 'Goal reached: route solved.' : 'Find the green goal cube near the far-right corner.',
     ]);
 
     renderer.strokeRect(this.viewport.x, this.viewport.y, this.viewport.width, this.viewport.height, '#d8d5ff', 2);
+    drawDepthBackdrop(renderer, this.viewport);
 
     const cameraState = this.camera3D?.getState?.() ?? {
       position: { x: 0, y: 10.2, z: -7.4 },
@@ -211,5 +230,10 @@ export default class MazeRunner3DScene extends Scene {
       `Goal: ${this.goalReached ? 'reached' : 'in progress'}`,
       'Pathing: stepWorldPhysics3D (AABB walls)',
     ]);
+
+    drawPhase16DebugOverlay(renderer, this.viewport, this.viewState, [
+      `Goal status: ${this.goalReached ? 'reached' : 'pending'}`,
+      `Collisions/frame: ${this.lastPhysicsSummary.collisionCount}`,
+    ]);
   }
 }

samples/phase-16/1603/FirstPersonWalkthroughScene.js

@@ -9,7 +9,16 @@ import { Theme, ThemeTokens } from '/src/engine/theme/index.js';
 import { drawFrame, drawPanel } from '/src/engine/debug/index.js';
 import { World } from '/src/engine/ecs/index.js';
 import { stepWorldPhysics3D } from '/src/engine/systems/index.js';
-import { createProjectionViewport, drawGroundGrid, drawWireBox } from '../shared/threeDWireframe.js';
+import {
+  applyPhase16CameraMode,
+  createPhase16ViewState,
+  createProjectionViewport,
+  drawDepthBackdrop,
+  drawGroundGrid,
+  drawPhase16DebugOverlay,
+  drawWireBox,
+  stepPhase16ViewToggles,
+} from '../shared/threeDWireframe.js';
 
 const theme = new Theme(ThemeTokens);
 
@@ -42,6 +51,7 @@ export default class FirstPersonWalkthroughScene extends Scene {
       depth: 26,
     };
     this.lastPhysicsSummary = { movedEntities: 0, collisionCount: 0 };
+    this.viewState = createPhase16ViewState();
 
     this.playerId = this.world.createEntity();
     this.world.addComponent(this.playerId, 'transform3D', {
@@ -106,20 +116,28 @@ export default class FirstPersonWalkthroughScene extends Scene {
     }
 
     const player = this.world.requireComponent(this.playerId, 'transform3D');
-    this.camera3D.setPosition({
+    const basePose = {
+      position: {
+        x: player.x + 0.45,
+        y: player.y + 1.2,
+        z: player.z + 0.45,
+      },
+      rotation: {
+        x: this.pitch,
+        y: -this.yaw,
+        z: 0,
+      },
+    };
+    applyPhase16CameraMode(this.camera3D, this.viewState, basePose, {
       x: player.x + 0.45,
-      y: player.y + 1.2,
+      y: player.y + 0.9,
       z: player.z + 0.45,
     });
-    this.camera3D.setRotation({
-      x: this.pitch,
-      y: -this.yaw,
-      z: 0,
-    });
   }
 
   step3DPhysics(dt, engine) {
     const input = engine.input;
+    stepPhase16ViewToggles(this.viewState, input);
     const velocity = this.world.requireComponent(this.playerId, 'velocity3D');
 
     const lookX = (input?.isDown('ArrowRight') ? 1 : 0) - (input?.isDown('ArrowLeft') ? 1 : 0);
@@ -153,11 +171,12 @@ export default class FirstPersonWalkthroughScene extends Scene {
     drawFrame(renderer, theme, [
       'Sample 1603 - First Person Walkthrough',
       'Navigate from a first-person camera while AABB collisions keep movement grounded.',
-      'Move: W A S D | Look: Arrow Keys',
+      'Move: W A S D | Look: Arrow Keys | Camera: C | Debug: V',
       'Stay centered in the lane and navigate around interior blockers.',
     ]);
 
     renderer.strokeRect(this.viewport.x, this.viewport.y, this.viewport.width, this.viewport.height, '#d8d5ff', 2);
+    drawDepthBackdrop(renderer, this.viewport);
 
     const cameraState = this.camera3D?.getState?.() ?? {
       position: { x: 0, y: 1.2, z: 2.5 },
@@ -202,5 +221,10 @@ export default class FirstPersonWalkthroughScene extends Scene {
       `Resolved collisions: ${this.lastPhysicsSummary.collisionCount}`,
       'View mode: first person + collision-aware movement',
     ]);
+
+    drawPhase16DebugOverlay(renderer, this.viewport, this.viewState, [
+      `Yaw: ${this.yaw.toFixed(2)} | Pitch: ${this.pitch.toFixed(2)}`,
+      `Collisions/frame: ${this.lastPhysicsSummary.collisionCount}`,
+    ]);
   }
 }