BlueGit

blue-star tribegen

Files

tribegen / web / docs / SPRITE_ARCHITECTURE_DIAGRAMS.md

SPRITE_ARCHITECTURE_DIAGRAMS.md

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

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
10API 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
55Frontend: 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```
88TribeGen 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
2201. 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
2292. 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
2433. 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
2544. 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
2665. 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
275STAT EFFECTS OVER TIME
276──────────────────────
277
278Age 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
286Vitality 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
294Will Progression:
295 Low (≤70) High (>70)
296 ┌─────────┐ ┌─────────┐
297 │ No │→ │ CROWN │
298 │ Crown │ │ Visible │
299 └─────────┘ └─────────┘
300```
301
302## API Endpoint Flow Diagram
303
304```
305Frontend 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```
350transformSprite()
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.*