# Cosmetics & Achievements

## Overview
Advenexus features cosmetic systems that let players personalize their profiles, guilds, and visual identity. This includes profile pictures, guild banners, and achievement badges — all purely cosmetic or reward-based. Achievements also award coin bonuses when unlocked.

---

## Profile Pictures

### Commands

| Command | Description |
|---|---|
| `.profile shop` | Browse all available profile pictures |
| `.buy picture<N>` | Purchase a profile picture (e.g. `.buy picture7`) |
| `.profile equip <pictureN>` | Equip an owned profile picture |
| `.profile unequip` | Remove your profile picture |

### Available Profiles

There are **23 profile pictures** across 8 rarity tiers:

| Tier | Price | Profiles |
|---|---|---|
| Common | 1,000 🪙 | Robber, Castle, Astronaut |
| Uncommon | 2,000 🪙 | Pentagram, Monalisa, Poker |
| Rare | 3,000 🪙 | Soul Take, Plague Doctor, Jason Mask |
| Epic | 5,000 🪙 | Danger, Ceasar, Sigma |
| Mythic | 10,000 🪙 | Peace Dove, Toxic, Beast |
| Legendary | 20,000 🪙 | Crown, Spy, King, Mafia |
| Fabled | 50,000 🪙 | Anonymous, Yin Yang, Power |
| Boundless | 200,000 🪙 | The One Above All |

### Profile Picture IDs
- IDs are `picture1` through `picture23`
- Must purchase before equipping
- Only one can be equipped at a time
- Unequipping removes the picture but doesn't refund

### Profile Display Data
The profile card shows:
- Equipped profile picture
- Profile tier / border color
- Profile border (if set)
- Profile title (if set)
- Custom profile image (patron feature)
- Equipped hunt effect (if any)

---

## Guild Banners

### Commands

| Command | Description |
|---|---|
| `.banner shop` | Browse all guild banners |
| `.banner buy <bannerID>` | Purchase a banner for your guild (leader only) |
| `.banner equip <bannerID>` | Equip a banner for your guild (leader only) |

### Available Banners

16 banners with escalating prices:

| Banner | Price |
|---|---|
| banner1 | 5,000 🪙 |
| banner2 | 8,000 🪙 |
| banner3 | 12,000 🪙 |
| banner4 | 20,000 🪙 |
| banner5 | 30,000 🪙 |
| banner6 | 40,000 🪙 |
| banner7 | 50,000 🪙 |
| banner8 | 60,000 🪙 |
| banner9 | 70,000 🪙 |
| banner10 | 80,000 🪙 |
| banner11 | 90,000 🪙 |
| banner12 | 100,000 🪙 |
| banner13 | 110,000 🪙 |
| banner14 | 120,000 🪙 |
| banner15 | 130,000 🪙 |
| banner16 | 150,000 🪙 |

### Banner Rules
- Only the **guild leader** can buy and equip banners
- Cost is paid from the **leader's personal coins** (not guild bank)
- Banners are **guild-owned** — they persist even if the leader changes
- Only one banner can be equipped at a time
- Owned banners are tracked in `guild_banners_owned` table

---

## Achievements

Achievements are automatically awarded when players meet specific milestones. Each achievement grants a coin reward and a badge displayed on the profile.

### Achievement List

| ID | Title | Requirement | Reward | Difficulty |
|---|---|---|---|---|
| `unstoppable` | Unstoppable | 25 win streak | 10,000 🪙 | Uncommon |
| `arena_dominator` | Arena Dominator | 50 win streak | 20,000 🪙 | Rare |
| `undefeated_legend` | Undefeated Legend | 100 win streak | 50,000 🪙 | Epic |
| `coin_frenzy` | Coin Frenzy | 100,000 coins held | 20,000 🪙 | Rare |
| `coin_whale` | Coin Whale | 500,000 coins held | 100,000 🪙 | Legendary |
| `keeper_of_legends` | Keeper of Legends | Own a Fabled animal | 30,000 🪙 | Fabled |
| `beyond_infinity` | Beyond Infinity | Own a Boundless animal | 100,000 🪙 | Boundless |
| `armed_and_ready` | Armed and Ready | Own 10 weapons | 10,000 🪙 | Uncommon |
| `war_gear` | War Gear | Own 20 weapons | 30,000 🪙 | Epic |

### Achievement Check Triggers
Achievements are checked automatically at specific moments:

| Check | Triggered By |
|---|---|
| Battle achievements | After any battle win (checks win streak) |
| Coin achievements | After selling animals, battle rewards, shop purchases |
| Animal achievements | After catching an animal (hunt, lootbox, dungeon) |
| Weapon achievements | After buying or receiving a weapon |

### Achievement Mechanics
- Each achievement can only be unlocked **once**
- Coin reward is added instantly on unlock
- A **server-wide broadcast** is emitted when an achievement is unlocked
- Achievement badges are displayed on the player's profile card
- Each badge has a unique SVG icon and a tier-specific color

---

## Guild Achievements

Separate from player achievements, guild achievements track collective progress:

| Key | Name | Icon |
|---|---|---|
| `first_blood` | First Blood | ⚔️ |
| `raid_veterans` | Raid Veterans | ⚔️ |
| `guild_treasury` | Guild Treasury | 💰 |
| `treasure_empire` | Treasure Empire | 💰 |
| `boss_hunter` | Boss Hunter | 👑 |
| `titan_breakers` | Titan Breakers | 👑 |
| `guild_rising` | Guild Rising | 📈 |
| `legendary_order` | Legendary Order | 📈 |
| `full_house` | Full House | 👥 |
| `perfect_coord` | Perfect Coordination | 👥 |
| `david_vs_goliath` | David vs Goliath | 🎯 |
| `flawless_victory` | Flawless Victory | ✨ |

---

## Profile Tiers

Profile tiers change your profile's border, glow effect, title, and aura. Managed via the Account Wallet page (REST API).

### Coin-Based Tiers

| Tier | Price | Title | Features |
|---|---|---|---|
| Common (default) | Free | Adventurer | Basic gray border |
| Gold | 40,000 🪙 | Gold Warden | Gold border + glow |
| Legendary | 120,000 🪙 | Legendary Champion | Red border + glow |

### Cash-Based Premium Tiers

| Tier | Price | Title | Features |
|---|---|---|---|
| Fabled | 500 💵 | Fabled One | Orange border + animated glow + aura |
| Celestial | 1,200 💵 | Celestial Being | Purple border + animated glow + aura |
| Divine | 2,500 💵 | Divine Entity | Golden border + animated glow + aura |
| Void | 5,000 💵 | Void Walker | Violet border + animated glow + aura |
| Boundless | 10,000 💵 | Boundless God | Cyan border + animated glow + aura + **crown** |

- Tiers are **permanently owned** once purchased
- Only one tier can be equipped at a time
- Equipping `common_tier` resets to default
- Cash tiers set `premium_status = 1` on the user

---

## Hunt Auras (Hunt Animations)

Visual effects that surround your hunt messages.

### Coin-Based Auras

| Aura | Price | Description |
|---|---|---|
| Epic Aura | 5,000 🪙 | Purple energy pulse |
| Mythic Aura | 10,000 🪙 | Pink gradient surge |

### Cash-Based Auras

| Aura | Price | Description |
|---|---|---|
| Legendary Aura | 500 💵 | Golden flame |
| Fabled Aura | 500 💵 | Crimson fire |
| Gods Aura | 700 💵 | Infernal blaze |
| Boundless Aura | 1,000 💵 | Rainbow cosmic |

- Auras are **permanently owned** once purchased
- Only one can be equipped at a time
- Unequipping removes the effect (no refund)
- Stored in `user_cosmetics` table (item_type: `hunt_animation`)

---

## Custom Profile Image

- Upload a custom image for your profile card
- Toggle on/off with a button (does not delete the image)
- Stored as a URL in `custom_profile_image` field
- Requires upload via REST API

---

## Black Friday Event

Black Friday is a limited-time event that allows cosmetic items to be purchased with coins instead of cash.

### Event Details

| Property | Value |
|---|---|
| **Duration** | 5 hours |
| **Trigger** | Randomly every 8-12 days |
| **Coin Conversion Rate** | 200 coins per 1 cash |
| **Discount** | 10-40% off converted price |

### How It Works

- When Black Friday is active, all cosmetic items (profile pictures, guild banners, profile tiers, hunt auras) can be purchased with coins instead of cash
- The coin price is calculated by converting the cash price to coins (200 coins per 1 cash) and applying a random discount (10-40%)
- Each cosmetic item gets a unique discounted price per event instance
- Push notifications are sent to all players when the event starts and ends
- Socket emissions (`black_friday_start`, `black_friday_end`) notify the client in real-time

### Event State

- Event state is persisted in the database (`event_state` table with key `black_friday_state`)
- Survives server restarts
- Automatically checks and triggers every minute

### Commands

| Command | Description |
|---|---|
| `.profile shop` | View current prices (shows coins during Black Friday) |
| `.banner shop` | View banner prices (shows coins during Black Friday) |

### Example Pricing

During Black Friday, a Fabled Profile Picture (normally 50,000 🪙 or 250 💵):
- Base conversion: 250 × 200 = 50,000 coins
- With 25% discount: 50,000 × 0.75 = 37,500 coins

---

## Edge Cases

- Cannot buy a profile picture you already own
- Must own a profile picture before equipping it
- Unequipping does not refund — the picture stays owned
- Banner purchases use personal coins, not guild bank
- Achievement coin rewards stack with your current balance (can trigger higher coin achievements)
- Guild achievements are tracked per guild, not per player
- Achievement badges persist forever once earned
- Profile tiers and hunt auras are stored in `user_cosmetics` table (separate from profile pictures)
- Deprecated tiers (Bronze, Silver) exist in code but are not purchasable
- Black Friday discounts are randomized per item per event — prices may vary between events