mate

Mate Pet Creator

Create animated desktop pet characters for MiMo Desktop's Mate (桌面伙伴) system.

Output Structure

A valid custom pet lives in a folder with this structure:

<pet-id>/
├── manifest.json     # Required — animation metadata
└── spritesheet.webp  # Required — all animation frames in a grid

The user places this folder in their MiMo Desktop custom pets directory (userData/pets/<pet-id>/), then clicks "Refresh" in Settings → Mate to load it.

Manifest Schema

{
  "id": "my-pet",
  "name": "My Pet",
  "description": "A cute custom pet",
  "version": 1,
  "spritesheet": "spritesheet.webp",
  "frameWidth": 240,
  "frameHeight": 240,
  "columns": 8,
  "totalFrames": 16,
  "animations": {
    "idle": { "row": 0, "frames": 8, "fps": 8, "loop": true }
  }
}

Required Fields

Field	Type	Description
id	string	Unique identifier (kebab-case)
name	string	Display name
version	number	Always 1
spritesheet	string	Filename of the spritesheet image
frameWidth	number	Width of each frame in pixels
frameHeight	number	Height of each frame in pixels
columns	number	Number of columns in the spritesheet grid
totalFrames	number	Total number of frames across all animations
animations	object	At minimum must include idle

Optional Fields

Field	Type	Description
description	string	Shown in settings UI
anchorX	number	Horizontal anchor (0–1, default 0.5) for centering

Animation Definition

Each animation entry:

Field	Type	Description
row	number	Row index in the spritesheet (0-based)
frames	number	Number of frames in this animation
fps	number	Playback speed (recommended: 6–12)
loop	boolean	Whether the animation loops

The idle animation is required — it plays by default when the pet is loaded.

Spritesheet Layout

• Frames are arranged left-to-right, top-to-bottom in a grid.
• Each row corresponds to one animation (matched by the row field in the animation definition).
• All frames must have identical dimensions (frameWidth × frameHeight).
• Transparent background (alpha channel) is required — the pet window has no background.
• Recommended frame size: 240×240 px (renders well at 1× scale on desktop).
• Format: WebP with transparency (lossless or near-lossless for crisp pixel art).

Workflow

Step 1: Understand the Character

Ask the user:

• What animal/creature/character?
• Art style preference (pixel art, cartoon, flat vector, kawaii)?
• Any specific colors or features?

Step 2: Generate the Spritesheet

Use the imagegen skill to generate the spritesheet image. Construct the prompt with these guidelines:

• Request a sprite sheet with specific grid layout (e.g., "8 frames in a single horizontal row, each frame 240×240 pixels")
• Specify transparent background (alpha channel)
• Describe the idle animation motion: gentle breathing, blinking, tail wag, bobbing, etc.
• Keep the character centered in each frame with consistent sizing
• Style: match the user's preference; default to cute/kawaii if unspecified

If the generated image is already WebP, use it directly. If it is PNG or another format, convert to WebP:

# Convert to lossless WebP preserving transparency
cwebp -lossless -q 100 spritesheet.png -o spritesheet.webp

If cwebp is not available, check for sips (macOS Ventura+ supports WebP export):

sips -s format webp spritesheet.png --out spritesheet.webp

If neither tool is available, instruct the user to install one:

brew install webp   # provides cwebp

Do NOT silently rename a PNG to .webp — the file must have valid WebP encoding (RIFF/WEBP header). If conversion genuinely cannot be performed, fail explicitly and tell the user what tool to install.

If imagegen is unavailable (skill not enabled or image generation fails), fall back to generating pixel-art frames directly as SVG, then rasterize. Compute dimensions from the manifest:

# Calculate actual spritesheet dimensions from manifest
WIDTH=$((frameWidth * columns))
HEIGHT=$((frameHeight * rows))  # rows = max animation row index + 1

# Rasterize SVG to PNG, then convert to WebP
rsvg-convert -w $WIDTH -h $HEIGHT spritesheet.svg -o spritesheet.png
cwebp -lossless spritesheet.png -o spritesheet.webp

As a last resort, output the SVG file directly and instruct the user to convert it manually.

Step 3: Write the Manifest

Generate manifest.json with correct dimensions matching the actual spritesheet output. Verify:

• frameWidth × columns = spritesheet total width
• frameHeight × (max animation row index + 1) = spritesheet total height
• animations.idle exists with valid row, frames, fps, loop
• Each animation's frames ≤ columns (frames per row cannot exceed grid columns)

Step 4: Deliver

Write both files to the current working directory under a folder named with the pet ID. Tell the user to:

1. Copy the folder to their MiMo Desktop pets directory (Settings → Mate → click "Open Folder" to find it)
2. Click "Refresh" in Settings → Mate
3. Select their new pet from the list

Constraints

• The idle animation MUST exist — the system falls back to it.
• Frame dimensions must be consistent across the entire spritesheet.
• Keep total file size under 2MB for smooth loading.
• Pet ID must be unique; if it conflicts with a preset (koala, panda), the preset wins.
• Do NOT reference or depend on any external URLs — all assets must be local files.