# donation-system

> Creates donation shop and VIP reward mechanics for Tales of Aden L2J server.
Use when: implementing VIP purchases, Hero status, name/class changes, clan services, augmentations, color customization, or donation shop items

- Author: valeriybaranyshyn-pixel
- Repository: valeriybaranyshyn-pixel/Tales-of-Aden
- Version: 20260202145225
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/valeriybaranyshyn-pixel/Tales-of-Aden
- Web: https://mule.run/skillshub/@@valeriybaranyshyn-pixel/Tales-of-Aden~donation-system:20260202145225

---

---
name: donation-system
description: |
  Creates donation shop and VIP reward mechanics for Tales of Aden L2J server.
  Use when: implementing VIP purchases, Hero status, name/class changes, clan services, augmentations, color customization, or donation shop items
allowed-tools: Read, Edit, Write, Glob, Grep, Bash
---

# Donation System Skill

Implements a comprehensive monetization system using Donate Coins (configurable item ID) for VIP/Hero status, character services, clan upgrades, and item shops via voiced commands (`.donate`) and multisell integration.

## Quick Start

### VIP Purchase Flow

```java
// VoicedDonate.java - VIP activation pattern
if (activeChar.destroyItemByItemId("Donate Coin", Config.DONATE_COIN_ID, Config.VIP_30_DAYS_PRICE, null, true)) {
    activeChar.setVip(true);
    activeChar.setEndTime("vip", 30);  // Days
    
    if (Config.ALLOW_VIP_NCOLOR && activeChar.isVip()) {
        activeChar.getAppearance().setNameColor(Config.VIP_NCOLOR);
    }
    activeChar.broadcastUserInfo();
    activeChar.sendPacket(new EtcStatusUpdate(activeChar));
}
```

### Hero Status with Expiration

```java
// HeroManagerCustom.java - Time-based Hero management
HeroManagerCustom.getInstance().addHero(objectId, endTimeMillis);

// Background task checks expiration every second
if (System.currentTimeMillis() > duration) {
    removeHero(objectId);
    player.sendPacket(new ExShowScreenMessage("Your Hero privileges were removed.", 10000));
}
```

### Admin Item Delivery

```java
// AdminSendDonate.java - Deliver items to online/offline players
// Online player: direct inventory add
player.getInventory().addItem("Admin", itemId, count, player, activeChar);

// Offline player: SQL insert
"INSERT INTO items (owner_id,item_id,count,loc,...) VALUES (?,?,?,?,...)"
```

## Key Concepts

| Concept | Usage | Example |
|---------|-------|---------|
| Donate Coin | Currency item consumed for purchases | `Config.DONATE_COIN_ID` (default: 57/Adena) |
| VIP Status | Boolean flag with timestamp expiration | `player.isVip()`, `player.setEndTime("vip", days)` |
| Hero Custom | Duration-based Hero with background task | `HeroManagerCustom.addHero(objId, endMillis)` |
| Rate Bonuses | VIP multipliers for XP/Drop/Spoil | `Config.VIP_XP_SP_RATE`, `Config.VIP_DROP_RATE` |
| Multisell | Donation item shop integration | `MultisellData.showList(player, listName)` |

## Common Patterns

### Coin Validation Before Purchase

**When:** Any purchase action requiring donate coins.

```java
// ALWAYS validate before granting privileges
if (activeChar.destroyItemByItemId("Donate Coin", Config.DONATE_COIN_ID, price, null, true)) {
    // Grant privilege
} else {
    activeChar.sendMessage("Insufficient Donate Coins.");
}
```

### Extending Existing Time-Based Privileges

**When:** Player already has VIP/Hero and wants to extend.

```java
if (activeChar.isVip()) {
    long daysleft = (activeChar.getVipEndTime() - Calendar.getInstance().getTimeInMillis()) / 86400000L;
    activeChar.setEndTime("vip", (int)(daysleft + newDays));
    activeChar.sendMessage("Extended by " + newDays + " days.");
} else {
    activeChar.setVip(true);
    activeChar.setEndTime("vip", newDays);
}
```

## Configuration Reference

| Key | File | Purpose |
|-----|------|---------|
| `DonateCoin_Id` | Donate.properties | Currency item ID |
| `Vip_30_Days_Price` | Donate.properties | 30-day VIP cost |
| `VIPXpSpRate` | server.properties | XP/SP multiplier (1.2 = 20% bonus) |
| `VIPDropRate` | server.properties | Drop multiplier |
| `EnableVIPNewbieDays` | Donate.properties | Free VIP for new characters |

## See Also

- [patterns](references/patterns.md) - Purchase flow, validation, rate application
- [workflows](references/workflows.md) - Adding services, testing, database management

## Related Skills

- See the **java** skill for L2J coding conventions
- See the **mariadb** skill for database schema management
- See the **configuration-management** skill for .properties file patterns
- See the **database-schema** skill for VIP/Hero table structures
- See the **l2j-gameserver** skill for handler registration