Add gameplay metrics and telemetry overlay to validate runtime behavior and performance.

DavidQ · DavidQ · commit 388c4be9ff32 · 2026-04-16T14:35:05.000-04:00
PR: BUILD_PR_LEVEL_17_42_SAMPLE_1712_GAMEPLAY_METRICS_AND_TELEMETRY
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,3 +1,3 @@
 MODEL: GPT-5.3-codex
 REASONING: high
-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
+COMMAND: Add gameplay metrics and telemetry overlay using existing debug systems and package to <project folder>/tmp/BUILD_PR_LEVEL_17_42_SAMPLE_1712_GAMEPLAY_METRICS_AND_TELEMETRY.zip
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,3 +1,3 @@
-Polish real gameplay sample into a complete mini-game with UI, feedback, and full game loop.
+Add gameplay metrics and telemetry overlay to validate runtime behavior and performance.
 
-PR: BUILD_PR_LEVEL_17_40_SAMPLE_1710_REAL_GAMEPLAY_POLISH
+PR: BUILD_PR_LEVEL_17_42_SAMPLE_1712_GAMEPLAY_METRICS_AND_TELEMETRY
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,5 +1,4 @@
-- [ ] game loop complete
-- [ ] score visible
-- [ ] restart works
-- [ ] debug panels intact
+- [ ] metrics visible
+- [ ] values update live
+- [ ] no performance issues
 - [ ] no console errors
diff --git a/docs/pr/BUILD_PR_LEVEL_17_42_SAMPLE_1712_GAMEPLAY_METRICS_AND_TELEMETRY.md b/docs/pr/BUILD_PR_LEVEL_17_42_SAMPLE_1712_GAMEPLAY_METRICS_AND_TELEMETRY.md
@@ -0,0 +1,23 @@
+# BUILD_PR_LEVEL_17_42_SAMPLE_1712_GAMEPLAY_METRICS_AND_TELEMETRY
+
+## Implementation
+
+Add metrics overlay:
+
+### Metrics
+- player speed
+- object count
+- FPS (if available)
+- event counters (collisions, actions)
+
+### Visualization
+- simple overlay or debug panel reuse
+
+### Constraints
+- use existing systems
+- no new engine features
+
+## Validation
+- metrics update live
+- no performance issues
+- no console errors
diff --git a/docs/pr/PLAN_PR_LEVEL_17_42_SAMPLE_1712_GAMEPLAY_METRICS_AND_TELEMETRY.md b/docs/pr/PLAN_PR_LEVEL_17_42_SAMPLE_1712_GAMEPLAY_METRICS_AND_TELEMETRY.md
@@ -0,0 +1,15 @@
+# PLAN_PR_LEVEL_17_42_SAMPLE_1712_GAMEPLAY_METRICS_AND_TELEMETRY
+
+## Purpose
+Add gameplay metrics and telemetry visibility to validate behavior and performance.
+
+## Scope
+Extend gameplay sample with runtime metrics.
+
+## Focus
+- player metrics
+- system metrics
+- simple telemetry visualization
+
+## Out of Scope
+- external telemetry systems
diff --git a/samples/index.html b/samples/index.html
@@ -510,6 +510,7 @@ <h2>Phase 17 - Rendering Technique Expansion</h2>
         <a class="live" href="./phase-17/1707/index.html" title="Minecraft-style voxel chunk-window streaming around a movable camera anchor." data-tags="camera3d, minecraft-style, voxel, chunk-streaming, filled-render, scene, themetokens" data-primary="minecraft-chunk-streaming">Sample 1707 - Minecraft Chunk Streaming</a>
         <a class="live" href="./phase-17/1708/index.html" title="Real 3D mini-game loop with movement, hazard interaction, objective scoring, camera follow, and standard 3D debug panels." data-tags="camera3d, gameplay, objective, hazards, debug-panels, scene, themetokens" data-primary="real-gameplay-mini-game">Sample 1708 - Real Gameplay Mini-Game</a>
         <a class="live" href="./phase-17/1709/index.html" title="Compares direct axis movement, tank rotation controls, and weighted movement with follow-camera framing." data-tags="camera3d, movement-models, direct-controls, tank-controls, weighted-motion, scene, themetokens" data-primary="movement-models-lab">Sample 1709 - 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>
       </div>
     </section>
     <section>
diff --git a/samples/phase-17/1707-1712.zip b/samples/phase-17/1707-1712.zip
diff --git a/samples/phase-17/1712/GameplayMetricsTelemetryScene.js b/samples/phase-17/1712/GameplayMetricsTelemetryScene.js
@@ -0,0 +1,120 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+GameplayMetricsTelemetryScene.js
+*/
+import { drawPanel } from '/src/engine/debug/index.js';
+import RealGameplayMiniGameScene from '/samples/phase-17/1708/RealGameplayMiniGameScene.js';
+
+function pushSample(history, value, limit = 48) {
+  history.push(Number.isFinite(value) ? Number(value) : 0);
+  if (history.length > limit) {
+    history.splice(0, history.length - limit);
+  }
+}
+
+function drawTelemetrySparkline(renderer, x, y, width, height, samples, color) {
+  renderer.drawRect(x, y, width, height, 'rgba(2, 6, 23, 0.72)');
+  renderer.strokeRect(x, y, width, height, '#334155', 1);
+
+  if (!Array.isArray(samples) || samples.length < 2) {
+    return;
+  }
+
+  const maxValue = Math.max(1, ...samples);
+  const stepX = (width - 4) / Math.max(1, samples.length - 1);
+  for (let i = 1; i < samples.length; i += 1) {
+    const prev = samples[i - 1];
+    const curr = samples[i];
+    const x1 = x + 2 + (i - 1) * stepX;
+    const x2 = x + 2 + i * stepX;
+    const y1 = y + height - 2 - (Math.max(0, prev) / maxValue) * (height - 4);
+    const y2 = y + height - 2 - (Math.max(0, curr) / maxValue) * (height - 4);
+    renderer.drawLine(x1, y1, x2, y2, color, 1.5);
+  }
+}
+
+export default class GameplayMetricsTelemetryScene extends RealGameplayMiniGameScene {
+  constructor() {
+    super();
+    this.telemetry = {
+      frames: 0,
+      rawFps: 60,
+      avgFps: 60,
+      playerSpeed: 0,
+      maxPlayerSpeed: 0,
+      collisionsTotal: 0,
+      actionEvents: 0,
+      stateTransitions: 0,
+      speedHistory: [],
+      fpsHistory: [],
+      collisionHistory: [],
+    };
+  }
+
+  step3DPhysics(dtSeconds, engine) {
+    const dt = Math.max(0.001, Math.min(0.05, Number(dtSeconds) || 0.016));
+    const beforeScore = this.score;
+    const beforeHealth = this.health;
+    const beforeState = this.gameState;
+    const beforeX = this.player.x;
+    const beforeZ = this.player.z;
+
+    super.step3DPhysics(dt, engine);
+
+    const dx = this.player.x - beforeX;
+    const dz = this.player.z - beforeZ;
+    const speed = Math.hypot(dx, dz) / dt;
+    const rawFps = 1 / dt;
+
+    this.telemetry.frames += 1;
+    this.telemetry.rawFps = rawFps;
+    this.telemetry.avgFps = this.telemetry.avgFps * 0.9 + rawFps * 0.1;
+    this.telemetry.playerSpeed = speed;
+    this.telemetry.maxPlayerSpeed = Math.max(this.telemetry.maxPlayerSpeed, speed);
+    this.telemetry.collisionsTotal += this.lastCollisionCount;
+
+    const actionDelta = Math.max(0, this.score - beforeScore) + Math.max(0, beforeHealth - this.health);
+    this.telemetry.actionEvents += actionDelta;
+    if (beforeState !== this.gameState) {
+      this.telemetry.stateTransitions += 1;
+    }
+
+    pushSample(this.telemetry.speedHistory, speed);
+    pushSample(this.telemetry.fpsHistory, this.telemetry.avgFps);
+    pushSample(this.telemetry.collisionHistory, this.lastCollisionCount);
+  }
+
+  render(renderer) {
+    super.render(renderer);
+
+    const remainingCores = this.cores.filter((core) => core.collected === false).length;
+    const objectCount = this.obstacles.length + this.enemies.length + this.cores.length + 1;
+    const panelX = 384;
+    const panelY = 34;
+    const panelW = 228;
+    const panelH = 244;
+
+    drawPanel(renderer, panelX, panelY, panelW, panelH, 'Telemetry Overlay', [
+      `state=${this.gameState}`,
+      `fps=${this.telemetry.avgFps.toFixed(1)} raw=${this.telemetry.rawFps.toFixed(1)}`,
+      `playerSpeed=${this.telemetry.playerSpeed.toFixed(2)}`,
+      `maxSpeed=${this.telemetry.maxPlayerSpeed.toFixed(2)}`,
+      `objects=${objectCount} coresRemaining=${remainingCores}`,
+      `collisions=${this.telemetry.collisionsTotal}`,
+      `actions=${this.telemetry.actionEvents}`,
+      `stateTransitions=${this.telemetry.stateTransitions}`,
+    ]);
+
+    drawTelemetrySparkline(
+      renderer,
+      panelX + 12,
+      panelY + panelH - 44,
+      panelW - 24,
+      30,
+      this.telemetry.speedHistory,
+      '#38bdf8'
+    );
+  }
+}
diff --git a/samples/phase-17/1712/index.html b/samples/phase-17/1712/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 1712 - Gameplay Metrics & Telemetry</title>
+  <link rel="stylesheet" href="../../../src/engine/ui/baseLayout.css" />
+</head>
+<body>
+  <main>
+    <h1>Sample 1712 - Gameplay Metrics & Telemetry</h1>
+    <p>Adds live gameplay metrics and telemetry overlay to a real mini-game using existing debug systems only.</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>
diff --git a/samples/phase-17/1712/main.js b/samples/phase-17/1712/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 GameplayMetricsTelemetryScene from './GameplayMetricsTelemetryScene.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 GameplayMetricsTelemetryScene());
+engine.start();
diff --git a/tests/runtime/Phase17Sample1712GameplayMetricsTelemetry.test.mjs b/tests/runtime/Phase17Sample1712GameplayMetricsTelemetry.test.mjs
@@ -0,0 +1,118 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+Phase17Sample1712GameplayMetricsTelemetry.test.mjs
+*/
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import GameplayMetricsTelemetryScene from '../../samples/phase-17/1712/GameplayMetricsTelemetryScene.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 = [];
+  const lines = [];
+  return {
+    texts,
+    lines,
+    getCanvasSize() {
+      return { width, height };
+    },
+    clear() {},
+    drawRect() {},
+    strokeRect() {},
+    drawText(text) {
+      texts.push(String(text));
+    },
+    drawLine(x1, y1, x2, y2, color) {
+      lines.push({ x1, y1, x2, y2, color });
+    },
+    drawPolygon() {},
+    drawImageFrame() {},
+  };
+}
+
+function assertIndexLinkPresent() {
+  const indexPath = path.join(repoRoot, 'samples', 'index.html');
+  const text = fs.readFileSync(indexPath, 'utf8');
+  assert.equal(text.includes('./phase-17/1712/index.html'), true, 'Sample 1712 link should exist in samples/index.html.');
+}
+
+function positionPlayerOnCore(scene, core) {
+  scene.player.x = core.x - scene.player.width * 0.5;
+  scene.player.z = core.z - scene.player.depth * 0.5;
+}
+
+function assertTelemetryOverlayAndCounters() {
+  const scene = new GameplayMetricsTelemetryScene();
+  scene.setCamera3D(createCameraStub());
+
+  assert.equal(scene.gameState, 'ready', 'Telemetry sample should begin in ready state.');
+  scene.step3DPhysics(0.02, { input: makeInput(['Space']) });
+  assert.equal(scene.gameState, 'running', 'Space should start gameplay run.');
+
+  scene.step3DPhysics(0.2, { input: makeInput(['KeyD']) });
+  assert.equal(scene.telemetry.playerSpeed > 0, true, 'Telemetry should report positive player speed after movement.');
+  assert.equal(scene.telemetry.avgFps > 0, true, 'Telemetry should report FPS.');
+
+  const firstCore = scene.cores.find((core) => core.collected === false);
+  positionPlayerOnCore(scene, firstCore);
+  scene.step3DPhysics(0.05, { input: makeInput([]) });
+
+  scene.hitCooldown = 0;
+  const firstEnemy = scene.enemies[0];
+  firstEnemy.x = scene.player.x;
+  firstEnemy.z = scene.player.z;
+  scene.step3DPhysics(0.05, { input: makeInput([]) });
+
+  assert.equal(scene.telemetry.actionEvents >= 1, true, 'Telemetry should count gameplay actions.');
+  assert.equal(scene.telemetry.collisionsTotal >= 1, true, 'Telemetry should accumulate collision events.');
+  assert.equal(scene.telemetry.speedHistory.length > 0, true, 'Telemetry should capture speed history.');
+
+  const renderer = createRendererProbe();
+  scene.render(renderer);
+  assert.equal(renderer.texts.some((text) => text.includes('Telemetry Overlay')), true, 'Telemetry overlay panel should render.');
+  assert.equal(renderer.texts.some((text) => text.includes('playerSpeed=')), true, 'Telemetry overlay should render player-speed metrics.');
+  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();
+  assertTelemetryOverlayAndCounters();
+}
