Improve Sample 1605 readability with vehicle-facing rotation and a behind-the-car chase camera<BUILD_PR_LEVEL_17_10_SAMPLE_1605_CHASE_CAMERA_AND_VEHICLE_FACING>

DavidQ · DavidQ · commit bbfbb8c3cc77 · 2026-04-15T16:36:06.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,10 +2,10 @@ MODEL: GPT-5.3-codex
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_LEVEL_17_9_SAMPLE_1605_DRIVING_CONTROL_FIX.
+Create BUILD_PR_LEVEL_17_10_SAMPLE_1605_CHASE_CAMERA_AND_VEHICLE_FACING.
 
 Goal:
-Fix Sample 1605 - 3D Driving Sandbox so left/right steering no longer gets stuck.
+Make Sample 1605 read clearly as a driving sandbox by ensuring the driven object turns with heading and the camera follows from behind.
 
 Constraints:
 - one PR purpose only
@@ -14,18 +14,22 @@ Constraints:
 - no zip output from Codex
 - keep 2D and networking untouched
 - do not modify start_of_day
+- preserve the prior 1605 steering fix
 
 Implement:
 1. Inspect samples/phase-16/1605/DrivingSandbox3DScene.js.
-2. Fix the steering/input-state bug causing left/right navigation to stick.
-3. Preserve current visible 3D output and forward/reverse behavior.
-4. Add or extend the smallest targeted behavioral sanity check if useful.
+2. Ensure the rendered vehicle/box orientation matches heading.
+3. Convert or tune the current camera into a chase camera that stays behind the driven object by default.
+4. Keep framing simple, stable, and readable.
+5. Preserve forward/reverse and current steering behavior.
+6. Extend the smallest targeted behavioral sanity check only if useful.
 
 Validate:
-- verify left turn works while held
-- verify right turn works while held
-- verify steering stops when released
-- verify opposite turn can be engaged immediately
+- verify vehicle visibly turns with heading
+- verify camera stays behind the vehicle during normal driving
+- verify vehicle remains visible during turning
+- verify forward/reverse still function
+- verify steering still behaves correctly
 - verify sample still renders on load
 - run targeted smoke for 1605
 - update:
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-Fix stuck left/right steering behavior in Sample 1605 driving controls with targeted validation<BUILD_PR_LEVEL_17_9_SAMPLE_1605_DRIVING_CONTROL_FIX>
+Improve Sample 1605 readability with vehicle-facing rotation and a behind-the-car chase camera<BUILD_PR_LEVEL_17_10_SAMPLE_1605_CHASE_CAMERA_AND_VEHICLE_FACING>
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,17 +1,21 @@
 Observed issue:
-- Sample 1605 renders and loads
-- steering behavior gets stuck left/right
+- Sample 1605 steering no longer sticks
+- sample still feels hard to read as a driving sandbox
+- camera can lose the vehicle
+- vehicle heading may not be visually obvious
 
 Applied fix:
-- isolated steering correction in samples/phase-16/1605/DrivingSandbox3DScene.js
-- removed reverse-dependent steering inversion so A/D turn direction remains consistent
-- preserved 1605 rendering path and forward/reverse speed model
-- extended existing targeted runtime sanity in tests/runtime/Phase16VisibilitySanity.test.mjs with 1605 steering behavior checks:
-  - left hold
-  - right hold
-  - release stop
-  - immediate opposite engagement
-  - reverse motion
+- tuned Sample 1605 to a stable chase camera profile:
+  - behind-car position based on current heading
+  - chase look-ahead target
+  - mild yaw lag for readable turning
+- kept prior steering fix and existing forward/reverse behavior intact
+- made vehicle facing explicit by drawing a heading-oriented vehicle wireframe and front marker in render path
+- extended existing targeted runtime sanity in tests/runtime/Phase16VisibilitySanity.test.mjs to cover:
+  - chase camera behind-car behavior
+  - visible heading distinction during turn
+  - vehicle visibility during turning/reverse
+  - retained steering/reverse behavior checks
 
 Validation outcome:
 - PASS Phase16VisibilitySanity
diff --git a/docs/dev/reports/launch_smoke_report.md b/docs/dev/reports/launch_smoke_report.md
@@ -1,6 +1,6 @@
 # Launch Smoke Report
 
-Generated: 2026-04-15T20:27:13.340Z
+Generated: 2026-04-15T20:33:44.997Z
 
 Filters: games=false, samples=true, tools=false, sampleRange=1605-1605
 
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,8 +1,8 @@
-Sample 1605 driving control checklist
-[x] left turn works while held
-[x] right turn works while held
-[x] steering stops on release
-[x] opposite direction can engage immediately
+Sample 1605 chase camera checklist
+[x] vehicle visibly turns with heading
+[x] camera stays behind during normal driving
+[x] vehicle remains visible during turning
+[x] steering still behaves correctly
 [x] forward/reverse still function
 [x] sample renders visibly on load
 [x] targeted smoke for 1605 passes
diff --git a/docs/pr/BUILD_PR_LEVEL_17_10_SAMPLE_1605_CHASE_CAMERA_AND_VEHICLE_FACING.md b/docs/pr/BUILD_PR_LEVEL_17_10_SAMPLE_1605_CHASE_CAMERA_AND_VEHICLE_FACING.md
@@ -0,0 +1,65 @@
+# BUILD PR: 17.10 Sample 1605 Chase Camera And Vehicle Facing
+
+## Purpose
+Improve Sample 1605 readability as a driving sample by making the driven object clearly face its heading and keeping the camera behind the vehicle.
+
+## Why This PR Exists
+The current 1605 sample may now accept steering correctly, but it still reads poorly as a driving sandbox because:
+- the driven object can feel visually disconnected from heading
+- the camera can lose the vehicle
+- navigation feels less like driving and more like free movement in 3D space
+
+A driving sample should prioritize orientation clarity over camera experimentation.
+
+## Scope
+Surgically improve Sample 1605 only:
+- make the driven box/vehicle clearly rotate to match heading
+- keep the camera behind the driven object by default
+- preserve existing visible 3D output and current steering fix
+- keep the sample simple and readable
+
+## In Scope
+- samples/phase-16/1605/DrivingSandbox3DScene.js
+- minimal targeted sanity extension if needed
+- docs/dev/reports/* validation updates
+
+## Out of Scope
+- no changes to 1601-1604 or 1606-1608 unless a truly shared safe defect is proven
+- no engine-wide camera abstraction work
+- no advanced vehicle physics rewrite
+- no 2D or networking changes
+- no repo-wide scanning
+- no zip output from Codex
+
+## Desired Behavior
+- left/right steering changes vehicle heading
+- the driven object visually turns with heading
+- camera follows from behind the driven object
+- camera framing remains stable enough that the player does not lose the vehicle during normal driving
+- forward/reverse remain usable
+- the sample remains a simple teaching sample, not a full racer
+
+## Required Fix Direction
+Implement the smallest valid correction:
+1. align rendered vehicle orientation with movement heading
+2. place/update camera as a chase camera behind the heading vector
+3. keep a readable height and distance offset
+4. ensure the vehicle remains visible during turning and reversing
+5. preserve current steering release behavior
+
+## Acceptance Criteria
+- [ ] the box/vehicle visibly turns with heading
+- [ ] the camera stays behind the driven object during normal driving
+- [ ] the vehicle remains easy to track during turning
+- [ ] forward/reverse still function
+- [ ] steering still behaves correctly after the prior fix
+- [ ] sample remains visible and playable
+- [ ] targeted Phase 16 sanity still passes where affected
+- [ ] no 2D regression introduced
+- [ ] no networking regression introduced
+
+## Validation
+- targeted behavioral check for 1605 heading + chase camera behavior
+- targeted smoke for 1605
+- update docs/dev/reports/change_summary.txt
+- update docs/dev/reports/validation_checklist.txt
diff --git a/samples/phase-16/1605/DrivingSandbox3DScene.js b/samples/phase-16/1605/DrivingSandbox3DScene.js
@@ -9,14 +9,112 @@ 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 { createProjectionViewport, drawGroundGrid, drawWireBox, projectPoint } from '../shared/threeDWireframe.js';
 
 const theme = new Theme(ThemeTokens);
+const BOX_EDGES = [
+  [0, 1], [1, 2], [2, 3], [3, 0],
+  [4, 5], [5, 6], [6, 7], [7, 4],
+  [0, 4], [1, 5], [2, 6], [3, 7],
+];
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
 }
 
+function normalizeAngle(angle) {
+  let value = angle;
+  const fullTurn = Math.PI * 2;
+  while (value > Math.PI) value -= fullTurn;
+  while (value < -Math.PI) value += fullTurn;
+  return value;
+}
+
+function rotateYaw(localX, localZ, yaw) {
+  const cos = Math.cos(yaw);
+  const sin = Math.sin(yaw);
+  return {
+    x: localX * cos + localZ * sin,
+    z: -localX * sin + localZ * cos,
+  };
+}
+
+function createOrientedBoxVertices(transform3D, size3D, yaw) {
+  const halfWidth = size3D.width * 0.5;
+  const halfHeight = size3D.height * 0.5;
+  const halfDepth = size3D.depth * 0.5;
+  const centerX = transform3D.x + halfWidth;
+  const centerY = transform3D.y + halfHeight;
+  const centerZ = transform3D.z + halfDepth;
+
+  const localVertices = [
+    { x: -halfWidth, y: -halfHeight, z: -halfDepth },
+    { x: halfWidth, y: -halfHeight, z: -halfDepth },
+    { x: halfWidth, y: halfHeight, z: -halfDepth },
+    { x: -halfWidth, y: halfHeight, z: -halfDepth },
+    { x: -halfWidth, y: -halfHeight, z: halfDepth },
+    { x: halfWidth, y: -halfHeight, z: halfDepth },
+    { x: halfWidth, y: halfHeight, z: halfDepth },
+    { x: -halfWidth, y: halfHeight, z: halfDepth },
+  ];
+
+  return localVertices.map((localVertex) => {
+    const rotated = rotateYaw(localVertex.x, localVertex.z, yaw);
+    return {
+      x: centerX + rotated.x,
+      y: centerY + localVertex.y,
+      z: centerZ + rotated.z,
+    };
+  });
+}
+
+function drawOrientedWireBox(renderer, transform3D, size3D, yaw, cameraState, viewport, color) {
+  const vertices = createOrientedBoxVertices(transform3D, size3D, yaw);
+  const projected = vertices.map((vertex) => projectPoint(vertex, cameraState, viewport));
+
+  for (const [startIndex, endIndex] of BOX_EDGES) {
+    const start = projected[startIndex];
+    const end = projected[endIndex];
+    if (!start || !end) {
+      continue;
+    }
+    renderer.drawLine(start.x, start.y, end.x, end.y, color, 2);
+  }
+}
+
+function drawVehicleHeadingMarker(renderer, transform3D, size3D, yaw, cameraState, viewport) {
+  const halfWidth = size3D.width * 0.5;
+  const halfHeight = size3D.height * 0.5;
+  const halfDepth = size3D.depth * 0.5;
+  const centerX = transform3D.x + halfWidth;
+  const centerY = transform3D.y + halfHeight;
+  const centerZ = transform3D.z + halfDepth;
+
+  const roofLocal = { x: 0, y: halfHeight * 0.55, z: 0 };
+  const frontLocal = { x: 0, y: halfHeight * 0.45, z: halfDepth + 0.15 };
+  const noseLocal = { x: 0, y: halfHeight * 0.45, z: halfDepth + 0.95 };
+
+  const toWorld = (local) => {
+    const rotated = rotateYaw(local.x, local.z, yaw);
+    return {
+      x: centerX + rotated.x,
+      y: centerY + local.y,
+      z: centerZ + rotated.z,
+    };
+  };
+
+  const roof = projectPoint(toWorld(roofLocal), cameraState, viewport);
+  const front = projectPoint(toWorld(frontLocal), cameraState, viewport);
+  const nose = projectPoint(toWorld(noseLocal), cameraState, viewport);
+
+  if (roof && front) {
+    renderer.drawLine(roof.x, roof.y, front.x, front.y, '#fde68a', 2);
+  }
+  if (front && nose) {
+    renderer.drawLine(front.x, front.y, nose.x, nose.y, '#fde68a', 3);
+  }
+}
+
 export default class DrivingSandbox3DScene extends Scene {
   constructor() {
     super();
@@ -28,6 +126,13 @@ export default class DrivingSandbox3DScene extends Scene {
     this.accel = 20;
     this.drag = 10;
     this.turnRate = 1.8;
+    this.chaseDistance = 9.4;
+    this.chaseHeight = 5.4;
+    this.chaseLookAhead = 2.8;
+    this.chaseYawLerp = 0.2;
+    this.cameraPitch = -0.38;
+    this.cameraYaw = 0;
+    this.cameraInitialized = false;
     this.distance = 0;
     this.viewport = {
       x: 40,
@@ -107,14 +212,29 @@ export default class DrivingSandbox3DScene extends Scene {
     }
 
     const car = this.world.requireComponent(this.carId, 'transform3D');
+    const forwardX = Math.sin(this.heading);
+    const forwardZ = Math.cos(this.heading);
+    const lookTargetX = car.x + forwardX * this.chaseLookAhead;
+    const lookTargetZ = car.z + forwardZ * this.chaseLookAhead;
+    const cameraX = car.x - forwardX * this.chaseDistance;
+    const cameraZ = car.z - forwardZ * this.chaseDistance;
+    const targetYaw = Math.atan2(lookTargetX - cameraX, lookTargetZ - cameraZ);
+
+    if (!this.cameraInitialized) {
+      this.cameraYaw = targetYaw;
+      this.cameraInitialized = true;
+    } else {
+      this.cameraYaw += normalizeAngle(targetYaw - this.cameraYaw) * this.chaseYawLerp;
+    }
+
     this.camera3D.setPosition({
-      x: car.x - Math.sin(this.heading) * 8.5,
-      y: car.y + 4.8,
-      z: car.z - Math.cos(this.heading) * 8.5,
+      x: cameraX,
+      y: car.y + this.chaseHeight,
+      z: cameraZ,
     });
     this.camera3D.setRotation({
-      x: -0.35,
-      y: this.heading,
+      x: this.cameraPitch,
+      y: this.cameraYaw,
       z: 0,
     });
   }
@@ -163,8 +283,8 @@ export default class DrivingSandbox3DScene extends Scene {
     renderer.strokeRect(this.viewport.x, this.viewport.y, this.viewport.width, this.viewport.height, '#d8d5ff', 2);
 
     const cameraState = this.camera3D?.getState?.() ?? {
-      position: { x: 0, y: 4.8, z: 0 },
-      rotation: { x: -0.35, y: 0, z: 0 },
+      position: { x: 0, y: 5.4, z: -0.9 },
+      rotation: { x: this.cameraPitch, y: this.cameraYaw, z: 0 },
     };
     const projectionViewport = createProjectionViewport(this.viewport);
 
@@ -184,21 +304,29 @@ export default class DrivingSandbox3DScene extends Scene {
       projectionViewport,
     );
 
-    const entities = this.world.getEntitiesWith('transform3D', 'size3D', 'renderable3D').map((entityId) => ({
-      transform3D: this.world.requireComponent(entityId, 'transform3D'),
-      size3D: this.world.requireComponent(entityId, 'size3D'),
-      renderable3D: this.world.requireComponent(entityId, 'renderable3D'),
-    }));
-    entities.sort((left, right) => right.transform3D.z - left.transform3D.z);
+    const car = this.world.requireComponent(this.carId, 'transform3D');
+    const carSize = this.world.requireComponent(this.carId, 'size3D');
+    const staticEntities = this.world
+      .getEntitiesWith('transform3D', 'size3D', 'renderable3D')
+      .filter((entityId) => entityId !== this.carId)
+      .map((entityId) => ({
+        transform3D: this.world.requireComponent(entityId, 'transform3D'),
+        size3D: this.world.requireComponent(entityId, 'size3D'),
+        renderable3D: this.world.requireComponent(entityId, 'renderable3D'),
+      }));
 
-    entities.forEach(({ transform3D, size3D, renderable3D }) => {
+    staticEntities.sort((left, right) => right.transform3D.z - left.transform3D.z);
+    staticEntities.forEach(({ transform3D, size3D, renderable3D }) => {
       drawWireBox(renderer, transform3D, size3D, cameraState, projectionViewport, renderable3D.color, 2);
     });
 
-    const car = this.world.requireComponent(this.carId, 'transform3D');
+    drawOrientedWireBox(renderer, car, carSize, this.heading, cameraState, projectionViewport, '#38bdf8');
+    drawVehicleHeadingMarker(renderer, car, carSize, this.heading, cameraState, projectionViewport);
+
     drawPanel(renderer, 620, 34, 300, 126, 'Driving Runtime', [
       `Car: x=${car.x.toFixed(2)} y=${car.y.toFixed(2)} z=${car.z.toFixed(2)}`,
       `Speed: ${this.speed.toFixed(2)} u/s | Heading: ${this.heading.toFixed(2)} rad`,
+      `Chase yaw: ${this.cameraYaw.toFixed(2)} rad`,
       `Track distance: ${this.distance.toFixed(1)} u`,
       `Moved entities: ${this.lastPhysicsSummary.movedEntities}`,
       `Resolved collisions: ${this.lastPhysicsSummary.collisionCount}`,
diff --git a/tests/runtime/Phase16VisibilitySanity.test.mjs b/tests/runtime/Phase16VisibilitySanity.test.mjs

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Fix stuck left/right steering behavior in Sample 1605 driving controls with targeted validation<BUILD_PR_LEVEL_17_9_SAMPLE_1605_DRIVING_CONTROL_FIX>`
	`1`	`+Improve Sample 1605 readability with vehicle-facing rotation and a behind-the-car chase camera<BUILD_PR_LEVEL_17_10_SAMPLE_1605_CHASE_CAMERA_AND_VEHICLE_FACING>`