Custom Pets - Create Your Own Digital Companions

Quick Start Guide

Get up and running with custom pets in just a few steps

✨ New: make a pet with AI

Turn a photo of your own cat, dog or hamster into a desktop pet. Copy-paste prompts, including one that has your AI package the finished pet, and a downloadable example pet. (Our own pets are all hand-drawn by our designers; AI is only for the pets you make.)

Open the AI tutorial →

🍎 macOS

Full Support

Click on a pet you like and export it
Modify the JSON file and sprites as you see fit
Double check filename conventions
Zip everything together
Drag and drop the zip into the app
Share your work on Discord!

🪟 Windows & 🐧 Linux

Import Supported

Start from the example pet or the AI tutorial
Modify the JSON file and sprites as you see fit
Double check filename conventions
Zip everything together
Open the About page and drop the zip on the Create your own! area, or click it to pick the file

Not yet on Windows/Linux: exporting built-in pets. Use the example pet as your template instead. The ZIP format is the same on every platform.

Setup Requirements

📱

Updated App

Make sure you have the latest version of Pets Therapy installed on your Mac.

🎨

Sprite Editor

Any tool for designing sprites works. We recommend Aseprite for pixel art.

Species Definition

Every custom pet is defined by a JSON configuration file

What defines a Species?

Unique ID: A distinctive identifier for your pet
Capabilities: Behaviors and physics properties
Animations: Visual states and movements
Attributes: Speed, scale, FPS, and other properties

Example JSON Structure

{
  "id": "ape",
  "dragPath": "drag",
  "fallPath": "drag",
  "fps": 10,
  "zIndex": 0,
  "scale": 1,
  "tags": ["jungle"],
  "movementPath": "walk",
  "speed": 0.7,
  "capabilities": [
    "AnimatedSprite",
    "AnimationsProvider",
    "AnimationsScheduler",
    "AutoRespawn",
    "BounceOnLateralCollisions",
    "Draggable",
    "FlipHorizontallyWhenGoingLeft",
    "Gravity",
    "LinearMovement",
    "PetsSpritesProvider",
    "Rotating",
    "ShowsMenuOnRightClick"
  ],
  "animations": [
    {
      "id": "front",
      "position": "fromEntityBottomLeft",
      "requiredLoops": 5
    }
  ]
}

⚠️ Important Naming Rules

Species ID: Do not include _ (underscore) in your species.id
Animation ID: Do not include _ (underscore) in your animation.id
Reason: Underscores separate species from animation names (e.g., ape_eat = ape + eat)
Required keys: id, animations, capabilities, dragPath, fps, movementPath, speed, tags (may be []) and zIndex. A missing one makes the import fail with "Invalid species.json file"
Required sprites: at least one {id}_{movementPath}-N.png and one {id}_{dragPath}-N.png, plus front for previews

Pet Capabilities

Capabilities define how your pet behaves and interacts with the environment

Standard Capabilities

Most pets use this recommended set:

AnimatedSprite BounceOnLateralCollisions FlipHorizontallyWhenGoingLeft Gravity LinearMovement Draggable

Special Capabilities

Unique behaviors for specific pet types:

GetsAngryWhenMeetingOtherCats: Grumpy Cat's special behavior
WallCrawler: Allows crawling along screen borders (snails)
RandomPlatformJumper: Enables jumping to other windows

Animation System

Create engaging animations that bring your pets to life

Animation Properties

ID: Determines which sprite set to use
Position: Where the animation appears
Required Loops: How many times the animation repeats
Size: Custom sizing (optional, see sloth's lightsaber)

Required Animation

Every species must have at least a "front" animation, which is used on the homepage and pet details.

Other Important Properties

movementPath: Sprite set for movement (usually "walk" or "fly")

dragPath: Sprite used when pet is dragged (usually "drag" or "front")

fallPath: Sprite used when pet is falling (v2.48+, optional)

speed: How fast the pet moves

fps: Animation frame rate (max 20 fps, recommend 10 fps)

Sprite Creation

Learn the file naming conventions and structure for your pet sprites

File Naming Convention

Each sprite file must follow this exact pattern:

{species.id}_{animation.id}-{index}.png

Examples:

ape_front-1.png ape_front-2.png ape_walk-0.png sloth_swag_lightsaber-0.png

Important Rules:

Indices can start from 0 or 1, but must be sequential
Names are case-sensitive
Use PNG format only
No gaps in the sequence

Animation Duration

All animations for a species must use the same FPS (frames per second).

Maximum FPS: 20 (for battery conservation)
Recommended FPS: 10 (100ms per frame)
Setting: Change the fps property in your JSON

App Integration

How to export, import, and manage your custom pets

🔄 Export Pets

macOS: open any pet's details and use Export to get its JSON and sprites as a starting point.

📥 Import Pets

Go to the About page and drag your ZIP file onto the "Create your own!" drop area. On Windows and Linux you can also click it to pick the file.

Resources & Community

Get help, inspiration, and share your creations

💬

Discord Community

Share your creations and get help from other creators

Join Discord

🎨

Aseprite Files

Ask the community for source files for reference and inspiration

Join Discord

📋

Complete Examples

Export any existing pet from the app to see its JSON and sprites

See the format

Ready to Get Started?

Download Pets Therapy for free and start enjoying digital companionship roaming around your desktop

macOS

Start your digital pet adventure today

Download on the Mac App Store

Windows

Bring desktop pets to your Windows PC

Get it from the Microsoft Store

Steam

Get Pets Therapy on Steam for Windows

Get it on Steam for Windows