@jjlmoya/utils-games-development 1.62.0 → 1.63.0

package/src/tool/hitboxHurtboxAnimator/logic.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+import {
+  clampShape,
+  cloneProject,
+  copyShapesToFrame,
+  createProject,
+  createSequenceFrames,
+  createShape,
+  createSheetFrames,
+  duplicateShape,
+  mirrorShape,
+  moveShape,
+  parseProject,
+  serializeProject,
+  shapeAtPoint,
+} from './logic';
+
+const image = { name: 'fighter.png', width: 128, height: 64 };
+
+describe('hitbox animator logic', () => {
+  it('slices a sheet row first with stable pixel coordinates', () => {
+    const frames = createSheetFrames(image, 2, 4);
+    expect(frames).toHaveLength(8);
+    expect(frames[5]).toMatchObject({ index: 5, sourceX: 32, sourceY: 32, width: 32, height: 32 });
+    expect(frames[0]?.pivot).toEqual({ x: 16, y: 16 });
+  });
+
+  it('normalizes invalid slicing counts', () => {
+    const frames = createSheetFrames(image, 0, -3);
+    expect(frames).toHaveLength(1);
+    expect(frames[0]).toMatchObject({ width: 128, height: 64 });
+  });
+
+  it('creates one full frame for every ordered image', () => {
+    const frames = createSequenceFrames([image, { name: 'fighter-2.webp', width: 96, height: 80 }]);
+    expect(frames[1]).toMatchObject({ imageIndex: 1, width: 96, height: 80, sourceX: 0, sourceY: 0 });
+  });
+
+  it('creates sheet and sequence projects with top left coordinates', () => {
+    const sheet = createProject([image], 2, 4);
+    const sequence = createProject([image, image], 4, 8);
+    const empty = createProject([]);
+    expect(sheet).toMatchObject({ rows: 2, columns: 4, fps: 12, coordinateSystem: 'top-left-pixels' });
+    expect(sequence).toMatchObject({ rows: 1, columns: 1 });
+    expect(empty.frames[0]).toMatchObject({ width: 1, height: 1 });
+  });
+
+  it('creates normalized rectangles and square circles inside a frame', () => {
+    const frame = createSheetFrames(image, 1, 1)[0]!;
+    const rectangle = createShape({ frame, type: 'hitbox', geometry: 'rectangle', startX: 60, startY: 40, endX: 20, endY: 10, name: 'Strike' });
+    const circle = createShape({ frame: { ...frame, shapes: [rectangle] }, type: 'sensor', geometry: 'circle', startX: -2, startY: 5, endX: 80, endY: 25, name: 'Range' });
+    expect(rectangle).toMatchObject({ id: 'shape-1-1', x: 20, y: 10, width: 40, height: 30 });
+    expect(circle).toMatchObject({ id: 'shape-1-2', x: 0, y: 5, width: 20, height: 20 });
+  });
+
+  it('clamps, moves, mirrors, and duplicates shapes', () => {
+    const frame = createSheetFrames(image, 1, 1)[0]!;
+    const shape = { id: 'shape-1-7', name: 'Body', type: 'hurtbox' as const, geometry: 'circle' as const, x: -5, y: 60, width: -20, height: 9 };
+    const clamped = clampShape(shape, frame);
+    expect(clamped).toMatchObject({ x: 0, y: 44, width: 20, height: 20 });
+    expect(moveShape(clamped, frame, 500, -500)).toMatchObject({ x: 108, y: 0 });
+    expect(mirrorShape(clamped, 128).x).toBe(108);
+    expect(duplicateShape(clamped, { ...frame, shapes: [shape] })).toMatchObject({ id: 'shape-1-8', name: 'Body copy', x: 2, y: 44 });
+  });
+
+  it('copies shapes with frame local identifiers', () => {
+    const [source, target] = createSheetFrames(image, 1, 2);
+    source!.shapes = [{ id: 'shape-1-1', name: 'Attack', type: 'hitbox', geometry: 'rectangle', x: 4, y: 5, width: 20, height: 10 }];
+    const copied = copyShapesToFrame(source!, target!);
+    expect(copied.shapes[0]).toMatchObject({ id: 'shape-2-1', name: 'Attack' });
+  });
+
+  it('finds the topmost shape and returns undefined outside shapes', () => {
+    const shapes = [
+      { id: 'a', name: 'A', type: 'hitbox' as const, geometry: 'rectangle' as const, x: 0, y: 0, width: 20, height: 20 },
+      { id: 'b', name: 'B', type: 'hurtbox' as const, geometry: 'rectangle' as const, x: 5, y: 5, width: 20, height: 20 },
+    ];
+    expect(shapeAtPoint(shapes, 10, 10)?.id).toBe('b');
+    expect(shapeAtPoint(shapes, 40, 40)).toBeUndefined();
+  });
+
+  it('round trips projects without sharing mutable references', () => {
+    const project = createProject([image], 2, 2);
+    const source = serializeProject(project);
+    const parsed = parseProject(source);
+    const cloned = cloneProject(project);
+    parsed.frames[0]!.pivot.x = 99;
+    cloned.frames[0]!.pivot.y = 88;
+    expect(project.frames[0]?.pivot).toEqual({ x: 32, y: 16 });
+  });
+
+  it('rejects malformed project JSON', () => {
+    expect(() => parseProject('{"version":1}')).toThrow('Invalid collision project');
+    expect(() => parseProject('not json')).toThrow();
+    expect(() => parseProject('null')).toThrow('Invalid collision project');
+  });
+});

package/src/tool/hitboxHurtboxAnimator/logic.ts

@@ -0,0 +1,173 @@
+export type CollisionType = 'hitbox' | 'hurtbox' | 'pushbox' | 'grabbox' | 'sensor' | 'custom';
+export type ShapeGeometry = 'rectangle' | 'circle';
+
+export interface ImageReference {
+  name: string;
+  width: number;
+  height: number;
+}
+
+export interface CollisionShape {
+  id: string;
+  name: string;
+  type: CollisionType;
+  geometry: ShapeGeometry;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface AnimationFrame {
+  index: number;
+  imageIndex: number;
+  sourceX: number;
+  sourceY: number;
+  width: number;
+  height: number;
+  pivot: { x: number; y: number };
+  shapes: CollisionShape[];
+}
+
+export interface CollisionProject {
+  schema: 'jjlmoya.hitbox-animation';
+  version: 1;
+  coordinateSystem: 'top-left-pixels';
+  images: ImageReference[];
+  rows: number;
+  columns: number;
+  fps: number;
+  frames: AnimationFrame[];
+}
+
+interface ShapeInput {
+  frame: AnimationFrame;
+  type: CollisionType;
+  geometry: ShapeGeometry;
+  startX: number;
+  startY: number;
+  endX: number;
+  endY: number;
+  name: string;
+}
+
+const round = (value: number): number => Math.round(value * 1000) / 1000;
+const clamp = (value: number, minimum: number, maximum: number): number => Math.min(maximum, Math.max(minimum, value));
+
+export function createSheetFrames(image: ImageReference, rows: number, columns: number): AnimationFrame[] {
+  const safeRows = Math.max(1, Math.floor(rows));
+  const safeColumns = Math.max(1, Math.floor(columns));
+  const width = image.width / safeColumns;
+  const height = image.height / safeRows;
+  return Array.from({ length: safeRows * safeColumns }, (_, index) => createFrame({ index, imageIndex: 0, width, height, columns: safeColumns }));
+}
+
+interface FrameInput {
+  index: number;
+  imageIndex: number;
+  width: number;
+  height: number;
+  columns: number;
+}
+
+function createFrame(input: FrameInput): AnimationFrame {
+  const column = input.index % input.columns;
+  const row = Math.floor(input.index / input.columns);
+  return {
+    index: input.index,
+    imageIndex: input.imageIndex,
+    sourceX: round(column * input.width),
+    sourceY: round(row * input.height),
+    width: round(input.width),
+    height: round(input.height),
+    pivot: { x: round(input.width / 2), y: round(input.height / 2) },
+    shapes: [],
+  };
+}
+
+export function createSequenceFrames(images: ImageReference[]): AnimationFrame[] {
+  return images.map((image, index) => ({
+    ...createFrame({ index, imageIndex: index, width: image.width, height: image.height, columns: 1 }),
+    sourceX: 0,
+    sourceY: 0,
+  }));
+}
+
+export function createProject(images: ImageReference[], rows = 1, columns = 1): CollisionProject {
+  const frames = images.length > 1 ? createSequenceFrames(images) : createSheetFrames(images[0] ?? { name: '', width: 1, height: 1 }, rows, columns);
+  return {
+    schema: 'jjlmoya.hitbox-animation',
+    version: 1,
+    coordinateSystem: 'top-left-pixels',
+    images,
+    rows: images.length > 1 ? 1 : Math.max(1, Math.floor(rows)),
+    columns: images.length > 1 ? 1 : Math.max(1, Math.floor(columns)),
+    fps: 12,
+    frames,
+  };
+}
+
+function shapeId(frame: AnimationFrame): string {
+  const numbers = frame.shapes.map(({ id }) => Number(id.match(/(\d+)$/)?.[1] ?? 0));
+  return `shape-${frame.index + 1}-${Math.max(0, ...numbers) + 1}`;
+}
+
+export function createShape(input: ShapeInput): CollisionShape {
+  const left = clamp(Math.min(input.startX, input.endX), 0, input.frame.width);
+  const top = clamp(Math.min(input.startY, input.endY), 0, input.frame.height);
+  const right = clamp(Math.max(input.startX, input.endX), 0, input.frame.width);
+  const bottom = clamp(Math.max(input.startY, input.endY), 0, input.frame.height);
+  const size = input.geometry === 'circle' ? Math.min(right - left, bottom - top) : 0;
+  const width = input.geometry === 'circle' ? size : right - left;
+  const height = input.geometry === 'circle' ? size : bottom - top;
+  return { id: shapeId(input.frame), name: input.name, type: input.type, geometry: input.geometry, x: round(left), y: round(top), width: round(width), height: round(height) };
+}
+
+export function clampShape(shape: CollisionShape, frame: AnimationFrame): CollisionShape {
+  const width = clamp(Math.abs(shape.width), 1, frame.width);
+  const heightValue = shape.geometry === 'circle' ? width : Math.abs(shape.height);
+  const height = clamp(heightValue, 1, frame.height);
+  return { ...shape, x: round(clamp(shape.x, 0, frame.width - width)), y: round(clamp(shape.y, 0, frame.height - height)), width: round(width), height: round(height) };
+}
+
+export function moveShape(shape: CollisionShape, frame: AnimationFrame, deltaX: number, deltaY: number): CollisionShape {
+  return clampShape({ ...shape, x: shape.x + deltaX, y: shape.y + deltaY }, frame);
+}
+
+export function mirrorShape(shape: CollisionShape, frameWidth: number): CollisionShape {
+  return { ...shape, x: round(frameWidth - shape.x - shape.width) };
+}
+
+export function duplicateShape(shape: CollisionShape, frame: AnimationFrame): CollisionShape {
+  return clampShape({ ...shape, id: shapeId(frame), name: `${shape.name} copy`, x: shape.x + 2, y: shape.y + 2 }, frame);
+}
+
+export function copyShapesToFrame(source: AnimationFrame, target: AnimationFrame): AnimationFrame {
+  const base = { ...target, shapes: [] as CollisionShape[] };
+  const shapes = source.shapes.map((shape) => duplicateShape({ ...shape, name: shape.name }, { ...base, shapes: base.shapes })).map((shape, index) => ({ ...shape, id: `shape-${target.index + 1}-${index + 1}`, name: source.shapes[index]?.name ?? shape.name }));
+  return { ...target, shapes };
+}
+
+export function shapeAtPoint(shapes: CollisionShape[], x: number, y: number): CollisionShape | undefined {
+  return [...shapes].reverse().find((shape) => x >= shape.x && y >= shape.y && x <= shape.x + shape.width && y <= shape.y + shape.height);
+}
+
+export function cloneProject(project: CollisionProject): CollisionProject {
+  return JSON.parse(JSON.stringify(project)) as CollisionProject;
+}
+
+export function serializeProject(project: CollisionProject): string {
+  return JSON.stringify(project, null, 2);
+}
+
+function isProject(value: unknown): value is CollisionProject {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as Partial<CollisionProject>;
+  return candidate.schema === 'jjlmoya.hitbox-animation' && candidate.version === 1 && Array.isArray(candidate.images) && Array.isArray(candidate.frames);
+}
+
+export function parseProject(source: string): CollisionProject {
+  const value: unknown = JSON.parse(source);
+  if (!isProject(value)) throw new Error('Invalid collision project');
+  return cloneProject(value);
+}

package/src/tool/hitboxHurtboxAnimator/project-actions.ts

@@ -0,0 +1,128 @@
+import type { EditorState } from './editor-state';
+import type { CollisionShape } from './logic';
+import {
+  clampShape,
+  cloneProject,
+  copyShapesToFrame,
+  createProject,
+  createShape,
+  duplicateShape,
+  mirrorShape,
+  moveShape,
+} from './logic';
+
+export function checkpoint(state: EditorState): void {
+  state.undoStack.push(cloneProject(state.project));
+  if (state.undoStack.length > 50) state.undoStack.shift();
+  state.redoStack = [];
+}
+
+export function undoProject(state: EditorState): boolean {
+  const previous = state.undoStack.pop();
+  if (!previous) return false;
+  state.redoStack.push(cloneProject(state.project));
+  state.project = previous;
+  normalizeSelection(state);
+  return true;
+}
+
+export function redoProject(state: EditorState): boolean {
+  const next = state.redoStack.pop();
+  if (!next) return false;
+  state.undoStack.push(cloneProject(state.project));
+  state.project = next;
+  normalizeSelection(state);
+  return true;
+}
+
+function normalizeSelection(state: EditorState): void {
+  state.currentFrame = Math.min(state.currentFrame, Math.max(0, state.project.frames.length - 1));
+  const exists = state.project.frames[state.currentFrame]?.shapes.some(({ id }) => id === state.selectedId);
+  if (!exists) state.selectedId = '';
+}
+
+export function replaceSlicing(state: EditorState, rows: number, columns: number): void {
+  if (state.project.images.length !== 1) return;
+  checkpoint(state);
+  const next = createProject(state.project.images, rows, columns);
+  next.fps = state.project.fps;
+  state.project = next;
+  state.currentFrame = 0;
+  state.selectedId = '';
+}
+
+export function addDrawnShape(state: EditorState, start: { x: number; y: number }, end: { x: number; y: number }): boolean {
+  const frame = state.project.frames[state.currentFrame];
+  if (!frame || Math.abs(end.x - start.x) < 1 || Math.abs(end.y - start.y) < 1) return false;
+  checkpoint(state);
+  const typeName = state.ui[`type${state.collisionType[0]?.toUpperCase()}${state.collisionType.slice(1)}`] ?? state.collisionType;
+  const shape = createShape({ frame, type: state.collisionType, geometry: state.geometry, startX: start.x, startY: start.y, endX: end.x, endY: end.y, name: `${typeName} ${frame.shapes.length + 1}` });
+  frame.shapes.push(shape);
+  state.selectedId = shape.id;
+  return true;
+}
+
+export function updateSelected(state: EditorState, update: Partial<CollisionShape>): boolean {
+  const frame = state.project.frames[state.currentFrame];
+  const index = frame?.shapes.findIndex(({ id }) => id === state.selectedId) ?? -1;
+  if (!frame || index < 0) return false;
+  checkpoint(state);
+  frame.shapes[index] = clampShape({ ...frame.shapes[index]!, ...update }, frame);
+  return true;
+}
+
+export function moveSelected(state: EditorState, deltaX: number, deltaY: number): boolean {
+  const frame = state.project.frames[state.currentFrame];
+  const index = frame?.shapes.findIndex(({ id }) => id === state.selectedId) ?? -1;
+  if (!frame || index < 0) return false;
+  frame.shapes[index] = moveShape(frame.shapes[index]!, frame, deltaX, deltaY);
+  return true;
+}
+
+export function deleteSelected(state: EditorState): boolean {
+  const frame = state.project.frames[state.currentFrame];
+  const index = frame?.shapes.findIndex(({ id }) => id === state.selectedId) ?? -1;
+  if (!frame || index < 0) return false;
+  checkpoint(state);
+  frame.shapes.splice(index, 1);
+  state.selectedId = '';
+  return true;
+}
+
+export function duplicateSelected(state: EditorState): boolean {
+  const frame = state.project.frames[state.currentFrame];
+  const shape = frame?.shapes.find(({ id }) => id === state.selectedId);
+  if (!frame || !shape) return false;
+  checkpoint(state);
+  const duplicate = duplicateShape(shape, frame);
+  frame.shapes.push(duplicate);
+  state.selectedId = duplicate.id;
+  return true;
+}
+
+export function mirrorSelected(state: EditorState): boolean {
+  const frame = state.project.frames[state.currentFrame];
+  const index = frame?.shapes.findIndex(({ id }) => id === state.selectedId) ?? -1;
+  if (!frame || index < 0) return false;
+  checkpoint(state);
+  frame.shapes[index] = mirrorShape(frame.shapes[index]!, frame.width);
+  return true;
+}
+
+export function copyPreviousFrame(state: EditorState): boolean {
+  const target = state.project.frames[state.currentFrame];
+  const source = state.project.frames[state.currentFrame - 1];
+  if (!source || !target) return false;
+  checkpoint(state);
+  state.project.frames[state.currentFrame] = copyShapesToFrame(source, target);
+  state.selectedId = '';
+  return true;
+}
+
+export function copyCurrentToAll(state: EditorState): boolean {
+  const source = state.project.frames[state.currentFrame];
+  if (!source) return false;
+  checkpoint(state);
+  state.project.frames = state.project.frames.map((frame) => frame.index === source.index ? frame : copyShapesToFrame(source, frame));
+  return true;
+}

package/src/tool/hitboxHurtboxAnimator/seo.astro

@@ -0,0 +1,13 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import type { SEOSection } from '../../types';
+
+interface Props {
+  locale?: string;
+  sections?: SEOSection[];
+}
+
+const { locale = 'en', sections = [] } = Astro.props;
+---
+
+<SEORenderer content={{ locale, sections }} />

package/src/tool/hitboxHurtboxAnimator/storage.ts

@@ -0,0 +1,27 @@
+export interface EditorPreferences {
+  fps: number;
+  onionPrevious: boolean;
+  onionNext: boolean;
+}
+
+const STORAGE_KEY = 'jjlmoya-hitbox-animator-preferences';
+const defaults: EditorPreferences = { fps: 12, onionPrevious: true, onionNext: true };
+
+export function loadPreferences(): EditorPreferences {
+  try {
+    const parsed = JSON.parse(localStorage.getItem(STORAGE_KEY) ?? '') as Partial<EditorPreferences>;
+    return {
+      fps: typeof parsed.fps === 'number' ? parsed.fps : defaults.fps,
+      onionPrevious: typeof parsed.onionPrevious === 'boolean' ? parsed.onionPrevious : defaults.onionPrevious,
+      onionNext: typeof parsed.onionNext === 'boolean' ? parsed.onionNext : defaults.onionNext,
+    };
+  } catch {
+    return { ...defaults };
+  }
+}
+
+export function savePreferences(preferences: EditorPreferences): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(preferences));
+  } catch {}
+}

package/src/tool/hitboxHurtboxAnimator/ui.ts

@@ -0,0 +1,70 @@
+export interface HitboxHurtboxAnimatorUI extends Record<string, string> {
+  onboarding: string;
+  privacyNote: string;
+  loadSprite: string;
+  loadHint: string;
+  chooseImages: string;
+  slicingTitle: string;
+  rowsLabel: string;
+  columnsLabel: string;
+  applySlicing: string;
+  playbackTitle: string;
+  previousFrame: string;
+  play: string;
+  pause: string;
+  nextFrame: string;
+  fpsLabel: string;
+  onionPrevious: string;
+  onionNext: string;
+  layerTitle: string;
+  typeHitbox: string;
+  typeHurtbox: string;
+  typePushbox: string;
+  typeGrabbox: string;
+  typeSensor: string;
+  typeCustom: string;
+  shapeRectangle: string;
+  shapeCircle: string;
+  drawShape: string;
+  selectShape: string;
+  stageLabel: string;
+  emptyStage: string;
+  frameReadout: string;
+  timelineTitle: string;
+  inspectorTitle: string;
+  noSelection: string;
+  nameLabel: string;
+  xLabel: string;
+  yLabel: string;
+  widthLabel: string;
+  heightLabel: string;
+  radiusLabel: string;
+  duplicateShape: string;
+  mirrorShape: string;
+  deleteShape: string;
+  copyPrevious: string;
+  copyAll: string;
+  pivotTitle: string;
+  pivotXLabel: string;
+  pivotYLabel: string;
+  exportTitle: string;
+  exportJson: string;
+  importJson: string;
+  exportContactSheet: string;
+  resetProject: string;
+  undo: string;
+  redo: string;
+  statusReady: string;
+  statusImageLoaded: string;
+  statusShapeCreated: string;
+  statusShapeUpdated: string;
+  statusImported: string;
+  statusExported: string;
+  statusError: string;
+  framesBadge: string;
+  shapesBadge: string;
+  coverageBadge: string;
+  coordinatesNote: string;
+  localOnlyDisclosure: string;
+  limitationDisclosure: string;
+}

package/src/tools.ts

@@ -10,6 +10,7 @@ import { STEAM_BBCODE_TRANSLATOR_TOOL } from './tool/steamBbcodeTranslator';
 import { RETRO_SFX_GENERATOR_TOOL } from './tool/retroSfxGenerator';
 import { PIXEL_ART_PALETTE_SWAPPER_TOOL } from './tool/pixelArtPaletteSwapper';
 import { GAME_UI_ACCESSIBILITY_TESTER_TOOL } from './tool/gameUIAccessibilityTester';
+import { HITBOX_HURTBOX_ANIMATOR_TOOL } from './tool/hitboxHurtboxAnimator';
 
 export const ALL_TOOLS: ToolDefinition[] = [
   STEAM_CAPSULE_GENERATOR_TOOL,
@@ -22,4 +23,5 @@ export const ALL_TOOLS: ToolDefinition[] = [
   RETRO_SFX_GENERATOR_TOOL,
   PIXEL_ART_PALETTE_SWAPPER_TOOL,
   GAME_UI_ACCESSIBILITY_TESTER_TOOL,
+  HITBOX_HURTBOX_ANIMATOR_TOOL,
 ];