Quick Start Guide
Get up and running with custom pets in just a few steps
🍎 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
Limited SupportWindows currently has limited support:
- No export functionality
- No drag and drop system
- Some capabilities not supported
Workaround: Access the PetAssets or Species folders directly to add, modify, or delete content.
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)
Pet Capabilities
Capabilities define how your pet behaves and interacts with the environment
Standard Capabilities
Most pets use this recommended set:
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
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
fpsproperty in your JSON
App Integration
How to export, import, and manage your custom pets
🔄 Export Pets
Go to the Info view in the bottom navigation bar to find and use the export functionality.
📥 Import Pets
Go to the Info view in the bottom navigation bar and drag your ZIP file to the designated drop area.
Resources & Community
Get help, inspiration, and share your creations