Fix stuck left/right steering behavior in Sample 1605 driving controls with targeted validation<BUILD_PR_LEVEL_17_9_SAMPLE_1605_DRIVING_CONTROL_FIX>

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,16 +2,10 @@ MODEL: GPT-5.3-codex
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_LEVEL_17_8_SAMPLES_1605_TO_1608_CORE_TRACK.
+Create BUILD_PR_LEVEL_17_9_SAMPLE_1605_DRIVING_CONTROL_FIX.
 
 Goal:
-Complete the remaining core Phase 16 / 3D sample track by implementing samples 1605 through 1608 as one testable package.
-
-Context:
-- 1601 is visible
-- 1602 and 1604 visibility defects were fixed
-- targeted Phase 16 visibility sanity passes
-- targeted smoke for 1601-1604 passes
+Fix Sample 1605 - 3D Driving Sandbox so left/right steering no longer gets stuck.
 
 Constraints:
 - one PR purpose only
@@ -20,32 +14,20 @@ Constraints:
 - no zip output from Codex
 - keep 2D and networking untouched
 - do not modify start_of_day
-- preserve prior Phase 16 samples unless a shared safe improvement is required
 
 Implement:
-1. Add and wire up:
-   - samples/phase-16/1605
-   - samples/phase-16/1606
-   - samples/phase-16/1607
-   - samples/phase-16/1608
-2. Reuse existing shared Phase 16 helpers where stable.
-3. Ensure each sample has visible 3D output on first load and one clear teaching purpose:
-   - 1605 driving sandbox
-   - 1606 physics playground
-   - 1607 space shooter
-   - 1608 dungeon crawler
-4. Update samples/index.html so these are live entries when implemented.
-5. Extend the existing targeted Phase 16 runtime sanity only if needed and keep it surgical.
+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.
 
-Validation:
-- verify 1605 visible on load
-- verify 1606 visible on load
-- verify 1607 visible on load
-- verify 1608 visible on load
-- verify intended controls function for each sample
-- run targeted smoke for 1601-1608
-- confirm no 2D regression in targeted checks
-- confirm no networking regression in targeted checks
+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 sample still renders on load
+- run targeted smoke for 1605
 - update:
   - docs/dev/reports/change_summary.txt
   - docs/dev/reports/validation_checklist.txt

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-Complete the remaining core Phase 16 sample track for 1605 through 1608 with targeted validation<BUILD_PR_LEVEL_17_8_SAMPLES_1605_TO_1608_CORE_TRACK>
+Fix stuck left/right steering behavior in Sample 1605 driving controls with targeted validation<BUILD_PR_LEVEL_17_9_SAMPLE_1605_DRIVING_CONTROL_FIX>

docs/dev/reports/change_summary.txt

@@ -1,17 +1,20 @@
-Applied scope:
-- implemented Phase 16 core track samples 1605 through 1608:
-  - 1605: 3D driving sandbox (throttle/steer + AABB track blockers)
-  - 1606: 3D physics playground (gravity, bounce, impulses, damping)
-  - 1607: 3D space shooter (lane movement, projectiles, asteroid hits)
-  - 1608: 3D dungeon crawler (maze traversal, relic gate unlock, exit)
-- wired launcher entries in samples/index.html from planned to live for 1605-1608
-- reused shared 3D wireframe helper path for rendering consistency
-- extended Phase16VisibilitySanity.test.mjs surgically to include 1605-1608:
-  - visibility on load checks
-  - one control/function assertion per new sample
+Observed issue:
+- Sample 1605 renders and loads
+- steering behavior gets stuck left/right
+
+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
 
 Validation outcome:
 - PASS Phase16VisibilitySanity
-- PASS launch smoke (samples 1601-1608): PASS=8 FAIL=0
+- PASS launch smoke (sample 1605): PASS=1 FAIL=0
 - PASS EngineTiming (targeted 2D regression check)
 - PASS MultiplayerNetworkingStack (targeted networking regression check)

docs/dev/reports/launch_smoke_report.md

@@ -1,16 +1,9 @@
 # Launch Smoke Report
 
-Generated: 2026-04-15T20:18:43.439Z
+Generated: 2026-04-15T20:27:13.340Z
 
-Filters: games=false, samples=true, tools=false, sampleRange=1601-1608
+Filters: games=false, samples=true, tools=false, sampleRange=1605-1605
 
 | 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 |
+| PASS | sample | 1605 | samples\phase-16\1605\index.html |  | npm install --prefix ./tmp ws → npm run test:launch-smoke |

docs/dev/reports/validation_checklist.txt

@@ -1,19 +1,17 @@
-Phase 16 core track checklist
-[x] 1605 visible on load
-[x] 1606 visible on load
-[x] 1607 visible on load
-[x] 1608 visible on load
-[x] 1605 controls function
-[x] 1606 controls function
-[x] 1607 controls function
-[x] 1608 controls function
-[x] targeted smoke 1601-1608 passes
+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
+[x] forward/reverse still function
+[x] sample renders visibly on load
+[x] targeted smoke for 1605 passes
 [x] no 2D regression observed in targeted checks
 [x] no networking regression observed in targeted checks
 
 Execution evidence:
 - PASS Phase16VisibilitySanity
-- Launch smoke targeted run: --samples --sample-range=1601-1608
-- Launch smoke result: PASS=8 FAIL=0 TOTAL=8
+- Launch smoke targeted run: --samples --sample-range=1605-1605
+- Launch smoke result: PASS=1 FAIL=0 TOTAL=1
 - PASS EngineTiming (2D baseline targeted check)
 - PASS MultiplayerNetworkingStack (network baseline targeted check)

docs/pr/BUILD_PR_LEVEL_17_9_SAMPLE_1605_DRIVING_CONTROL_FIX.md

@@ -0,0 +1,56 @@
+# BUILD PR: 17.9 Sample 1605 Driving Control Fix
+
+## Purpose
+Fix the behavioral defect in Sample 1605 - 3D Driving Sandbox where navigation gets stuck turning left or right.
+
+## Observed Runtime Symptom
+- sample loads
+- 3D renders
+- driving controls are not correct
+- turning appears to stick on left/right instead of behaving like normal held-input steering
+
+## Scope
+Surgically correct 1605 driving input/state behavior only.
+
+## In Scope
+- samples/phase-16/1605/DrivingSandbox3DScene.js
+- minimal targeted test update if needed
+- docs/dev/reports/* validation updates
+
+## Out of Scope
+- no changes to 1606-1608 unless a truly shared safe helper defect is proven
+- no engine-wide input changes
+- no 2D or networking changes
+- no repo-wide scanning
+- no zip output from Codex
+
+## Likely Failure Areas To Inspect
+- left/right turn state not clearing when key is released
+- one-sided steering accumulator not recentering
+- input polling using stale state
+- mutually exclusive left/right handling not resolved correctly
+- heading/turn velocity damping missing or sign-clamped incorrectly
+
+## Required Fix Direction
+Implement the smallest valid correction so:
+- left turn works while held
+- right turn works while held
+- steering stops when released
+- opposite direction can be engaged immediately
+- forward/reverse behavior remains intact
+
+## Acceptance Criteria
+- [ ] 1605 no longer sticks turning left
+- [ ] 1605 no longer sticks turning right
+- [ ] steering responds correctly to press/hold/release
+- [ ] forward/reverse still function
+- [ ] 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 steering release/reset
+- targeted smoke for 1605
+- update docs/dev/reports/change_summary.txt
+- update docs/dev/reports/validation_checklist.txt

samples/phase-16/1605/DrivingSandbox3DScene.js

@@ -138,8 +138,7 @@ export default class DrivingSandbox3DScene extends Scene {
 
     this.speed = clamp(this.speed, -this.maxReverseSpeed, this.maxForwardSpeed);
     if (Math.abs(this.speed) > 0.1) {
-      const steeringDirection = this.speed >= 0 ? 1 : -1;
-      this.heading += steer * this.turnRate * steeringDirection * dt;
+      this.heading += steer * this.turnRate * dt;
     }
 
     velocity.x = Math.sin(this.heading) * this.speed;
@@ -206,4 +205,3 @@ export default class DrivingSandbox3DScene extends Scene {
     ]);
   }
 }
-

tests/runtime/Phase16VisibilitySanity.test.mjs

@@ -128,6 +128,36 @@ function assertDrivingVisibilityAndInput() {
   const startZ = car.z;
   scene.step3DPhysics(1 / 60, { input: makeInput(['KeyW']) });
   assert.equal(car.z > startZ, true, 'Driving sample W input should advance car forward.');
+
+  const startHeading = scene.heading;
+  for (let i = 0; i < 4; i += 1) {
+    scene.step3DPhysics(1 / 60, { input: makeInput(['KeyW', 'KeyA']) });
+  }
+  const afterLeftHeading = scene.heading;
+  assert.equal(afterLeftHeading < startHeading, true, 'Driving sample A hold should turn left.');
+
+  scene.step3DPhysics(1 / 60, { input: makeInput(['KeyW']) });
+  const afterReleaseHeading = scene.heading;
+  scene.step3DPhysics(1 / 60, { input: makeInput(['KeyW']) });
+  assert.equal(scene.heading, afterReleaseHeading, 'Driving sample steering should stop when A/D is released.');
+
+  scene.step3DPhysics(1 / 60, { input: makeInput(['KeyW', 'KeyD']) });
+  assert.equal(scene.heading > afterReleaseHeading, true, 'Driving sample D should engage immediately after left release.');
+  const afterImmediateRightHeading = scene.heading;
+
+  for (let i = 0; i < 3; i += 1) {
+    scene.step3DPhysics(1 / 60, { input: makeInput(['KeyW', 'KeyD']) });
+  }
+  assert.equal(scene.heading > afterImmediateRightHeading, true, 'Driving sample D hold should continue turning right.');
+
+  const beforeReverseHeading = scene.heading;
+  scene.step3DPhysics(1 / 60, { input: makeInput(['KeyS', 'KeyD']) });
+  assert.equal(scene.heading > beforeReverseHeading, true, 'Driving sample D should still steer right while reversing.');
+
+  for (let i = 0; i < 120; i += 1) {
+    scene.step3DPhysics(1 / 60, { input: makeInput(['KeyS']) });
+  }
+  assert.equal(scene.speed < 0, true, 'Driving sample S input should produce reverse motion.');
 }
 
 function assertPhysicsPlaygroundVisibilityAndInput() {