Developer documentation

Slice sheet JSON

A slice sheet comes with a JSON file that says where each slice is in the sheet, and what else it has: nine-slice guides, a pivot and named points. Read it in your game to cut the sheet into sprites.

The files#

File ▸ Export ▸ Slice Sheet... with JSON metadata checked (it is at first) writes name.json beside name.png.
On the Grouped Sheets tab, each layer group gets a sheet of its own, sheet_<group>.png, all laid out the same, and one sheet_meta.json goes with all of them.

An example#

What SpriteGrid writes for three slices: a knight with a pivot at his feet and a point in his hand, a button with nine-slice guides, and a banner that runs 4 pixels off the left edge of the canvas.

sheet.json

{
  "frames": {
    "knight": {
      "frame": {
        "x": 0,
        "y": 0,
        "w": 16,
        "h": 24
      },
      "pivot": {
        "x": 0.5,
        "y": 1
      },
      "points": {
        "hand": {
          "x": 13.5,
          "y": 14.5
        }
      }
    },
    "button": {
      "frame": {
        "x": 16,
        "y": 0,
        "w": 8,
        "h": 8
      },
      "nineSlice": {
        "top": 3,
        "right": 3,
        "bottom": 3,
        "left": 3
      }
    },
    "banner": {
      "frame": {
        "x": 0,
        "y": 24,
        "w": 16,
        "h": 8
      },
      "trimmed": true,
      "spriteSourceSize": {
        "x": 4,
        "y": 0,
        "w": 16,
        "h": 8
      },
      "sourceSize": {
        "w": 20,
        "h": 8
      },
      "pivot": {
        "x": 0.5,
        "y": 1
      }
    }
  },
  "meta": {
    "size": {
      "w": 24,
      "h": 32
    },
    "format": "RGBA8888"
  }
}

It's laid out like the "JSON hash" sheets that loaders such as Phaser's read: frames by name, each with its frame in the sheet. A reader that doesn't know SpriteGrid's own fields (nineSlice, pivot and points) can skip them.

Reading it in a game#

Positions count from the top-left corner, with y going down. Where y goes up, as in Unity, a pivot's y is 1 − y there, and a point's is the slice's height − y.
A pivot is fractions of its slice; points are pixels.
When a frame is trimmed, its image is only the part of the slice that was on the canvas. Place it at spriteSourceSize's x and y in a box the size of sourceSize, and the pivot and points line up.
Give every slice its own name: slices that share one share one entry.
The file's JSON Schema is at https://spritegrid.com/schemas/slice-sheet.schema.json. Check a file against it, or make your game's types from it.

The file#

framesframes by namerequired: Every slice in the sheet, by its name. Slices that share a name share one entry (the last one's), so give each slice its own name.
metaobjectrequired: About the sheet image.

A frame#

framerectanglerequired: Where the slice's image is in the sheet. It holds the part of the slice inside the canvas, so a slice that runs off the canvas is smaller here than it is (see trimmed), and one all outside it is 0 × 0.
trimmedtrue or false: True when the slice runs off the canvas and has a pivot or points, so its image is only part of it. Then spriteSourceSize says where that part sits in the slice, and sourceSize is the whole slice's size, so the pivot and points still mean the whole slice.
spriteSourceSizerectangle: With trimmed: where the image sits in the whole slice (from the slice's top-left corner), and its size.
sourceSizesize: With trimmed: the whole slice's size.
nineSliceinsets: The slice's nine-slice guides: how far in from each edge its corners end, in pixels. Drawn bigger, the corners keep their size and the edges and middle stretch. There when all four are set.
pivotpoint: The slice's pivot, the spot a game places and turns the sprite by, as fractions of the slice's own width and height (never the sheet's): { "x": 0, "y": 0 } is its top-left corner and { "x": 0.5, "y": 1 } the middle of its bottom edge. A pivot outside the slice is below 0 or above 1.
pointspoints by name: The slice's named points, like where a hand holds a sword, by name: each in pixels from the slice's top-left corner, where whole numbers are between pixels and .5 is a pixel's middle. A point can be outside the slice.

The sheet image#

sizesizerequired: The sheet image's size in pixels.
formatstringrequired: The image's pixels: always "RGBA8888", 8 bits each of red, green, blue and alpha.

Rectangles, sizes, insets and points#

A rectangle#

xnumberrequired: Pixels from the left edge.
ynumberrequired: Pixels from the top edge.
wnumberrequired: The width in pixels.
hnumberrequired: The height in pixels.

A size#

wnumberrequired: The width in pixels.
hnumberrequired: The height in pixels.

Nine-slice insets#

topnumberrequired: Pixels in from the top edge.
rightnumberrequired: Pixels in from the right edge.
bottomnumberrequired: Pixels in from the bottom edge.
leftnumberrequired: Pixels in from the left edge.

A pivot or point#

xnumberrequired: How far right of the slice's left edge.
ynumberrequired: How far down from the slice's top edge.