# 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.