--- description: 🐣 Hatch Pet Workflow — Quy trình tạo và đóng gói Codex Pet động từ ý tưởng hoặc hình ảnh alwaysApply: false category: workflow priority: medium --- triggers: - "keywords: hatch pet, create pet, custom pet, pet spritesheet, animated pet" - "context: pet creation, mascot animation, pet bundle" version: 1.0.0 track: - quick - method --- # /hatch-pet — Animated Companion Hatching Workflow Quy trình này giúp bạn (hoặc AI) tự động hóa việc tạo một Codex Pet động (spritesheet 8x9) từ ý tưởng, ảnh tham chiếu hoặc grounding images. --- ## 📋 Hướng Dẫn Chuẩn Bị 1. **Thông tin cơ bản**: - **Tên Pet** (Name): Chọn tên ngắn gọn (ví dụ: `Dewey`, `BSOD`). - **Mô tả** (Description): Một câu mô tả tính cách. - **Chroma Key**: Màu nền tách (mặc định: `#00FF00` hoặc `#FF00FF`). - **Mẫu Thiết Kế**: Phong cách Vector 2D, nét vẽ viền đen dày, bóng đổ phẳng (Cel-shading). 2. **Folder Chạy Thử**: - Mọi tiến trình chạy sẽ được lưu trữ tại một thư mục tạm thời (staging run), ví dụ: `assets/pets/runs/`. --- ## ⚡ Các Bước Thực Hiện ### Bước 1: Chuẩn Bị Run Folder & Manifest Khởi tạo run folder và tạo danh sách các frame cần sinh (base và các trạng thái động như `idle`, `jumping`, `running-right`, `running-left`, `waving`, `failed`, `review`, `sleeping`, `eating`): ```bash python ~/.gemini/antigravity/skills/hatch-pet/scripts/prepare_pet_run.py \ --pet-name "" \ --description "" \ --reference "/path/to/reference.png" \ --output-dir "assets/pets/runs/" \ --pet-notes "" \ --style-notes "smooth vector-2d, digital chibi mascot, bold outline, cel-shading" ``` ### Bước 2: Sinh Ảnh Base (Mẫu) AI sẽ sử dụng file prompt được sinh ra tại `assets/pets/runs//prompts/base.txt` kết hợp công cụ `$imagegen` để tạo ảnh mẫu ban đầu. Sau khi ảnh mẫu được sinh, record kết quả: ```bash python ~/.gemini/antigravity/skills/hatch-pet/scripts/record_imagegen_result.py \ --run-dir "assets/pets/runs/" \ --job-id base \ --source "/path/to/generated-base.png" ``` ### Bước 3: Sinh Các Dãy Trạng Thái Động (Row Strips) Với mỗi trạng thái động còn lại, AI chạy subagents song song sử dụng hướng dẫn layout guide và file prompt mẫu tương ứng. Sau khi nhận được ảnh strip thô từ subagent: ```bash python ~/.gemini/antigravity/skills/hatch-pet/scripts/record_imagegen_result.py \ --run-dir "assets/pets/runs/" \ --job-id \ --source "/path/to/generated-strip.png" ``` *Mẹo*: Với `running-left`, nếu pet có tính đối xứng cao, có thể tạo nhanh bằng cách lật gương từ `running-right`: ```bash python ~/.gemini/antigravity/skills/hatch-pet/scripts/derive_running_left_from_running_right.py \ --run-dir "assets/pets/runs/" \ --confirm-appropriate-mirror \ --decision-note "Pet is symmetrical and has no text/directional lighting" ``` ### Bước 4: Ghép Ảnh Atlas & Validate Sau khi tất cả trạng thái đã được record, tiến hành trích xuất frame nhỏ (`192x208`), ghép thành atlas tổng hợp (`1536x1872`), validate hình học và tạo video preview QA: ```bash python ~/.gemini/antigravity/skills/hatch-pet/scripts/finalize_pet_run.py \ --run-dir "assets/pets/runs/" ``` ### Bước 5: Khử Viền Màu Nền (Chroma Edge Despill) Nếu ảnh spritesheet xuất hiện viền hồng hoặc xanh lá (fringe) do tách nền tự động, thực hiện chạy công cụ khử viền: ```bash # 1. Chạy dry-run kiểm tra số lượng file python ~/.gemini/antigravity/skills/hatch-pet/scripts/clean_chroma_edges.py \ "assets/pets/runs//frames" --edge-despill # 2. Áp dụng sửa đổi trực tiếp lên các frame python ~/.gemini/antigravity/skills/hatch-pet/scripts/clean_chroma_edges.py \ "assets/pets/runs//frames" --edge-despill --apply # 3. Ghép lại Atlas từ các frame đã làm sạch python ~/.gemini/antigravity/skills/hatch-pet/scripts/compose_atlas.py \ --frames-root "assets/pets/runs//frames" \ --output "assets/pets/runs//final/spritesheet.png" \ --webp-output "assets/pets/runs//final/spritesheet.webp" ``` ### Bước 6: Đóng Gói (Package & Promote) Chuyển pet đã được kiểm duyệt và làm sạch vào thư mục chính thức của ứng dụng: - Sao chép `spritesheet.webp` và `pet.json` sang `assets/pets//` - Cập nhật file manifest của game/app. - Xóa dọn dẹp các thư mục staging run tạm để giữ sạch repository. --- ## 🔍 QA Checklist - [ ] Spritesheet có kích thước chuẩn `1536x1872`, định dạng WebP/PNG có alpha channel. - [ ] Các cell trống trong grid phải hoàn toàn trong suốt. - [ ] Nét vẽ, màu sắc, chi tiết của pet đồng nhất trên tất cả 9 hàng trạng thái. - [ ] Video preview trong `qa/videos/*.mp4` chạy mượt mà, không bị rung giật hoặc lệch trục. - [ ] Không chứa các hiệu ứng lơ lửng, shadow tách rời hay bụi mù xung quanh. - [ ] Không có viền màu xanh lá hoặc hồng trên nền tối (test qua contact sheet).