# Sprite System Quick Reference

## Key Methods in Kobold.php

### `initializeSprite()` - Private
Copies base sprite from assets to save folder and applies all transformations.
Called automatically during `Kobold::generate()`.

```php
// Copies: /assets/sprites/{morph}/{age}.png 
//      → /data/saves/{userId}/kobolds/{koboldId}/sprites/{age}.png
// Then applies transformations based on stats
```

### `getAgeSpriteName()` - Public
Returns the sprite filename for the kobold's current age category.

```php
$kobold->getAgeSpriteName(); // Returns: "egg", "baby", "adult", or "old"
```

### `getSpritePath()` - Public
Returns the full path to the kobold's current sprite file.

```php
$kobold->getSpritePath(); // Returns: "/data/saves/{userId}/kobolds/{koboldId}/sprites/adult.png"
```

### `transformSprite()` - Private
Modifies the sprite based on kobold stats using PHP GD library.

```php
// Called by initializeSprite()
// Applies:
// - Injury scars if vitality < 50
// - Age desaturation if old/very_old
// - Leadership crown if will > 70
```

## Image Transformation Rules

| Condition | Modification | Visual Effect |
|-----------|--------------|---------------|
| vitality < 50 | applyInjuryMarkings() | Red scars appear |
| Age = old or very_old | desaturateImage() | Sprite becomes grayscale |
| will > 70 | addLeadershipMarkings() | Gold crown appears |

## API Endpoint

### Serve Sprite Image
```
GET /tribegen/api/game/sprite?userId={userId}&koboldId={koboldId}&age={ageCategory}
```

**Response:** PNG image file (Content-Type: image/png)

**Example:**
```
GET /tribegen/api/game/sprite?userId=user123&koboldId=kob_abc123&age=adult
```

## Frontend Usage

### Display Kobold Sprite
```javascript
// In displayKobolds() method
const spriteUrl = `/tribegen/api/game/sprite?userId=${this.currentUser.email}&koboldId=${kobold.id}&age=${kobold.ageCategory}`;
const img = document.createElement('img');
img.src = spriteUrl;
img.alt = 'Kobold sprite';
container.appendChild(img);
```

## File Structure

```
Save Folder Location:
/data/saves/{userId}/kobolds/{koboldId}/sprites/

Sprite Files per Kobold:
├── egg.png      (Age < 0)
├── baby.png     (Age 0-3)
├── adult.png    (Age 4-34, 35-59)
└── old.png      (Age 60+)
```

## Common Tasks

### Add New Visual Effect
1. Modify `transformSprite()` method in Kobold.php
2. Add new helper method (e.g., `applyCustomEffect()`)
3. Call it from `transformSprite()`
4. No frontend changes needed - automatic on next sprite render

### Change Desaturation Level
Edit in `desaturateImage()`:
```php
// Currently 60% desaturated (40% original, 60% grayscale)
$newR = intval($r * 0.4 + $gray * 0.6);
// Change to different ratio (e.g., 70% desaturated):
$newR = intval($r * 0.3 + $gray * 0.7);
```

### Adjust Injury Scar Count
Edit in `applyInjuryMarkings()`:
```php
// Currently: (50 - vitality) / 10 + 1, max 5 scars
$scarCount = intval((50 - $vitalityStat) / 10) + 1;
$scarCount = min(5, $scarCount); // Change 5 to different max
```

### Change Leadership Requirement
Edit in `transformSprite()`:
```php
// Currently requires will > 70
if ($this->getStat('will') > 70) {
    $this->addLeadershipMarkings($image);
}
```

## Debugging

### Verify Sprite Created
```bash
# Check if sprite files exist for kobold:
ls -la /data/saves/{userId}/kobolds/{koboldId}/sprites/
# Should show: egg.png, baby.png, adult.png, old.png
```

### Check API Endpoint
```bash
# Test sprite endpoint directly:
curl "http://localhost/tribegen/api/game/sprite?userId=user123&koboldId=kob_abc&age=adult" -o test.png
# Should return valid PNG file
```

### Inspect Sprite Modifications
1. Load sprite in image viewer
2. Compare with original in `/assets/sprites/`
3. Look for:
   - Red lines (injury scars)
   - Grayscale tint (age)
   - Gold crown at top (leadership)

## Performance Notes

- Sprite copy: ~10-50ms per kobold (depends on image size)
- Image modification: ~50-200ms per kobold (GD library pixel operations)
- Total generation time per kobold: ~100-300ms
- API serving: <10ms with caching (1 hour)

## Age Category Reference

```php
$kobold->getAgeCategory() returns:
- "egg"      (age < 0)
- "baby"     (age 0-3)
- "young"    (age 4-34)
- "adult"    (age 35-59)
- "very_old" (age 60+)

Note: "young" and "adult" both use adult.png sprite
```

## Dependencies

- PHP GD Library (for image manipulation)
- SaveManager class (for directory handling)
- Kobold class stats system (for transformation conditions)

## Related Classes

- **SaveManager** - Handles file paths and directory creation
- **Tribe** - Contains collection of kobolds
- **GameHelper** - Has age category mapping (legacy, can be deprecated)

---

*Last Updated: [Current Date]*
*For full documentation, see SPRITE_REFACTORING_SUMMARY.md*
