@jjlmoya/utils-games-development 1.46.0 → 1.49.0

package/src/tool/itchioGameTester/logic.ts

@@ -0,0 +1,266 @@
+export interface WebGameFileInfo {
+  name: string;
+  size: number;
+  isDirectory: boolean;
+}
+
+export interface GameValidationIssue {
+  type: 'error' | 'warning' | 'info';
+  code: string;
+  message: string;
+  details?: string;
+}
+
+export type DetectedGameEngine = 'Godot 4' | 'Godot 3' | 'Unity WebGL' | 'Phaser / Construct' | 'Custom HTML5';
+
+export interface GameValidationResult {
+  score: number;
+  engine: DetectedGameEngine;
+  hasIndexHtml: boolean;
+  indexHtmlPath: string;
+  totalFiles: number;
+  totalUncompressedSize: number;
+  issues: GameValidationIssue[];
+  fileList: WebGameFileInfo[];
+}
+
+export interface ResolutionPreset {
+  name: string;
+  width: number;
+  height: number;
+  ratio: string;
+}
+
+export const RESOLUTION_PRESETS: ResolutionPreset[] = [
+  { name: '16:9 Standard HD', width: 1280, height: 720, ratio: '16:9' },
+  { name: '16:9 Itch Classic', width: 960, height: 540, ratio: '16:9' },
+  { name: '16:9 Full HD', width: 1920, height: 1080, ratio: '16:9' },
+  { name: '4:3 VGA', width: 800, height: 600, ratio: '4:3' },
+  { name: '4:3 XGA', width: 1024, height: 768, ratio: '4:3' },
+  { name: '3:2 Classic', width: 960, height: 640, ratio: '3:2' },
+  { name: '1:1 Square', width: 800, height: 800, ratio: '1:1' },
+  { name: 'Itch Desktop Default', width: 960, height: 600, ratio: '16:10' },
+];
+
+export function detectGameEngine(files: WebGameFileInfo[]): DetectedGameEngine {
+  const fileNames = files.map((f) => f.name.replace(/\\/g, '/'));
+  
+  if (fileNames.some((n) => n.endsWith('.pck') || n.endsWith('.wasm'))) {
+    const isGodot4 = fileNames.some((n) => n.toLowerCase().includes('godot') || n.endsWith('.side.wasm'));
+    return isGodot4 ? 'Godot 4' : 'Godot 3';
+  }
+
+  if (fileNames.some((n) => n.includes('Build/') || n.endsWith('.framework.js') || n.endsWith('.data'))) {
+    return 'Unity WebGL';
+  }
+
+  if (fileNames.some((n) => n.includes('phaser') || n.includes('c2runtime') || n.includes('c3runtime'))) {
+    return 'Phaser / Construct';
+  }
+
+  return 'Custom HTML5';
+}
+
+function checkCaseConflict(normalizedPath: string, lowerCaseMap: Map<string, string>): GameValidationIssue | null {
+  const lowerPath = normalizedPath.toLowerCase();
+  const existing = lowerCaseMap.get(lowerPath);
+  if (existing && existing !== normalizedPath) {
+    return {
+      type: 'warning',
+      code: 'CASE_CONFLICT',
+      message: 'File name case sensitivity conflict detected',
+      details: `${normalizedPath} conflicts with ${existing}. Case differences cause 404 errors on Itch.io Linux/macOS servers.`
+    };
+  }
+  lowerCaseMap.set(lowerPath, normalizedPath);
+  return null;
+}
+
+function checkFileExtension(file: WebGameFileInfo): GameValidationIssue | null {
+  const ext = file.name.split('.').pop() || '';
+  if (ext && ext !== ext.toLowerCase() && !file.isDirectory) {
+    return {
+      type: 'warning',
+      code: 'UPPERCASE_EXTENSION',
+      message: 'Uppercase file extension detected',
+      details: `${file.name} has an uppercase extension .${ext}. Web servers may fail to send correct MIME types.`
+    };
+  }
+  return null;
+}
+
+function checkHeavyAudio(file: WebGameFileInfo): GameValidationIssue | null {
+  const ext = file.name.split('.').pop() || '';
+  if (ext.toLowerCase() === 'wav' && file.size > 5 * 1024 * 1024) {
+    return {
+      type: 'info',
+      code: 'HEAVY_AUDIO',
+      message: 'Large uncompressed WAV audio file',
+      details: `${file.name} is ${Math.round(file.size / (1024 * 1024))}MB. Convert to OGG or MP3 for faster web loading.`
+    };
+  }
+  return null;
+}
+
+function evaluateIndexHtml(hasIndexHtml: boolean, indexHtmlPath: string): { issue: GameValidationIssue | null; penalty: number } {
+  if (hasIndexHtml) {
+    return { issue: null, penalty: 0 };
+  }
+  if (indexHtmlPath !== '') {
+    return {
+      issue: {
+        type: 'error',
+        code: 'NESTED_INDEX',
+        message: 'index.html is nested inside a subfolder',
+        details: `Found index.html at ${indexHtmlPath}. Itch.io requires index.html to be located in the root directory.`
+      },
+      penalty: 50
+    };
+  }
+  return {
+    issue: {
+      type: 'error',
+      code: 'MISSING_INDEX',
+      message: 'Missing index.html file',
+      details: 'No index.html file was found in the uploaded package. Web builds require an index.html entry point.'
+    },
+    penalty: 80
+  };
+}
+
+interface ScanAccumulator {
+  score: number;
+  hasIndexHtml: boolean;
+  indexHtmlPath: string;
+  totalFiles: number;
+  totalUncompressedSize: number;
+}
+
+function checkIndexLocation(normalizedPath: string, acc: ScanAccumulator) {
+  if (normalizedPath === 'index.html') {
+    acc.hasIndexHtml = true;
+    acc.indexHtmlPath = normalizedPath;
+  } else if ((normalizedPath.endsWith('/index.html') || normalizedPath.endsWith('\\index.html')) && !acc.hasIndexHtml) {
+    acc.indexHtmlPath = normalizedPath;
+  }
+}
+
+function processSingleFile(file: WebGameFileInfo, lowerCaseMap: Map<string, string>, acc: ScanAccumulator, issues: GameValidationIssue[]) {
+  if (!file.isDirectory) {
+    acc.totalFiles++;
+    acc.totalUncompressedSize += file.size;
+  }
+
+  const normalizedPath = file.name.replace(/\\/g, '/');
+  const caseIssue = checkCaseConflict(normalizedPath, lowerCaseMap);
+  if (caseIssue) {
+    issues.push(caseIssue);
+    acc.score -= 10;
+  }
+
+  checkIndexLocation(normalizedPath, acc);
+
+  const extIssue = checkFileExtension(file);
+  if (extIssue) {
+    issues.push(extIssue);
+    acc.score -= 5;
+  }
+
+  const audioIssue = checkHeavyAudio(file);
+  if (audioIssue) {
+    issues.push(audioIssue);
+    acc.score -= 2;
+  }
+}
+
+function appendEngineAndSizeIssues(engine: DetectedGameEngine, totalUncompressedSize: number, score: number, issues: GameValidationIssue[]): number {
+  let updatedScore = score;
+  if (engine === 'Godot 4') {
+    issues.push({
+      type: 'info',
+      code: 'GODOT4_HEADERS',
+      message: 'Godot 4 Web export detected',
+      details: 'Ensure "SharedArrayBuffer support" or Cross-Origin Isolation headers are enabled in your Itch.io game edit page.'
+    });
+  }
+
+  if (totalUncompressedSize > 500 * 1024 * 1024) {
+    issues.push({
+      type: 'warning',
+      code: 'LARGE_BUILD',
+      message: 'Total build size exceeds 500MB',
+      details: 'Large web builds may experience high bounce rates or memory crashes on mobile browsers.'
+    });
+    updatedScore -= 15;
+  }
+  return updatedScore;
+}
+
+export function validateGameFiles(files: WebGameFileInfo[]): GameValidationResult {
+  const issues: GameValidationIssue[] = [];
+  const engine = detectGameEngine(files);
+  const lowerCaseMap = new Map<string, string>();
+  const acc: ScanAccumulator = { score: 100, hasIndexHtml: false, indexHtmlPath: '', totalFiles: 0, totalUncompressedSize: 0 };
+
+  for (const file of files) {
+    processSingleFile(file, lowerCaseMap, acc, issues);
+  }
+
+  const indexEval = evaluateIndexHtml(acc.hasIndexHtml, acc.indexHtmlPath);
+  if (indexEval.issue) {
+    issues.unshift(indexEval.issue);
+    acc.score -= indexEval.penalty;
+  }
+
+  const finalScore = appendEngineAndSizeIssues(engine, acc.totalUncompressedSize, acc.score, issues);
+
+  return {
+    score: Math.max(0, finalScore),
+    engine,
+    hasIndexHtml: acc.hasIndexHtml,
+    indexHtmlPath: acc.indexHtmlPath,
+    totalFiles: acc.totalFiles,
+    totalUncompressedSize: acc.totalUncompressedSize,
+    issues,
+    fileList: files,
+  };
+}
+
+export function calculateAspectRatio(width: number, height: number): string {
+  if (!width || !height) return '16:9';
+  const gcd = (a: number, b: number): number => (b === 0 ? a : gcd(b, a % b));
+  const divisor = gcd(width, height);
+  const wRatio = width / divisor;
+  const hRatio = height / divisor;
+
+  const ratioKey = `${wRatio}:${hRatio}`;
+  const knownRatios: Record<string, string> = {
+    '16:9': '16:9',
+    '4:3': '4:3',
+    '3:2': '3:2',
+    '16:10': '16:10',
+    '1:1': '1:1',
+  };
+
+  if (knownRatios[ratioKey]) {
+    return knownRatios[ratioKey];
+  }
+
+  const decimal = width / height;
+  if (Math.abs(decimal - 16 / 9) < 0.05) return '16:9 Approx';
+  if (Math.abs(decimal - 4 / 3) < 0.05) return '4:3 Approx';
+
+  return ratioKey;
+}
+
+export function generateItchioEmbedConfig(width: number, height: number, orientation: 'landscape' | 'portrait' = 'landscape') {
+  return {
+    viewportWidth: width,
+    viewportHeight: height,
+    embedMode: 'Embed in page',
+    scrollbars: false,
+    fullscreenButton: true,
+    orientation,
+    codeSnippet: `Dimensions: ${width}px x ${height}px\nEmbed Mode: Embed in page\nMobile Orientation: ${orientation}\nFullscreen Button: Enabled`
+  };
+}

package/src/tool/itchioGameTester/seo.astro

@@ -0,0 +1,15 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { itchioGameTester } from './entry';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props;
+const loader = itchioGameTester.i18n[locale] ?? itchioGameTester.i18n.en;
+const content = loader ? await loader() : null;
+---
+
+{content && content.seo && content.seo.length > 0 && <SEORenderer content={{ locale, sections: content.seo }} />}

package/src/tool/itchioGameTester/ui.ts

@@ -0,0 +1,20 @@
+export interface ItchioGameTesterUI extends Record<string, string> {
+  dropzoneTitle: string;
+  dropzoneHint: string;
+  chooseFiles: string;
+  engineDetected: string;
+  compatibilityScore: string;
+  viewportWidth: string;
+  viewportHeight: string;
+  presets: string;
+  fitTest: string;
+  copySettings: string;
+  copied: string;
+  embedMode: string;
+  scrollbars: string;
+  noIssuesFound: string;
+  filesInspected: string;
+  resetViewport: string;
+  autoScaleToggle: string;
+  scaledNotice: string;
+}

package/src/tool/spriteSheetPacker/app-client.ts

@@ -0,0 +1,248 @@
+import JSZip from 'jszip';
+import { bindDropzone } from './dropzone-client';
+import { initExtractor, updateExtractor } from './extractor-client';
+import { bindFlipbook, startFlipbookLoop } from './flipbook-client';
+import { calculateBinPacking, type ExportFormat, type SpriteFrameInput } from './logic';
+import { drawEmptyCanvasMessage, setupStepper, spawnParticle, triggerButtonFeedback, type LoadedImageItem } from './packer-ui';
+
+let loadedImages: LoadedImageItem[] = [];
+let currentAtlasData: ReturnType<typeof calculateBinPacking> | null = null;
+
+function parseInputValue(id: string, fallback: string): number {
+  const el = document.getElementById(id) as HTMLInputElement | null;
+  return parseInt(el?.value || fallback, 10);
+}
+
+function renderAtlasCanvas(): void {
+  const canvas = document.getElementById('ssp-atlas-canvas') as HTMLCanvasElement | null;
+  if (!canvas) return;
+
+  if (!currentAtlasData || loadedImages.length === 0) {
+    drawEmptyCanvasMessage(canvas, 'Upload PNG frames to preview packed texture atlas');
+    return;
+  }
+
+  canvas.width = currentAtlasData.textureWidth;
+  canvas.height = currentAtlasData.textureHeight;
+
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return;
+
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+  for (const frame of currentAtlasData.frames) {
+    const found = loadedImages.find((img) => img.id === frame.id);
+    if (found) {
+      ctx.drawImage(found.img, frame.x, frame.y, frame.width, frame.height);
+      ctx.strokeStyle = 'rgba(99, 102, 241, 0.4)';
+      ctx.lineWidth = 1;
+      ctx.strokeRect(frame.x, frame.y, frame.width, frame.height);
+    }
+  }
+}
+
+function updateStatsUI(): void {
+  if (!currentAtlasData) return;
+
+  const effEl = document.getElementById('ssp-stat-efficiency');
+  const dcEl = document.getElementById('ssp-stat-drawcalls');
+  const framesEl = document.getElementById('ssp-stat-frames');
+  const sizeEl = document.getElementById('ssp-stat-size');
+  const codeEl = document.getElementById('ssp-code-snippet');
+
+  if (effEl) effEl.textContent = `${currentAtlasData.efficiency}%`;
+  if (dcEl) dcEl.textContent = `${currentAtlasData.drawCallsBefore} -> ${currentAtlasData.drawCallsAfter}`;
+  if (framesEl) framesEl.textContent = currentAtlasData.totalFrames.toString();
+  if (sizeEl) sizeEl.textContent = `${currentAtlasData.textureWidth}x${currentAtlasData.textureHeight}`;
+  if (codeEl) codeEl.textContent = currentAtlasData.codeSnippet;
+}
+
+function getPackerSettings() {
+  const pad = parseInputValue('ssp-padding', '2');
+  const ext = parseInputValue('ssp-extrusion', '0');
+  const max = parseInputValue('ssp-max-size', '2048');
+  const fmt = ((document.getElementById('ssp-export-format') as HTMLSelectElement)?.value || 'generic-json-hash') as ExportFormat;
+  const pot = (document.getElementById('ssp-power-two') as HTMLInputElement)?.checked ?? true;
+  return { padding: pad, borderExtrusion: ext, format: fmt, maxTextureWidth: max, forcePowerOfTwo: pot };
+}
+
+function updatePacker(): void {
+  const { padding, borderExtrusion, format, maxTextureWidth, forcePowerOfTwo } = getPackerSettings();
+
+  const frameInputs: SpriteFrameInput[] = loadedImages.map((item) => ({
+    id: item.id,
+    name: item.name,
+    width: item.img.width,
+    height: item.img.height,
+  }));
+
+  currentAtlasData = calculateBinPacking(frameInputs, {
+    padding,
+    borderExtrusion,
+    forcePowerOfTwo,
+    maxTextureWidth,
+    maxTextureHeight: maxTextureWidth,
+    allowRotation: false,
+    trimTransparency: false,
+    format,
+  });
+
+  renderAtlasCanvas();
+  updateStatsUI();
+}
+
+function setPresetValues(padding: number, extrusion: number, maxSize: string, pot: boolean): void {
+  const padInput = document.getElementById('ssp-padding') as HTMLInputElement | null;
+  const extInput = document.getElementById('ssp-extrusion') as HTMLInputElement | null;
+  const maxSelect = document.getElementById('ssp-max-size') as HTMLSelectElement | null;
+  const potCheck = document.getElementById('ssp-power-two') as HTMLInputElement | null;
+
+  if (padInput) {
+    padInput.value = padding.toString();
+    const valEl = document.getElementById('ssp-padding-val');
+    if (valEl) valEl.textContent = padding.toString();
+  }
+  if (extInput) {
+    extInput.value = extrusion.toString();
+    const valEl = document.getElementById('ssp-extrusion-val');
+    if (valEl) valEl.textContent = extrusion.toString();
+  }
+  if (maxSelect) maxSelect.value = maxSize;
+  if (potCheck) potCheck.checked = pot;
+
+  updatePacker();
+}
+
+function downloadZipPackage(e: MouseEvent): void {
+  if (!currentAtlasData || currentAtlasData.frames.length === 0) return;
+  const canvas = document.getElementById('ssp-atlas-canvas') as HTMLCanvasElement | null;
+  if (!canvas) return;
+
+  triggerButtonFeedback(document.getElementById('ssp-btn-download-zip'), 'ZIP Generated!', e);
+
+  const zip = new JSZip();
+  canvas.toBlob((blob) => {
+    if (!blob) return;
+    zip.file('spritesheet.png', blob);
+    zip.file('spritesheet.json', currentAtlasData!.atlasJson);
+    zip.generateAsync({ type: 'blob' }).then((content) => {
+      const link = document.createElement('a');
+      link.href = URL.createObjectURL(content);
+      link.download = 'sprite-sheet-package.zip';
+      link.click();
+    });
+  });
+}
+
+function bindTabs(): void {
+  const tabPacker = document.getElementById('ssp-tab-packer');
+  const tabExtractor = document.getElementById('ssp-tab-extractor');
+  const panelPacker = document.getElementById('ssp-packer-panel');
+  const panelExtractor = document.getElementById('ssp-extractor-panel');
+
+  tabPacker?.addEventListener('click', () => {
+    tabPacker.classList.add('active');
+    tabExtractor?.classList.remove('active');
+    if (panelPacker) panelPacker.style.display = 'grid';
+    if (panelExtractor) panelExtractor.style.display = 'none';
+    renderAtlasCanvas();
+  });
+
+  tabExtractor?.addEventListener('click', () => {
+    tabExtractor.classList.add('active');
+    tabPacker?.classList.remove('active');
+    if (panelPacker) panelPacker.style.display = 'none';
+    if (panelExtractor) panelExtractor.style.display = 'grid';
+    updateExtractor();
+  });
+}
+
+function bindPresets(): void {
+  const setActivePreset = (target: HTMLElement) => {
+    document.querySelectorAll('.ssp-chip-btn').forEach((el) => el.classList.remove('active'));
+    target.classList.add('active');
+  };
+
+  document.getElementById('ssp-preset-pixel')?.addEventListener('click', (e) => {
+    setActivePreset(e.target as HTMLElement);
+    setPresetValues(2, 0, '512', true);
+    spawnParticle(e.clientX, e.clientY, 'PIXEL 16x16');
+  });
+  document.getElementById('ssp-preset-hd')?.addEventListener('click', (e) => {
+    setActivePreset(e.target as HTMLElement);
+    setPresetValues(4, 1, '1024', true);
+    spawnParticle(e.clientX, e.clientY, 'HD 1024');
+  });
+  document.getElementById('ssp-preset-mobile')?.addEventListener('click', (e) => {
+    setActivePreset(e.target as HTMLElement);
+    setPresetValues(2, 0, '2048', true);
+    spawnParticle(e.clientX, e.clientY, 'MOBILE 2048');
+  });
+}
+
+function bindSliders(): void {
+  const paddingSlider = document.getElementById('ssp-padding') as HTMLInputElement | null;
+  const extrusionSlider = document.getElementById('ssp-extrusion') as HTMLInputElement | null;
+
+  paddingSlider?.addEventListener('input', () => {
+    const valEl = document.getElementById('ssp-padding-val');
+    if (valEl) valEl.textContent = paddingSlider.value;
+    updatePacker();
+  });
+
+  extrusionSlider?.addEventListener('input', () => {
+    const valEl = document.getElementById('ssp-extrusion-val');
+    if (valEl) valEl.textContent = extrusionSlider.value;
+    updatePacker();
+  });
+}
+
+function bindExportCopies(): void {
+  document.getElementById('ssp-btn-copy-json')?.addEventListener('click', (e) => {
+    if (!currentAtlasData) return;
+    triggerButtonFeedback(document.getElementById('ssp-btn-copy-json'), 'Copied!', e);
+    navigator.clipboard.writeText(currentAtlasData.atlasJson);
+  });
+  document.getElementById('ssp-btn-download-png')?.addEventListener('click', (e) => {
+    const canvas = document.getElementById('ssp-atlas-canvas') as HTMLCanvasElement | null;
+    if (!canvas) return;
+    triggerButtonFeedback(document.getElementById('ssp-btn-download-png'), 'Downloaded!', e);
+    const link = document.createElement('a');
+    link.href = canvas.toDataURL('image/png');
+    link.download = 'spritesheet.png';
+    link.click();
+  });
+  document.getElementById('ssp-btn-copy-code')?.addEventListener('click', (e) => {
+    if (!currentAtlasData) return;
+    triggerButtonFeedback(document.getElementById('ssp-btn-copy-code'), 'Copied Code!', e);
+    navigator.clipboard.writeText(currentAtlasData.codeSnippet);
+  });
+}
+
+function bindActionButtons(): void {
+  setupStepper('ssp-pad-dec', 'ssp-pad-inc', 'ssp-padding', updatePacker);
+  setupStepper('ssp-ext-dec', 'ssp-ext-inc', 'ssp-extrusion', updatePacker);
+  bindSliders();
+  bindExportCopies();
+
+  document.getElementById('ssp-export-format')?.addEventListener('change', updatePacker);
+  document.getElementById('ssp-max-size')?.addEventListener('change', updatePacker);
+  document.getElementById('ssp-power-two')?.addEventListener('change', updatePacker);
+  document.getElementById('ssp-btn-download-zip')?.addEventListener('click', (e) => downloadZipPackage(e));
+  document.getElementById('ssp-btn-clear')?.addEventListener('click', (e) => {
+    loadedImages = [];
+    updatePacker();
+    spawnParticle(e.clientX, e.clientY, 'CLEARED!');
+  });
+}
+
+export function initSpriteSheetPackerApp(): void {
+  bindTabs();
+  bindPresets();
+  bindDropzone(loadedImages, updatePacker);
+  bindActionButtons();
+  bindFlipbook();
+  initExtractor();
+  startFlipbookLoop(loadedImages);
+  renderAtlasCanvas();
+  updateExtractor();
+}

package/src/tool/spriteSheetPacker/bibliography.astro

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

package/src/tool/spriteSheetPacker/bibliography.ts

@@ -0,0 +1,12 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliographyEntries: BibliographyEntry[] = [
+  {
+    name: 'Godot Engine 2D Sprite Sheets Documentation',
+    url: 'https://docs.godotengine.org/en/stable/tutorials/2d/2d_sprite_animation.html',
+  },
+  {
+    name: 'Unity Sprite Atlas Manual',
+    url: 'https://docs.unity3d.com/Manual/class-SpriteAtlas.html',
+  },
+];