# 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.id}&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*