Implement Sample 1713 as the final reference gameplay sample for the repaired Level 17 sequence, with a complete playable loop, HUD, camera follow, and index integration.

PR: BUILD_PR_LEVEL_17_45_SAMPLE_1713_FINAL_REFERENCE_GAME

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,3 +1,3 @@
 MODEL: GPT-5.3-codex
 REASONING: high
-COMMAND: Use provided 1707-1712.zip as source. Separate and map folders into correct sample structure (1707-1712), fix numbering, update samples/index.html, and package to <project folder>/tmp/BUILD_PR_LEVEL_17_44_SAMPLE_SEQUENCE_REPAIR_1707_1712.zip
+COMMAND: Implement Sample 1713 as the final reference game using existing engine/sample systems only. Register it in samples/index.html after the repaired 1707-1712 sequence, preserve existing work, keep logic bounded unless truly shared, and package the repo-structured result to <project folder>/tmp/BUILD_PR_LEVEL_17_45_SAMPLE_1713_FINAL_REFERENCE_GAME.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1,3 +1,3 @@
-Repair sample sequence 1707-1712 using provided folders as source of truth, enforcing correct structure and index alignment.
+Implement Sample 1713 as the final reference gameplay sample for the repaired Level 17 sequence, with a complete playable loop, HUD, camera follow, and index integration.
 
-PR: BUILD_PR_LEVEL_17_44_SAMPLE_SEQUENCE_REPAIR_1707_1712
+PR: BUILD_PR_LEVEL_17_45_SAMPLE_1713_FINAL_REFERENCE_GAME

docs/dev/reports/validation_checklist.txt

@@ -1,4 +1,8 @@
-- [ ] all samples present (1707–1712)
-- [ ] index updated
-- [ ] samples run independently
+- [ ] Sample 1713 exists and launches from samples/index.html
+- [ ] player movement works
+- [ ] camera follow works
+- [ ] hazard/enemy/obstacle interaction works
+- [ ] score or objective loop works
+- [ ] restart/reset path works
 - [ ] no console errors
+- [ ] samples 1707-1712 remain intact

docs/pr/BUILD_PR_LEVEL_17_45_SAMPLE_1713_FINAL_REFERENCE_GAME.md

@@ -0,0 +1,34 @@
+# BUILD_PR_LEVEL_17_45_SAMPLE_1713_FINAL_REFERENCE_GAME
+
+## Instructions for Codex
+
+Implement Sample 1713 as the final reference game for the Level 17 gameplay sequence.
+
+### Required Structure
+- create or normalize sample folder for 1713
+- ensure standalone execution
+- register in samples/index.html in correct order
+
+### Required Gameplay
+- complete playable loop
+- player movement and response
+- obstacles, enemies, or hazard interaction
+- score and/or objective completion
+- restart or reset path
+
+### Required Presentation
+- simple HUD / score / state text
+- camera follow
+- compatibility with existing debug surfaces where already available
+
+### Constraints
+- do not add new engine systems
+- do not delete user work
+- do not break 1707–1712
+- keep logic bounded to the sample unless truly shared
+
+### Validation
+- Sample 1713 loads from samples/index.html
+- gameplay loop is complete
+- no console errors
+- sequence remains continuous

docs/pr/PLAN_PR_LEVEL_17_45_SAMPLE_1713_FINAL_REFERENCE_GAME.md

@@ -0,0 +1,22 @@
+# PLAN_PR_LEVEL_17_45_SAMPLE_1713_FINAL_REFERENCE_GAME
+
+## Purpose
+Create Sample 1713 as the final reference game for the repaired Level 17 gameplay sample sequence.
+
+## Why This PR Exists
+After repairing Samples 1707–1712 into a clean sequence, the next step is a single reference game that proves the intended gameplay stack in one cohesive sample.
+
+## Must Demonstrate
+- player movement
+- camera follow
+- enemy or obstacle interaction
+- scoring or objective loop
+- UI/HUD presence
+- debug compatibility
+- standalone launch from samples/index.html
+
+## Constraints
+- use existing engine and sample patterns only
+- no new engine systems
+- no destructive cleanup
+- keep the sample educational and representative

samples/index.html

@@ -513,6 +513,7 @@ <h2>Phase 17 - Rendering Technique Expansion</h2>
         <a class="live" href="./phase-17/1710/index.html" title="Polished gameplay loop variant with mission-state feedback, objective progression, and standard 3D debug panels." data-tags="camera3d, gameplay, polished-loop, objective, hazards, debug-panels, scene, themetokens" data-primary="real-gameplay-mini-game-polished">Sample 1710 - Real Gameplay Mini-Game</a>
         <a class="live" href="./phase-17/1711/index.html" title="Movement-models lab variant for sequence alignment with direct, tank, and weighted controls plus follow camera." data-tags="camera3d, movement-models, direct-controls, tank-controls, weighted-motion, scene, themetokens" data-primary="movement-models-lab-sequence">Sample 1711 - Movement Models Lab</a>
         <a class="live" href="./phase-17/1712/index.html" title="Gameplay telemetry overlay for mini-game state, speed, collisions, actions, and live FPS trend." data-tags="camera3d, gameplay, telemetry, metrics, debug-overlay, scene, themetokens" data-primary="gameplay-metrics-telemetry">Sample 1712 - Gameplay Metrics & Telemetry</a>
+        <a class="live" href="./phase-17/1713/index.html" title="Final reference game sample that combines complete mission loop, camera/collision debug output, and runtime telemetry using existing systems only." data-tags="camera3d, gameplay, reference-game, telemetry, debug-panels, mission-loop, scene, themetokens" data-primary="final-reference-game">Sample 1713 - Final Reference Game</a>
       </div>
     </section>
     <section>

samples/phase-17/1713/FinalReferenceGameScene.js

@@ -0,0 +1,141 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+FinalReferenceGameScene.js
+*/
+import { drawPanel } from '/src/engine/debug/index.js';
+import GameplayMetricsTelemetryScene from '/samples/phase-17/1712/GameplayMetricsTelemetryScene.js';
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+function computeReferenceRank(scene) {
+  if (scene.gameState === 'lost') {
+    return 'D';
+  }
+  if (scene.gameState !== 'won') {
+    return 'N/A';
+  }
+
+  const objectiveRatio = clamp(scene.score / Math.max(1, scene.targetScore), 0, 1);
+  const healthRatio = clamp(scene.health / Math.max(1, scene.maxHealth), 0, 1);
+  const timeRatio = clamp(scene.timeLeft / Math.max(1, scene.roundSeconds), 0, 1);
+  const collisionPenalty = Math.min(0.35, scene.telemetry.collisionsTotal * 0.01);
+  const weightedScore = objectiveRatio * 0.6 + healthRatio * 0.25 + timeRatio * 0.15 - collisionPenalty;
+
+  if (weightedScore >= 0.9) return 'S';
+  if (weightedScore >= 0.78) return 'A';
+  if (weightedScore >= 0.63) return 'B';
+  return 'C';
+}
+
+function isBetterRank(candidate, baseline) {
+  const rankOrder = ['S', 'A', 'B', 'C', 'D', 'N/A'];
+  return rankOrder.indexOf(candidate) < rankOrder.indexOf(baseline);
+}
+
+export default class FinalReferenceGameScene extends GameplayMetricsTelemetryScene {
+  constructor() {
+    super();
+
+    this.maxHealth = 4;
+    this.targetScore = 8;
+    this.roundSeconds = 70;
+    this.playerSpeed = 8.8;
+    this.hitCooldownSeconds = 0.95;
+    this.resetMatch({ toReady: true });
+
+    this.referenceRuntime = {
+      runCount: 0,
+      activeSeconds: 0,
+      missionRank: 'N/A',
+      bestRank: 'N/A',
+      bestScore: 0,
+      bestTimeRemaining: 0,
+      completionBonus: 0,
+      phase: 'briefing',
+    };
+  }
+
+  step3DPhysics(dtSeconds, engine) {
+    const dt = Math.max(0, Math.min(0.05, Number(dtSeconds) || 0));
+    const previousState = this.gameState;
+    const input = engine?.input;
+
+    if (previousState === 'ready') {
+      const wantsMovement =
+        input?.isDown('KeyW') === true ||
+        input?.isDown('KeyA') === true ||
+        input?.isDown('KeyS') === true ||
+        input?.isDown('KeyD') === true;
+      if (wantsMovement) {
+        this.startMatch();
+      }
+    }
+
+    super.step3DPhysics(dt, engine);
+
+    if (this.gameState === 'running') {
+      if (previousState !== 'running') {
+        this.referenceRuntime.runCount += 1;
+        this.referenceRuntime.activeSeconds = 0;
+        this.referenceRuntime.phase = 'active';
+      }
+      this.referenceRuntime.activeSeconds += dt;
+      this.referenceRuntime.missionRank = 'N/A';
+      this.referenceRuntime.completionBonus = 0;
+      return;
+    }
+
+    if (this.gameState === 'ready') {
+      this.referenceRuntime.phase = 'briefing';
+      this.referenceRuntime.activeSeconds = 0;
+      this.referenceRuntime.missionRank = 'N/A';
+      this.referenceRuntime.completionBonus = 0;
+      return;
+    }
+
+    if (previousState !== this.gameState) {
+      this.referenceRuntime.phase = this.gameState === 'won' ? 'complete' : 'failed';
+      this.referenceRuntime.missionRank = computeReferenceRank(this);
+      this.referenceRuntime.completionBonus = this.gameState === 'won'
+        ? Math.max(0, Math.floor(this.timeLeft * 4 + this.health * 25))
+        : 0;
+
+      if (this.gameState === 'won') {
+        if (this.score > this.referenceRuntime.bestScore) {
+          this.referenceRuntime.bestScore = this.score;
+          this.referenceRuntime.bestTimeRemaining = this.timeLeft;
+        } else if (this.score === this.referenceRuntime.bestScore) {
+          this.referenceRuntime.bestTimeRemaining = Math.max(this.referenceRuntime.bestTimeRemaining, this.timeLeft);
+        }
+
+        if (
+          this.referenceRuntime.bestRank === 'N/A' ||
+          isBetterRank(this.referenceRuntime.missionRank, this.referenceRuntime.bestRank)
+        ) {
+          this.referenceRuntime.bestRank = this.referenceRuntime.missionRank;
+        }
+      }
+    }
+  }
+
+  render(renderer) {
+    super.render(renderer);
+
+    drawPanel(renderer, 384, 286, 228, 248, 'Final Reference Runtime', [
+      `profile=final-reference`,
+      `phase=${this.referenceRuntime.phase}`,
+      `runs=${this.referenceRuntime.runCount}`,
+      `activeSeconds=${this.referenceRuntime.activeSeconds.toFixed(1)}`,
+      `missionRank=${this.referenceRuntime.missionRank}`,
+      `bestRank=${this.referenceRuntime.bestRank}`,
+      `bestScore=${this.referenceRuntime.bestScore}/${this.targetScore}`,
+      `bestTimeLeft=${this.referenceRuntime.bestTimeRemaining.toFixed(1)}s`,
+      `completionBonus=${this.referenceRuntime.completionBonus}`,
+      'restart=R after mission outcome',
+    ]);
+  }
+}

samples/phase-17/1713/index.html

@@ -0,0 +1,32 @@
+<!--
+Toolbox Aid
+David Quesenberry
+04/16/2026
+index.html
+-->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Sample 1713 - Final Reference Game</title>
+  <link rel="stylesheet" href="../../../src/engine/ui/baseLayout.css" />
+</head>
+<body>
+  <main>
+    <h1>Sample 1713 - Final Reference Game</h1>
+    <p>Final reference mini-game that combines gameplay loop, camera debug panels, collision overlays, and telemetry in one bounded sample.</p>
+    <canvas id="game" width="960" height="540"></canvas>
+
+    <section>
+      <h3>Engine Classes Used</h3>
+      <ul>
+        <li>Engine</li>
+        <li>Scene</li>
+      </ul>
+    </section>
+  </main>
+
+  <script type="module" src="/samples/shared/sampleDetailPageEnhancement.js"></script>
+  <script type="module" src="./main.js"></script>
+</body>
+</html>

samples/phase-17/1713/main.js

@@ -0,0 +1,27 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+main.js
+*/
+import Engine from '/src/engine/core/Engine.js';
+import { InputService } from '/src/engine/input/index.js';
+import { Theme, ThemeTokens } from '/src/engine/theme/index.js';
+import FinalReferenceGameScene from './FinalReferenceGameScene.js';
+
+const theme = new Theme(ThemeTokens);
+theme.applyDocumentTheme();
+
+const canvas = document.getElementById('game');
+const input = new InputService();
+
+const engine = new Engine({
+  canvas,
+  width: 960,
+  height: 540,
+  fixedStepMs: 1000 / 60,
+  input,
+});
+
+engine.setScene(new FinalReferenceGameScene());
+engine.start();

tests/runtime/Phase17Sample1713FinalReferenceGame.test.mjs

@@ -0,0 +1,106 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+Phase17Sample1713FinalReferenceGame.test.mjs
+*/
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import FinalReferenceGameScene from '../../samples/phase-17/1713/FinalReferenceGameScene.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, '..', '..');
+
+function createCameraStub() {
+  const state = {
+    position: { x: 0, y: 0, z: 0 },
+    rotation: { x: 0, y: 0, z: 0 },
+  };
+  return {
+    setPosition(position) {
+      state.position = { ...position };
+    },
+    setRotation(rotation) {
+      state.rotation = { ...rotation };
+    },
+    getState() {
+      return {
+        position: { ...state.position },
+        rotation: { ...state.rotation },
+      };
+    },
+  };
+}
+
+function makeInput(keys = []) {
+  const down = new Set(keys);
+  return {
+    isDown(code) {
+      return down.has(code);
+    },
+  };
+}
+
+function createRendererProbe(width = 960, height = 540) {
+  const texts = [];
+  return {
+    texts,
+    getCanvasSize() {
+      return { width, height };
+    },
+    clear() {},
+    drawRect() {},
+    strokeRect() {},
+    drawText(text) {
+      texts.push(String(text));
+    },
+    drawLine() {},
+    drawPolygon() {},
+    drawImageFrame() {},
+  };
+}
+
+function assertIndexLinkPresent() {
+  const indexPath = path.join(repoRoot, 'samples', 'index.html');
+  const text = fs.readFileSync(indexPath, 'utf8');
+  assert.equal(text.includes('./phase-17/1713/index.html'), true, 'Sample 1713 link should exist in samples/index.html.');
+}
+
+function assertFinalReferenceRuntimeFlow() {
+  const scene = new FinalReferenceGameScene();
+  scene.setCamera3D(createCameraStub());
+
+  assert.equal(scene.gameState, 'ready', 'Reference game should start in ready state.');
+  const beforeX = scene.player.x;
+  const beforeZ = scene.player.z;
+  scene.step3DPhysics(0.05, { input: makeInput(['KeyW']) });
+  assert.equal(scene.gameState, 'running', 'Movement input should start the reference game.');
+  assert.equal(scene.player.x !== beforeX || scene.player.z !== beforeZ, true, 'Movement input should move the player.');
+  assert.equal(scene.referenceRuntime.runCount, 1, 'Reference runtime should count mission runs.');
+
+  scene.step3DPhysics(0.18, { input: makeInput(['KeyD']) });
+  assert.equal(scene.telemetry.playerSpeed > 0, true, 'Telemetry should remain active in the reference game.');
+
+  scene.score = scene.targetScore;
+  scene.timeLeft = 16;
+  scene.health = scene.maxHealth;
+  scene.step3DPhysics(0.02, { input: makeInput([]) });
+
+  assert.equal(scene.gameState, 'won', 'Score completion should transition the reference game to won state.');
+  assert.equal(scene.referenceRuntime.missionRank !== 'N/A', true, 'Reference runtime should compute mission rank.');
+
+  const renderer = createRendererProbe();
+  scene.render(renderer);
+  assert.equal(renderer.texts.some((text) => text.includes('Final Reference Runtime')), true, 'Final runtime panel should render.');
+  assert.equal(renderer.texts.some((text) => text.includes('profile=final-reference')), true, 'Reference runtime metrics should render.');
+  assert.equal(renderer.texts.some((text) => text.includes('activeCameraId=')), true, 'Camera debug panel should remain visible.');
+  assert.equal(renderer.texts.some((text) => text.includes('overlayCount=')), true, 'Collision debug panel should remain visible.');
+}
+
+export function run() {
+  assertIndexLinkPresent();
+  assertFinalReferenceRuntimeFlow();
+}