novafarma/ASSET_NAMING_STANDARDS.md

📐 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:

# 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:

## 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 ✅