# 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
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
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.*