Desktop Pet

Desktop Pet Creator

Create pixel-art chibi desktop pet companions for OpenWork's Tauri pet window. Given any character name, generate a complete pet package with animated spritesheet and place it in ~/.qwen/pets/ where OpenWork auto-discovers it through the scoped Tauri asset protocol.

Workflow

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 to gather visual reference. 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:

Important: All colors must be distinct and work at small pixel scale (3x = 9px details).

Step 3: Generate the Spritesheet

Use the template script at scripts/gen_spritesheet.py as a starting point. The script generates a 1536×1872 pixel RGBA spritesheet (8 columns × 9 rows, 192×208 px cells) — the exact format OpenWork expects.

Run it like this:

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

Or copy and customize the script for characters that need unique visual elements not covered by the parameterized version.

The 9 animation rows are:

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 in Preview for the user to check:

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

3. Tell the user to activate:

   Reopen OpenWork → Settings → Appearance → Desktop pet, then select . Selection opens a live preview.

Character 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 -2px) + blink every 3rd-4th frame
• Running: alternating leg offset (±4px), body tilt (±2px), 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 Variants

The template supports several headgear types. Set via features.headgear:

• cap — baseball cap with brim (default for F1 drivers)
• helmet — full racing helmet with visor
• none — no headgear (just hair)
• hat — generic hat
• hood — hooded outfit
• crown — royal crown
• horns — devil/dragon horns
• ears — animal ears (cat, dog, etc.)
• halo — angel halo
• headband — ninja/sports headband

Special Features

Set via features.extras (list):

• glasses — round or rectangular glasses
• scarf — neck scarf
• tail — animal tail
• wings — small wings on back
• number — chest number (set features.number to the number string)
• logo — chest badge/logo area
• sweat_drop — anime sweat drop (in waiting/failed states)

Example Characters

F1 Driver (e.g., Piastri, Norris, Verstappen)

{
  "colors": {
    "outfit": [255, 135, 32],
    "outfit_dark": [220, 110, 20],
    "outfit_light": [255, 170, 80],
    "hair": [120, 80, 40],
    "number": [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",
    "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],
    "accent": [255, 255, 255]
  },
  "features": {
    "headgear": "ears",
    "extras": ["tail"]
  }
}

Troubleshooting

• Pet not showing: Reopen Settings → Appearance so OpenWork rescans ~/.qwen/pets/; confirm pet.json points to a file inside the same pet folder
• Colors look wrong: Check that RGB values are tuples, not hex strings
• Spritesheet too large: Must be under 5MB (webp lossless usually ~8-50KB)
• Animation jittery: Ensure all 8 frames per row are visually distinct but not jarring