novafarma/MASTER_ANIMATION_GUIDE.md

# 🎬 MASTER ANIMATION GUIDE - STYLE 32

**Agent, slike v MASTER_REFS so zaklenjene.**  
**Zdaj začni z izdelavo animacijskih listov (Spritesheets).**  
**Vsaka animacija mora striktno upoštevati ta pravila:**

---

## 1️⃣ TEHNIČNI FORMAT (Stardew Valley Standard):

### **Grid Specs:**
- **Size:** 64×64 pixels per sprite frame
- **Background:** Pure Chroma Green (#00FF00)
- **File format:** PNG with alpha channel
- **Naming:** `[character]_[animation]_[direction]_[frame].png`

### **Directions:**
- **4-way movement:** Down, Up, Right, (Left = mirror Right)
- **Front-facing (Down):** Main reference view
- **Back-facing (Up):** Hair/back visible
- **Right-facing:** Profile view
- **Left-facing:** ⚠️ **MIRROR RIGHT** (don't generate separately!)

### **Frame Organization:**
```
Spritesheet layout (horizontal strip):
[Frame 1] [Frame 2] [Frame 3] [Frame 4] [Frame 5] [Frame 6]
```

---

## 2️⃣ SEZNAM OSNOVNIH ANIMACIJ:

### **ALL CHARACTERS Need:**

#### **A. IDLE (Mirovanje) - 4 frames**
**Purpose:** Character standing still, breathing  
**Duration:** Loop seamlessly  

**Frame breakdown:**
1. **Frame 1:** Neutral stance, start of breath IN
2. **Frame 2:** Slight chest rise, dreadlocks sway RIGHT
3. **Frame 3:** Peak breath, hold
4. **Frame 4:** Exhale, dreadlocks sway LEFT (return to Frame 1)

**Key details:**
- Dreadlocks (Kai, Gronk) must sway gently (2-3px movement)
- Body barely moves (subtle breathing only)
- Arms relaxed at sides
- Loop: 1→2→3→4→1 (infinite)

---

#### **B. WALK (Hoja) - 6 frames**
**Purpose:** Normal walking speed  
**Style:** Classic "hop-step" cozy RPG  

**Frame breakdown:**
1. **Frame 1:** Contact (left foot forward, touching ground)
2. **Frame 2:** Down (weight shifts, body lowers slightly)
3. **Frame 3:** Passing (both feet together, mid-stride)
4. **Frame 4:** Up (body lifts, slight hop, right foot forward)
5. **Frame 5:** Contact (right foot forward, touching ground)
6. **Frame 6:** Return transition (back to Frame 1 position)

**Key details:**
- **HOP motion:** Body must lift slightly in air (Frame 4)
- **Dreadlocks:** Bounce UP när hop, DOWN när contact
- **Arms:** Swing opposite to legs (left arm forward when right leg forward)
- **Speed:** 10 FPS playback

---

#### **C. WORK (Delo) - 4-6 frames**
**Purpose:** Using tools (axe, pickaxe, hoe)  
**Style:** Kinetic energy, impactful  

**Frame breakdown (example: Axe chop):**
1. **Frame 1:** Wind-up (axe behind head, body tension)
2. **Frame 2:** Mid-swing (axe arc, motion blur on outlines)
3. **Frame 3:** **IMPACT** (freeze frame, axe hits, screen shake cue)
4. **Frame 4:** Follow-through (axe embedded, body relaxes)
5. **Frame 5:** Pull back (axe lifts)
6. **Frame 6:** Return to idle stance

**Key details:**
- **Thick black outlines (4-5px) "stretch" during swing** (motion blur effect)
- Impact frame (3) should have visual emphasis (stars, wood chips as VFX)
- Different tools = different arcs (pickaxe = overhead, hoe = downward)

---

#### **D. TRANSFORM (Preobrazba - Zombies only) - 4 frames**
**Purpose:** Zombie changes worker role  
**Style:** Quick "poof" cloud  

**Frame breakdown:**
1. **Frame 1:** Zombie idle stance (before)
2. **Frame 2:** "Poof" cloud appears (covers zombie completely)
3. **Frame 3:** Cloud at peak (zombie silhouette changing inside)
4. **Frame 4:** Cloud dissipates, zombie in new outfit (after)

**Poof cloud details:**
- Pastel smoke/dust color with dark gothic edges
- Completely obscures zombie during transformation
- Should be separate VFX layer (can overlay on any zombie)

---

## 3️⃣ STYLE 32 SPECIFICS:

### **Movement Rules:**

**✅ DO:**
- **Sharp, clear movements** (roguelike clarity)
- **Distinct poses** each frame (no in-betweens)
- **Flat color fills** stay clean (NO blurring edges)
- **Thick outlines** remain 4-5px throughout
- **Hop motion** for walk (classic cozy RPG feel)

**❌ DON'T:**
- No soft blurs or gradients
- No pixel confusion (muddy colors)
- No smooth tweening (motion should be choppy/charming)
- No outline thickness changes (keep 4-5px)

---

### **Eye Rules:**

**NORMAL (alive, active):**
- Eyes stay **WITH PUPILS** (like Kai reference - colored eyes)
- Pupils can shift slightly for direction changes
- **Example:** Kai looking down = pupils visible, centered

**SPECIAL STATES:**
- **DEAD:** X_X eyes (cross marks)
- **STUNNED:** Spiral eyes @_@
- **SLEEPING:** Closed eyes (horizontal lines)

**NOT "empty cult eyes" - Style 32 HAS PUPILS!** ✅

---

### **Dreadlock Physics:**

**Kai & Gronk have dreadlocks = IMPORTANT!**

**Rules:**
- Dreadlocks always lag behind head movement (delayed follow)
- **Jump/hop:** Dreads fly UP (gravity delayed)
- **Land:** Dreads fall DOWN (bounce)
- **Turn:** Dreads swing in opposite direction (momentum)
- **Idle:** Gentle side-to-side sway (breathing motion)

**Amount of movement:**
- Idle: 2-3px sway
- Walk: 5-8px swing
- Run: 10-15px dramatic swing
- Impact: Full swing 20px+

---

## 4️⃣ SHRANJEVANJE IN POTRJEVANJE:

### **File Structure:**

```
/assets/animations/
├── kai/
│   ├── idle_down.png       (4 frames horizontal strip)
│   ├── idle_up.png
│   ├── idle_right.png      (left = mirror this!)
│   ├── walk_down.png       (6 frames)
│   ├── walk_up.png
│   ├── walk_right.png
│   ├── work_axe.png        (6 frames)
│   ├── work_pickaxe.png
│   └── work_hoe.png
│
├── gronk/
│   ├── idle_front.png      (only front view for companion)
│   ├── walk_down.png
│   └── vape_exhale.png
│
├── ana/
│   ├── idle_front.png
│   └── portraits.png       (3 emotions side-by-side)
│
├── susi/
│   ├── idle_side.png
│   └── walk_side.png
│
└── zombiji/
    ├── gardener/
    │   ├── idle_front.png
    │   ├── walk_down.png
    │   └── work_till.png
    ├── miner/
    ├── lumberjack/
    ├── scavenger/
    └── poof_transform.png  (shared VFX)
```

---

### **Quality Checklist (Before ✅):**

**Per animation, verify:**

**Visual Match:**
- [ ] Colors match MASTER_REFS exactly (eyedropper test)
- [ ] Dreadlock color identical (Kai green, Gronk pink)
- [ ] Outline thickness 4-5px consistent
- [ ] Eyes have pupils (colored, like Kai)
- [ ] Chibi proportions maintained (big head, small body)
- [ ] Clothing details correct (patches, piercings, etc)

**Technical:**
- [ ] Chroma green background (#00FF00) clean
- [ ] 64×64px per frame
- [ ] Transparent PNG (alpha channel)
- [ ] No green fringing on edges
- [ ] Frames aligned properly (no jumping)

**Animation:**
- [ ] Loop smoothly (last frame → first frame seamless)
- [ ] Dreadlocks physics accurate (lag, bounce)
- [ ] Hop motion visible in walk (Frame 4 = up in air)
- [ ] Impact frame clear (tool work animations)

**When ALL checks pass → Add ✅ to filename and commit!**

---

## 5️⃣ GENERATION WORKFLOW:

### **Step-by-step per animation:**

**1. PREPARE:**
- Load MASTER_REF for character
- Extract exact colors (eyedropper)
- Note all details (piercings, patches, etc)

**2. GENERATE FRAMES:**
- Generate Frame 1 (key pose)
- Verify against MASTER_REF
- If match ✅ → continue to Frame 2
- If mismatch ❌ → regenerate Frame 1
- Repeat for all frames

**3. ASSEMBLE SPRITESHEET:**
- Combine frames into horizontal strip
- Verify spacing (64px per frame)
- Check alignment (no wobble)
- Test loop (last → first seamless?)

**4. SAVE & MARK:**
- Save to correct folder
- Add ✅ to commit message
- Update production checklist

---

## 6️⃣ SPECIAL NOTES PER CHARACTER:

### **KAI:**
- Green dreadlocks (exact shade from ref_kai.png)
- Multiple piercings visible in ALL frames
- Torn hoodie with patches
- Backpack visible from behind
- **Most complex** - do this character FIRST to set standard!

### **GRONK:**
- Pink dreadlocks (exact shade from ref_gronk.png)
- Pastel green orc skin
- **ALWAYS holding vape pen** (not cigarette!)
- Wide baggy shirt (loose fit)
- **ONLY 2 ARMS** (common mistake - verify!)

### **ANA:**
- **TWIN of Kai** (similar face structure!)
- Pink/magenta hair (not dreadlocks)
- Tactical vest always visible
- Less animations than Kai (only idle + portraits for demo)

### **SUSI:**
- Dachshund-shaped (long body, short legs)
- Black & orange coloring
- Pink collar always visible
- Cute hop for walk (exaggerated chibi motion)

### **ZOMBIES:**
- ALL use ref_zombie.png as base face/body
- ONLY outfit changes between roles
- Matted dirty dreadlocks on ALL zombie variants
- Gray-green decayed skin (consistent tone)
- Shambling walk (slower, heavier than alive characters)

---

## 7️⃣ PRODUCTION START ORDER:

**Priority sequence (from easiest to hardest):**

1. **✅ SUSI** (simplest, 2 animations) - Practice/warm-up
2. **✅ ANA** (simple, mostly static) - Build confidence  
3. **✅ GRONK** (companion, 3 animations) - Moderate complexity
4. **✅ KAI** (main character, MOST animations) - Full production
5. **✅ ZOMBIE ROLES** (modular system, 4 roles) - Final push

**Per character:**
- Start with IDLE (establish baseline)
- Then WALK (verify motion works)
- Then specialized (WORK, VAPE, etc)

---

## 8️⃣ TROUBLESHOOTING:

**Common issues & fixes:**

❌ **Problem:** Dreadlocks don't move  
✅ **Fix:** Add 2-3px sway in idle, 5-8px in walk

❌ **Problem:** Walk looks like "slide"  
✅ **Fix:** Add hop motion (Frame 4 = body UP)

❌ **Problem:** Colors don't match reference  
✅ **Fix:** Use eyedropper on MASTER_REF, copy exact hex codes

❌ **Problem:** Outlines inconsistent thickness  
✅ **Fix:** Regenerate with "very thick black outlines 4-5px" in prompt

❌ **Problem:** Green fringing on edges  
✅ **Fix:** Ensure pure #00FF00 background, no anti-aliasing on edges

❌ **Problem:** Animation doesn't loop  
✅ **Fix:** Last frame must transition smoothly back to Frame 1

---

## ✅ FINAL CONFIRMATION:

**Agent, kada završiš svaki spritesheet:**

1. Verify against MASTER_REF (pixel-perfect check)
2. Test loop (play all frames, check seamless)
3. Save to `/assets/animations/[character]/`
4. Git commit with "✅ [Character] [Animation] COMPLETE"
5. Update DEMO_COMPLETE_ASSET_LIST.md checklist
6. Move to next animation

**When zie totale animacije za en character = DONE:**
- Mark character as ✅ in production tracker
- Celebrate! 🎉
- Move to next character

---

## 🎯 SUCCESS CRITERIA:

**Demo is shippable when ALL these have ✅:**

- [ ] Susi (idle, walk)
- [ ] Ana (idle, portraits)
- [ ] Gronk (idle, walk, vape)
- [ ] Kai (idle, walk, work×3)
- [ ] Zombies (4 roles: idle, walk, work each)
- [ ] Poof transform effect (shared VFX)

**When ALL ✅ → DEMO ANIMATIONS COMPLETE!** 🎉🎮

---

**Ready to start with SUSI (warmup character)?** 🦖✨