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