# Kolossium - Valheim PvP Arena Mod

A comprehensive PvP arena system for Valheim that adds organized player-vs-player combat with registration, matchmaking, leaderboards, and rewards.

## Features

### 🏟️ **Arena System**
- **Automated Matchmaking**: Players register for fights, and matches start automatically when 2+ players are available
- **Arena Teleportation**: Registered players are teleported to a designated arena location
- **Safe Return**: Players are automatically returned to their original position after fights
- **Timed Matches**: Configurable fight duration with status effects

### 📊 **Leaderboard System**
- **Win/Loss Tracking**: Comprehensive statistics for all participants
- **Points-Based Ranking**: Advanced ranking system (3 points per win, -1 per loss)
- **Persistent Data**: Player statistics are saved and tracked over time
- **Real-Time Updates**: Leaderboard updates immediately after each match

### 🛒 **Token Store**
- **Reward System**: Winners receive configurable tokens/items
- **Custom Shop**: Purchase items using earned tokens
- **Configurable Items**: Server admins can customize available store items
- **Economy Integration**: Full inventory and currency management

### 🎮 **User Interface**
- **In-Game Menu**: Accessible through the main menu system
- **Multiple Tabs**: Registration, Leaderboard, and Store in one interface
- **Real-Time Status**: Live updates of arena state and player counts
- **Player Avatars**: Shows player profile pictures in lists
- **Fight State Display**: Shows current arena status (Idle, Waiting, In Progress)

### ⚙️ **Configuration Options**
- **Arena Position**: Set custom arena location
- **Reward Items**: Configure what items winners receive
- **Fight Duration**: Set match time limits
- **UI Scaling**: Adjust interface size
- **Module Toggles**: Enable/disable Leaderboard and Store features
- **Background Options**: Opaque or transparent UI panels

## Installation

1. **Install BepInEx** for Valheim (if not already installed)
2. **Download** the latest Kolossium release
3. **Extract** the mod files to your Valheim BepInEx plugins folder:
   ```
   Valheim/BepInEx/plugins/Kolossium/
   ```
4. **Launch** Valheim - the mod will create default configuration files

## Usage

### For Players

#### **Accessing the Arena**
1. Open the main menu (ESC)
2. Click "Kolossium" to open the arena interface
3. Use the tabs to navigate between Registration, Leaderboard, and Store

#### **Participating in Fights**
1. Go to the **Registration** tab
2. Click "Register" to join the queue
3. Wait for another player to register
4. You'll be automatically teleported to the arena when a match starts
5. Fight until one player dies or the timer expires
6. Winners receive rewards and both players are returned to their original positions

#### **Viewing Statistics**
1. Go to the **Leaderboard** tab
2. View player rankings based on points system
3. Rankings update automatically after each fight

#### **Using the Store**
1. Go to the **Store** tab (if enabled)
2. Browse available items
3. Click items to see details and costs
4. Purchase items using earned tokens

### For Server Administrators

#### **Basic Configuration**
The mod creates a configuration file at:
```
Valheim/BepInEx/config/Kolossium.cfg
```

Key settings include:
- `Arena Position`: Coordinates where fights take place
- `Reward Item`: Item given to winners (default: "KolossiumToken_RS")
- `Reward Amount`: Number of items awarded per win
- `Fight Duration`: Maximum fight time in seconds

#### **Advanced Setup**
- **Custom Arena**: Set arena position using in-game coordinates
- **Store Items**: Configure available store items and prices
- **Module Control**: Enable/disable leaderboard and store features
- **UI Customization**: Adjust scaling and appearance

## How It Works

### **Fight Flow**
1. **Registration Phase**: Players register for fights through the UI
2. **Matchmaking**: When 2+ players are registered, a match begins automatically
3. **Arena Teleport**: Participants are teleported to the arena with random positioning
4. **Combat Phase**: Players fight with a status effect applied
5. **Resolution**: Match ends when a player dies or timer expires
6. **Cleanup**: Players are returned home, stats updated, rewards distributed

### **State Management**
The arena has three states:
- **Idle**: No registered players, arena available
- **Waiting for Players**: Players registered, waiting for minimum participants
- **In Progress**: Fight currently happening

### **Network Architecture**
- **Server Authority**: All matchmaking and state management handled server-side
- **Real-Time Sync**: All clients receive live updates of arena status
- **RPC Communication**: Efficient network messaging for all arena operations

## Configuration Examples

### **Basic PvP Arena**
```ini
[2 - Settings]
Arena Position = 100, 50, 200
Fight Duration = 300
Reward Item = Coins
Reward Amount = 10
```

### **Token Economy Setup**
```ini
[2 - Settings]
Reward Item = KolossiumToken_RS
Reward Amount = 5
Use Store = On
```
[![KeyManager Disclaimer](https://noobtrap.eu/images/keymanager_disclaimer.png)](https://key.sayless.eu/faq.php)

Contact: Monarch011 for access