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