================================================================================
GUIDE: Adding New Skins to the Shop System
================================================================================

IMPORTANT: When adding new skins, you MUST ensure consistency between:
1. Database (counter_strike_skins.name)
2. Config file (vip_skin_shop.cfg)
3. Model files (v_, p_, w_ models)

================================================================================
STEP 1: Add Skin to Config File (vip_skin_shop.cfg)
================================================================================

Location: cstrike/addons/amxmodx/configs/vip_skin_shop.cfg

Format:
weapon_key | skin_key | Display Name | v_model | p_model | w_model

Example:
m4a1 | musica | M4A1 Musica | models/vip/custom/v_m4a1_muzica.mdl | models/vip/custom/p_m4a1_muzica.mdl | models/vip/custom/w_m4a1_muzica.mdl

REQUIREMENTS:
- weapon_key: lowercase, no spaces (ak47, m4a1, deagle, etc.)
- skin_key: lowercase, no spaces, unique (anubis, derby, musica, etc.)
- Display Name: EXACT name that will be used in database (e.g., "M4A1 Musica")
- Model paths: must exist on server

================================================================================
STEP 2: Add Skin to Database (counter_strike_skins table)
================================================================================

Location: Use admin_add_skin.php or directly in database

CRITICAL: The "name" field MUST match the "Display Name" from config file EXACTLY!

Example:
- Config: "M4A1 Musica"
- Database name: "M4A1 Musica" (EXACT match, case-sensitive)

DO NOT use:
- "M4A1 Muzica" (typo - z instead of s)
- "m4a1 musica" (lowercase)
- "M4A1|musica" (pipe format - this is for internal use only)

================================================================================
STEP 3: Verify Model Files Exist
================================================================================

Make sure all 3 model files exist on the server:
- v_model (view model - what player sees)
- p_model (player model - what others see)
- w_model (world model - dropped weapon)

Location: cstrike/models/vip/custom/

Example:
- v_m4a1_muzica.mdl
- p_m4a1_muzica.mdl
- w_m4a1_muzica.mdl

================================================================================
COMMON MISTAKES TO AVOID
================================================================================

1. TYPOS IN DISPLAY NAME:
   ❌ Database: "M4A1 Muzica" (with z)
   ✅ Config: "M4A1 Musica" (with s)
   → Plugin has fuzzy matching, but it's better to be exact!

2. CASE SENSITIVITY:
   ❌ Database: "m4a1 musica" (lowercase)
   ✅ Config: "M4A1 Musica" (proper case)
   → Plugin does case-insensitive matching, but exact match is faster

3. EXTRA SPACES:
   ❌ Database: "M4A1  Musica" (double space)
   ✅ Config: "M4A1 Musica" (single space)
   → Plugin normalizes spaces, but exact match is better

4. USING PIPE FORMAT IN DB:
   ❌ Database: "m4a1|musica"
   ✅ Database: "M4A1 Musica"
   → Pipe format (weapon_key|skin_key) is for internal matching only!

5. MISSING CONFIG ENTRY:
   ❌ Skin in DB but not in config
   → Plugin won't be able to match it, skin won't appear in menu

6. MISSING MODEL FILES:
   ❌ Config has model paths but files don't exist
   → Skin will appear in menu but won't apply (no visual change)

================================================================================
RECOMMENDED WORKFLOW
================================================================================

1. First, add skin to config file (vip_skin_shop.cfg)
   - Use exact Display Name you want (e.g., "M4A1 Musica")
   - Verify model paths are correct

2. Then, add skin to database (counter_strike_skins)
   - Use EXACT same Display Name from config
   - Set price, image_url, etc.

3. Upload model files to server
   - Place in cstrike/models/vip/custom/
   - Verify all 3 files exist (v_, p_, w_)

4. Test:
   - Restart server (to reload config)
   - Purchase skin from shop
   - Type /refreshskins in game
   - Type /skins to see if it appears
   - Apply skin and verify it works

================================================================================
FORMAT OPTIONS (Plugin supports both)
================================================================================

OPTION 1: Display Name (RECOMMENDED for new skins)
- Database: "M4A1 Musica"
- Config Display Name: "M4A1 Musica"
- Plugin matches by Display Name

OPTION 2: Pipe Format (for backward compatibility)
- Database: "m4a1|musica"
- Config: weapon_key="m4a1", skin_key="musica"
- Plugin matches by weapon_key|skin_key

RECOMMENDATION: Use Display Name format (Option 1) for all new skins!

================================================================================
VERIFICATION CHECKLIST
================================================================================

Before marking a skin as "ready":
[ ] Skin added to vip_skin_shop.cfg with correct format
[ ] Display Name in config matches database name EXACTLY
[ ] All 3 model files exist on server
[ ] Model paths in config are correct
[ ] Skin appears in shop (admin_add_skin.php)
[ ] Skin can be purchased
[ ] Skin appears in /skins menu after purchase
[ ] Skin applies correctly when selected

================================================================================
TROUBLESHOOTING
================================================================================

Problem: Skin purchased but doesn't appear in /skins menu
Solution:
1. Check if Display Name in DB matches config EXACTLY
2. Type /refreshskins in game
3. Check server logs for matching errors
4. Verify skin is in config file

Problem: Skin appears in menu but doesn't apply
Solution:
1. Check if model files exist on server
2. Verify model paths in config are correct
3. Check server logs for model loading errors

Problem: Skin doesn't match (fuzzy matching fails)
Solution:
1. Use EXACT Display Name in both DB and config
2. Avoid typos (z/s, c/k, etc.)
3. Check for extra spaces or special characters

================================================================================
END OF GUIDE
================================================================================

