Sprite System Architecture Diagrams
Data Flow Diagram
┌─────────────────────────────────────────────────────────────────┐
│ SPRITE GENERATION FLOW │
└─────────────────────────────────────────────────────────────────┘
API Call: POST /tribegen/api/game/generation
│
├─> Tribe::create()
│ └─> Tribe::addKobold() x20
│
└─> Kobold::generate()
│
├─> new Kobold()
│ ├─ Assign ID, stats, age
│ └─ Initialize SaveManager
│
├─> $kobold->initializeSprite()
│ │
│ ├─> SaveManager::getKoboldSpritePath()
│ │ └─> Create /data/saves/{userId}/kobolds/{id}/sprites/
│ │
│ ├─> Copy base sprite
│ │ ├─ Source: /assets/sprites/{morph}/{age}.png
│ │ └─ Dest: /data/saves/{userId}/kobolds/{id}/sprites/{age}.png
│ │
│ └─> transformSprite()
│ │
│ ├─> imagecreatefrompng() [Load image]
│ │
│ ├─> if vitality < 50:
│ │ └─> applyInjuryMarkings()
│ │ └─> Draw red scar lines
│ │
│ ├─> if age category is old/very_old:
│ │ └─> desaturateImage()
│ │ └─> Reduce color saturation 60%
│ │
│ ├─> if will > 70:
│ │ └─> addLeadershipMarkings()
│ │ └─> Draw gold crown
│ │
│ └─> imagepng() [Save modified image]
│
└─> return $kobold [FULLY INITIALIZED]
┌─────────────────────────────────────────────────────────────────┐
│ SPRITE DISPLAY FLOW │
└─────────────────────────────────────────────────────────────────┘
Frontend: displayKobolds()
│
├─> Generate sprite URL:
│ /tribegen/api/game/sprite?userId={id}&koboldId={id}&age={age}
│
├─> Create <img> element
│ └─> img.src = URL
│
└─> Browser loads image
│
├─> GET /api/game/sprite
│ │
│ └─> Backend: game.php
│ │
│ ├─> Validate userId, koboldId
│ │
│ ├─> SaveManager::getKoboldSpritePath()
│ │ └─> /data/saves/{userId}/kobolds/{koboldId}/sprites/
│ │
│ ├─> Load file: {age}.png
│ │
│ ├─> Set headers:
│ │ ├─ Content-Type: image/png
│ │ └─ Cache-Control: public, max-age=3600
│ │
│ └─> readfile() [Send PNG to browser]
│
└─> Browser caches and displays image [1 hour TTL]
Directory Structure Diagram
TribeGen Project Root
│
├── /assets
│ └── /sprites [READ-ONLY SOURCE]
│ ├── /default
│ │ ├── egg.png [Original sprite]
│ │ ├── baby.png [Original sprite]
│ │ ├── adult.png [Original sprite]
│ │ └── old.png [Original sprite]
│ │
│ ├── /aggressive
│ │ ├── egg.png
│ │ ├── baby.png
│ │ ├── adult.png
│ │ └── old.png
│ │
│ └── [other morphs...]
│
├── /data
│ └── /saves [RUNTIME DATA - MODIFIED]
│ ├── /user1_id
│ │ ├── /saves
│ │ │ └── /save1_id
│ │ │ ├── tribe.json [Tribe metadata]
│ │ │ ├── kobolds.json [Kobold list]
│ │ │ └── items.json [Inventory]
│ │ │
│ │ └── /kobolds
│ │ ├── /kob_abc123
│ │ │ └── /sprites [MODIFIED COPIES]
│ │ │ ├── egg.png [MODIFIED with effects]
│ │ │ ├── baby.png [MODIFIED with effects]
│ │ │ ├── adult.png [MODIFIED with effects]
│ │ │ └── old.png [MODIFIED with effects]
│ │ │
│ │ ├── /kob_def456
│ │ │ └── /sprites
│ │ │ ├── egg.png
│ │ │ ├── baby.png
│ │ │ ├── adult.png
│ │ │ └── old.png
│ │ │
│ │ └── [more kobolds...]
│ │
│ └── /user2_id
│ └── [same structure as user1...]
│
├── /src
│ ├── /Classes
│ │ ├── Kobold.php [MODIFIED - sprite methods added]
│ │ ├── Tribe.php
│ │ ├── Item.php
│ │ └── NPC.php
│ │
│ ├── /api
│ │ └── game.php [MODIFIED - sprite endpoint added]
│ │
│ ├── /Utilities
│ │ └── GameHelper.php [Reference only - can be deprecated]
│ │
│ └── /System
│ └── SaveManager.php [Used for path handling]
│
└── /public
├── index.html
└── /js
└── app.js [MODIFIED - sprite URL generation]
Class Relationship Diagram
┌──────────────────────────────────────────────────────────────┐
│ Kobold Class │
├──────────────────────────────────────────────────────────────┤
│ Properties: │
│ - id, userId, saveId │
│ - name, age, stats[] │
│ - spriteMorph, saveManager (NEW) │
├──────────────────────────────────────────────────────────────┤
│ Sprite Methods (NEW): │
│ + generate() - static factory │
│ └─> initializeSprite() - PRIVATE │
│ + getAgeSpriteName() - maps age to filename │
│ + getSpritePath() - returns full sprite path │
│ - transformSprite() - applies visual effects │
│ ├─ applyInjuryMarkings() - draws scars │
│ ├─ desaturateImage() - grays elderly │
│ └─ addLeadershipMarkings() - adds crown │
│ │
│ Existing Methods (UNCHANGED): │
│ + getAge(), setAge(), incrementAge() │
│ + getAgeCategory() - returns age tier │
│ + getStat(), setStat(), checkStat() │
│ + fromArray(), toArray() │
│ + save(), getId(), getName(), etc. │
└──────────────────────────────────────────────────────────────┘
│
│ uses
↓
┌──────────────────────────────────────────────────────────────┐
│ SaveManager (Existing) │
├──────────────────────────────────────────────────────────────┤
│ Methods used by Sprite System: │
│ + getKoboldSpritePath($userId, $koboldId) │
│ └─> Creates: /data/saves/{userId}/kobolds/{id}/sprites/ │
│ └─> Returns path with trailing slash │
└──────────────────────────────────────────────────────────────┘
│
│ manages paths for
↓
┌──────────────────────────────────────────────────────────────┐
│ File System (PHP/GD) │
├──────────────────────────────────────────────────────────────┤
│ Operations: │
│ - copy($source, $dest) [Copy sprite from assets] │
│ - imagecreatefrompng() [Load PNG image] │
│ - imagecolorat() [Read pixel colors] │
│ - imageline() [Draw lines for scars/crown] │
│ - imagesetpixel() [Modify individual pixels] │
│ - imagepng() [Save modified image] │
│ - imagedestroy() [Free image resource] │
└──────────────────────────────────────────────────────────────┘
State Diagram - Kobold Sprite Lifecycle
┌─────────────────────────────────────────────────────────────┐
│ KOBOLD SPRITE LIFECYCLE │
└─────────────────────────────────────────────────────────────┘
1. INITIALIZATION
─────────────
Kobold::generate()
└─> state = "initializing"
├─> SaveManager creates /data/saves/{userId}/kobolds/{id}/sprites/
├─> Copy from: /assets/sprites/{morph}/{ageSprite}.png
├─> Paste to: /data/saves/{userId}/kobolds/{id}/sprites/
└─> state = "copied"
2. TRANSFORMATION
────────────────
transformSprite()
└─> state = "transforming"
├─> Load PNG file
├─> Check vitality < 50
│ └─> YES: applyInjuryMarkings() [RED SCARS]
├─> Check age category (old/very_old)
│ └─> YES: desaturateImage() [GRAYSCALE]
├─> Check will > 70
│ └─> YES: addLeadershipMarkings() [GOLD CROWN]
├─> Save PNG file
└─> state = "ready"
3. STORAGE
────────
File System
└─> state = "persisted"
└─> Files exist at:
/data/saves/{userId}/kobolds/{koboldId}/sprites/
├── egg.png [MODIFIED & SAVED]
├── baby.png [MODIFIED & SAVED]
├── adult.png [MODIFIED & SAVED]
└── old.png [MODIFIED & SAVED]
4. DISPLAY
───────
GET /api/game/sprite
└─> state = "serving"
├─> Validate parameters
├─> Load file from save folder
├─> Set HTTP headers
│ ├─ Content-Type: image/png
│ └─ Cache-Control: public, max-age=3600
├─> Send PNG to browser
└─> state = "displayed"
5. BROWSER CACHE
──────────────
Client Side
└─> state = "cached"
├─> First request: Download (10-50ms)
├─> Subsequent requests (within 1 hour): Cached (1-5ms)
└─> Cache expires: Request new image
STAT EFFECTS OVER TIME
──────────────────────
Age Progression:
Age 0-3 Age 4-34 Age 35-59 Age 60+
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ egg.png │→│ baby.png │→ │adult.png │→ │ old.png │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
[Color] [Color] [Color] [GRAYSCALE]
(desaturated)
Vitality Degradation:
High (80+) Medium (50-79) Low (<50)
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Clean │→ │ Some │→ │ Scarred │
│ Sprite │ │ Scars │ │ Sprite │
└─────────┘ └─────────┘ └─────────┘
(1-3 scars) (3-5 scars)
Will Progression:
Low (≤70) High (>70)
┌─────────┐ ┌─────────┐
│ No │→ │ CROWN │
│ Crown │ │ Visible │
└─────────┘ └─────────┘
API Endpoint Flow Diagram
Frontend Request
│
└─> GET /tribegen/api/game/sprite?userId=U1&koboldId=K1&age=adult
│
├─ Browser checks cache
│ └─> If cached: Use cached image (< 1 hour TTL)
│ └─> If not cached or expired: Continue to backend
│
└─> Backend Processing (game.php)
│
├─> Validate parameters
│ ├─> userId present? [Required]
│ ├─> koboldId present? [Required]
│ └─> age valid? [Optional, default='adult']
│
├─> Get sprite path
│ └─> SaveManager::getKoboldSpritePath($userId, $koboldId)
│ └─> /data/saves/{userId}/kobolds/{koboldId}/sprites/
│
├─> Build file path
│ └─> {spritePath}/{ageSprite}.png
│ └─> /data/saves/U1/kobolds/K1/sprites/adult.png
│
├─> Check file exists
│ ├─> YES: Continue to response
│ └─> NO: Return 404 error
│
├─> Set HTTP Headers
│ ├─ HTTP/1.1 200 OK
│ ├─ Content-Type: image/png
│ └─ Cache-Control: public, max-age=3600
│
├─> Send File
│ └─> readfile(/data/saves/U1/kobolds/K1/sprites/adult.png)
│
└─> Return to Browser
│
├─> Browser receives PNG binary data
├─> Browser stores in cache (1 hour)
└─> Browser renders <img> element
Transformation Decision Tree
transformSprite()
│
├─ Is image loaded successfully?
│ │
│ ├─ NO → Return (exit early)
│ │
│ └─ YES → Continue
│ │
│ ├─ [Check Vitality]
│ │ │
│ │ └─ vitality < 50?
│ │ │
│ │ ├─ YES → applyInjuryMarkings()
│ │ │ └─ Draw (50 - vitality) / 10 + 1 scars (max 5)
│ │ │
│ │ └─ NO → Skip injury marks
│ │
│ ├─ [Check Age]
│ │ │
│ │ └─ Age category is old or very_old?
│ │ │
│ │ ├─ YES → desaturateImage()
│ │ │ └─ Reduce saturation 60% (0.4 original + 0.6 gray)
│ │ │
│ │ └─ NO → Skip age effect
│ │
│ ├─ [Check Will]
│ │ │
│ │ └─ will > 70?
│ │ │
│ │ ├─ YES → addLeadershipMarkings()
│ │ │ └─ Draw gold crown at top center
│ │ │
│ │ └─ NO → Skip leadership mark
│ │
│ └─ Save modified image
│ └─ imagepng($image, $spritePath)
│ └─ Overwrites original sprite file in save folder
---
These diagrams provide visual understanding of the sprite system architecture and data flows.
Source
| 1 | # Sprite System Architecture Diagrams |
| 2 | |
| 3 | ## Data Flow Diagram |
| 4 | |
| 5 | ``` |
| 6 | ┌─────────────────────────────────────────────────────────────────┐ |
| 7 | │ SPRITE GENERATION FLOW │ |
| 8 | └─────────────────────────────────────────────────────────────────┘ |
| 9 | |
| 10 | API Call: POST /tribegen/api/game/generation |
| 11 | │ |
| 12 | ├─> Tribe::create() |
| 13 | │ └─> Tribe::addKobold() x20 |
| 14 | │ |
| 15 | └─> Kobold::generate() |
| 16 | │ |
| 17 | ├─> new Kobold() |
| 18 | │ ├─ Assign ID, stats, age |
| 19 | │ └─ Initialize SaveManager |
| 20 | │ |
| 21 | ├─> $kobold->initializeSprite() |
| 22 | │ │ |
| 23 | │ ├─> SaveManager::getKoboldSpritePath() |
| 24 | │ │ └─> Create /data/saves/{userId}/kobolds/{id}/sprites/ |
| 25 | │ │ |
| 26 | │ ├─> Copy base sprite |
| 27 | │ │ ├─ Source: /assets/sprites/{morph}/{age}.png |
| 28 | │ │ └─ Dest: /data/saves/{userId}/kobolds/{id}/sprites/{age}.png |
| 29 | │ │ |
| 30 | │ └─> transformSprite() |
| 31 | │ │ |
| 32 | │ ├─> imagecreatefrompng() [Load image] |
| 33 | │ │ |
| 34 | │ ├─> if vitality < 50: |
| 35 | │ │ └─> applyInjuryMarkings() |
| 36 | │ │ └─> Draw red scar lines |
| 37 | │ │ |
| 38 | │ ├─> if age category is old/very_old: |
| 39 | │ │ └─> desaturateImage() |
| 40 | │ │ └─> Reduce color saturation 60% |
| 41 | │ │ |
| 42 | │ ├─> if will > 70: |
| 43 | │ │ └─> addLeadershipMarkings() |
| 44 | │ │ └─> Draw gold crown |
| 45 | │ │ |
| 46 | │ └─> imagepng() [Save modified image] |
| 47 | │ |
| 48 | └─> return $kobold [FULLY INITIALIZED] |
| 49 | |
| 50 | |
| 51 | ┌─────────────────────────────────────────────────────────────────┐ |
| 52 | │ SPRITE DISPLAY FLOW │ |
| 53 | └─────────────────────────────────────────────────────────────────┘ |
| 54 | |
| 55 | Frontend: displayKobolds() |
| 56 | │ |
| 57 | ├─> Generate sprite URL: |
| 58 | │ /tribegen/api/game/sprite?userId={id}&koboldId={id}&age={age} |
| 59 | │ |
| 60 | ├─> Create <img> element |
| 61 | │ └─> img.src = URL |
| 62 | │ |
| 63 | └─> Browser loads image |
| 64 | │ |
| 65 | ├─> GET /api/game/sprite |
| 66 | │ │ |
| 67 | │ └─> Backend: game.php |
| 68 | │ │ |
| 69 | │ ├─> Validate userId, koboldId |
| 70 | │ │ |
| 71 | │ ├─> SaveManager::getKoboldSpritePath() |
| 72 | │ │ └─> /data/saves/{userId}/kobolds/{koboldId}/sprites/ |
| 73 | │ │ |
| 74 | │ ├─> Load file: {age}.png |
| 75 | │ │ |
| 76 | │ ├─> Set headers: |
| 77 | │ │ ├─ Content-Type: image/png |
| 78 | │ │ └─ Cache-Control: public, max-age=3600 |
| 79 | │ │ |
| 80 | │ └─> readfile() [Send PNG to browser] |
| 81 | │ |
| 82 | └─> Browser caches and displays image [1 hour TTL] |
| 83 | ``` |
| 84 | |
| 85 | ## Directory Structure Diagram |
| 86 | |
| 87 | ``` |
| 88 | TribeGen Project Root |
| 89 | │ |
| 90 | ├── /assets |
| 91 | │ └── /sprites [READ-ONLY SOURCE] |
| 92 | │ ├── /default |
| 93 | │ │ ├── egg.png [Original sprite] |
| 94 | │ │ ├── baby.png [Original sprite] |
| 95 | │ │ ├── adult.png [Original sprite] |
| 96 | │ │ └── old.png [Original sprite] |
| 97 | │ │ |
| 98 | │ ├── /aggressive |
| 99 | │ │ ├── egg.png |
| 100 | │ │ ├── baby.png |
| 101 | │ │ ├── adult.png |
| 102 | │ │ └── old.png |
| 103 | │ │ |
| 104 | │ └── [other morphs...] |
| 105 | │ |
| 106 | ├── /data |
| 107 | │ └── /saves [RUNTIME DATA - MODIFIED] |
| 108 | │ ├── /user1_id |
| 109 | │ │ ├── /saves |
| 110 | │ │ │ └── /save1_id |
| 111 | │ │ │ ├── tribe.json [Tribe metadata] |
| 112 | │ │ │ ├── kobolds.json [Kobold list] |
| 113 | │ │ │ └── items.json [Inventory] |
| 114 | │ │ │ |
| 115 | │ │ └── /kobolds |
| 116 | │ │ ├── /kob_abc123 |
| 117 | │ │ │ └── /sprites [MODIFIED COPIES] |
| 118 | │ │ │ ├── egg.png [MODIFIED with effects] |
| 119 | │ │ │ ├── baby.png [MODIFIED with effects] |
| 120 | │ │ │ ├── adult.png [MODIFIED with effects] |
| 121 | │ │ │ └── old.png [MODIFIED with effects] |
| 122 | │ │ │ |
| 123 | │ │ ├── /kob_def456 |
| 124 | │ │ │ └── /sprites |
| 125 | │ │ │ ├── egg.png |
| 126 | │ │ │ ├── baby.png |
| 127 | │ │ │ ├── adult.png |
| 128 | │ │ │ └── old.png |
| 129 | │ │ │ |
| 130 | │ │ └── [more kobolds...] |
| 131 | │ │ |
| 132 | │ └── /user2_id |
| 133 | │ └── [same structure as user1...] |
| 134 | │ |
| 135 | ├── /src |
| 136 | │ ├── /Classes |
| 137 | │ │ ├── Kobold.php [MODIFIED - sprite methods added] |
| 138 | │ │ ├── Tribe.php |
| 139 | │ │ ├── Item.php |
| 140 | │ │ └── NPC.php |
| 141 | │ │ |
| 142 | │ ├── /api |
| 143 | │ │ └── game.php [MODIFIED - sprite endpoint added] |
| 144 | │ │ |
| 145 | │ ├── /Utilities |
| 146 | │ │ └── GameHelper.php [Reference only - can be deprecated] |
| 147 | │ │ |
| 148 | │ └── /System |
| 149 | │ └── SaveManager.php [Used for path handling] |
| 150 | │ |
| 151 | └── /public |
| 152 | ├── index.html |
| 153 | └── /js |
| 154 | └── app.js [MODIFIED - sprite URL generation] |
| 155 | ``` |
| 156 | |
| 157 | ## Class Relationship Diagram |
| 158 | |
| 159 | ``` |
| 160 | ┌──────────────────────────────────────────────────────────────┐ |
| 161 | │ Kobold Class │ |
| 162 | ├──────────────────────────────────────────────────────────────┤ |
| 163 | │ Properties: │ |
| 164 | │ - id, userId, saveId │ |
| 165 | │ - name, age, stats[] │ |
| 166 | │ - spriteMorph, saveManager (NEW) │ |
| 167 | ├──────────────────────────────────────────────────────────────┤ |
| 168 | │ Sprite Methods (NEW): │ |
| 169 | │ + generate() - static factory │ |
| 170 | │ └─> initializeSprite() - PRIVATE │ |
| 171 | │ + getAgeSpriteName() - maps age to filename │ |
| 172 | │ + getSpritePath() - returns full sprite path │ |
| 173 | │ - transformSprite() - applies visual effects │ |
| 174 | │ ├─ applyInjuryMarkings() - draws scars │ |
| 175 | │ ├─ desaturateImage() - grays elderly │ |
| 176 | │ └─ addLeadershipMarkings() - adds crown │ |
| 177 | │ │ |
| 178 | │ Existing Methods (UNCHANGED): │ |
| 179 | │ + getAge(), setAge(), incrementAge() │ |
| 180 | │ + getAgeCategory() - returns age tier │ |
| 181 | │ + getStat(), setStat(), checkStat() │ |
| 182 | │ + fromArray(), toArray() │ |
| 183 | │ + save(), getId(), getName(), etc. │ |
| 184 | └──────────────────────────────────────────────────────────────┘ |
| 185 | │ |
| 186 | │ uses |
| 187 | ↓ |
| 188 | ┌──────────────────────────────────────────────────────────────┐ |
| 189 | │ SaveManager (Existing) │ |
| 190 | ├──────────────────────────────────────────────────────────────┤ |
| 191 | │ Methods used by Sprite System: │ |
| 192 | │ + getKoboldSpritePath($userId, $koboldId) │ |
| 193 | │ └─> Creates: /data/saves/{userId}/kobolds/{id}/sprites/ │ |
| 194 | │ └─> Returns path with trailing slash │ |
| 195 | └──────────────────────────────────────────────────────────────┘ |
| 196 | │ |
| 197 | │ manages paths for |
| 198 | ↓ |
| 199 | ┌──────────────────────────────────────────────────────────────┐ |
| 200 | │ File System (PHP/GD) │ |
| 201 | ├──────────────────────────────────────────────────────────────┤ |
| 202 | │ Operations: │ |
| 203 | │ - copy($source, $dest) [Copy sprite from assets] │ |
| 204 | │ - imagecreatefrompng() [Load PNG image] │ |
| 205 | │ - imagecolorat() [Read pixel colors] │ |
| 206 | │ - imageline() [Draw lines for scars/crown] │ |
| 207 | │ - imagesetpixel() [Modify individual pixels] │ |
| 208 | │ - imagepng() [Save modified image] │ |
| 209 | │ - imagedestroy() [Free image resource] │ |
| 210 | └──────────────────────────────────────────────────────────────┘ |
| 211 | ``` |
| 212 | |
| 213 | ## State Diagram - Kobold Sprite Lifecycle |
| 214 | |
| 215 | ``` |
| 216 | ┌─────────────────────────────────────────────────────────────┐ |
| 217 | │ KOBOLD SPRITE LIFECYCLE │ |
| 218 | └─────────────────────────────────────────────────────────────┘ |
| 219 | |
| 220 | 1. INITIALIZATION |
| 221 | ───────────── |
| 222 | Kobold::generate() |
| 223 | └─> state = "initializing" |
| 224 | ├─> SaveManager creates /data/saves/{userId}/kobolds/{id}/sprites/ |
| 225 | ├─> Copy from: /assets/sprites/{morph}/{ageSprite}.png |
| 226 | ├─> Paste to: /data/saves/{userId}/kobolds/{id}/sprites/ |
| 227 | └─> state = "copied" |
| 228 | |
| 229 | 2. TRANSFORMATION |
| 230 | ──────────────── |
| 231 | transformSprite() |
| 232 | └─> state = "transforming" |
| 233 | ├─> Load PNG file |
| 234 | ├─> Check vitality < 50 |
| 235 | │ └─> YES: applyInjuryMarkings() [RED SCARS] |
| 236 | ├─> Check age category (old/very_old) |
| 237 | │ └─> YES: desaturateImage() [GRAYSCALE] |
| 238 | ├─> Check will > 70 |
| 239 | │ └─> YES: addLeadershipMarkings() [GOLD CROWN] |
| 240 | ├─> Save PNG file |
| 241 | └─> state = "ready" |
| 242 | |
| 243 | 3. STORAGE |
| 244 | ──────── |
| 245 | File System |
| 246 | └─> state = "persisted" |
| 247 | └─> Files exist at: |
| 248 | /data/saves/{userId}/kobolds/{koboldId}/sprites/ |
| 249 | ├── egg.png [MODIFIED & SAVED] |
| 250 | ├── baby.png [MODIFIED & SAVED] |
| 251 | ├── adult.png [MODIFIED & SAVED] |
| 252 | └── old.png [MODIFIED & SAVED] |
| 253 | |
| 254 | 4. DISPLAY |
| 255 | ─────── |
| 256 | GET /api/game/sprite |
| 257 | └─> state = "serving" |
| 258 | ├─> Validate parameters |
| 259 | ├─> Load file from save folder |
| 260 | ├─> Set HTTP headers |
| 261 | │ ├─ Content-Type: image/png |
| 262 | │ └─ Cache-Control: public, max-age=3600 |
| 263 | ├─> Send PNG to browser |
| 264 | └─> state = "displayed" |
| 265 | |
| 266 | 5. BROWSER CACHE |
| 267 | ────────────── |
| 268 | Client Side |
| 269 | └─> state = "cached" |
| 270 | ├─> First request: Download (10-50ms) |
| 271 | ├─> Subsequent requests (within 1 hour): Cached (1-5ms) |
| 272 | └─> Cache expires: Request new image |
| 273 | |
| 274 | |
| 275 | STAT EFFECTS OVER TIME |
| 276 | ────────────────────── |
| 277 | |
| 278 | Age Progression: |
| 279 | Age 0-3 Age 4-34 Age 35-59 Age 60+ |
| 280 | ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ |
| 281 | │ egg.png │→│ baby.png │→ │adult.png │→ │ old.png │ |
| 282 | └──────────┘ └──────────┘ └──────────┘ └──────────┘ |
| 283 | [Color] [Color] [Color] [GRAYSCALE] |
| 284 | (desaturated) |
| 285 | |
| 286 | Vitality Degradation: |
| 287 | High (80+) Medium (50-79) Low (<50) |
| 288 | ┌─────────┐ ┌─────────┐ ┌─────────┐ |
| 289 | │ Clean │→ │ Some │→ │ Scarred │ |
| 290 | │ Sprite │ │ Scars │ │ Sprite │ |
| 291 | └─────────┘ └─────────┘ └─────────┘ |
| 292 | (1-3 scars) (3-5 scars) |
| 293 | |
| 294 | Will Progression: |
| 295 | Low (≤70) High (>70) |
| 296 | ┌─────────┐ ┌─────────┐ |
| 297 | │ No │→ │ CROWN │ |
| 298 | │ Crown │ │ Visible │ |
| 299 | └─────────┘ └─────────┘ |
| 300 | ``` |
| 301 | |
| 302 | ## API Endpoint Flow Diagram |
| 303 | |
| 304 | ``` |
| 305 | Frontend Request |
| 306 | │ |
| 307 | └─> GET /tribegen/api/game/sprite?userId=U1&koboldId=K1&age=adult |
| 308 | │ |
| 309 | ├─ Browser checks cache |
| 310 | │ └─> If cached: Use cached image (< 1 hour TTL) |
| 311 | │ └─> If not cached or expired: Continue to backend |
| 312 | │ |
| 313 | └─> Backend Processing (game.php) |
| 314 | │ |
| 315 | ├─> Validate parameters |
| 316 | │ ├─> userId present? [Required] |
| 317 | │ ├─> koboldId present? [Required] |
| 318 | │ └─> age valid? [Optional, default='adult'] |
| 319 | │ |
| 320 | ├─> Get sprite path |
| 321 | │ └─> SaveManager::getKoboldSpritePath($userId, $koboldId) |
| 322 | │ └─> /data/saves/{userId}/kobolds/{koboldId}/sprites/ |
| 323 | │ |
| 324 | ├─> Build file path |
| 325 | │ └─> {spritePath}/{ageSprite}.png |
| 326 | │ └─> /data/saves/U1/kobolds/K1/sprites/adult.png |
| 327 | │ |
| 328 | ├─> Check file exists |
| 329 | │ ├─> YES: Continue to response |
| 330 | │ └─> NO: Return 404 error |
| 331 | │ |
| 332 | ├─> Set HTTP Headers |
| 333 | │ ├─ HTTP/1.1 200 OK |
| 334 | │ ├─ Content-Type: image/png |
| 335 | │ └─ Cache-Control: public, max-age=3600 |
| 336 | │ |
| 337 | ├─> Send File |
| 338 | │ └─> readfile(/data/saves/U1/kobolds/K1/sprites/adult.png) |
| 339 | │ |
| 340 | └─> Return to Browser |
| 341 | │ |
| 342 | ├─> Browser receives PNG binary data |
| 343 | ├─> Browser stores in cache (1 hour) |
| 344 | └─> Browser renders <img> element |
| 345 | ``` |
| 346 | |
| 347 | ## Transformation Decision Tree |
| 348 | |
| 349 | ``` |
| 350 | transformSprite() |
| 351 | │ |
| 352 | ├─ Is image loaded successfully? |
| 353 | │ │ |
| 354 | │ ├─ NO → Return (exit early) |
| 355 | │ │ |
| 356 | │ └─ YES → Continue |
| 357 | │ │ |
| 358 | │ ├─ [Check Vitality] |
| 359 | │ │ │ |
| 360 | │ │ └─ vitality < 50? |
| 361 | │ │ │ |
| 362 | │ │ ├─ YES → applyInjuryMarkings() |
| 363 | │ │ │ └─ Draw (50 - vitality) / 10 + 1 scars (max 5) |
| 364 | │ │ │ |
| 365 | │ │ └─ NO → Skip injury marks |
| 366 | │ │ |
| 367 | │ ├─ [Check Age] |
| 368 | │ │ │ |
| 369 | │ │ └─ Age category is old or very_old? |
| 370 | │ │ │ |
| 371 | │ │ ├─ YES → desaturateImage() |
| 372 | │ │ │ └─ Reduce saturation 60% (0.4 original + 0.6 gray) |
| 373 | │ │ │ |
| 374 | │ │ └─ NO → Skip age effect |
| 375 | │ │ |
| 376 | │ ├─ [Check Will] |
| 377 | │ │ │ |
| 378 | │ │ └─ will > 70? |
| 379 | │ │ │ |
| 380 | │ │ ├─ YES → addLeadershipMarkings() |
| 381 | │ │ │ └─ Draw gold crown at top center |
| 382 | │ │ │ |
| 383 | │ │ └─ NO → Skip leadership mark |
| 384 | │ │ |
| 385 | │ └─ Save modified image |
| 386 | │ └─ imagepng($image, $spritePath) |
| 387 | │ └─ Overwrites original sprite file in save folder |
| 388 | ``` |
| 389 | |
| 390 | --- |
| 391 | |
| 392 | *These diagrams provide visual understanding of the sprite system architecture and data flows.* |