# AuctionPrime - Complete Documentation

## Table of Contents
1. [Installation](#installation)
2. [Basic Setup](#basic-setup)
3. [Commands Guide](#commands-guide)
4. [Permissions](#permissions)
5. [Configuration](#configuration)
6. [Admin Panel](#admin-panel)
7. [Advanced Features](#advanced-features)
8. [Troubleshooting](#troubleshooting)

---

## Installation

### Requirements
- **Minecraft**: 1.21+ (Paper/Spigot recommended)
- **Java**: 17+
- **Vault**: Required for economy features
- **Economy Plugin**: EssentialsX, CMI, or similar

### Steps
1. Download the latest `AuctionPrime.jar`
2. Place it in your `/plugins/` folder
3. Restart the server or reload plugins
4. Configure settings in `/plugins/AuctionPrime/config.yml`

---

## ⚙️ Basic Setup

### First Run
1. The plugin automatically creates configuration files
2. Default language is Italian (`it_IT.yml`)
3. English language file (`en_US.yml`) is also provided

### Essential Settings
```yaml
# config.yml
generale:
  lingua: "it_IT"  # Change to "en_US" for English
  max-inserzioni-per-giocatore: 10
economia:
  tassa-vendita: 0.05  # 5% sales tax
  costo-inserzione: 100  # Listing fee
```

---

## Commands Guide

### Basic Commands
| Command | Description | Permission |
|---------|-------------|------------|
| `/mercato` | Open main market GUI | `auctionprime.use` |
| `/mercato vendi <price>` | Sell item in hand | `auctionprime.sell` |
| `/mercato cerca` | Search via sign input | `auctionprime.use` |
| `/mercato inserzioni` | Your active listings | `auctionprime.use` |
| `/mercato scaduti` | Collect expired items | `auctionprime.use` |
| `/mercato venduti` | View sold items | `auctionprime.use` |

### Admin Commands
| Command | Description | Permission |
|---------|-------------|------------|
| `/mercato admin` | Admin management panel | `auctionprime.admin` |
| `/mercato reload` | Reload configuration | `auctionprime.admin.reload` |

### Tab Completion
- Press TAB after `/mercato` to see available commands
- Suggestions are **permission-based** - only shows commands you can use
- Type partial commands to filter suggestions

---

## Permissions

### Basic Permissions
```yaml
auctionprime.use: true          # Use basic market features
auctionprime.sell: true         # Sell items
auctionprime.sell.unlimited: false  # Unlimited listings
auctionprime.notify: true       # Receive new listing notifications
```

### Admin Permissions
```yaml
auctionprime.admin: false       # Access admin panel
auctionprime.admin.reload: false  # Reload configuration
auctionprime.bypass.restrictions: false  # Bypass item restrictions
auctionprime.bypass.cooldown: false       # Bypass cooldowns
```

### Permission Nodes
- `auctionprime.maxlistings.<number>` - Custom listing limit
- `auctionprime.world.<world>` - Access specific worlds

---

## Configuration

### Main Config (`config.yml`)
```yaml
# General Settings
generale:
  lingua: "it_IT"
  max-inserzioni-per-giocatore: 10
  durata-inserzione-ore: 72
  cleanup-intervallo-minuti: 30

# Economy Settings
economia:
  tassa-vendita: 0.05
  costo-inserzione: 100
  prezzo-minimo: 100
  prezzo-massimo: 1000000

# GUI Settings
gui:
  material-pulsanti:
    precedente: "ARROW"
    successivo: "ARROW"
    cerca: "COMPASS"
    vendi: "EMERALD"
```

### Language Files
- **Italian**: `/plugins/AuctionPrime/lang/it_IT.yml`
- **English**: `/plugins/AuctionPrime/lang/en_US.yml`
- **Custom**: Create new language files following the same format

---

## ️ Admin Panel

### Access
- Use `/mercato admin` command
- Requires `auctionprime.admin` permission

### Features

#### 1. **List View**
- Shows ALL listings (active, expired, sold, cancelled)
- Color-coded status indicators
- Pagination with statistics
- Filter options (active only / all)

#### 2. **Detail View**
Click any listing to access detailed management:

| Action | Description | Location |
|--------|-------------|----------|
| **Remove Listing** | Permanently delete listing | Barrier (red) |
| **Edit Price** | Set custom price via sign | Name Tag |
| **Half Price** | Quick 50% price reduction | Iron Nugget |
| **Double Price** | Quick 200% price increase | Gold Nugget |
| **Change Seller** | Transfer ownership | Player Head |
| **Toggle Expired** | Activate/deactivate listing | Clock |
| **Toggle Unlimited** | Set unlimited duration | Bedrock |
| **Give Copy** | Get item copy | Chest |
| **Back to List** | Return to list view | Arrow |

#### 3. **Sign Input**
- Price editing: Opens sign with price input prompt
- Seller change: Opens sign for player name entry
- Automatic validation and error handling

---

## Advanced Features

### Item Restrictions
Control what items can be sold:

```yaml
# config.yml
restrizioni-oggetti:
  abilitato: true
  tipi-vietati:
    - "BEDROCK"
    - "COMMAND_BLOCK"
  nomi-vietati:
    - ".*[Hh]acked.*"  # Regex pattern
  incantesimi-vietati:
    - "DAMAGE_ALL"
```

### Multi-World Support
```yaml
# config.yml
mondi:
  abilitati: true
  gruppi:
    survival: ["world", "world_nether", "world_the_end"]
    creative: ["world_creative"]
```

### Discord Integration
```yaml
# config.yml
discord:
  abilitato: true
  webhook-url: "YOUR_WEBHOOK_URL"
  notifiche-nuove-inserzioni: true
  notifiche-vendite: true
```

### Cooldown System
```yaml
# config.yml
cooldown:
  abilitato: true
  secondi-tra-inserzioni: 300  # 5 minutes
```

---

## Transaction Logging

### Log Files
- **Location**: `/plugins/AuctionPrime/transactions.log`
- **Format**: Timestamped entries for all transactions
- **Types**: Listings, sales, cancellations, expirations

### Example Log Entry
```
[2024-03-03 14:30:15] [LISTING] PlayerName listed DIAMOND_SWORD for 5000.00
[2024-03-03 14:32:20] [SALE] BuyerName bought DIAMOND_SWORD from PlayerName for 5000.00
```

---

## Troubleshooting

### Common Issues

#### **Economy Not Ready**
```
[AuctionPrime] Il sistema economico non è ancora pronto
```
**Solution**: Ensure Vault and economy plugin are loaded before AuctionPrime

#### **Permission Denied**
```
Non hai il permesso per farlo
```
**Solution**: Check permissions in your permissions plugin

#### **World Not Enabled**
```
Il mercato non è disponibile in questo mondo
```
**Solution**: Add world to enabled worlds in config

#### **Item Cannot Be Sold**
```
Questo oggetto non può essere venduto
```
**Solution**: Check item restrictions in config

### Debug Mode
Enable debug logging:
```yaml
# config.yml
debug: true
```

### Support
- Check console for detailed error messages
- Verify all dependencies are installed
- Ensure configuration files are valid YAML

---

## Maintenance

### Automatic Cleanup
- Expired listings are automatically processed
- Cleanup runs every 30 minutes (configurable)
- Abandoned items are returned to owners

### Manual Commands
```bash
# Reload configuration
/mercato reload

# Check plugin status
/auctionprime status  # If installed
```

### Backup Recommendations
- Backup `/plugins/AuctionPrime/` folder regularly
- Especially `listings.yml` and `transactions.log`

---

## API Usage

### Getting AuctionManager
```java
AuctionPrime plugin = (AuctionPrime) Bukkit.getPluginManager().getPlugin("AuctionPrime");
AuctionManager auctionManager = plugin.getAuctionManager();
```

### Creating Listings Programmatically
```java
Player player = ...;
ItemStack item = ...;
double price = 1000.0;
auctionManager.createListing(player, item, price);
```

### Getting Player Listings
```java
UUID playerId = player.getUniqueId();
List<AuctionListing> listings = plugin.getStorageManager().getPlayerListings(playerId);
```

---

## Tips & Best Practices

### For Server Owners
1. **Set appropriate listing limits** to prevent market flooding
2. **Configure reasonable fees** to balance economy
3. **Enable item restrictions** for valuable/rare items
4. **Regular backup** of listings data

### For Players
1. **Use descriptive item names** before selling
2. **Set competitive prices** by checking existing listings
3. **Collect expired items** regularly to free up slots
4. **Use search feature** to find specific items quickly

### For Admins
1. **Monitor market activity** through admin panel
2. **Use price editing** to correct market imbalances
3. **Check transaction logs** for suspicious activity
4. **Backup before major changes**

---

## Performance Optimization

### Recommended Settings
```yaml
generale:
  cleanup-intervallo-minuti: 30  # Balance between performance and freshness
  max-inserzioni-per-giocatore: 15  # Prevent database bloat

gui:
  oggetti-per-pagina: 45  # Standard chest size
```

### Large Server Tips
- Increase cleanup interval for very large servers
- Consider database backend for 1000+ concurrent players
- Monitor memory usage with GUI-heavy usage

---

## Future Updates

### Planned Features
- [ ] Database backend support (MySQL/SQLite)
- [ ] Auction bidding system
- [ ] Market analytics dashboard
- [ ] Bulk listing operations
- [ ] Item category filtering

### Version History
- **v1.0.0**: Initial release with core features
- **v1.1.0**: Added admin panel and sign-based search
- **v1.2.0**: Permission-based tab completion and help system

---

*For the latest updates and support, visit the plugin page or join our Discord community.*