Move Asteroids weighted beat timing into a focused helper module - PR_26139_027-asteroids-beat-timing-helper-cleanup

Author: DavidQ

docs/dev/reports/PR_26139_027-asteroids-beat-timing-helper-cleanup_report.md

@@ -0,0 +1,42 @@
+# PR_26139_027-asteroids-beat-timing-helper-cleanup
+
+## Summary
+- Extracted Asteroids weighted beat timing logic from `AsteroidsGameScene.js` into `games/Asteroids/game/asteroidsBeatTiming.js`.
+- Preserved the PR_26139_026 weights and cadence behavior:
+  - large asteroid: `9`
+  - medium asteroid: `4`
+  - small asteroid: `1`
+- Kept cadence tuning unchanged at the existing `0.18s` fast bound and `0.98s` slow bound.
+- Left `AsteroidsGameScene.js` responsible only for baseline lifecycle and applying the resolved beat interval.
+
+## Behavior Preservation
+- The targeted PR_26139_026 validation still confirms:
+  - `8 large = 72`
+  - `16 medium = 64`
+  - `32 small = 32`
+  - inactive asteroid objects do not contribute
+  - lower weighted total produces faster cadence
+
+## Validation
+- PASS: `npm run build:manifest`
+- PASS: `npx playwright test tests/playwright/tools/AsteroidsBeatTiming.spec.mjs --project=playwright --workers=1 --reporter=list`
+  - 1 passed.
+- PASS: `git diff --check`
+
+## Coverage
+- Playwright impacted: Yes.
+- V8 coverage collected the changed Asteroids files:
+  - `(51%) games/Asteroids/game/AsteroidsGameScene.js - changed JS file with browser V8 coverage`
+  - `(100%) games/Asteroids/game/asteroidsBeatTiming.js - changed JS file with browser V8 coverage`
+- Note: the existing changed-runtime guardrail classifies only `src/`, `tools/`, and `common/` as runtime JS, so Asteroids game files appear under `Changed JS files considered` rather than `Changed runtime JS files covered`.
+
+## Full Samples
+- Full samples smoke test was skipped.
+- Reason: scope is limited to a focused Asteroids helper extraction with unchanged beat timing behavior covered by the targeted Asteroids Playwright test.
+
+## Manual Validation
+1. Launch `games/Asteroids/index.html`.
+2. Start a game.
+3. Split large asteroids into medium asteroids and confirm the beat speeds up.
+4. Split medium asteroids into small asteroids and confirm the beat speeds up again.
+5. Confirm cadence remains bounded and no gameplay/rendering behavior changes beyond the PR_26139_026 beat timing behavior.

games/Asteroids/game/AsteroidsGameScene.js

@@ -14,6 +14,10 @@ import AsteroidsAttractAdapter from './AsteroidsAttractAdapter.js';
 import AsteroidsHighScoreService from '../systems/AsteroidsHighScoreService.js';
 import AsteroidsInitialsEntry from '../systems/AsteroidsInitialsEntry.js';
 import { createAsteroidGeometryProfilesFromObjectVectorAssets } from './asteroidObjectGeometry.js';
+import {
+  calculateAsteroidsBeatTiming,
+  getAsteroidsBeatWeightedTotal
+} from './asteroidsBeatTiming.js';
 import {
   ASTEROIDS_OBJECT_GEOMETRY_IDS,
   ASTEROIDS_ASTEROID_SIZE_OBJECT_IDS,
@@ -32,13 +36,6 @@ const SCORE_TWO_X = 824;
 const LIFE_SPACING = 22;
 const PAUSE_OVERLAY_COLOR = 'rgba(2, 6, 23, 0.58)';
 const INITIALS_OVERLAY_COLOR = 'rgba(1, 6, 19, 0.62)';
-const ASTEROID_BEAT_MIN_INTERVAL_SECONDS = 0.18;
-const ASTEROID_BEAT_MAX_INTERVAL_SECONDS = 0.98;
-const ASTEROID_BEAT_SIZE_WEIGHTS = Object.freeze({
-  1: 1,
-  2: 4,
-  3: 9,
-});
 const ATTRACT_INPUT_CODES = [
   'Digit1',
   'Digit2',
@@ -81,31 +78,6 @@ function screenDimensionsFromOptions(options) {
   return { width, height };
 }
 
-function isActiveAsteroid(asteroid) {
-  return Boolean(asteroid)
-    && typeof asteroid === 'object'
-    && asteroid.active !== false
-    && asteroid.alive !== false
-    && asteroid.destroyed !== true;
-}
-
-export function getAsteroidsBeatWeightedTotal(asteroids) {
-  if (!Array.isArray(asteroids)) {
-    return 0;
-  }
-  return asteroids.reduce((total, asteroid) => (
-    total + (isActiveAsteroid(asteroid) ? ASTEROID_BEAT_SIZE_WEIGHTS[asteroid.size] || 0 : 0)
-  ), 0);
-}
-
-export function getAsteroidsBeatInterval(weightedTotal, maxWeightedTotal) {
-  const safeWeightedTotal = Math.max(0, Number.isFinite(weightedTotal) ? weightedTotal : 0);
-  const safeMaxWeightedTotal = Math.max(1, Number.isFinite(maxWeightedTotal) ? maxWeightedTotal : safeWeightedTotal);
-  const weightedProgress = Math.min(1, safeWeightedTotal / safeMaxWeightedTotal);
-  return ASTEROID_BEAT_MIN_INTERVAL_SECONDS
-    + ((ASTEROID_BEAT_MAX_INTERVAL_SECONDS - ASTEROID_BEAT_MIN_INTERVAL_SECONDS) * weightedProgress);
-}
-
 export default class AsteroidsGameScene extends Scene {
   constructor(options = {}) {
     super();
@@ -553,13 +525,9 @@ export default class AsteroidsGameScene extends Scene {
   }
 
   resolveAsteroidsBeatTiming() {
-    const weightedTotal = getAsteroidsBeatWeightedTotal(this.world?.asteroids);
-    this.beatMaxWeightedTotal = Math.max(this.beatMaxWeightedTotal, weightedTotal, 1);
-    return {
-      intervalSeconds: getAsteroidsBeatInterval(weightedTotal, this.beatMaxWeightedTotal),
-      maxWeightedTotal: this.beatMaxWeightedTotal,
-      weightedTotal,
-    };
+    const beatTiming = calculateAsteroidsBeatTiming(this.world?.asteroids, this.beatMaxWeightedTotal);
+    this.beatMaxWeightedTotal = beatTiming.maxWeightedTotal;
+    return beatTiming;
   }
 
   update(dtSeconds, engine) {

games/Asteroids/game/asteroidsBeatTiming.js

@@ -0,0 +1,43 @@
+const ASTEROID_BEAT_MIN_INTERVAL_SECONDS = 0.18;
+const ASTEROID_BEAT_MAX_INTERVAL_SECONDS = 0.98;
+const ASTEROID_BEAT_SIZE_WEIGHTS = Object.freeze({
+  1: 1,
+  2: 4,
+  3: 9,
+});
+
+function isActiveAsteroid(asteroid) {
+  return Boolean(asteroid)
+    && typeof asteroid === 'object'
+    && asteroid.active !== false
+    && asteroid.alive !== false
+    && asteroid.destroyed !== true;
+}
+
+export function getAsteroidsBeatWeightedTotal(asteroids) {
+  if (!Array.isArray(asteroids)) {
+    return 0;
+  }
+  return asteroids.reduce((total, asteroid) => (
+    total + (isActiveAsteroid(asteroid) ? ASTEROID_BEAT_SIZE_WEIGHTS[asteroid.size] || 0 : 0)
+  ), 0);
+}
+
+function getAsteroidsBeatInterval(weightedTotal, maxWeightedTotal) {
+  const safeWeightedTotal = Math.max(0, Number.isFinite(weightedTotal) ? weightedTotal : 0);
+  const safeMaxWeightedTotal = Math.max(1, Number.isFinite(maxWeightedTotal) ? maxWeightedTotal : safeWeightedTotal);
+  const weightedProgress = Math.min(1, safeWeightedTotal / safeMaxWeightedTotal);
+  return ASTEROID_BEAT_MIN_INTERVAL_SECONDS
+    + ((ASTEROID_BEAT_MAX_INTERVAL_SECONDS - ASTEROID_BEAT_MIN_INTERVAL_SECONDS) * weightedProgress);
+}
+
+export function calculateAsteroidsBeatTiming(asteroids, currentMaxWeightedTotal) {
+  const weightedTotal = getAsteroidsBeatWeightedTotal(asteroids);
+  const baselineWeightedTotal = Number.isFinite(currentMaxWeightedTotal) ? currentMaxWeightedTotal : 1;
+  const maxWeightedTotal = Math.max(baselineWeightedTotal, weightedTotal, 1);
+  return {
+    intervalSeconds: getAsteroidsBeatInterval(weightedTotal, maxWeightedTotal),
+    maxWeightedTotal,
+    weightedTotal,
+  };
+}