@jjlmoya/utils-games-development 1.47.0 → 1.49.0

package/src/tool/spriteSheetPacker/component.astro

@@ -0,0 +1,229 @@
+---
+import type { SpriteSheetPackerUI } from './ui';
+import './sprite-sheet-packer.css';
+
+interface Props {
+  ui: SpriteSheetPackerUI;
+}
+
+const { ui } = Astro.props;
+---
+
+<div class="ssp-container">
+  <div class="ssp-main-card">
+    <div class="ssp-header-tabs" role="tablist">
+      <button id="ssp-tab-packer" class="ssp-tab-btn active" role="tab" aria-selected="true" aria-controls="ssp-packer-panel">
+        {ui.packerTab}
+      </button>
+      <button id="ssp-tab-extractor" class="ssp-tab-btn" role="tab" aria-selected="false" aria-controls="ssp-extractor-panel">
+        {ui.extractorTab}
+      </button>
+    </div>
+
+    <div id="ssp-packer-panel" class="ssp-body-grid" role="tabpanel" aria-labelledby="ssp-tab-packer">
+      <div class="ssp-sidebar-section">
+        <div id="ssp-dropzone" class="ssp-dropzone">
+          <div class="ssp-drop-title">{ui.dropZoneTitle}</div>
+          <div class="ssp-drop-sub">{ui.dropZoneSubtitle}</div>
+          <input type="file" id="ssp-file-input" class="ssp-file-input" multiple accept="image/png,image/jpeg,image/webp" aria-label={ui.selectFilesButton} />
+        </div>
+
+        <div class="ssp-btn-row">
+          <button id="ssp-btn-select" class="ssp-btn ssp-btn-primary" type="button">{ui.selectFilesButton}</button>
+          <button id="ssp-btn-clear" class="ssp-btn ssp-btn-danger" type="button">{ui.clearAllButton}</button>
+        </div>
+
+        <div class="ssp-presets-row">
+          <button id="ssp-preset-pixel" class="ssp-chip-btn" type="button">{ui.presetPixelArt}</button>
+          <button id="ssp-preset-hd" class="ssp-chip-btn" type="button">{ui.presetHdUi}</button>
+          <button id="ssp-preset-mobile" class="ssp-chip-btn" type="button">{ui.presetMobile}</button>
+        </div>
+
+        <div class="ssp-controls-list">
+          <div class="ssp-control-group">
+            <label for="ssp-export-format" class="ssp-label"><span>{ui.exportFormatLabel}</span></label>
+            <select id="ssp-export-format" class="ssp-select">
+              <option value="generic-json-hash">{ui.formatGenericHash}</option>
+              <option value="generic-json-array">{ui.formatGenericArray}</option>
+              <option value="unity">{ui.formatUnity}</option>
+              <option value="godot">{ui.formatGodot}</option>
+              <option value="phaser">{ui.formatPhaser}</option>
+              <option value="css">{ui.formatCss}</option>
+            </select>
+          </div>
+
+          <div class="ssp-control-group">
+            <label for="ssp-padding" class="ssp-label">
+              <span>{ui.paddingLabel}</span>
+              <span id="ssp-padding-val">2</span>
+            </label>
+            <div class="ssp-stepper-box">
+              <button id="ssp-pad-dec" class="ssp-step-btn" type="button" aria-label="Decrease Padding">-</button>
+              <input type="range" id="ssp-padding" class="ssp-slider" min="0" max="32" value="2" aria-label={ui.paddingLabel} />
+              <button id="ssp-pad-inc" class="ssp-step-btn" type="button" aria-label="Increase Padding">+</button>
+            </div>
+          </div>
+
+          <div class="ssp-control-group">
+            <label for="ssp-extrusion" class="ssp-label">
+              <span>{ui.borderExtrusionLabel}</span>
+              <span id="ssp-extrusion-val">0</span>
+            </label>
+            <div class="ssp-stepper-box">
+              <button id="ssp-ext-dec" class="ssp-step-btn" type="button" aria-label="Decrease Extrusion">-</button>
+              <input type="range" id="ssp-extrusion" class="ssp-slider" min="0" max="8" value="0" aria-label={ui.borderExtrusionLabel} />
+              <button id="ssp-ext-inc" class="ssp-step-btn" type="button" aria-label="Increase Extrusion">+</button>
+            </div>
+          </div>
+
+          <div class="ssp-control-group">
+            <label for="ssp-max-size" class="ssp-label"><span>{ui.maxTextureSizeLabel}</span></label>
+            <select id="ssp-max-size" class="ssp-select">
+              <option value="512">512 x 512 px</option>
+              <option value="1024">1024 x 1024 px</option>
+              <option value="2048" selected>2048 x 2048 px</option>
+              <option value="4096">4096 x 4096 px</option>
+            </select>
+          </div>
+
+          <div class="ssp-toggle-group">
+            <label for="ssp-power-two" class="ssp-label">{ui.powerOfTwoLabel}</label>
+            <input type="checkbox" id="ssp-power-two" class="ssp-toggle-input" checked aria-label={ui.powerOfTwoLabel} />
+          </div>
+        </div>
+      </div>
+
+      <div class="ssp-main-section">
+        <div class="ssp-stats-grid">
+          <div class="ssp-stat-badge">
+            <div id="ssp-stat-efficiency" class="ssp-stat-val">0%</div>
+            <div class="ssp-stat-lbl">{ui.efficiencyBadge}</div>
+          </div>
+          <div class="ssp-stat-badge">
+            <div id="ssp-stat-drawcalls" class="ssp-stat-val">0</div>
+            <div class="ssp-stat-lbl">{ui.drawCallsBadge}</div>
+          </div>
+          <div class="ssp-stat-badge">
+            <div id="ssp-stat-frames" class="ssp-stat-val">0</div>
+            <div class="ssp-stat-lbl">{ui.totalFramesBadge}</div>
+          </div>
+          <div class="ssp-stat-badge">
+            <div id="ssp-stat-size" class="ssp-stat-val">0x0</div>
+            <div class="ssp-stat-lbl">{ui.textureSizeBadge}</div>
+          </div>
+        </div>
+
+        <div class="ssp-canvas-wrapper">
+          <canvas id="ssp-atlas-canvas" class="ssp-canvas" width="512" height="512" aria-label={ui.previewTitle}></canvas>
+        </div>
+
+        <div class="ssp-btn-row">
+          <button id="ssp-btn-download-zip" class="ssp-btn ssp-btn-primary" type="button">{ui.downloadZipButton}</button>
+          <button id="ssp-btn-copy-json" class="ssp-btn ssp-btn-secondary" type="button">{ui.copyJsonButton}</button>
+          <button id="ssp-btn-download-png" class="ssp-btn ssp-btn-secondary" type="button">{ui.downloadSheetPngButton}</button>
+        </div>
+
+        <div class="ssp-flipbook-box">
+          <div class="ssp-flipbook-header">{ui.flipbookTitle}</div>
+          <div class="ssp-flipbook-body">
+            <canvas id="ssp-flipbook-canvas" class="ssp-flipbook-canvas" width="128" height="128" aria-label={ui.flipbookTitle}></canvas>
+            <div class="ssp-flipbook-controls">
+              <div class="ssp-control-group">
+                <label for="ssp-fps-slider" class="ssp-label">
+                  <span>{ui.flipbookFpsLabel}</span>
+                  <span id="ssp-fps-val">12 FPS</span>
+                </label>
+                <input type="range" id="ssp-fps-slider" class="ssp-slider" min="1" max="60" value="12" aria-label={ui.flipbookFpsLabel} />
+              </div>
+              <div class="ssp-btn-row">
+                <button id="ssp-btn-play" class="ssp-btn ssp-btn-secondary" type="button">{ui.playAnimation}</button>
+                <button id="ssp-btn-pause" class="ssp-btn ssp-btn-secondary" type="button">{ui.pauseAnimation}</button>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <div class="ssp-code-container">
+          <div class="ssp-code-header">
+            <span class="ssp-code-title">{ui.codeSnippetTitle}</span>
+            <button id="ssp-btn-copy-code" class="ssp-copy-btn" type="button">{ui.copySnippetButton}</button>
+          </div>
+          <pre id="ssp-code-snippet" class="ssp-code-block"></pre>
+        </div>
+      </div>
+    </div>
+
+    <div id="ssp-extractor-panel" class="ssp-body-grid" role="tabpanel" aria-labelledby="ssp-tab-extractor" style="display: none;">
+      <div class="ssp-sidebar-section">
+        <div id="ssp-ext-dropzone" class="ssp-dropzone">
+          <div class="ssp-drop-title">{ui.dropZoneTitle}</div>
+          <div class="ssp-drop-sub">{ui.dropZoneSubtitle}</div>
+          <input type="file" id="ssp-ext-file-input" class="ssp-file-input" accept="image/png,image/jpeg,image/webp" aria-label={ui.selectFilesButton} />
+        </div>
+
+        <div class="ssp-controls-list">
+          <div class="ssp-control-group">
+            <label for="ssp-ext-width" class="ssp-label">{ui.frameWidthLabel}</label>
+            <div class="ssp-stepper-box">
+              <button id="ssp-fw-dec" class="ssp-step-btn" type="button" aria-label="Decrease Frame Width">-</button>
+              <input type="number" id="ssp-ext-width" class="ssp-input" value="32" min="1" aria-label={ui.frameWidthLabel} />
+              <button id="ssp-fw-inc" class="ssp-step-btn" type="button" aria-label="Increase Frame Width">+</button>
+            </div>
+          </div>
+
+          <div class="ssp-control-group">
+            <label for="ssp-ext-height" class="ssp-label">{ui.frameHeightLabel}</label>
+            <div class="ssp-stepper-box">
+              <button id="ssp-fh-dec" class="ssp-step-btn" type="button" aria-label="Decrease Frame Height">-</button>
+              <input type="number" id="ssp-ext-height" class="ssp-input" value="32" min="1" aria-label={ui.frameHeightLabel} />
+              <button id="ssp-fh-inc" class="ssp-step-btn" type="button" aria-label="Increase Frame Height">+</button>
+            </div>
+          </div>
+
+          <div class="ssp-control-group">
+            <label for="ssp-ext-margin" class="ssp-label">{ui.marginLabel}</label>
+            <div class="ssp-stepper-box">
+              <button id="ssp-mar-dec" class="ssp-step-btn" type="button" aria-label="Decrease Margin">-</button>
+              <input type="number" id="ssp-ext-margin" class="ssp-input" value="0" min="0" aria-label={ui.marginLabel} />
+              <button id="ssp-mar-inc" class="ssp-step-btn" type="button" aria-label="Increase Margin">+</button>
+            </div>
+          </div>
+
+          <div class="ssp-control-group">
+            <label for="ssp-ext-spacing" class="ssp-label">{ui.spacingLabel}</label>
+            <div class="ssp-stepper-box">
+              <button id="ssp-spc-dec" class="ssp-step-btn" type="button" aria-label="Decrease Spacing">-</button>
+              <input type="number" id="ssp-ext-spacing" class="ssp-input" value="0" min="0" aria-label={ui.spacingLabel} />
+              <button id="ssp-spc-inc" class="ssp-step-btn" type="button" aria-label="Increase Spacing">+</button>
+            </div>
+          </div>
+        </div>
+
+        <button id="ssp-btn-extract-zip" class="ssp-btn ssp-btn-primary" type="button">{ui.downloadZipButton}</button>
+      </div>
+
+      <div class="ssp-main-section">
+        <div class="ssp-stat-badge" style="align-self: flex-start;">
+          <div id="ssp-ext-count" class="ssp-stat-val">0</div>
+          <div class="ssp-stat-lbl">{ui.extractedCountLabel}</div>
+        </div>
+        <div class="ssp-canvas-wrapper">
+          <canvas id="ssp-ext-canvas" class="ssp-canvas" width="512" height="512" aria-label={ui.previewTitle}></canvas>
+        </div>
+      </div>
+    </div>
+
+    <div id="ssp-toast" class="ssp-toast">{ui.copiedToast}</div>
+    <div id="ssp-particle-container" class="ssp-particle-container"></div>
+  </div>
+</div>
+
+<script>
+  import { initSpriteSheetPackerApp } from './app-client';
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initSpriteSheetPackerApp);
+  } else {
+    initSpriteSheetPackerApp();
+  }
+</script>

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

@@ -0,0 +1,55 @@
+import { spawnParticle, type LoadedImageItem } from './packer-ui';
+
+export function handleFilesUpload(files: File[], loadedImages: LoadedImageItem[], updatePacker: () => void): void {
+  const promises = files.map((file) => {
+    return new Promise<void>((resolve) => {
+      const img = new Image();
+      const url = URL.createObjectURL(file);
+      img.onload = () => {
+        loadedImages.push({
+          file,
+          img,
+          id: Math.random().toString(36).substring(2, 9),
+          name: file.name.replace(/\.[^/.]+$/, ''),
+        });
+        resolve();
+      };
+      img.src = url;
+    });
+  });
+
+  Promise.all(promises).then(() => updatePacker());
+}
+
+export function bindDropzone(loadedImages: LoadedImageItem[], updatePacker: () => void): void {
+  const dropzone = document.getElementById('ssp-dropzone');
+  const fileInput = document.getElementById('ssp-file-input') as HTMLInputElement | null;
+
+  document.getElementById('ssp-btn-select')?.addEventListener('click', () => fileInput?.click());
+  dropzone?.addEventListener('click', () => fileInput?.click());
+
+  dropzone?.addEventListener('dragover', (e) => {
+    e.preventDefault();
+    dropzone.classList.add('dragover');
+  });
+
+  dropzone?.addEventListener('dragleave', (e) => {
+    e.preventDefault();
+    dropzone.classList.remove('dragover');
+  });
+
+  dropzone?.addEventListener('drop', (e: DragEvent) => {
+    e.preventDefault();
+    dropzone.classList.remove('dragover');
+    if (e.dataTransfer?.files?.length) {
+      handleFilesUpload(Array.from(e.dataTransfer.files), loadedImages, updatePacker);
+      spawnParticle(e.clientX, e.clientY, 'PACKED!');
+    }
+  });
+
+  fileInput?.addEventListener('change', () => {
+    if (fileInput.files?.length) {
+      handleFilesUpload(Array.from(fileInput.files), loadedImages, updatePacker);
+    }
+  });
+}

package/src/tool/spriteSheetPacker/entry.ts

@@ -0,0 +1,28 @@
+import type { GamesToolEntry, ToolLocaleContent } from '../../types';
+import type { SpriteSheetPackerUI } from './ui';
+
+export type { SpriteSheetPackerUI };
+
+export type SpriteSheetPackerLocaleContent = ToolLocaleContent<SpriteSheetPackerUI>;
+
+export const spriteSheetPacker: GamesToolEntry<SpriteSheetPackerUI> = {
+  id: 'sprite-sheet-packer',
+  icons: { bg: 'mdi:gamepad-variant', fg: 'mdi:texture-box' },
+  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),
+  },
+};

package/src/tool/spriteSheetPacker/exporter.ts

@@ -0,0 +1,116 @@
+import type { ExportFormat, PackedFrame } from './types';
+
+function buildGenericHashJson(frames: PackedFrame[], width: number, height: number): string {
+  const frameHash: Record<string, unknown> = {};
+  for (const f of frames) {
+    frameHash[f.name] = {
+      frame: { x: f.x, y: f.y, w: f.width, h: f.height },
+      rotated: f.rotated,
+      trimmed: f.trimmed,
+      spriteSourceSize: f.spriteSourceSize,
+      sourceSize: f.sourceSize,
+      pivot: f.pivot,
+    };
+  }
+  return JSON.stringify(
+    {
+      frames: frameHash,
+      meta: { app: 'GameBob Sprite Sheet Packer', version: '1.0', size: { w: width, h: height }, scale: 1 },
+    },
+    null,
+    2
+  );
+}
+
+function buildGenericArrayJson(frames: PackedFrame[], width: number, height: number): string {
+  const frameArray = frames.map((f) => ({
+    filename: f.name,
+    frame: { x: f.x, y: f.y, w: f.width, h: f.height },
+    rotated: f.rotated,
+    trimmed: f.trimmed,
+    spriteSourceSize: f.spriteSourceSize,
+    sourceSize: f.sourceSize,
+    pivot: f.pivot,
+  }));
+  return JSON.stringify(
+    {
+      frames: frameArray,
+      meta: { app: 'GameBob Sprite Sheet Packer', version: '1.0', size: { w: width, h: height }, scale: 1 },
+    },
+    null,
+    2
+  );
+}
+
+function buildGodotJson(frames: PackedFrame[], width: number, height: number): string {
+  const godotData = {
+    textures: [
+      {
+        image: 'spritesheet.png',
+        size: { w: width, h: height },
+        sprites: frames.map((f) => ({
+          name: f.name,
+          region: [f.x, f.y, f.width, f.height],
+          margin: [f.spriteSourceSize.x, f.spriteSourceSize.y, f.sourceSize.w, f.sourceSize.h],
+        })),
+      },
+    ],
+  };
+  return JSON.stringify(godotData, null, 2);
+}
+
+function buildUnityJson(frames: PackedFrame[], width: number, height: number): string {
+  const unityFrames = frames.map((f) => ({
+    name: f.name,
+    x: f.x,
+    y: f.y,
+    width: f.width,
+    height: f.height,
+    pivotX: f.pivot.x,
+    pivotY: f.pivot.y,
+  }));
+  return JSON.stringify({ sprites: unityFrames, meta: { width, height } }, null, 2);
+}
+
+export function generateAtlasJson(
+  frames: PackedFrame[],
+  width: number,
+  height: number,
+  format: ExportFormat
+): string {
+  if (format === 'generic-json-hash' || format === 'phaser') {
+    return buildGenericHashJson(frames, width, height);
+  }
+  if (format === 'generic-json-array') {
+    return buildGenericArrayJson(frames, width, height);
+  }
+  if (format === 'godot') {
+    return buildGodotJson(frames, width, height);
+  }
+  if (format === 'unity') {
+    return buildUnityJson(frames, width, height);
+  }
+  return JSON.stringify({ frames, meta: { width, height } }, null, 2);
+}
+
+export function generateCssSnippet(frames: PackedFrame[]): string {
+  return frames
+    .map(
+      (f) =>
+        `.sprite-${f.name.replace(/[^a-zA-Z0-9_-]/g, '_')} {\n  width: ${f.width}px;\n  height: ${f.height}px;\n  background-position: -${f.x}px -${f.y}px;\n}`
+    )
+    .join('\n\n');
+}
+
+export function generateEngineCodeSnippet(format: ExportFormat): string {
+  if (format === 'unity') {
+    return `// Unity C# Load Example\nSprite[] sprites = Resources.LoadAll<Sprite>("spritesheet");\nSprite myFrame = System.Array.Find(sprites, s => s.name == "frame_0");`;
+  }
+  if (format === 'godot') {
+    return `# Godot GDScript Load Example\nvar atlas_texture = AtlasTexture.new()\natlas_texture.atlas = load("res://spritesheet.png")\natlas_texture.region = Rect2(0, 0, 32, 32)`;
+  }
+  if (format === 'phaser') {
+    return `// Phaser 3 Load Example\nthis.load.atlas('sheetKey', 'spritesheet.png', 'spritesheet.json');\nconst sprite = this.add.sprite(400, 300, 'sheetKey', 'frame_0');`;
+  }
+  return `// HTML / JS Load Example\nconst image = new Image();\nimage.src = 'spritesheet.png';`;
+}

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

@@ -0,0 +1,127 @@
+import JSZip from 'jszip';
+import { calculateGridSlices } from './logic';
+import { drawEmptyCanvasMessage, setupStepper, triggerButtonFeedback } from './packer-ui';
+
+let extImage: HTMLImageElement | null = null;
+
+function parseInputValue(id: string, fallback: string): number {
+  const el = document.getElementById(id) as HTMLInputElement | null;
+  return parseInt(el?.value || fallback, 10);
+}
+
+function getExtractorInputs() {
+  return {
+    fw: parseInputValue('ssp-ext-width', '32'),
+    fh: parseInputValue('ssp-ext-height', '32'),
+    margin: parseInputValue('ssp-ext-margin', '0'),
+    spacing: parseInputValue('ssp-ext-spacing', '0'),
+  };
+}
+
+export function updateExtractor(): void {
+  const canvas = document.getElementById('ssp-ext-canvas') as HTMLCanvasElement | null;
+  if (!canvas) return;
+
+  if (!extImage) {
+    drawEmptyCanvasMessage(canvas, 'Upload sprite sheet to slice frames');
+    return;
+  }
+
+  canvas.width = extImage.width;
+  canvas.height = extImage.height;
+
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return;
+
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+  ctx.drawImage(extImage, 0, 0);
+
+  const { fw, fh, margin, spacing } = getExtractorInputs();
+  const slices = calculateGridSlices({
+    imageWidth: extImage.width,
+    imageHeight: extImage.height,
+    frameWidth: fw,
+    frameHeight: fh,
+    margin,
+    spacing,
+  });
+
+  const countEl = document.getElementById('ssp-ext-count');
+  if (countEl) countEl.textContent = slices.length.toString();
+
+  ctx.strokeStyle = '#38bdf8';
+  ctx.lineWidth = 1;
+  for (const slice of slices) {
+    ctx.strokeRect(slice.x, slice.y, slice.width, slice.height);
+  }
+}
+
+function processExtractedZip(e: MouseEvent, fw: number, fh: number, slices: ReturnType<typeof calculateGridSlices>) {
+  triggerButtonFeedback(document.getElementById('ssp-btn-extract-zip'), 'SPLIT ZIP!', e);
+
+  const zip = new JSZip();
+  const tempCanvas = document.createElement('canvas');
+  tempCanvas.width = fw;
+  tempCanvas.height = fh;
+  const tempCtx = tempCanvas.getContext('2d');
+  if (!tempCtx || !extImage) return;
+
+  slices.forEach((slice) => {
+    tempCtx.clearRect(0, 0, fw, fh);
+    tempCtx.drawImage(extImage!, slice.x, slice.y, slice.width, slice.height, 0, 0, fw, fh);
+    const dataUrl = tempCanvas.toDataURL('image/png').split(',')[1] ?? '';
+    zip.file(`frame_${slice.index}.png`, dataUrl, { base64: true });
+  });
+
+  zip.generateAsync({ type: 'blob' }).then((content) => {
+    const link = document.createElement('a');
+    link.href = URL.createObjectURL(content);
+    link.download = 'extracted-sprites.zip';
+    link.click();
+  });
+}
+
+export function downloadExtractedZip(e: MouseEvent): void {
+  if (!extImage) return;
+  const { fw, fh, margin, spacing } = getExtractorInputs();
+  const slices = calculateGridSlices({
+    imageWidth: extImage.width,
+    imageHeight: extImage.height,
+    frameWidth: fw,
+    frameHeight: fh,
+    margin,
+    spacing,
+  });
+
+  if (slices.length === 0) return;
+  processExtractedZip(e, fw, fh, slices);
+}
+
+export function initExtractor(): void {
+  const extDrop = document.getElementById('ssp-ext-dropzone');
+  const extInput = document.getElementById('ssp-ext-file-input') as HTMLInputElement | null;
+
+  extDrop?.addEventListener('click', () => extInput?.click());
+  extInput?.addEventListener('change', () => {
+    if (extInput.files && extInput.files[0]) {
+      const file = extInput.files[0];
+      const img = new Image();
+      img.onload = () => {
+        extImage = img;
+        updateExtractor();
+      };
+      img.src = URL.createObjectURL(file);
+    }
+  });
+
+  setupStepper('ssp-fw-dec', 'ssp-fw-inc', 'ssp-ext-width', updateExtractor);
+  setupStepper('ssp-fh-dec', 'ssp-fh-inc', 'ssp-ext-height', updateExtractor);
+  setupStepper('ssp-mar-dec', 'ssp-mar-inc', 'ssp-ext-margin', updateExtractor);
+  setupStepper('ssp-spc-dec', 'ssp-spc-inc', 'ssp-ext-spacing', updateExtractor);
+
+  ['ssp-ext-width', 'ssp-ext-height', 'ssp-ext-margin', 'ssp-ext-spacing'].forEach((id) => {
+    document.getElementById(id)?.addEventListener('input', updateExtractor);
+  });
+
+  document.getElementById('ssp-btn-extract-zip')?.addEventListener('click', (e) => downloadExtractedZip(e));
+}

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

@@ -0,0 +1,60 @@
+import { spawnParticle, type LoadedImageItem } from './packer-ui';
+
+let currentAnimFrameIndex = 0;
+let animFps = 12;
+let isPlayingAnim = true;
+let lastFrameTime = 0;
+
+export function renderFlipbookFrame(loadedImages: LoadedImageItem[]): void {
+  const canvas = document.getElementById('ssp-flipbook-canvas') as HTMLCanvasElement | null;
+  if (!canvas || loadedImages.length === 0) return;
+
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return;
+
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+  const item = loadedImages[currentAnimFrameIndex % loadedImages.length];
+
+  if (item && item.img) {
+    const scale = Math.min(canvas.width / item.img.width, canvas.height / item.img.height);
+    const drawW = item.img.width * scale;
+    const drawH = item.img.height * scale;
+    const drawX = (canvas.width - drawW) / 2;
+    const drawY = (canvas.height - drawH) / 2;
+    ctx.drawImage(item.img, drawX, drawY, drawW, drawH);
+  }
+}
+
+export function startFlipbookLoop(loadedImages: LoadedImageItem[]): void {
+  function loop(timestamp: number) {
+    if (isPlayingAnim && loadedImages.length > 0) {
+      const interval = 1000 / animFps;
+      if (timestamp - lastFrameTime > interval) {
+        currentAnimFrameIndex = (currentAnimFrameIndex + 1) % loadedImages.length;
+        lastFrameTime = timestamp;
+        renderFlipbookFrame(loadedImages);
+      }
+    }
+    requestAnimationFrame(loop);
+  }
+  requestAnimationFrame(loop);
+}
+
+export function bindFlipbook(): void {
+  const fpsSlider = document.getElementById('ssp-fps-slider') as HTMLInputElement | null;
+  fpsSlider?.addEventListener('input', () => {
+    animFps = parseInt(fpsSlider.value, 10);
+    const valEl = document.getElementById('ssp-fps-val');
+    if (valEl) valEl.textContent = `${animFps} FPS`;
+  });
+
+  document.getElementById('ssp-btn-play')?.addEventListener('click', (e) => {
+    isPlayingAnim = true;
+    spawnParticle(e.clientX, e.clientY, 'PLAYING');
+  });
+
+  document.getElementById('ssp-btn-pause')?.addEventListener('click', (e) => {
+    isPlayingAnim = false;
+    spawnParticle(e.clientX, e.clientY, 'PAUSED');
+  });
+}