# 📐 ASSET NAMING & ORGANIZATION STANDARDS
**Created:** January 4, 2026  
**Purpose:** Standardized naming for all game assets

---

## 🎨 SPRITE NAMING CONVENTION

### **Format:**
```
{category}_{name}_{variation}_{timestamp}.png
```

### **Examples:**
```
interior_bed_sleepingbag_1767523722494.png
interior_bed_wooden_1767523739033.png
interior_bed_kingsize_1767523753754.png
mine_elevator_cage_1767524542789.png
npc_baker_idle_1767524000000.png
```

---

## 📁 CATEGORY PREFIXES

### **Interior Objects:**
```
interior_{object_name}.png
```
Examples:
- `interior_bed_wooden.png`
- `interior_table_small.png`
- `interior_kitchen_stove.png`
- `interior_alchemy_bottle.png`

### **Buildings:**
```
building_{name}_{type}.png
```
Examples:
- `building_bakery_exterior.png`
- `building_barbershop_exterior.png`
- `building_lawyer_office.png`

### **Mine Assets:**
```
mine_{object_name}.png
```
Examples:
- `mine_entrance_portal.png`
- `mine_elevator_cage.png`
- `mine_ore_vein_copper.png`

### **NPCs:**
```
npc_{name}_{state}.png
```
Examples:
- `npc_baker_idle.png`
- `npc_barber_working.png`
- `npc_lawyer_sitting.png`

### **UI Elements:**
```
ui_{element_name}.png
```
Examples:
- `ui_sleep_button.png`
- `ui_crafting_menu_bg.png`
- `ui_shop_window.png`

### **Terrain:**
```
terrain_{type}_{variant}.png
```
Examples:
- `terrain_grass_dark_01.png`
- `terrain_stone_cursed_02.png`
- `terrain_water_purple.png`

### **Weapons & Tools:**
```
weapon_{name}_{tier}.png
tool_{name}_{tier}.png
```
Examples:
- `weapon_sword_steel.png`
- `weapon_scythe_cursed.png`
- `tool_pickaxe_wooden.png`
- `tool_hoe_iron.png`

---

## 📦 DIRECTORY STRUCTURE

```
/assets/images/
├── STYLE_32_SESSION_JAN_04/      # Current session
│   ├── interior_*.png             # All interior objects
│   ├── mine_*.png                 # Mine equipment
│   ├── building_*.png             # Building exteriors
│   ├── npc_*.png                  # NPC sprites
│   └── ui_*.png                   # UI elements
│
├── buildings/                     # Legacy organized by type
│   ├── bakery/
│   ├── barbershop/
│   └── lawyer_office/
│
├── npcs/                          # NPC-specific assets
│   ├── baker/
│   ├── barber/
│   └── lawyer/
│
├── ui/                            # UI components
│   ├── menus/
│   ├── buttons/
│   └── icons/
│
└── tilesets/                      # Tileset images
    ├── interior_objects.png       # Combined tileset
    └── mine_assets.png            # Combined mine tileset
```

---

## 🏷️ FILENAME COMPONENTS

### **1. Category** (Required)
- Identifies asset type
- Lowercase, singular
- Examples: `interior`, `building`, `npc`, `ui`, `mine`

### **2. Name** (Required)
- Descriptive object name
- Lowercase, underscores for spaces
- Examples: `bed`, `crafting_table`, `stone_crusher`

### **3. Variation** (Optional)
- Distinguishes similar items
- Examples: `wooden`, `small`, `kingsize`, `tier1`

### **4. State/Animation** (Optional for NPCs)
- Character state or animation frame
- Examples: `idle`, `walking`, `working`, `sitting`

### **5. Timestamp** (Auto-generated)
- Unix timestamp from generation
- Format: 13 digits
- Example: `1767523722494`

---

## 📏 SIZE STANDARDS

### **Interior Objects:**
```
Small items:     32x32px   (bottles, tools)
Medium items:    64x64px   (chests, chairs)
Large items:     96x96px   (beds, ovens, crushers)
Tall items:      64x96px   (wardrobes, shelves)
Wide items:      96x64px   (counters, tables)
Floor decals:    96x96px   (ritual circle)
Vertical:        32x128px  (ladders)
Horizontal:      128x32px  (rails, tracks)
```

### **Buildings:**
```
Small:    128x128px  (shops)
Medium:   192x192px  (houses)
Large:    256x256px  (town hall)
```

### **NPCs:**
```
Standard: 48x64px   (chibi characters)
Large:    64x96px   (bosses, special NPCs)
```

### **UI Elements:**
```
Icons:    32x32px   (inventory items)
Buttons:  128x48px  (action buttons)
Panels:   400x300px (menus, dialogs)
```

---

## ✅ CLEAN FILENAME EXAMPLES

### **Good:**
```
✅ interior_bed_wooden.png
✅ mine_ore_vein_gold.png
✅ npc_baker_idle.png
✅ building_bakery_exterior.png
✅ ui_sleep_menu_bg.png
```

### **Bad:**
```
❌ BedWooden.png              (CamelCase)
❌ interior-bed-wooden.png    (dashes instead of underscores)
❌ bed_wooden_interior.png    (wrong order)
❌ wooden bed.png             (spaces)
❌ bed2.png                   (not descriptive)
```

---

## 🔄 RENAMING SCRIPT

**Batch rename generated files:**
```bash
# Remove timestamps from final assets
for file in interior_*_*.png; do
    # Extract base name (remove timestamp)
    newname=$(echo "$file" | sed 's/_[0-9]\{13\}\.png/.png/')
    mv "$file" "$newname"
done
```

**Example output:**
```
interior_bed_wooden_1767523722494.png → interior_bed_wooden.png
interior_table_small_1767523769657.png → interior_table_small.png
```

---

## 📋 ASSET CHECKLIST

Before committing new assets:

- [ ] Correct category prefix used
- [ ] Descriptive, clear name
- [ ] Lowercase with underscores
- [ ] Correct size (multiple of 32px)
- [ ] Chroma green background (#00FF00)
- [ ] Style 32 compliance (5px outlines, noir aesthetic)
- [ ] Placed in correct directory
- [ ] Documented in manifest

---

## 📚 MANIFEST FORMAT

**Track all assets in `ASSET_MANIFEST.md`:**

```markdown
## Interior Objects

| Filename | Size | Category | Status | Notes |
|----------|------|----------|--------|-------|
| interior_bed_sleepingbag.png | 64x48 | Home | ✅ Complete | Basic tier |
| interior_bed_wooden.png | 96x64 | Home | ✅ Complete | Mid tier |
| interior_bed_kingsize.png | 128x96 | Home | ✅ Complete | Premium tier |
```

---

**Created:** January 4, 2026  
**Version:** 1.0  
**Status:** Official Standard ✅