Sprite Sheet Metadata: JSON Atlas and CSS Mapping

Sprite Sheet Metadata

Beyond the image file itself, sprite sheets need metadata that describes the position, size, and name of each sprite. This metadata can take various formats depending on the use case.

JSON Texture Atlas

The most common metadata format for game engines:

{
  "meta": {
    "image": "sprites.png",
    "size": { "w": 256, "h": 128 },
    "format": "RGBA8888"
  },
  "frames": {
    "icon-home": {
      "frame": { "x": 0, "y": 0, "w": 32, "h": 32 },
      "sourceSize": { "w": 32, "h": 32 },
      "spriteSourceSize": { "x": 0, "y": 0, "w": 32, "h": 32 },
      "rotated": false,
      "trimmed": false
    },
    "icon-search": {
      "frame": { "x": 34, "y": 0, "w": 32, "h": 32 },
      "sourceSize": { "w": 32, "h": 32 },
      "spriteSourceSize": { "x": 0, "y": 0, "w": 32, "h": 32 },
      "rotated": false,
      "trimmed": false
    }
  }
}

SCSS Mixins

Generate SCSS for programmatic sprite usage:

// Generated sprite map
$sprite-sheet: 'sprites.png';
$sprites: (
  home:   (x: 0, y: 0, width: 32px, height: 32px),
  search: (x: 34px, y: 0, width: 32px, height: 32px),
  user:   (x: 68px, y: 0, width: 32px, height: 32px),
);

// Mixin
@mixin sprite($name) {
  $sprite: map-get($sprites, $name);
  width: map-get($sprite, width);
  height: map-get($sprite, height);
  background: url($sprite-sheet) no-repeat;
  background-position: -(map-get($sprite, x)) -(map-get($sprite, y));
}

// Usage
.icon-home { @include sprite(home); }
.icon-search { @include sprite(search); }

TypeScript Type Definitions

For type-safe sprite usage in TypeScript projects:

// sprites.d.ts (auto-generated)
export type SpriteName =
  | 'home'
  | 'search'
  | 'user'
  | 'settings'
  | 'notification';

export interface SpriteData {
  x: number;
  y: number;
  width: number;
  height: number;
}

export const sprites: Record<SpriteName, SpriteData>;
export const spriteSheetUrl: string;

CSS Custom Properties

Generate CSS custom properties for flexible usage:

:root {
  --sprite-sheet: url('sprites.png');
  --sprite-home-x: 0px;
  --sprite-home-y: 0px;
  --sprite-home-w: 32px;
  --sprite-home-h: 32px;
  --sprite-search-x: -34px;
  --sprite-search-y: 0px;
  --sprite-search-w: 32px;
  --sprite-search-h: 32px;
}

.sprite {
  background: var(--sprite-sheet) no-repeat;
  display: inline-block;
}

.sprite-home {
  width: var(--sprite-home-w);
  height: var(--sprite-home-h);
  background-position: var(--sprite-home-x) var(--sprite-home-y);
}

Integration Patterns

Different frameworks consume sprite metadata differently:

• React — Import JSON atlas, use inline styles or CSS modules
• Vue — Computed properties from imported sprite map
• Angular — Directive that reads sprite metadata
• Game engines — Load JSON atlas at runtime for Canvas/WebGL rendering