@jjlmoya/utils-games-development 1.54.0 → 1.56.0

package/src/tool/pixelArtPaletteSwapper/ui.ts

@@ -0,0 +1,35 @@
+export interface PixelArtPaletteSwapperUI extends Record<string, string> {
+  uploadTitle: string;
+  uploadHint: string;
+  chooseImage: string;
+  replaceImage: string;
+  paletteTitle: string;
+  gameBoyPalette: string;
+  nesPalette: string;
+  pico8Palette: string;
+  commodore64Palette: string;
+  dawnBringerPalette: string;
+  customPalette: string;
+  customPaletteHint: string;
+  applyCustomPalette: string;
+  resetCustomPalette: string;
+  sourcePreview: string;
+  resultPreview: string;
+  waitingForImage: string;
+  uploadToPreview: string;
+  resultEmpty: string;
+  downloadPng: string;
+  downloadDisabled: string;
+  colorCount: string;
+  mappedCount: string;
+  imageSize: string;
+  paletteCount: string;
+  preserveAlpha: string;
+  zoomLabel: string;
+  processing: string;
+  invalidPalette: string;
+  invalidImage: string;
+  readyStatus: string;
+  dropActive: string;
+  mappedSummary: string;
+}

package/src/tool/retroSfxGenerator/bibliography.astro

@@ -0,0 +1,6 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import { bibliographyEntries } from './bibliography';
+---
+
+<SharedBibliography links={bibliographyEntries} />

package/src/tool/retroSfxGenerator/bibliography.ts

@@ -0,0 +1,16 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliographyEntries: BibliographyEntry[] = [
+  {
+    name: 'W3C Web Audio API Recommendation',
+    url: 'https://www.w3.org/TR/webaudio/',
+  },
+  {
+    name: 'MDN OscillatorNode Web API Reference',
+    url: 'https://developer.mozilla.org/en-US/docs/Web/API/OscillatorNode',
+  },
+  {
+    name: 'Microsoft RIFF WAVE Audio File Format',
+    url: 'https://www.mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/WAVE.html',
+  },
+];

package/src/tool/retroSfxGenerator/client.ts

@@ -0,0 +1,263 @@
+import {
+  calculateEndFrequency,
+  createDefaultParams,
+  encodeWav,
+  formatDuration,
+  formatFrequency,
+  generateSfx,
+  getPresetParams,
+  type SfxParams,
+  type SfxPreset,
+  type SfxWaveform,
+} from './logic';
+
+const root = document.querySelector<HTMLElement>('#rsfx-root');
+
+if (root) {
+  const canvas = root.querySelector<HTMLCanvasElement>('#rsfx-waveform');
+  const status = root.querySelector<HTMLElement>('#rsfx-status');
+  const readout = root.querySelector<HTMLElement>('#rsfx-readout');
+  const led = root.querySelector<HTMLElement>('#rsfx-led');
+  const frequencyReadout = root.querySelector<HTMLElement>('#rsfx-frequency-readout');
+  const durationReadout = root.querySelector<HTMLElement>('#rsfx-duration-readout');
+  const waveformSelect = root.querySelector<HTMLSelectElement>('#rsfx-waveform-select');
+  const playButton = root.querySelector<HTMLButtonElement>('#rsfx-play');
+  const stopButton = root.querySelector<HTMLButtonElement>('#rsfx-stop');
+  const downloadButton = root.querySelector<HTMLButtonElement>('#rsfx-download');
+  const randomizeButton = root.querySelector<HTMLButtonElement>('#rsfx-randomize');
+  const resetButton = root.querySelector<HTMLButtonElement>('#rsfx-reset');
+  const presetButtons = Array.from(root.querySelectorAll<HTMLButtonElement>('[data-preset]'));
+  const statusReady = root.dataset.statusReady ?? 'Ready';
+  const statusPlaying = root.dataset.statusPlaying ?? 'Playing';
+  const statusStopped = root.dataset.statusStopped ?? 'Stopped';
+  const statusDownloaded = root.dataset.statusDownloaded ?? 'Downloaded';
+  const statusAudioBlocked = root.dataset.statusAudioBlocked ?? 'Audio playback is unavailable';
+  const statusGenerating = root.dataset.statusGenerating ?? 'Generating';
+  const generatedLabel = root.dataset.generatedLabel ?? 'Generated';
+  const frequencyLabel = root.dataset.frequencyLabel ?? 'Frequency';
+  const frequencyEndLabel = root.dataset.frequencyEndLabel ?? 'End frequency';
+  const durationLabel = root.dataset.durationLabel ?? 'Duration';
+  const activePresetButton = presetButtons.find((button) => button.classList.contains('is-active'));
+  let currentPreset = (activePresetButton?.dataset.preset as SfxPreset | undefined) ?? 'explosion';
+  let params = createDefaultParams();
+  let generated = generateSfx(params);
+  let audioContext: AudioContext | undefined;
+  let source: AudioBufferSourceNode | undefined;
+
+  const input = (id: string): HTMLInputElement | null => root.querySelector<HTMLInputElement>(id);
+  const output = (id: string): HTMLOutputElement | null => root.querySelector<HTMLOutputElement>(id);
+
+  function drawCenterLine(ctx: CanvasRenderingContext2D, width: number, height: number, color: string): void {
+    ctx.shadowBlur = 0;
+    ctx.strokeStyle = color;
+    ctx.globalAlpha = 0.45;
+    ctx.beginPath();
+    ctx.moveTo(0, height / 2);
+    ctx.lineTo(width, height / 2);
+    ctx.stroke();
+    ctx.globalAlpha = 1;
+  }
+
+  function drawSamplesPath(ctx: CanvasRenderingContext2D, samples: Float32Array, width: number, height: number): void {
+    ctx.beginPath();
+    const step = Math.max(1, Math.floor(samples.length / width));
+    for (let x = 0; x < width; x += 1) {
+      const index = Math.min(samples.length - 1, x * step);
+      const sample = samples[index] ?? 0;
+      const y = height / 2 - sample * height * 0.38;
+      if (x === 0) {
+        ctx.moveTo(x, y);
+      } else {
+        ctx.lineTo(x, y);
+      }
+    }
+    ctx.stroke();
+  }
+
+  function drawWaveform(): void {
+    if (!canvas || !root) return;
+    const rect = canvas.getBoundingClientRect();
+    const ratio = window.devicePixelRatio || 1;
+    const width = Math.max(320, Math.round(rect.width * ratio));
+    const height = Math.max(160, Math.round(rect.height * ratio));
+    canvas.width = width;
+    canvas.height = height;
+    const context = canvas.getContext('2d');
+    if (!context) return;
+    const styles = getComputedStyle(root);
+    const waveformColor = styles.getPropertyValue('--rsfx-waveform').trim() || '#72f2c8';
+    const waveformGlow = styles.getPropertyValue('--rsfx-waveform-glow').trim() || 'rgba(114, 242, 200, 0.75)';
+    context.clearRect(0, 0, width, height);
+    context.lineWidth = Math.max(1, ratio * 1.5);
+    context.strokeStyle = waveformColor;
+    context.shadowColor = waveformGlow;
+    context.shadowBlur = 8 * ratio;
+    drawSamplesPath(context, generated.samples, width, height);
+    drawCenterLine(context, width, height, waveformGlow);
+  }
+
+  function setStatus(value: string): void {
+    if (status) status.textContent = value;
+  }
+
+  function setOutputValue(id: string, value: string): void {
+    const target = output(id);
+    if (target) target.value = value;
+  }
+
+  function updateOutputReadouts(): void {
+    setOutputValue('#rsfx-frequency-value', formatFrequency(params.frequency));
+    setOutputValue('#rsfx-sweep-value', `${Math.round(params.sweep * 100)}%`);
+    setOutputValue('#rsfx-duration-value', formatDuration(params.duration));
+    setOutputValue('#rsfx-decay-value', `${Math.round(params.decay * 100)}%`);
+    setOutputValue('#rsfx-vibrato-value', `${Math.round(params.vibrato * 100)}%`);
+    setOutputValue('#rsfx-lowpass-value', formatFrequency(params.lowpass));
+    setOutputValue('#rsfx-highpass-value', formatFrequency(params.highpass));
+    setOutputValue('#rsfx-noise-mix-value', `${Math.round(params.noiseMix * 100)}%`);
+  }
+
+  function renderReadouts(): void {
+    updateOutputReadouts();
+    if (readout) readout.textContent = `${generatedLabel} · ${params.waveform}`;
+    if (frequencyReadout) frequencyReadout.textContent = `${frequencyLabel} ${formatFrequency(params.frequency)} → ${frequencyEndLabel} ${formatFrequency(params.frequencyEnd)}`;
+    if (durationReadout) durationReadout.textContent = `${durationLabel} ${formatDuration(params.duration)}`;
+  }
+
+  function syncInputs(): void {
+    const values: Record<string, string> = {
+      '#rsfx-frequency': String(Math.round(params.frequency)),
+      '#rsfx-sweep': String(Math.round(params.sweep * 100)),
+      '#rsfx-duration': params.duration.toFixed(2),
+      '#rsfx-decay': String(Math.round(params.decay * 100)),
+      '#rsfx-vibrato': String(Math.round(params.vibrato * 100)),
+      '#rsfx-lowpass': String(Math.round(params.lowpass)),
+      '#rsfx-highpass': String(Math.round(params.highpass)),
+      '#rsfx-noise-mix': String(Math.round(params.noiseMix * 100)),
+    };
+    Object.entries(values).forEach(([selector, value]) => {
+      const element = input(selector);
+      if (element) element.value = value;
+    });
+    if (waveformSelect) waveformSelect.value = params.waveform;
+    renderReadouts();
+  }
+
+  function regenerate(nextParams: SfxParams, nextStatus = statusReady): void {
+    setStatus(statusGenerating);
+    params = { ...nextParams, frequencyEnd: calculateEndFrequency(nextParams.frequency, nextParams.sweep) };
+    generated = generateSfx(params);
+    syncInputs();
+    drawWaveform();
+    setStatus(nextStatus);
+  }
+
+  function parseInputValue(selector: string, fallback: number, divisor = 1): number {
+    const raw = input(selector)?.value;
+    if (raw === undefined) return fallback;
+    const val = Number(raw) / divisor;
+    return Number.isFinite(val) ? val : fallback;
+  }
+
+  function readParams(): SfxParams {
+    const frequency = parseInputValue('#rsfx-frequency', params.frequency);
+    const sweep = parseInputValue('#rsfx-sweep', params.sweep * 100, 100);
+    const duration = parseInputValue('#rsfx-duration', params.duration);
+    const decay = parseInputValue('#rsfx-decay', params.decay * 100, 100);
+    const vibrato = parseInputValue('#rsfx-vibrato', params.vibrato * 100, 100);
+    const lowpass = parseInputValue('#rsfx-lowpass', params.lowpass);
+    const highpass = parseInputValue('#rsfx-highpass', params.highpass);
+    const noiseMix = parseInputValue('#rsfx-noise-mix', params.noiseMix * 100, 100);
+    const waveform = (waveformSelect?.value ?? params.waveform) as SfxWaveform;
+    return {
+      ...params,
+      waveform,
+      frequency,
+      frequencyEnd: calculateEndFrequency(frequency, sweep),
+      duration,
+      decay,
+      sweep,
+      vibrato,
+      lowpass,
+      highpass,
+      noiseMix,
+    };
+  }
+
+  function stopAudio(): void {
+    if (source) {
+      source.stop();
+      source.disconnect();
+      source = undefined;
+    }
+    if (led) led.classList.remove('is-on');
+    setStatus(statusStopped);
+  }
+
+  async function playAudio(): Promise<void> {
+    try {
+      if (!audioContext) audioContext = new AudioContext();
+      await audioContext.resume();
+      stopAudio();
+      const buffer = audioContext.createBuffer(1, generated.samples.length, generated.sampleRate);
+      buffer.getChannelData(0).set(generated.samples);
+      source = audioContext.createBufferSource();
+      source.buffer = buffer;
+      source.connect(audioContext.destination);
+      source.onended = () => {
+        source = undefined;
+        if (led) led.classList.remove('is-on');
+        setStatus(statusReady);
+      };
+      source.start();
+      if (led) led.classList.add('is-on');
+      setStatus(statusPlaying);
+    } catch {
+      setStatus(statusAudioBlocked);
+    }
+  }
+
+  function downloadWav(): void {
+    const wav = encodeWav(generated.samples, generated.sampleRate);
+    const url = URL.createObjectURL(new Blob([wav.buffer as ArrayBuffer], { type: 'audio/wav' }));
+    const anchor = document.createElement('a');
+    anchor.href = url;
+    anchor.download = `retro-${params.waveform}-${Math.round(params.frequency)}hz.wav`;
+    anchor.click();
+    URL.revokeObjectURL(url);
+    setStatus(statusDownloaded);
+  }
+
+  function bindControls(): void {
+    const ids = ['#rsfx-frequency', '#rsfx-sweep', '#rsfx-duration', '#rsfx-decay', '#rsfx-vibrato', '#rsfx-lowpass', '#rsfx-highpass', '#rsfx-noise-mix'];
+    ids.forEach((selector) => {
+      input(selector)?.addEventListener('input', () => regenerate(readParams()));
+    });
+    waveformSelect?.addEventListener('change', () => regenerate(readParams()));
+    presetButtons.forEach((button) => {
+      button.addEventListener('click', () => {
+        const preset = button.dataset.preset as SfxPreset;
+        currentPreset = preset;
+        presetButtons.forEach((item) => item.classList.toggle('is-active', item === button));
+        regenerate(getPresetParams(preset));
+      });
+    });
+    playButton?.addEventListener('click', () => void playAudio());
+    stopButton?.addEventListener('click', stopAudio);
+    downloadButton?.addEventListener('click', downloadWav);
+    randomizeButton?.addEventListener('click', () => {
+      regenerate(getPresetParams(currentPreset));
+      void playAudio();
+    });
+    resetButton?.addEventListener('click', () => {
+      currentPreset = 'explosion';
+      presetButtons.forEach((item) => item.classList.toggle('is-active', item.dataset.preset === 'explosion'));
+      regenerate(createDefaultParams());
+    });
+    window.addEventListener('resize', drawWaveform);
+  }
+
+  syncInputs();
+  bindControls();
+  drawWaveform();
+  void canvas?.getContext('2d');
+}

package/src/tool/retroSfxGenerator/component.astro

@@ -0,0 +1,146 @@
+---
+import type { RetroSfxGeneratorUI } from './ui';
+import './retro-sfx-generator.css';
+
+interface Props {
+  ui: RetroSfxGeneratorUI;
+}
+
+const { ui } = Astro.props;
+---
+
+<div
+  class="rsfx-app"
+  id="rsfx-root"
+  data-status-ready={ui.statusReady}
+  data-status-playing={ui.statusPlaying}
+  data-status-stopped={ui.statusStopped}
+  data-status-downloaded={ui.statusDownloaded}
+  data-status-audio-blocked={ui.statusAudioBlocked}
+  data-status-generating={ui.statusGenerating}
+  data-waveform-preview-label={ui.waveformPreviewLabel}
+  data-generated-label={ui.generatedLabel}
+  data-frequency-label={ui.frequencyLabel}
+  data-frequency-end-label={ui.frequencyEndLabel}
+  data-duration-label={ui.durationLabel}
+  data-mono-wav-hint={ui.monoWavHint}
+>
+  <section class="rsfx-scope-panel" aria-labelledby="rsfx-scope-heading">
+    <div class="rsfx-scope-topline">
+      <div>
+        <span class="rsfx-kicker" id="rsfx-scope-heading">{ui.waveformPreviewLabel}</span>
+        <span class="rsfx-scope-readout" id="rsfx-readout">{ui.generatedLabel}</span>
+      </div>
+      <span class="rsfx-scope-led" id="rsfx-led" aria-hidden="true"></span>
+    </div>
+    <div class="rsfx-scope-screen">
+      <canvas id="rsfx-waveform" class="rsfx-waveform" aria-label={ui.waveformPreviewLabel}></canvas>
+      <div class="rsfx-scope-grid" aria-hidden="true"></div>
+    </div>
+    <div class="rsfx-scope-footer">
+      <span id="rsfx-frequency-readout">{ui.frequencyLabel}</span>
+      <span id="rsfx-duration-readout">{ui.durationLabel}</span>
+      <span>{ui.monoWavHint}</span>
+    </div>
+  </section>
+
+  <section class="rsfx-preset-strip" aria-labelledby="rsfx-preset-heading">
+    <div class="rsfx-section-label" id="rsfx-preset-heading">{ui.presetLabel}</div>
+    <div class="rsfx-preset-grid">
+      <button type="button" class="rsfx-preset is-active" data-preset="explosion" aria-label={ui.presetExplosion}>
+        <span class="rsfx-preset-glyph">FX</span><span>{ui.presetExplosion}</span>
+      </button>
+      <button type="button" class="rsfx-preset" data-preset="laser" aria-label={ui.presetLaser}>
+        <span class="rsfx-preset-glyph">LZR</span><span>{ui.presetLaser}</span>
+      </button>
+      <button type="button" class="rsfx-preset" data-preset="jump" aria-label={ui.presetJump}>
+        <span class="rsfx-preset-glyph">JMP</span><span>{ui.presetJump}</span>
+      </button>
+      <button type="button" class="rsfx-preset" data-preset="coin" aria-label={ui.presetCoin}>
+        <span class="rsfx-preset-glyph">COIN</span><span>{ui.presetCoin}</span>
+      </button>
+      <button type="button" class="rsfx-preset" data-preset="powerUp" aria-label={ui.presetPowerUp}>
+        <span class="rsfx-preset-glyph">UP</span><span>{ui.presetPowerUp}</span>
+      </button>
+    </div>
+    <p class="rsfx-hint">{ui.presetHint}</p>
+  </section>
+
+  <section class="rsfx-control-board" aria-label={ui.toneSection}>
+    <div class="rsfx-control-section">
+      <div class="rsfx-section-label">{ui.toneSection}</div>
+      <div class="rsfx-waveform-picker">
+        <label class="rsfx-control-label" for="rsfx-waveform-select">{ui.waveformLabel}</label>
+        <select id="rsfx-waveform-select" class="rsfx-select" aria-label={ui.waveformLabel}>
+          <option value="square">{ui.waveformSquare}</option>
+          <option value="sawtooth">{ui.waveformSawtooth}</option>
+          <option value="sine">{ui.waveformSine}</option>
+          <option value="triangle">{ui.waveformTriangle}</option>
+          <option value="noise">{ui.waveformNoise}</option>
+        </select>
+      </div>
+      <div class="rsfx-slider-grid">
+        <label class="rsfx-slider-control" for="rsfx-frequency">
+          <span><span>{ui.frequencyLabel}</span><output id="rsfx-frequency-value">0 Hz</output></span>
+          <input id="rsfx-frequency" type="range" min="60" max="8000" step="10" value="1200" aria-label={ui.frequencyLabel} />
+        </label>
+        <label class="rsfx-slider-control" for="rsfx-sweep">
+          <span><span>{ui.sweepLabel}</span><output id="rsfx-sweep-value">0%</output></span>
+          <input id="rsfx-sweep" type="range" min="-100" max="100" step="1" value="-70" aria-label={ui.sweepLabel} />
+        </label>
+      </div>
+    </div>
+
+    <div class="rsfx-control-section">
+      <div class="rsfx-section-label">{ui.dynamicsSection}</div>
+      <div class="rsfx-slider-grid">
+        <label class="rsfx-slider-control" for="rsfx-duration">
+          <span><span>{ui.durationLabel}</span><output id="rsfx-duration-value">0.32 s</output></span>
+          <input id="rsfx-duration" type="range" min="0.08" max="2.5" step="0.01" value="0.32" aria-label={ui.durationLabel} />
+        </label>
+        <label class="rsfx-slider-control" for="rsfx-decay">
+          <span><span>{ui.decayLabel}</span><output id="rsfx-decay-value">0%</output></span>
+          <input id="rsfx-decay" type="range" min="0" max="100" step="1" value="56" aria-label={ui.decayLabel} />
+        </label>
+        <label class="rsfx-slider-control" for="rsfx-vibrato">
+          <span><span>{ui.vibratoLabel}</span><output id="rsfx-vibrato-value">0%</output></span>
+          <input id="rsfx-vibrato" type="range" min="0" max="100" step="1" value="3" aria-label={ui.vibratoLabel} />
+        </label>
+      </div>
+    </div>
+
+    <div class="rsfx-control-section">
+      <div class="rsfx-section-label">{ui.filterSection}</div>
+      <div class="rsfx-slider-grid">
+        <label class="rsfx-slider-control" for="rsfx-lowpass">
+          <span><span>{ui.lowpassLabel}</span><output id="rsfx-lowpass-value">0 kHz</output></span>
+          <input id="rsfx-lowpass" type="range" min="400" max="12000" step="100" value="9000" aria-label={ui.lowpassLabel} />
+        </label>
+        <label class="rsfx-slider-control" for="rsfx-highpass">
+          <span><span>{ui.highpassLabel}</span><output id="rsfx-highpass-value">0 Hz</output></span>
+          <input id="rsfx-highpass" type="range" min="20" max="1800" step="10" value="180" aria-label={ui.highpassLabel} />
+        </label>
+        <label class="rsfx-slider-control" for="rsfx-noise-mix">
+          <span><span>{ui.noiseMixLabel}</span><output id="rsfx-noise-mix-value">0%</output></span>
+          <input id="rsfx-noise-mix" type="range" min="0" max="100" step="1" value="4" aria-label={ui.noiseMixLabel} />
+        </label>
+      </div>
+    </div>
+  </section>
+
+  <div class="rsfx-action-bar">
+    <div class="rsfx-primary-actions">
+      <button type="button" class="rsfx-action rsfx-action-play" id="rsfx-play" aria-label={ui.playButton}>{ui.playButton}</button>
+      <button type="button" class="rsfx-action rsfx-action-stop" id="rsfx-stop" aria-label={ui.stopButton}>{ui.stopButton}</button>
+      <button type="button" class="rsfx-action rsfx-action-download" id="rsfx-download" aria-label={ui.downloadButton}>{ui.downloadButton}</button>
+    </div>
+    <div class="rsfx-secondary-actions">
+      <button type="button" class="rsfx-text-action" id="rsfx-randomize" aria-label={ui.randomizeButton}>{ui.randomizeButton}</button>
+      <button type="button" class="rsfx-text-action" id="rsfx-reset" aria-label={ui.resetButton}>{ui.resetButton}</button>
+    </div>
+  </div>
+
+  <p class="rsfx-status" id="rsfx-status" role="status" aria-live="polite">{ui.statusReady}</p>
+</div>
+
+<script src="./client.ts"></script>

package/src/tool/retroSfxGenerator/entry.ts

@@ -0,0 +1,27 @@
+import type { GamesToolEntry, ToolLocaleContent } from '../../types';
+import type { RetroSfxGeneratorUI } from './ui';
+
+export type { RetroSfxGeneratorUI };
+export type RetroSfxGeneratorLocaleContent = ToolLocaleContent<RetroSfxGeneratorUI>;
+
+export const retroSfxGenerator: GamesToolEntry<RetroSfxGeneratorUI> = {
+  id: 'retro-sfx-generator',
+  icons: { bg: 'mdi:gamepad-variant', fg: 'mdi:waveform' },
+  i18n: {
+    de: () => import('./i18n/de').then((m) => m.content),
+    en: () => import('./i18n/en').then((m) => m.content),
+    es: () => import('./i18n/es').then((m) => m.content),
+    fr: () => import('./i18n/fr').then((m) => m.content),
+    id: () => import('./i18n/id').then((m) => m.content),
+    it: () => import('./i18n/it').then((m) => m.content),
+    ja: () => import('./i18n/ja').then((m) => m.content),
+    ko: () => import('./i18n/ko').then((m) => m.content),
+    nl: () => import('./i18n/nl').then((m) => m.content),
+    pl: () => import('./i18n/pl').then((m) => m.content),
+    pt: () => import('./i18n/pt').then((m) => m.content),
+    ru: () => import('./i18n/ru').then((m) => m.content),
+    sv: () => import('./i18n/sv').then((m) => m.content),
+    tr: () => import('./i18n/tr').then((m) => m.content),
+    zh: () => import('./i18n/zh').then((m) => m.content),
+  },
+};