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().
// 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.
$kobold->getAgeSpriteName(); // Returns: "egg", "baby", "adult", or "old"
getSpritePath() - Public
Returns the full path to the kobold's current sprite file.
$kobold->getSpritePath(); // Returns: "/data/saves/{userId}/kobolds/{koboldId}/sprites/adult.png"
transformSprite() - Private
Modifies the sprite based on kobold stats using PHP GD library.
// 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
// 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():
// 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():
// 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():
// Currently requires will > 70
if ($this->getStat('will') > 70) {
$this->addLeadershipMarkings($image);
}
Debugging
Verify Sprite Created
# 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
# 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
$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
Source
| 1 | # Sprite System Quick Reference |
| 2 | |
| 3 | ## Key Methods in Kobold.php |
| 4 | |
| 5 | ### `initializeSprite()` - Private |
| 6 | Copies base sprite from assets to save folder and applies all transformations. |
| 7 | Called automatically during `Kobold::generate()`. |
| 8 | |
| 9 | ```php |
| 10 | // Copies: /assets/sprites/{morph}/{age}.png |
| 11 | // → /data/saves/{userId}/kobolds/{koboldId}/sprites/{age}.png |
| 12 | // Then applies transformations based on stats |
| 13 | ``` |
| 14 | |
| 15 | ### `getAgeSpriteName()` - Public |
| 16 | Returns the sprite filename for the kobold's current age category. |
| 17 | |
| 18 | ```php |
| 19 | $kobold->getAgeSpriteName(); // Returns: "egg", "baby", "adult", or "old" |
| 20 | ``` |
| 21 | |
| 22 | ### `getSpritePath()` - Public |
| 23 | Returns the full path to the kobold's current sprite file. |
| 24 | |
| 25 | ```php |
| 26 | $kobold->getSpritePath(); // Returns: "/data/saves/{userId}/kobolds/{koboldId}/sprites/adult.png" |
| 27 | ``` |
| 28 | |
| 29 | ### `transformSprite()` - Private |
| 30 | Modifies the sprite based on kobold stats using PHP GD library. |
| 31 | |
| 32 | ```php |
| 33 | // Called by initializeSprite() |
| 34 | // Applies: |
| 35 | // - Injury scars if vitality < 50 |
| 36 | // - Age desaturation if old/very_old |
| 37 | // - Leadership crown if will > 70 |
| 38 | ``` |
| 39 | |
| 40 | ## Image Transformation Rules |
| 41 | |
| 42 | | Condition | Modification | Visual Effect | |
| 43 | |-----------|--------------|---------------| |
| 44 | | vitality < 50 | applyInjuryMarkings() | Red scars appear | |
| 45 | | Age = old or very_old | desaturateImage() | Sprite becomes grayscale | |
| 46 | | will > 70 | addLeadershipMarkings() | Gold crown appears | |
| 47 | |
| 48 | ## API Endpoint |
| 49 | |
| 50 | ### Serve Sprite Image |
| 51 | ``` |
| 52 | GET /tribegen/api/game/sprite?userId={userId}&koboldId={koboldId}&age={ageCategory} |
| 53 | ``` |
| 54 | |
| 55 | **Response:** PNG image file (Content-Type: image/png) |
| 56 | |
| 57 | **Example:** |
| 58 | ``` |
| 59 | GET /tribegen/api/game/sprite?userId=user123&koboldId=kob_abc123&age=adult |
| 60 | ``` |
| 61 | |
| 62 | ## Frontend Usage |
| 63 | |
| 64 | ### Display Kobold Sprite |
| 65 | ```javascript |
| 66 | // In displayKobolds() method |
| 67 | const spriteUrl = `/tribegen/api/game/sprite?userId=${this.currentUser.id}&koboldId=${kobold.id}&age=${kobold.ageCategory}`; |
| 68 | const img = document.createElement('img'); |
| 69 | img.src = spriteUrl; |
| 70 | img.alt = 'Kobold sprite'; |
| 71 | container.appendChild(img); |
| 72 | ``` |
| 73 | |
| 74 | ## File Structure |
| 75 | |
| 76 | ``` |
| 77 | Save Folder Location: |
| 78 | /data/saves/{userId}/kobolds/{koboldId}/sprites/ |
| 79 | |
| 80 | Sprite Files per Kobold: |
| 81 | ├── egg.png (Age < 0) |
| 82 | ├── baby.png (Age 0-3) |
| 83 | ├── adult.png (Age 4-34, 35-59) |
| 84 | └── old.png (Age 60+) |
| 85 | ``` |
| 86 | |
| 87 | ## Common Tasks |
| 88 | |
| 89 | ### Add New Visual Effect |
| 90 | 1. Modify `transformSprite()` method in Kobold.php |
| 91 | 2. Add new helper method (e.g., `applyCustomEffect()`) |
| 92 | 3. Call it from `transformSprite()` |
| 93 | 4. No frontend changes needed - automatic on next sprite render |
| 94 | |
| 95 | ### Change Desaturation Level |
| 96 | Edit in `desaturateImage()`: |
| 97 | ```php |
| 98 | // Currently 60% desaturated (40% original, 60% grayscale) |
| 99 | $newR = intval($r * 0.4 + $gray * 0.6); |
| 100 | // Change to different ratio (e.g., 70% desaturated): |
| 101 | $newR = intval($r * 0.3 + $gray * 0.7); |
| 102 | ``` |
| 103 | |
| 104 | ### Adjust Injury Scar Count |
| 105 | Edit in `applyInjuryMarkings()`: |
| 106 | ```php |
| 107 | // Currently: (50 - vitality) / 10 + 1, max 5 scars |
| 108 | $scarCount = intval((50 - $vitalityStat) / 10) + 1; |
| 109 | $scarCount = min(5, $scarCount); // Change 5 to different max |
| 110 | ``` |
| 111 | |
| 112 | ### Change Leadership Requirement |
| 113 | Edit in `transformSprite()`: |
| 114 | ```php |
| 115 | // Currently requires will > 70 |
| 116 | if ($this->getStat('will') > 70) { |
| 117 | $this->addLeadershipMarkings($image); |
| 118 | } |
| 119 | ``` |
| 120 | |
| 121 | ## Debugging |
| 122 | |
| 123 | ### Verify Sprite Created |
| 124 | ```bash |
| 125 | # Check if sprite files exist for kobold: |
| 126 | ls -la /data/saves/{userId}/kobolds/{koboldId}/sprites/ |
| 127 | # Should show: egg.png, baby.png, adult.png, old.png |
| 128 | ``` |
| 129 | |
| 130 | ### Check API Endpoint |
| 131 | ```bash |
| 132 | # Test sprite endpoint directly: |
| 133 | curl "http://localhost/tribegen/api/game/sprite?userId=user123&koboldId=kob_abc&age=adult" -o test.png |
| 134 | # Should return valid PNG file |
| 135 | ``` |
| 136 | |
| 137 | ### Inspect Sprite Modifications |
| 138 | 1. Load sprite in image viewer |
| 139 | 2. Compare with original in `/assets/sprites/` |
| 140 | 3. Look for: |
| 141 | - Red lines (injury scars) |
| 142 | - Grayscale tint (age) |
| 143 | - Gold crown at top (leadership) |
| 144 | |
| 145 | ## Performance Notes |
| 146 | |
| 147 | - Sprite copy: ~10-50ms per kobold (depends on image size) |
| 148 | - Image modification: ~50-200ms per kobold (GD library pixel operations) |
| 149 | - Total generation time per kobold: ~100-300ms |
| 150 | - API serving: <10ms with caching (1 hour) |
| 151 | |
| 152 | ## Age Category Reference |
| 153 | |
| 154 | ```php |
| 155 | $kobold->getAgeCategory() returns: |
| 156 | - "egg" (age < 0) |
| 157 | - "baby" (age 0-3) |
| 158 | - "young" (age 4-34) |
| 159 | - "adult" (age 35-59) |
| 160 | - "very_old" (age 60+) |
| 161 | |
| 162 | Note: "young" and "adult" both use adult.png sprite |
| 163 | ``` |
| 164 | |
| 165 | ## Dependencies |
| 166 | |
| 167 | - PHP GD Library (for image manipulation) |
| 168 | - SaveManager class (for directory handling) |
| 169 | - Kobold class stats system (for transformation conditions) |
| 170 | |
| 171 | ## Related Classes |
| 172 | |
| 173 | - **SaveManager** - Handles file paths and directory creation |
| 174 | - **Tribe** - Contains collection of kobolds |
| 175 | - **GameHelper** - Has age category mapping (legacy, can be deprecated) |
| 176 | |
| 177 | --- |
| 178 | |
| 179 | *Last Updated: [Current Date]* |
| 180 | *For full documentation, see SPRITE_REFACTORING_SUMMARY.md* |