← All how-tos
PACKS

Import your own pack from a .zip

Drew or rendered your own pet? Bundle 3 PNGs into a .zip and Dockling will import it in one click — no website round-trip. Add up to 6 more for extra personality.

What you need

  • 3 required PNG frames (the bare minimum Dockling needs to animate your pet)
  • Up to 6 optional bonus frames for extra personality — Dockling falls back gracefully if you skip them
  • Transparent, magenta (#FF00FF), or white background — Dockling auto-removes all three on import and crops to the silhouette
  • Square frames, ~512×512 px works well

Required scenes (3)

These three are mandatory. Each frame must be named exactly as shown — case-sensitive, ending in .png. Miss one and the import will fail.

idle_stand.pngDefault standing pose. Used as the dock icon and most idle moments.
happy_stand.pngSmiling, attentive. Pairs with idle_stand for the walk animation.
sleep_curl.pngSleeping pose. Used during Pomodoro breaks.

Optional bonus scenes (up to 6)

These add flavor — celebration animations, personality blips, transitions. If a file is missing, Dockling silently falls back to a sensible required frame.

idle_smug.pngAlt idle / thinking pose. — falls back to idle_stand
success_fire.pngPlays after a save / success moment. — falls back to happy_stand
action_fly.pngTake-off frame for mode transitions. — transition still plays with happy_stand
action_eat.pngSnack pose. Triggered by personality. — personality skipped
action_shower.pngShower / cleanup pose. Triggered by personality. — personality skipped
excited_punch.pngAlt success pose (10% of successes). — uses success_fire instead

Zip layout

Either of these layouts works:

Minimal (3 required PNGs)
my-pet.zip
├── idle_stand.png
├── happy_stand.png
└── sleep_curl.png
Folder (single top-level dir)
my-pet.zip
└── my-pet/
    ├── idle_stand.png
    ├── happy_stand.png
    ├── sleep_curl.png
    └── … (any optional frames)

Naming your pet

Dockling will prompt you for a name during import. The default is taken from pack.json (if present) or the .zip filename — most people just hit Enter. You can rename a pack any time from the Settings popover.

Optionally include a pack.json to pre-fill the name:

pack.json (optional)
{
  "name": "Pixel Goose"
}

Import it in the app

  1. Open Dockling.
  2. Right-click your pet → Character → Import Pack from .zip…
    (Or use the menu bar: Dockling → Import Pack from .zip…)
  3. Pick your .zip. The new pack becomes your active pet.

Troubleshooting

  • "Zip is missing required frame PNGs." Check the filenames — they're case-sensitive and must end in .png.
  • Pack imports but pet looks off-center. Trim whitespace and re-export. Frames are drawn at their full bounding box.
  • Want to swap back? Right-click → Character → pick any other pack. Custom packs can be deleted from the Settings popover.
Or generate one from a photo →More how-tos