Your First Animation

Let's create a simple blinking star animation.

Step 1: Define the Palette

First, create a file called blink.pxl and add a palette:

{
  type: "palette",
  name: "star",
  colors: {
    _: "transparent",
    y: "#FFD700",  // Yellow (gold)
    w: "#FFFFFF",  // White (bright)
  },
}

Step 2: Create Animation Frames

Add two sprite frames - one normal, one bright:

{
  type: "sprite",
  name: "star_normal",
  size: [3, 3],
  palette: "star",
  regions: {
    y: {
      union: [
        { points: [[1, 0], [1, 2]] },
        { rect: [0, 1, 3, 1] },
      ],
    },
  },
}

{
  type: "sprite",
  name: "star_bright",
  size: [3, 3],
  palette: "star",
  regions: {
    w: {
      union: [
        { points: [[1, 0], [1, 2]] },
        { rect: [0, 1, 3, 1] },
      ],
    },
  },
}

Step 3: Define the Animation

Add the animation object that sequences the frames:

{
  type: "animation",
  name: "blink",
  frames: ["star_normal", "star_normal", "star_normal", "star_bright"],
  duration: 150,
}

This creates a blink effect:

• Three frames of normal yellow (450ms total)
• One frame of bright white (150ms)
• Then loops

Complete File

Your blink.pxl should look like:

// blink.pxl - A blinking star animation
{
  type: "palette",
  name: "star",
  colors: {
    _: "transparent",
    y: "#FFD700",
    w: "#FFFFFF",
  },
}

{
  type: "sprite",
  name: "star_normal",
  size: [3, 3],
  palette: "star",
  regions: {
    y: {
      union: [
        { points: [[1, 0], [1, 2]] },
        { rect: [0, 1, 3, 1] },
      ],
    },
  },
}

{
  type: "sprite",
  name: "star_bright",
  size: [3, 3],
  palette: "star",
  regions: {
    w: {
      union: [
        { points: [[1, 0], [1, 2]] },
        { rect: [0, 1, 3, 1] },
      ],
    },
  },
}

{
  type: "animation",
  name: "blink",
  frames: ["star_normal", "star_normal", "star_normal", "star_bright"],
  duration: 150,
}

Step 4: Render as GIF

Export the animation as a GIF:

pxl render blink.pxl --gif --animation blink -o blink.gif --scale 8

This creates blink.gif - an 8x scaled animated GIF of your blinking star!

Step 5: Export as Spritesheet

For game engines, export as a horizontal spritesheet:

pxl render blink.pxl --spritesheet --animation blink -o blink_sheet.png --scale 4

This creates a horizontal strip with all frames side by side.

Animation Options

The animation object supports these fields:

Tips

• Reuse frames - Repeat sprite names in the frames array for timing control
• Frame duration - Lower values = faster animation
• Scale - Always scale up for previews; pixel art is small!
• Validate first - Run pxl validate before rendering to catch issues

Next Steps

• Learn about Variants to create frame variations efficiently
• Explore Compositions to layer animated sprites
• Check the GIF Export guide for advanced options