desktop-pet

Desktop Pet Creator

Create pixel-art chibi desktop pet companions for Qwen Code's floating pet window. Given any character name, generate a complete pet package with animated spritesheet and place it in ~/.qwen/pets/ where Qwen Code auto-discovers it.

Prerequisites

• Python 3 with Pillow (pip3 install Pillow). Check before running the script:

python3 -c "from PIL import Image; print('OK')" 2>/dev/null || echo "Pillow not installed — run: pip3 install Pillow"

Step 1: Identify the Character

Ask the user who they want as their desktop pet if not already specified. Then research the character's visual appearance:

• Team/organization colors (e.g., McLaren papaya orange, Ferrari red)
• Outfit/uniform (racing suit, school uniform, armor, etc.)
• Distinguishing features (hair color/style, accessories, number, helmet)
• Personality traits (for animation style — energetic, calm, goofy, serious)
• Iconic items (steering wheel, lightsaber, guitar, etc.)

Use web search if needed. For well-known characters (F1 drivers, popular anime, etc.), rely on training knowledge.

Step 2: Design the Color Palette

Define 8–12 colors for the character. All colors must be distinct and work at small pixel scale (3× = 9 px details).

Step 3: Generate the Spritesheet

Run the generation script. Always resolve the path relative to the skill's base directory:

python3 <skill_dir>/scripts/gen_spritesheet.py \
  --output ~/.qwen/pets/<character_id>/spritesheet.webp \
  --config '{"colors":{...},"features":{...}}'

Atlas format: 1536×1872 px, RGBA, 8 cols × 9 rows, 192×208 px cells.

Animation rows:

Step 4: Create pet.json

Write the manifest to ~/.qwen/pets/<character_id>/pet.json:

{
  "id": "<character_id>",
  "displayName": "<Display Name>",
  "description": "<Short description — who is this character?>",
  "spritesheetPath": "spritesheet.webp"
}

Rules:

• id: lowercase, no spaces, URL-safe (e.g., piastri, satoru, goku)
• displayName: The name shown in the UI (e.g., "Piastri", "五条悟", "悟空")
• description: One short sentence describing the character

Step 5: Verify and Activate

1. Confirm the files exist:

ls -lh ~/.qwen/pets/<character_id>/

2. Open the spritesheet for the user to check:

open ~/.qwen/pets/<character_id>/spritesheet.webp

3. Tell the user to activate: open Qwen Code Settings → Appearance → Pet Companion, click Refresh, then select the new pet.

Design Guidelines

Chibi Proportions

• Head: ~40% of total height (big head = cute)
• Body: ~30% of total height
• Legs: ~25% of total height
• Scale: Each "pixel" in the art = 3×3 actual pixels (scale=3)
• Character center: approximately (96, 124) within the 192×208 cell

Drawing Order (back to front)

1. Legs (behind body)
2. Body / outfit
3. Arms
4. Head shape
5. Hair (back layer)
6. Hair (front/top layer)
7. Face features (eyes, mouth, expression)
8. Accessories (hat, helmet, glasses, etc.)
9. Foreground details (number, logo, badge)

Animation Tips

• Idle: subtle Y bob (0 to −2 px) + blink every 3rd–4th frame
• Running: alternating leg offset (±4 px), body tilt (±2 px), arm swing
• Waving: one arm raised high, alternating frames
• Jumping: Y offset curve (0 → −30 → 0), arms up
• Failed: body tilt increases, then collapse to sitting pose
• Happy expression: curved eyes (∧ shape), blush marks on cheeks
• Sad expression: straight eyebrows, downturned mouth

Headgear Options (features.headgear)

cap · helmet · hat · hood · crown · horns · ears · halo · headband · none

Hair Styles (features.hair_style)

short · long · spiky · ponytail · bald

Extras (features.extras list)

glasses · scarf · tail · wings · number (set features.number) · logo · sweat_drop

Example Characters

F1 Driver (e.g., Piastri)

{
  "colors": {
    "outfit": [255, 135, 32],
    "outfit_dark": [220, 110, 20],
    "outfit_light": [255, 170, 80],
    "hair": [120, 80, 40],
    "accent": [30, 30, 30]
  },
  "features": {
    "headgear": "cap",
    "number": "81",
    "extras": ["logo"]
  }
}

Anime Character (e.g., Gojo Satoru)

{
  "colors": {
    "outfit": [30, 30, 50],
    "outfit_dark": [20, 20, 35],
    "outfit_light": [60, 60, 80],
    "hair": [230, 230, 250],
    "accent": [100, 180, 255]
  },
  "features": {
    "headgear": "none",
    "hair_style": "spiky",
    "extras": ["glasses"]
  }
}

Animal (e.g., Shiba Inu)

{
  "colors": {
    "outfit": [220, 170, 100],
    "outfit_dark": [180, 130, 70],
    "outfit_light": [240, 200, 140],
    "hair": [220, 170, 100]
  },
  "features": {
    "headgear": "ears",
    "extras": ["tail"]
  }
}

Troubleshooting

• Pet not showing: Click Refresh in Settings → Appearance → Pet Companion
• Colors look wrong: Check that RGB values are tuples, not hex strings
• Spritesheet too large: Must be under 5 MB (webp lossless usually ~8–50 KB)
• Animation jittery: Ensure all 8 frames per row are visually distinct but not jarring