@jjlmoya/utils-games-development 1.64.0 → 1.65.0

package/src/tool/gameDeltaTimeFixedTimestepLab/component.astro

@@ -0,0 +1,51 @@
+---
+import type { GameDeltaTimeFixedTimestepLabUI } from './ui';
+
+interface Props {
+  ui: GameDeltaTimeFixedTimestepLabUI;
+}
+
+const { ui } = Astro.props as Props;
+---
+
+<div class="game-loop-lab" data-game-loop-lab>
+  <div class="gll-shell">
+    <form class="gll-controls" data-controls>
+      <div class="gll-control-heading"><p class="gll-kicker">{ui.controlsTitle}</p></div>
+      <label class="gll-range-field"><span>{ui.fpsLabel}</span><output data-output="fps">60</output><input data-field="fps" type="range" min="1" max="240" step="1" value="60" /></label>
+      <p class="gll-field-hint">{ui.fpsHint}</p>
+      <label class="gll-range-field"><span>{ui.spikeLabel} ({ui.unitMs})</span><output data-output="spikeMs">80</output><input data-field="spikeMs" type="range" min="0" max="250" step="1" value="80" /></label>
+      <p class="gll-field-hint">{ui.spikeHint}</p>
+      <label class="gll-number-field"><span>{ui.spikeEveryLabel}</span><input data-field="spikeEveryFrames" type="number" min="1" max="600" step="1" value="30" /></label>
+      <label class="gll-range-field"><span>{ui.fixedDtLabel} ({ui.unitMs})</span><output data-output="fixedDtMs">16.666</output><input data-field="fixedDtMs" type="range" min="1" max="50" step="0.001" value="16.666" /></label>
+      <p class="gll-field-hint">{ui.fixedDtHint}</p>
+      <label class="gll-range-field"><span>{ui.velocityLabel}</span><output data-output="velocity">20</output><input data-field="velocity" type="range" min="0" max="100" step="1" value="20" /></label>
+      <label class="gll-range-field"><span>{ui.durationLabel}</span><output data-output="durationSeconds">6</output><input data-field="durationSeconds" type="range" min="1" max="20" step="1" value="6" /></label>
+      <div class="gll-clamp" data-clamp-detail>
+        <label class="gll-check-field"><input data-field="clampEnabled" type="checkbox" /><span>{ui.clampToggle}</span></label>
+        <label class="gll-range-field"><span>{ui.clampLabel} ({ui.unitMs})</span><output data-output="clampMs">100</output><input data-field="clampMs" type="range" min="1" max="250" step="1" value="100" /></label>
+      </div>
+      <div class="gll-actions"><button type="button" class="gll-primary" data-run>{ui.runLabel}</button><button type="button" class="gll-secondary" data-reset>{ui.resetLabel}</button></div>
+    </form>
+    <section class="gll-stage" aria-labelledby="gll-stage-title">
+      <div class="gll-stage-heading"><div><p class="gll-kicker">{ui.stageKicker}</p><h2 id="gll-stage-title">{ui.stageTitle}</h2><p>{ui.stageCaption}</p></div><span class="gll-live-badge" data-live aria-live="polite">{ui.statusReady}</span></div>
+      <div class="gll-stage-visual" data-stage></div>
+      <div data-summary></div>
+      <div class="gll-timeline-heading"><h3>{ui.timelineTitle}</h3><p>{ui.timelineCaption}</p></div>
+      <div data-chart></div>
+      <div class="gll-legend"><span><i class="gll-legend-dot gll-variable-dot"></i>{ui.legendVariable}</span><span><i class="gll-legend-dot gll-fixed-dot"></i>{ui.legendFixed}</span><span><i class="gll-legend-dot gll-spike-dot"></i>{ui.legendSpike}</span></div>
+      <div class="gll-table" data-table></div>
+      <p class="gll-model-note">{ui.modelNote}</p>
+      <p class="gll-privacy">{ui.privacyDisclosure}</p>
+    </section>
+  </div>
+</div>
+
+<script is:inline type="application/json" data-game-loop-ui set:html={JSON.stringify(ui)}></script>
+
+<script>
+  import { mountGameDeltaTimeFixedTimestepLab } from './controller';
+  const root = document.querySelector<HTMLElement>('[data-game-loop-lab]');
+  const uiScript = document.querySelector<HTMLScriptElement>('[data-game-loop-ui]');
+  if (root && uiScript) mountGameDeltaTimeFixedTimestepLab(root, JSON.parse(uiScript.textContent ?? '{}'));
+</script>

package/src/tool/gameDeltaTimeFixedTimestepLab/controller.ts

@@ -0,0 +1,79 @@
+import { evaluateLoop } from './evaluator';
+import { DEFAULT_LOOP_CONFIG, normalizeLoopConfig, simulateLoop, type LoopConfig } from './logic';
+import { renderAccessibleTable, renderChart, renderStage, renderSummary } from './dom-views';
+import { loadLoopConfig, saveLoopConfig } from './storage';
+import type { GameDeltaTimeFixedTimestepLabUI } from './ui';
+
+const fieldNames: (keyof LoopConfig)[] = ['fps', 'spikeMs', 'spikeEveryFrames', 'fixedDtMs', 'velocity', 'durationSeconds', 'clampMs'];
+
+function input(root: HTMLElement, name: string): HTMLInputElement {
+  return root.querySelector<HTMLInputElement>(`[data-field="${name}"]`) as HTMLInputElement;
+}
+
+function readConfig(root: HTMLElement): LoopConfig {
+  const values = Object.fromEntries(fieldNames.map((name) => [name, Number(input(root, name).value)]));
+  const clampEnabled = root.querySelector<HTMLInputElement>('[data-field="clampEnabled"]')?.checked ?? false;
+  return normalizeLoopConfig({ ...values, clampEnabled });
+}
+
+function syncOutputs(root: HTMLElement): void {
+  fieldNames.forEach((name) => {
+    const field = input(root, name);
+    const output = root.querySelector<HTMLOutputElement>(`[data-output="${name}"]`);
+    if (output) output.value = field.value;
+  });
+}
+
+function syncClamp(root: HTMLElement): void {
+  const enabled = root.querySelector<HTMLInputElement>('[data-field="clampEnabled"]')?.checked ?? false;
+  input(root, 'clampMs').disabled = !enabled;
+  root.querySelector<HTMLElement>('[data-clamp-detail]')?.toggleAttribute('data-disabled', !enabled);
+}
+
+function render(root: HTMLElement, ui: GameDeltaTimeFixedTimestepLabUI, config: LoopConfig): void {
+  const result = simulateLoop(config);
+  const diagnostic = evaluateLoop(result);
+  const stage = root.querySelector<HTMLElement>('[data-stage]');
+  const summary = root.querySelector<HTMLElement>('[data-summary]');
+  const chart = root.querySelector<HTMLElement>('[data-chart]');
+  const table = root.querySelector<HTMLElement>('[data-table]');
+  if (stage) renderStage(stage, result, ui);
+  if (summary) renderSummary(summary, result, diagnostic, ui);
+  if (chart) renderChart(chart, result, ui);
+  if (table) renderAccessibleTable(table, result, ui);
+  root.querySelector<HTMLElement>('[data-live]')!.textContent = ui.statusReady;
+  saveLoopConfig(config);
+}
+
+function bindInputs(root: HTMLElement, ui: GameDeltaTimeFixedTimestepLabUI): void {
+  fieldNames.forEach((name) => input(root, name).addEventListener('input', () => {
+    syncOutputs(root);
+    render(root, ui, readConfig(root));
+  }));
+  root.querySelector<HTMLInputElement>('[data-field="clampEnabled"]')?.addEventListener('change', () => {
+    syncClamp(root);
+    render(root, ui, readConfig(root));
+  });
+  root.querySelector<HTMLButtonElement>('[data-run]')?.addEventListener('click', () => {
+    render(root, ui, readConfig(root));
+  });
+  root.querySelector<HTMLButtonElement>('[data-reset]')?.addEventListener('click', () => {
+    fieldNames.forEach((name) => { input(root, name).value = String(DEFAULT_LOOP_CONFIG[name]); });
+    const checkbox = root.querySelector<HTMLInputElement>('[data-field="clampEnabled"]');
+    if (checkbox) checkbox.checked = DEFAULT_LOOP_CONFIG.clampEnabled;
+    syncOutputs(root);
+    syncClamp(root);
+    render(root, ui, readConfig(root));
+  });
+}
+
+export function mountGameDeltaTimeFixedTimestepLab(root: HTMLElement, ui: GameDeltaTimeFixedTimestepLabUI): void {
+  const stored = normalizeLoopConfig(loadLoopConfig());
+  fieldNames.forEach((name) => { input(root, name).value = String(stored[name]); });
+  const checkbox = root.querySelector<HTMLInputElement>('[data-field="clampEnabled"]');
+  if (checkbox) checkbox.checked = stored.clampEnabled;
+  syncOutputs(root);
+  syncClamp(root);
+  bindInputs(root, ui);
+  render(root, ui, stored);
+}

package/src/tool/gameDeltaTimeFixedTimestepLab/dom-views.ts

@@ -0,0 +1,88 @@
+import type { GameDeltaTimeFixedTimestepLabUI } from './ui';
+import type { LoopResult, LoopSample } from './logic';
+import type { Diagnostic } from './evaluator';
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (character) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character] ?? character);
+}
+
+function number(value: number, digits = 2): string {
+  return value.toLocaleString('en-US', { maximumFractionDigits: digits, minimumFractionDigits: digits });
+}
+
+function samplePoints(samples: LoopSample[]): LoopSample[] {
+  const stride = Math.max(1, Math.ceil(samples.length / 80));
+  return samples.filter((_, index) => index % stride === 0 || index === samples.length - 1);
+}
+
+interface PathOptions {
+  samples: LoopSample[];
+  key: 'variablePosition' | 'fixedPosition';
+  max: number;
+  top?: number;
+  height?: number;
+}
+
+function pathFor(options: PathOptions): string {
+  const { samples, key, max, top = 190, height = 140 } = options;
+  return samples.map((sample, index) => {
+    const x = 54 + (index / Math.max(1, samples.length - 1)) * 672;
+    const y = top - (sample[key] / max) * height;
+    return `${index === 0 ? 'M' : 'L'} ${x.toFixed(1)} ${y.toFixed(1)}`;
+  }).join(' ');
+}
+
+function differencePath(samples: LoopSample[], max: number): string {
+  return samples.map((sample, index) => {
+    const x = 54 + (index / Math.max(1, samples.length - 1)) * 672;
+    const difference = sample.variablePosition - sample.fixedPosition;
+    const y = 247 - ((difference + max) / (max * 2)) * 54;
+    return `${index === 0 ? 'M' : 'L'} ${x.toFixed(1)} ${y.toFixed(1)}`;
+  }).join(' ');
+}
+
+function frameBars(samples: LoopSample[], baseMs: number, maxMs: number): string {
+  return samples.map((sample, index) => {
+    const x = 54 + (index / Math.max(1, samples.length - 1)) * 672;
+    const height = (sample.frameMs / maxMs) * 30;
+    const isSpike = sample.frameMs > baseMs * 1.25;
+    return `<rect class="${isSpike ? 'gll-spike-bar' : 'gll-frame-bar'}" x="${(x - 3).toFixed(1)}" y="${(76 - height).toFixed(1)}" width="6" height="${height.toFixed(1)}" rx="2" />`;
+  }).join('');
+}
+
+export function renderStage(target: HTMLElement, result: LoopResult, ui: GameDeltaTimeFixedTimestepLabUI): void {
+  const points = samplePoints(result.samples);
+  const maxPosition = Math.max(1, result.variablePosition, result.fixedPosition);
+  const maxDifference = Math.max(1, ...points.map((sample) => Math.abs(sample.variablePosition - sample.fixedPosition)));
+  const baseMs = 1000 / result.config.fps;
+  const maxMs = Math.max(baseMs, ...points.map((sample) => sample.frameMs));
+  const bars = frameBars(points, baseMs, maxMs);
+  const variablePath = pathFor({ samples: points, key: 'variablePosition', max: maxPosition, top: 170, height: 60 });
+  const fixedPath = pathFor({ samples: points, key: 'fixedPosition', max: maxPosition, top: 170, height: 60 });
+  const deltaPath = differencePath(points, maxDifference);
+  const variableY = 170 - (result.variablePosition / maxPosition) * 60;
+  const fixedY = 170 - (result.fixedPosition / maxPosition) * 60;
+  target.innerHTML = `<svg class="gll-stage-svg" viewBox="0 0 760 330" role="img" aria-label="${escapeHtml(ui.stageTitle)}"><rect class="gll-paper" x="0" y="0" width="760" height="330" rx="18" /><text class="gll-plot-title" x="24" y="28">${escapeHtml(ui.frameTraceLabel)}</text><line class="gll-base-line" x1="54" y1="76" x2="726" y2="76" />${bars}<text class="gll-plot-axis" x="726" y="94" text-anchor="end">${number(maxMs, 1)} ${escapeHtml(ui.unitMs)}</text><text class="gll-plot-title" x="24" y="112">${escapeHtml(ui.positionPlotLabel)}</text><line class="gll-grid-line" x1="54" y1="170" x2="726" y2="170" /><text class="gll-plot-label" x="24" y="140">${escapeHtml(ui.variableLane)}</text><text class="gll-plot-label" x="24" y="165">${escapeHtml(ui.fixedLane)}</text><path class="gll-variable-line gll-stage-position-line" d="${variablePath}" /><path class="gll-fixed-line gll-stage-position-line" d="${fixedPath}" /><circle class="gll-variable-token" cx="726" cy="${variableY.toFixed(1)}" r="7" /><circle class="gll-fixed-token" cx="726" cy="${fixedY.toFixed(1)}" r="7" /><text class="gll-plot-axis" x="726" y="184" text-anchor="end">${number(maxPosition)} ${escapeHtml(ui.unitPixels)}</text><text class="gll-plot-title" x="24" y="210">${escapeHtml(ui.differencePlotLabel)}</text><line class="gll-zero-line" x1="54" y1="247" x2="726" y2="247" />${deltaPath ? `<path class="gll-difference-line" d="${deltaPath}" />` : ''}<text class="gll-plot-axis" x="726" y="268" text-anchor="end">+/- ${number(maxDifference)} ${escapeHtml(ui.unitPixels)}</text><text class="gll-stage-axis" x="54" y="302">0 ${escapeHtml(ui.unitSeconds)}</text><text class="gll-stage-axis" x="726" y="302" text-anchor="end">${number(result.totalWallTime)} ${escapeHtml(ui.unitSeconds)}</text></svg>`;
+}
+
+export function renderChart(target: HTMLElement, result: LoopResult, ui: GameDeltaTimeFixedTimestepLabUI): void {
+  const points = samplePoints(result.samples);
+  const max = Math.max(1, ...points.map((sample) => Math.max(sample.variablePosition, sample.fixedPosition)));
+  const variablePath = pathFor({ samples: points, key: 'variablePosition', max });
+  const fixedPath = pathFor({ samples: points, key: 'fixedPosition', max });
+  target.innerHTML = `<svg class="gll-chart-svg" viewBox="0 0 760 250" role="img" aria-label="${escapeHtml(ui.timelineTitle)}"><line class="gll-chart-axis" x1="54" y1="190" x2="726" y2="190" /><line class="gll-chart-axis" x1="54" y1="32" x2="54" y2="190" /><path class="gll-variable-line" d="${variablePath}" /><path class="gll-fixed-line" d="${fixedPath}" /><text class="gll-chart-label" x="54" y="220">0 ${escapeHtml(ui.unitSeconds)}</text><text class="gll-chart-label" x="726" y="220" text-anchor="end">${number(result.totalWallTime)} ${escapeHtml(ui.unitSeconds)}</text><text class="gll-chart-label" x="42" y="38" text-anchor="end">${number(max)} ${escapeHtml(ui.unitPixels)}</text><text class="gll-chart-label" x="390" y="244" text-anchor="middle">${escapeHtml(ui.frameAxis)}</text><text class="gll-chart-label" x="14" y="110" transform="rotate(-90 14 110)" text-anchor="middle">${escapeHtml(ui.positionAxis)}</text></svg>`;
+}
+
+function diagnosticText(diagnostic: Diagnostic, ui: GameDeltaTimeFixedTimestepLabUI): string {
+  const labels = { stable: ui.stableStatus, variable: ui.variableStatus, fixed: ui.fixedStatus, clamped: ui.clampStatus };
+  return labels[diagnostic.key];
+}
+
+export function renderSummary(target: HTMLElement, result: LoopResult, diagnostic: Diagnostic, ui: GameDeltaTimeFixedTimestepLabUI): void {
+  target.innerHTML = `<div class="gll-summary-grid"><div><span>${escapeHtml(ui.frameCountLabel)}</span><strong>${result.frameCount.toLocaleString('en-US')}</strong></div><div><span>${escapeHtml(ui.wallTimeLabel)}</span><strong>${number(result.totalWallTime)} ${escapeHtml(ui.unitSeconds)}</strong></div><div><span>${escapeHtml(ui.variableTimeLabel)}</span><strong>${number(result.variableTime)} ${escapeHtml(ui.unitSeconds)}</strong></div><div><span>${escapeHtml(ui.fixedTimeLabel)}</span><strong>${number(result.fixedTime)} ${escapeHtml(ui.unitSeconds)}</strong></div><div><span>${escapeHtml(ui.divergenceLabel)}</span><strong>${number(result.divergence)} ${escapeHtml(ui.unitPixels)}</strong></div><div><span>${escapeHtml(ui.stepsLabel)}</span><strong>${result.fixedSteps.toLocaleString('en-US')}</strong></div></div><p class="gll-diagnostic gll-diagnostic-${diagnostic.severity}">${escapeHtml(ui.diagnosticsTitle)}: ${escapeHtml(diagnosticText(diagnostic, ui))}</p>`;
+}
+
+export function renderAccessibleTable(target: HTMLElement, result: LoopResult, ui: GameDeltaTimeFixedTimestepLabUI): void {
+  const rows = samplePoints(result.samples).slice(-8).map((sample) => `<tr><td>${sample.frame}</td><td>${number(sample.wallTime)} ${escapeHtml(ui.unitSeconds)}</td><td>${number(sample.variablePosition)} ${escapeHtml(ui.unitPixels)}</td><td>${number(sample.fixedPosition)} ${escapeHtml(ui.unitPixels)}</td><td>${number(sample.variablePosition - sample.fixedPosition)} ${escapeHtml(ui.unitPixels)}</td></tr>`).join('');
+  target.innerHTML = `<h3>${escapeHtml(ui.tableTitle)}</h3><table><thead><tr><th>${escapeHtml(ui.tableFrame)}</th><th>${escapeHtml(ui.tableWall)}</th><th>${escapeHtml(ui.tableVariable)}</th><th>${escapeHtml(ui.tableFixed)}</th><th>${escapeHtml(ui.tableDelta)}</th></tr></thead><tbody>${rows}</tbody></table>`;
+}

package/src/tool/gameDeltaTimeFixedTimestepLab/entry.ts

@@ -0,0 +1,27 @@
+import type { GamesToolEntry, ToolLocaleContent } from '../../types';
+import type { GameDeltaTimeFixedTimestepLabUI } from './ui';
+
+export type { GameDeltaTimeFixedTimestepLabUI };
+export type GameDeltaTimeFixedTimestepLabLocaleContent = ToolLocaleContent<GameDeltaTimeFixedTimestepLabUI>;
+
+export const gameDeltaTimeFixedTimestepLab: GamesToolEntry<GameDeltaTimeFixedTimestepLabUI> = {
+  id: 'game-delta-time-fixed-timestep-lab',
+  icons: { bg: 'mdi:timer-sand', fg: 'mdi:gamepad-variant' },
+  i18n: {
+    de: () => import('./i18n/de').then((module) => module.content),
+    en: () => import('./i18n/en').then((module) => module.content),
+    es: () => import('./i18n/es').then((module) => module.content),
+    fr: () => import('./i18n/fr').then((module) => module.content),
+    id: () => import('./i18n/id').then((module) => module.content),
+    it: () => import('./i18n/it').then((module) => module.content),
+    ja: () => import('./i18n/ja').then((module) => module.content),
+    ko: () => import('./i18n/ko').then((module) => module.content),
+    nl: () => import('./i18n/nl').then((module) => module.content),
+    pl: () => import('./i18n/pl').then((module) => module.content),
+    pt: () => import('./i18n/pt').then((module) => module.content),
+    ru: () => import('./i18n/ru').then((module) => module.content),
+    sv: () => import('./i18n/sv').then((module) => module.content),
+    tr: () => import('./i18n/tr').then((module) => module.content),
+    zh: () => import('./i18n/zh').then((module) => module.content),
+  },
+};

package/src/tool/gameDeltaTimeFixedTimestepLab/evaluator.ts

@@ -0,0 +1,21 @@
+import type { LoopResult } from './logic';
+
+export type DiagnosticKey = 'stable' | 'variable' | 'fixed' | 'clamped';
+
+export interface Diagnostic {
+  key: DiagnosticKey;
+  severity: 'calm' | 'notice' | 'warning';
+}
+
+export function evaluateLoop(result: LoopResult): Diagnostic {
+  if (result.config.clampEnabled && Math.abs(result.divergence) > 0.01) {
+    return { key: 'clamped', severity: 'warning' };
+  }
+  if (Math.abs(result.divergence) > 0.01 && result.variablePosition > result.fixedPosition) {
+    return { key: 'variable', severity: 'warning' };
+  }
+  if (result.maxCatchUp > 1) {
+    return { key: 'fixed', severity: 'notice' };
+  }
+  return { key: 'stable', severity: 'calm' };
+}