【📖 English README doc】 【📖 简体中文 README 文档】

🎤 MikuStage for Codex Pets

MikuStage is a fan-made pixel-art Codex pet based on the supplied Hatsune Miku character references. It preserves her long cyan-teal twin tails, headset, classic stage outfit, detached sleeves, boots, and visible 01 shoulder marking.

This is an unofficial personal project. Hatsune Miku and related character rights belong to their respective rights holders. The magenta preview background is a production chroma key; the packaged spritesheet is transparent.

✨ Features

• Codex Pets sprite format v2
• 8 columns by 11 rows with 192x208 cells
• Idle, right/left movement, waving, jumping, failed, waiting, working, and review animations
• 16 clockwise look directions
• Deterministic atlas, transparency, blind-direction, continuity, and visual QA artifacts

📦 Install

💻 PowerShell

Run this command from the repository root:

$target = Join-Path $env:USERPROFILE '.codex\pets\mikustage'
New-Item -ItemType Directory -Force -Path $target | Out-Null
Copy-Item -Force 'pets\mikustage\pet.json', 'pets\mikustage\spritesheet.webp' -Destination $target

🛠️ Manual installation

Copy the complete pets\mikustage directory to:

%USERPROFILE%\.codex\pets\mikustage

The installed directory must contain both files:

%USERPROFILE%\.codex\pets\mikustage\pet.json
%USERPROFILE%\.codex\pets\mikustage\spritesheet.webp

Open Settings > Pets, select Refresh, and choose MikuStage. Wake it with /pet or the Wake Pet command if needed. Custom pets are stored locally and do not automatically sync to the web app.

🗑️ Uninstall

Close Codex and remove:

%USERPROFILE%\.codex\pets\mikustage

🗂️ Repository layout

.
├─ .gitattributes
├─ .gitignore
├─ README.md
├─ README.zh-cn.md
├─ pets/
│  └─ mikustage/
│     ├─ pet.json
│     └─ spritesheet.webp
└─ docs/
   ├─ assets/
   │  └─ mikustage-canonical.png
   └─ qa/
      ├─ chroma-despill-extended.json
      ├─ contact-sheet-extended.png
      ├─ direction-blind-pairs.png
      ├─ direction-blind-validation.json
      ├─ direction-blind-verdicts-1.json
      ├─ direction-blind-verdicts-2.json
      ├─ direction-blind-verdicts-3.json
      ├─ direction-blind-verdicts.json
      ├─ direction-semantics.json
      ├─ final-visual-qa.txt
      ├─ look-continuity.json
      ├─ look-directions.png
      ├─ look-mechanics.md
      ├─ previews/
      │  ├─ failed.gif
      │  ├─ idle.gif
      │  ├─ jumping.gif
      │  ├─ review.gif
      │  ├─ running-left.gif
      │  ├─ running-right.gif
      │  ├─ running.gif
      │  ├─ waiting.gif
      │  └─ waving.gif
      ├─ repository-validation.json
      ├─ review.json
      ├─ standard-visual-qa.txt
      └─ validation-extended.json

The tmp/ directory and .venv/ are intentionally excluded from version control. Keep API keys and relay configuration only under tmp/private/; never commit them.

✅ Validation

The packaged WebP is RGBA, exactly 1536x2288, and declares spriteVersionNumber: 2. Deterministic v2 validation, chroma cleanup, three isolated blind-direction reviews, labeled direction semantics, continuity metrics, and final visual QA are retained under docs/qa/.