# TribeGen Sprite System Refactoring - Implementation Summary
## Overview
This refactoring restructures TribeGen's sprite handling system to make the save folder the source of truth for all kobold sprite images. Previously, sprites were loaded on-demand from the `/assets/sprites/` directory. Now, base sprites are copied to the save folder during kobold generation and modified there, enabling persistent visual changes without altering the asset directory.
## Architecture Change
### Before
```
Assets Directory (read-only)
└── /assets/sprites/{morph}/{age}.png
└── Loaded on every render via GameHelper::getAgeSprite()
```
**Problem**: Visual modifications (injuries, age effects, leadership marks) weren't persistent and asset directory remained static.
### After
```
Save Directory (primary source)
└── /data/saves/{userId}/kobolds/{koboldId}/sprites/
└── /{ageCategory}.png (modified copy from assets)
└── Applied transformations saved to file
└── Loaded on every render via API endpoint
└── SaveManager handles path creation
Assets Directory (initialization only)
└── /assets/sprites/{morph}/{age}.png
└── Only copied to save folder during generation
└── Never modified
```
**Benefits**:
1. **Persistence** - Visual modifications saved immediately to file
2. **Flexibility** - Future enhancements (scars, aging effects, leadership marks) stay in place
3. **Modularity** - Image logic isolated in Kobold class, not scattered in GameHelper
4. **Extensibility** - New visual effects only require modifying `transformSprite()` method
## Files Modified
### 1. [src/Classes/Kobold.php](src/Classes/Kobold.php)
**Changes:**
- Modified `generate()` method to call `initializeSprite()` on new kobolds
- Added `initializeSprite()` - Copies base sprite from assets to save folder and applies transformations
- Added `getAgeSpriteName()` - Maps age category to sprite filename
- Added `getSpritePath()` - Returns full path to kobold's sprite file
- Updated `transformSprite()` - Actual image modification using PHP GD library
- Added `applyInjuryMarkings()` - Draws red scars based on vitality stat
- Added `desaturateImage()` - Reduces color saturation for elderly kobolds
- Added `addLeadershipMarkings()` - Adds gold crown for high willpower kobolds
**Line Count Impact:**
- Added ~175 lines of sprite management code
- Removed old stub transformSprite() implementation
### 2. [src/api/game.php](src/api/game.php)
**Changes:**
- Added `/sprite` GET endpoint that serves kobold sprite images from save folder
- Returns PNG image with cache headers for performance
- Parameters: `userId`, `koboldId`, `age` (optional, defaults to current age category)
- Validates file existence before serving
**New Endpoint:**
```
GET /tribegen/api/game/sprite?userId={userId}&koboldId={koboldId}&age={ageCategory}
```
### 3. [public/js/app.js](public/js/app.js)
**Changes:**
- Updated `displayKobolds()` to use new sprite endpoint instead of static assets
- Changed from `
` to `
`
- Automatically passes userId, koboldId, and ageCategory to sprite API
## Implementation Details
### Sprite Generation Flow
```
Kobold::generate()
└── new Kobold(...)
└── initializeSprite()
├── Copy base sprite: assets → save folder
│ Source: /assets/sprites/{morph}/{ageSprite}.png
│ Dest: /data/saves/{userId}/kobolds/{koboldId}/sprites/{ageSprite}.png
│
└── transformSprite()
├── Load PNG from save folder
├── Apply transformations:
│ ├── If vitality < 50: applyInjuryMarkings()
│ ├── If age is old/very_old: desaturateImage()
│ └── If will > 70: addLeadershipMarkings()
└── Save modified image back to save folder
```
### Visual Modifications
1. **Injury Markings** (when vitality < 50)
- Number of scars calculated: `(50 - vitality) / 10 + 1` (max 5)
- Red lines drawn at random positions
- Simulates combat wounds
2. **Age Desaturation** (old/very_old category)
- Reduces color saturation by 60%
- Uses luminance formula for accurate grayscale conversion
- Makes elderly kobolds appear grayed with age
3. **Leadership Crown** (when will > 70)
- Gold crown drawn at top center of sprite
- Five-point crown shape using gold and dark gold colors
- Indicates strong willpower/leadership potential
### Directory Structure
```
/data/saves/
├── {userId}/
│ ├── saves/
│ │ └── {saveId}/
│ │ ├── tribe.json (Tribe data)
│ │ ├── kobolds.json (Kobold list)
│ │ └── items.json (Item inventory)
│ │
│ └── kobolds/
│ └── {koboldId}/
│ └── sprites/
│ ├── egg.png (Egg stage sprite)
│ ├── baby.png (Baby stage sprite)
│ ├── adult.png (Adult stage sprite - primary)
│ └── old.png (Elderly stage sprite)
```
### Age Category Mapping
```php
Age Range → Category → Sprite Name
< 0 → egg → egg.png
0-3 → baby → baby.png
4-34 → young → adult.png (uses adult sprite)
35-59 → adult → adult.png
60+ → very_old → old.png
```
## Technical Details
### PHP GD Library Usage
The implementation uses PHP GD library functions:
- `imagecreatefrompng()` - Load PNG image
- `imagecolorat()` - Read pixel color
- `imagecolorallocate()` - Allocate color
- `imagecolorallocatealpha()` - Allocate color with alpha
- `imageline()` - Draw lines (for scars and crown)
- `imagesetpixel()` - Set individual pixels (for desaturation)
- `imagepng()` - Save image back to file
- `imagedestroy()` - Clean up image resource
### SaveManager Integration
Uses existing SaveManager methods:
```php
$saveManager->getKoboldSpritePath($userId, $koboldId)
```
Returns `/data/saves/{userId}/kobolds/{koboldId}/sprites/` with automatic directory creation.
## Usage Examples
### Frontend - Display Kobold Sprite
```javascript
// Automatically handled in displayKobolds()
const spriteUrl = `/tribegen/api/game/sprite?userId=${userId}&koboldId=${koboldId}&age=${ageCategory}`;
const img = document.createElement('img');
img.src = spriteUrl;
img.alt = 'Kobold sprite';
```
### Backend - Generate Kobold with Sprite
```php
// On game creation, automatically copies and transforms sprites
$kobold = Kobold::generate($userId, $saveId);
// Sprite now exists at: /data/saves/{userId}/kobolds/{koboldId}/sprites/{age}.png
```
### Custom Transformations - Future Enhancement
```php
// To add new visual effects, modify transformSprite() only:
private function transformSprite() {
// ... existing code ...
// Add custom effect:
if ($this->someCondition) {
$this->newCustomEffect($image);
}
imagepng($image, $spritePath);
imagedestroy($image);
}
```
## Testing Checklist
- [ ] Kobold generation calls initializeSprite()
- [ ] Sprites copied from `/assets/sprites/` to save folder
- [ ] transformSprite() modifies images based on stats
- [ ] API endpoint `/sprite` serves PNG files correctly
- [ ] Frontend displays sprites from API endpoint
- [ ] Sprite modifications persist across page reloads
- [ ] Aging system updates sprite correctly
- [ ] Stats affect visual appearance (vitality → scars, will → crown)
- [ ] Injuries remain visible on saved sprites
## Performance Considerations
1. **Image Copy on Generation** - One-time cost during kobold creation
2. **Image Modification on Generation** - One-time cost using GD library
3. **API Caching** - HTTP cache headers set to 1 hour (`Cache-Control: public, max-age=3600`)
4. **Save Folder Storage** - Each kobold needs 4 PNG files (egg, baby, adult, old)
## Future Enhancements
1. **Dynamic Recoloring** - Tribe-specific color schemes for sprites
2. **Scar Persistence** - Track specific injury locations and draw detailed scars
3. **Breeding Effects** - Blend parent sprites into offspring
4. **Equipment Rendering** - Draw armor/weapons onto sprite
5. **Animation Frames** - Store multiple animation poses per age category
6. **Custom Morphs** - Generate new sprite morphs from existing images
## Backward Compatibility
- Old saves without sprites will generate them on first load
- GameHelper::getAgeSprite() remains available for reference but can be deprecated
- Asset directory unchanged - no breaking changes to image storage
- Database schema unchanged - pure architectural improvement
## Summary
This refactoring successfully implements a robust sprite management system that:
- Makes save folder the authoritative source for kobold visuals
- Enables persistent visual modifications without code changes
- Provides clean separation between asset initialization and transformation
- Sets foundation for future sprite enhancement features
- Maintains full backward compatibility with existing saves
The architecture now supports the game designer's vision of each kobold having a unique, persistent visual representation that evolves with their experiences.