@flighthq/spritesheet 0.1.0

package/src/spritesheetAnimation.test.ts

@@ -0,0 +1,128 @@
+import { createTextureAtlas, createTextureAtlasRegion } from '@flighthq/textureatlas';
+
+import { createSpritesheet } from './spritesheet';
+import { createSpritesheetAnimation, createSpritesheetAnimationFromFrameNames } from './spritesheetAnimation';
+import { createSpritesheetFrame } from './spritesheetFrame';
+
+describe('createSpritesheetAnimation', () => {
+  it('defaults direction to forward and frameDurations to null', () => {
+    const anim = createSpritesheetAnimation();
+
+    expect(anim.direction).toBe('forward');
+    expect(anim.frameDurations).toBeNull();
+  });
+
+  it('initializes default values', () => {
+    const anim = createSpritesheetAnimation();
+
+    expect(anim.frameDuration).toBe(0);
+    expect(anim.frames).toEqual([]);
+    expect(anim.loop).toBe(false);
+    expect(anim.originX).toBe(0);
+    expect(anim.originY).toBe(0);
+  });
+
+  it('applies partial overrides', () => {
+    const anim = createSpritesheetAnimation({ frameDuration: 100, loop: true, frames: [0, 1, 2] });
+
+    expect(anim.frameDuration).toBe(100);
+    expect(anim.loop).toBe(true);
+    expect(anim.frames).toEqual([0, 1, 2]);
+    expect(anim.originX).toBe(0);
+    expect(anim.originY).toBe(0);
+  });
+
+  it('uses a provided frames array directly', () => {
+    const frames = [0, 1, 2];
+    const anim = createSpritesheetAnimation({ frames });
+    expect(anim.frames).toBe(frames);
+  });
+
+  it('applies originX and originY overrides', () => {
+    const anim = createSpritesheetAnimation({ originX: 16, originY: 32 });
+
+    expect(anim.originX).toBe(16);
+    expect(anim.originY).toBe(32);
+  });
+
+  it('returns a new object for each call', () => {
+    const a = createSpritesheetAnimation();
+    const b = createSpritesheetAnimation();
+
+    expect(a).not.toBe(b);
+  });
+
+  it('does not share frames array reference across instances', () => {
+    const a = createSpritesheetAnimation();
+    const b = createSpritesheetAnimation();
+    a.frames.push(99);
+
+    expect(b.frames).toEqual([]);
+  });
+});
+
+describe('createSpritesheetAnimationFromFrameNames', () => {
+  function makeSheet() {
+    const atlas = createTextureAtlas();
+    atlas.regions.push(
+      createTextureAtlasRegion({ id: 0, name: 'walk_0', x: 0, y: 0, width: 32, height: 32 }),
+      createTextureAtlasRegion({ id: 1, name: 'walk_1', x: 32, y: 0, width: 32, height: 32 }),
+      createTextureAtlasRegion({ id: 2, name: 'run_0', x: 64, y: 0, width: 32, height: 32 }),
+      createTextureAtlasRegion({ id: 3, name: null, x: 96, y: 0, width: 32, height: 32 }),
+    );
+    const sheet = createSpritesheet({ atlas });
+    for (let i = 0; i < 4; i++) {
+      sheet.frames.push(createSpritesheetFrame({ id: i }));
+    }
+    return sheet;
+  }
+
+  it('applies options to the returned animation', () => {
+    const sheet = makeSheet();
+    const anim = createSpritesheetAnimationFromFrameNames(sheet, 'walk_', {
+      direction: 'pingpong',
+      frameDuration: 80,
+      loop: true,
+    });
+    expect(anim!.direction).toBe('pingpong');
+    expect(anim!.frameDuration).toBe(80);
+    expect(anim!.loop).toBe(true);
+  });
+
+  it('returns null when no frames match the pattern', () => {
+    const sheet = makeSheet();
+    expect(createSpritesheetAnimationFromFrameNames(sheet, 'jump_')).toBeNull();
+  });
+
+  it('returns null when spritesheet has no atlas', () => {
+    const sheet = createSpritesheet();
+    expect(createSpritesheetAnimationFromFrameNames(sheet, 'walk_')).toBeNull();
+  });
+
+  it('selects frames matching a RegExp pattern', () => {
+    const sheet = makeSheet();
+    const anim = createSpritesheetAnimationFromFrameNames(sheet, /^walk_/);
+    expect(anim).not.toBeNull();
+    expect(anim!.frames).toEqual([0, 1]);
+  });
+
+  it('selects frames matching a string prefix', () => {
+    const sheet = makeSheet();
+    const anim = createSpritesheetAnimationFromFrameNames(sheet, 'walk_');
+    expect(anim).not.toBeNull();
+    expect(anim!.frames).toEqual([0, 1]);
+  });
+
+  it('selects frames matching an exact name', () => {
+    const sheet = makeSheet();
+    const anim = createSpritesheetAnimationFromFrameNames(sheet, 'run_0');
+    expect(anim).not.toBeNull();
+    expect(anim!.frames).toEqual([2]);
+  });
+
+  it('skips frames whose atlas region has a null name', () => {
+    const sheet = makeSheet();
+    const anim = createSpritesheetAnimationFromFrameNames(sheet, /./);
+    expect(anim!.frames).toEqual([0, 1, 2]);
+  });
+});

package/src/spritesheetData.test.ts

@@ -0,0 +1,149 @@
+import { createSpritesheetAnimationData, createSpritesheetData, createSpritesheetFrameData } from './spritesheetData';
+
+describe('createSpritesheetAnimationData', () => {
+  it('creates with all defaults when no argument is passed', () => {
+    const anim = createSpritesheetAnimationData();
+    expect(anim.direction).toBe('forward');
+    expect(anim.frameDuration).toBe(100);
+    expect(anim.frameDurations).toBeNull();
+    expect(anim.frameNames).toEqual([]);
+    expect(anim.loop).toBe(true);
+    expect(anim.name).toBe('');
+    expect(anim.originX).toBe(0);
+    expect(anim.originY).toBe(0);
+  });
+
+  it('applies provided partial fields', () => {
+    const anim = createSpritesheetAnimationData({
+      direction: 'pingpong',
+      frameDuration: 80,
+      frameNames: ['a', 'b', 'c'],
+      loop: false,
+      name: 'walk',
+      originX: 0.5,
+      originY: 1,
+    });
+    expect(anim.direction).toBe('pingpong');
+    expect(anim.frameDuration).toBe(80);
+    expect(anim.frameNames).toEqual(['a', 'b', 'c']);
+    expect(anim.loop).toBe(false);
+    expect(anim.name).toBe('walk');
+    expect(anim.originX).toBe(0.5);
+    expect(anim.originY).toBe(1);
+  });
+
+  it('stores per-frame durations when provided', () => {
+    const anim = createSpritesheetAnimationData({
+      frameDurations: [100, 200, 150],
+      frameNames: ['a', 'b', 'c'],
+    });
+    expect(anim.frameDurations).toEqual([100, 200, 150]);
+  });
+
+  it('accepts all direction values', () => {
+    expect(createSpritesheetAnimationData({ direction: 'forward' }).direction).toBe('forward');
+    expect(createSpritesheetAnimationData({ direction: 'reverse' }).direction).toBe('reverse');
+    expect(createSpritesheetAnimationData({ direction: 'pingpong' }).direction).toBe('pingpong');
+    expect(createSpritesheetAnimationData({ direction: 'pingpong_reverse' }).direction).toBe('pingpong_reverse');
+  });
+
+  it('does not share the frameNames array between instances', () => {
+    const a = createSpritesheetAnimationData();
+    const b = createSpritesheetAnimationData();
+    a.frameNames.push('x');
+    expect(b.frameNames).toHaveLength(0);
+  });
+});
+
+describe('createSpritesheetData', () => {
+  it('creates with all defaults when no argument is passed', () => {
+    const data = createSpritesheetData();
+    expect(data.animations).toEqual([]);
+    expect(data.frames).toEqual([]);
+    expect(data.imageFile).toBe('');
+    expect(data.imageHeight).toBe(0);
+    expect(data.imageWidth).toBe(0);
+    expect(data.scale).toBe(1);
+  });
+
+  it('applies provided partial fields', () => {
+    const data = createSpritesheetData({
+      imageFile: 'atlas.png',
+      imageHeight: 512,
+      imageWidth: 256,
+      scale: 2,
+    });
+    expect(data.imageFile).toBe('atlas.png');
+    expect(data.imageHeight).toBe(512);
+    expect(data.imageWidth).toBe(256);
+    expect(data.scale).toBe(2);
+  });
+
+  it('stores frames and animations when provided', () => {
+    const frame = createSpritesheetFrameData({ name: 'hero' });
+    const anim = createSpritesheetAnimationData({ name: 'run' });
+    const data = createSpritesheetData({ animations: [anim], frames: [frame] });
+    expect(data.frames).toHaveLength(1);
+    expect(data.animations).toHaveLength(1);
+  });
+
+  it('does not share arrays between instances', () => {
+    const a = createSpritesheetData();
+    const b = createSpritesheetData();
+    a.frames.push(createSpritesheetFrameData());
+    expect(b.frames).toHaveLength(0);
+  });
+});
+
+describe('createSpritesheetFrameData', () => {
+  it('creates with all defaults when no argument is passed', () => {
+    const frame = createSpritesheetFrameData();
+    expect(frame.height).toBe(0);
+    expect(frame.name).toBe('');
+    expect(frame.offsetX).toBe(0);
+    expect(frame.offsetY).toBe(0);
+    expect(frame.pivotX).toBeNull();
+    expect(frame.pivotY).toBeNull();
+    expect(frame.rotated).toBe(false);
+    expect(frame.sourceHeight).toBe(0);
+    expect(frame.sourceWidth).toBe(0);
+    expect(frame.width).toBe(0);
+    expect(frame.x).toBe(0);
+    expect(frame.y).toBe(0);
+  });
+
+  it('applies all provided fields', () => {
+    const frame = createSpritesheetFrameData({
+      height: 64,
+      name: 'hero_idle',
+      offsetX: 2,
+      offsetY: 4,
+      pivotX: 0.5,
+      pivotY: 1,
+      rotated: true,
+      sourceHeight: 72,
+      sourceWidth: 68,
+      width: 60,
+      x: 128,
+      y: 64,
+    });
+    expect(frame.height).toBe(64);
+    expect(frame.name).toBe('hero_idle');
+    expect(frame.offsetX).toBe(2);
+    expect(frame.offsetY).toBe(4);
+    expect(frame.pivotX).toBe(0.5);
+    expect(frame.pivotY).toBe(1);
+    expect(frame.rotated).toBe(true);
+    expect(frame.sourceHeight).toBe(72);
+    expect(frame.sourceWidth).toBe(68);
+    expect(frame.width).toBe(60);
+    expect(frame.x).toBe(128);
+    expect(frame.y).toBe(64);
+  });
+
+  it('accepts null pivots explicitly', () => {
+    const frame = createSpritesheetFrameData({ pivotX: null, pivotY: null });
+    expect(frame.pivotX).toBeNull();
+    expect(frame.pivotY).toBeNull();
+  });
+});

package/src/spritesheetFrame.test.ts

@@ -0,0 +1,50 @@
+import { createSpritesheetFrame } from './spritesheetFrame';
+
+describe('createSpritesheetFrame', () => {
+  it('initializes default values', () => {
+    const frame = createSpritesheetFrame();
+
+    expect(frame.id).toBe(0);
+    expect(frame.offsetX).toBe(0);
+    expect(frame.offsetY).toBe(0);
+  });
+
+  it('defaults pivotX and pivotY to null and rotated to false', () => {
+    const frame = createSpritesheetFrame();
+
+    expect(frame.pivotX).toBeNull();
+    expect(frame.pivotY).toBeNull();
+    expect(frame.rotated).toBe(false);
+  });
+
+  it('applies partial overrides', () => {
+    const frame = createSpritesheetFrame({ id: 5, offsetX: 10, offsetY: 20 });
+
+    expect(frame.id).toBe(5);
+    expect(frame.offsetX).toBe(10);
+    expect(frame.offsetY).toBe(20);
+  });
+
+  it('applies partial override for id only', () => {
+    const frame = createSpritesheetFrame({ id: 3 });
+
+    expect(frame.id).toBe(3);
+    expect(frame.offsetX).toBe(0);
+    expect(frame.offsetY).toBe(0);
+  });
+
+  it('stores pivot and rotated values', () => {
+    const frame = createSpritesheetFrame({ id: 2, pivotX: 8, pivotY: 16, rotated: true });
+
+    expect(frame.pivotX).toBe(8);
+    expect(frame.pivotY).toBe(16);
+    expect(frame.rotated).toBe(true);
+  });
+
+  it('returns a new object for each call', () => {
+    const a = createSpritesheetFrame();
+    const b = createSpritesheetFrame();
+
+    expect(a).not.toBe(b);
+  });
+});

package/src/spritesheetFrom.test.ts

@@ -0,0 +1,259 @@
+import { createTextureAtlas, createTextureAtlasRegion } from '@flighthq/textureatlas';
+import { buildTilesetRegions, createTileset } from '@flighthq/tileset';
+
+import { createSpritesheetAnimationData, createSpritesheetData, createSpritesheetFrameData } from './spritesheetData';
+import { createSpritesheetFromData, createSpritesheetFromGrid, createSpritesheetFromTileset } from './spritesheetFrom';
+
+function makeTileset(columns: number, rows: number) {
+  const atlas = createTextureAtlas();
+  const tileset = createTileset({ atlas, columns, rows, tileWidth: 32, tileHeight: 32 });
+  buildTilesetRegions(tileset);
+  return tileset;
+}
+
+describe('createSpritesheetFromData', () => {
+  it('builds one frame per SpritesheetFrameData entry', () => {
+    const atlas = createTextureAtlas();
+    atlas.regions.push(
+      createTextureAtlasRegion({ id: 0, name: 'hero_0', x: 0, y: 0, width: 32, height: 32 }),
+      createTextureAtlasRegion({ id: 1, name: 'hero_1', x: 32, y: 0, width: 32, height: 32 }),
+    );
+    const data = createSpritesheetData({
+      frames: [
+        createSpritesheetFrameData({ name: 'hero_0', offsetX: 0, offsetY: 0 }),
+        createSpritesheetFrameData({ name: 'hero_1', offsetX: 4, offsetY: 0 }),
+      ],
+      imageFile: 'hero.png',
+      imageHeight: 64,
+      imageWidth: 64,
+    });
+    const sheet = createSpritesheetFromData(data, atlas);
+    expect(sheet.frames).toHaveLength(2);
+    expect(sheet.frames[0].id).toBe(0);
+    expect(sheet.frames[1].id).toBe(1);
+    expect(sheet.frames[1].offsetX).toBe(4);
+  });
+
+  it('resolves frame region IDs by name', () => {
+    const atlas = createTextureAtlas();
+    atlas.regions.push(createTextureAtlasRegion({ id: 5, name: 'walk_0', x: 0, y: 0, width: 32, height: 32 }));
+    const data = createSpritesheetData({
+      frames: [createSpritesheetFrameData({ name: 'walk_0' })],
+      imageHeight: 32,
+      imageWidth: 32,
+    });
+    const sheet = createSpritesheetFromData(data, atlas);
+    expect(sheet.frames[0].id).toBe(5);
+  });
+
+  it('falls back to positional index when frame name is empty', () => {
+    const atlas = createTextureAtlas();
+    atlas.regions.push(createTextureAtlasRegion({ id: 0, name: null, x: 0, y: 0, width: 32, height: 32 }));
+    const data = createSpritesheetData({
+      frames: [createSpritesheetFrameData({ name: '' })],
+      imageHeight: 32,
+      imageWidth: 32,
+    });
+    const sheet = createSpritesheetFromData(data, atlas);
+    expect(sheet.frames[0].id).toBe(0);
+  });
+
+  it('builds animations keyed by name with direction and frameDurations', () => {
+    const atlas = createTextureAtlas();
+    atlas.regions.push(
+      createTextureAtlasRegion({ id: 0, name: 'f0', x: 0, y: 0, width: 32, height: 32 }),
+      createTextureAtlasRegion({ id: 1, name: 'f1', x: 32, y: 0, width: 32, height: 32 }),
+    );
+    const data = createSpritesheetData({
+      animations: [
+        createSpritesheetAnimationData({
+          name: 'walk',
+          direction: 'pingpong',
+          frameDuration: 100,
+          frameDurations: [80, 120],
+          frameNames: ['f0', 'f1'],
+          loop: true,
+        }),
+      ],
+      frames: [createSpritesheetFrameData({ name: 'f0' }), createSpritesheetFrameData({ name: 'f1' })],
+      imageHeight: 32,
+      imageWidth: 64,
+    });
+    const sheet = createSpritesheetFromData(data, atlas);
+    const walk = sheet.animations['walk'];
+    expect(walk).toBeDefined();
+    expect(walk.direction).toBe('pingpong');
+    expect(walk.frameDurations).toEqual([80, 120]);
+    expect(walk.frames).toEqual([0, 1]);
+    expect(walk.loop).toBe(true);
+  });
+
+  it('carries pivot and rotated onto runtime frames', () => {
+    const atlas = createTextureAtlas();
+    atlas.regions.push(createTextureAtlasRegion({ id: 0, name: 'r0', x: 0, y: 0, width: 32, height: 32 }));
+    const data = createSpritesheetData({
+      frames: [createSpritesheetFrameData({ name: 'r0', pivotX: 8, pivotY: 16, rotated: true })],
+      imageHeight: 32,
+      imageWidth: 32,
+    });
+    const sheet = createSpritesheetFromData(data, atlas);
+    expect(sheet.frames[0].pivotX).toBe(8);
+    expect(sheet.frames[0].pivotY).toBe(16);
+    expect(sheet.frames[0].rotated).toBe(true);
+  });
+
+  it('uses all data frames when animation has no frameNames', () => {
+    const atlas = createTextureAtlas();
+    atlas.regions.push(
+      createTextureAtlasRegion({ id: 0, name: null, x: 0, y: 0, width: 32, height: 32 }),
+      createTextureAtlasRegion({ id: 1, name: null, x: 32, y: 0, width: 32, height: 32 }),
+    );
+    const data = createSpritesheetData({
+      animations: [createSpritesheetAnimationData({ name: 'idle', frameNames: [] })],
+      frames: [createSpritesheetFrameData({ name: '' }), createSpritesheetFrameData({ name: '' })],
+      imageHeight: 32,
+      imageWidth: 64,
+    });
+    const sheet = createSpritesheetFromData(data, atlas);
+    expect(sheet.animations['idle'].frames).toEqual([0, 1]);
+  });
+});
+
+describe('createSpritesheetFromGrid', () => {
+  it('creates one frame per cell in row-major order', () => {
+    const sheet = createSpritesheetFromGrid({
+      columns: 4,
+      rows: 2,
+      imageFile: 'sheet.png',
+      imageWidth: 128,
+      imageHeight: 64,
+    });
+    expect(sheet.frames).toHaveLength(8);
+    expect(sheet.atlas!.regions).toHaveLength(8);
+  });
+  it('assigns sequential IDs starting at 0', () => {
+    const sheet = createSpritesheetFromGrid({
+      columns: 2,
+      rows: 1,
+      imageFile: 'sheet.png',
+      imageWidth: 64,
+      imageHeight: 32,
+    });
+    expect(sheet.frames[0].id).toBe(0);
+    expect(sheet.frames[1].id).toBe(1);
+  });
+  it('computes cell x/y positions correctly with no margin or spacing', () => {
+    const sheet = createSpritesheetFromGrid({
+      columns: 2,
+      rows: 2,
+      imageFile: 'sheet.png',
+      imageWidth: 64,
+      imageHeight: 64,
+    });
+    const regions = sheet.atlas!.regions;
+    expect(regions[0].x).toBe(0);
+    expect(regions[0].y).toBe(0);
+    expect(regions[1].x).toBe(32);
+    expect(regions[1].y).toBe(0);
+    expect(regions[2].x).toBe(0);
+    expect(regions[2].y).toBe(32);
+    expect(regions[3].x).toBe(32);
+    expect(regions[3].y).toBe(32);
+  });
+  it('accounts for marginX, marginY, spacingX, and spacingY', () => {
+    const sheet = createSpritesheetFromGrid({
+      columns: 2,
+      rows: 1,
+      imageFile: 'sheet.png',
+      imageWidth: 74,
+      imageHeight: 36,
+      frameWidth: 32,
+      frameHeight: 32,
+      marginX: 2,
+      marginY: 2,
+      spacingX: 4,
+      spacingY: 0,
+    });
+    const regions = sheet.atlas!.regions;
+    expect(regions[0].x).toBe(2);
+    expect(regions[0].y).toBe(2);
+    expect(regions[1].x).toBe(38); // 2 + 32 + 4
+    expect(regions[1].y).toBe(2);
+  });
+  it('uses a custom namePrefix for region names', () => {
+    const sheet = createSpritesheetFromGrid({
+      columns: 2,
+      rows: 1,
+      imageFile: 'sheet.png',
+      imageWidth: 64,
+      imageHeight: 32,
+      namePrefix: 'hero_',
+    });
+    expect(sheet.atlas!.regions[0].name).toBe('hero_0');
+    expect(sheet.atlas!.regions[1].name).toBe('hero_1');
+  });
+  it('uses explicit frameWidth and frameHeight over derived values', () => {
+    const sheet = createSpritesheetFromGrid({
+      columns: 2,
+      rows: 1,
+      imageFile: 'sheet.png',
+      imageWidth: 80,
+      imageHeight: 40,
+      frameWidth: 30,
+      frameHeight: 40,
+    });
+    const regions = sheet.atlas!.regions;
+    expect(regions[0].width).toBe(30);
+    expect(regions[0].height).toBe(40);
+  });
+  it('creates a new atlas with no image (caller must assign image)', () => {
+    const sheet = createSpritesheetFromGrid({
+      columns: 1,
+      rows: 1,
+      imageFile: 'sheet.png',
+      imageWidth: 32,
+      imageHeight: 32,
+    });
+    expect(sheet.atlas!.image).toBeNull();
+  });
+});
+
+describe('createSpritesheetFromTileset', () => {
+  it('creates one frame per tile region', () => {
+    const tileset = makeTileset(3, 2);
+    const sheet = createSpritesheetFromTileset(tileset);
+
+    expect(sheet.frames).toHaveLength(6);
+  });
+
+  it('assigns region ids to frames in order', () => {
+    const tileset = makeTileset(2, 1);
+    const sheet = createSpritesheetFromTileset(tileset);
+    const regions = tileset.atlas?.regions ?? [];
+
+    expect(sheet.frames[0].id).toBe(regions[0].id);
+    expect(sheet.frames[1].id).toBe(regions[1].id);
+  });
+
+  it('passes the atlas through to the spritesheet', () => {
+    const tileset = makeTileset(1, 1);
+    const sheet = createSpritesheetFromTileset(tileset);
+
+    expect(sheet.atlas).toBe(tileset.atlas);
+  });
+
+  it('produces no frames when atlas is null', () => {
+    const tileset = createTileset();
+    const sheet = createSpritesheetFromTileset(tileset);
+
+    expect(sheet.frames).toHaveLength(0);
+    expect(sheet.atlas).toBeNull();
+  });
+
+  it('starts with no animations', () => {
+    const tileset = makeTileset(2, 2);
+    const sheet = createSpritesheetFromTileset(tileset);
+
+    expect(Object.keys(sheet.animations)).toHaveLength(0);
+  });
+});