BlueGit

blue-star tribegen

Files

tribegen / web / docs / SPRITE_SYSTEM_REFERENCE.md

SPRITE_SYSTEM_REFERENCE.md

various fixes
timfa Tim · pushed by timfa · 9 months ago
49730f61 History
SPRITE_SYSTEM_REFERENCE.md 4.7 KiB Download Raw

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

ConditionModificationVisual Effect
vitality < 50applyInjuryMarkings()Red scars appear
Age = old or very_olddesaturateImage()Sprite becomes grayscale
will > 70addLeadershipMarkings()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
6Copies base sprite from assets to save folder and applies all transformations.
7Called 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
16Returns 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
23Returns 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
30Modifies 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```
52GET /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```
59GET /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
67const spriteUrl = `/tribegen/api/game/sprite?userId=${this.currentUser.id}&koboldId=${kobold.id}&age=${kobold.ageCategory}`;
68const img = document.createElement('img');
69img.src = spriteUrl;
70img.alt = 'Kobold sprite';
71container.appendChild(img);
72```
73
74## File Structure
75
76```
77Save Folder Location:
78/data/saves/{userId}/kobolds/{koboldId}/sprites/
79
80Sprite 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
901. Modify `transformSprite()` method in Kobold.php
912. Add new helper method (e.g., `applyCustomEffect()`)
923. Call it from `transformSprite()`
934. No frontend changes needed - automatic on next sprite render
94
95### Change Desaturation Level
96Edit 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
105Edit 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
113Edit in `transformSprite()`:
114```php
115// Currently requires will > 70
116if ($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:
126ls -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:
133curl "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
1381. Load sprite in image viewer
1392. Compare with original in `/assets/sprites/`
1403. 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
162Note: "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*