DailyRewardsPlus

# DailyRewardsPlus - Complete Documentation

A comprehensive daily reward system plugin for Spigot 1.12.2 Minecraft servers. Players can claim daily rewards with streak tracking, weekly bonuses, and an interactive GUI menu.

## Features

### ✅ Daily Reward System
- Players can claim one reward every 24 hours
- Streak increases by +1 for each on-time claim
- Streaks reset if player doesn't claim within 48 hours
- Reward formula: `reward = baseReward × streak`
- Economy integration via Vault

### ✅ Interactive GUI Menu
- Opens with `/daily` command
- 27-slot inventory (3 rows)
- Emerald item in center (slot 13) for claiming
- Gray stained glass panes as decorative filler
- Real-time lore showing:
- Current streak count
- Next reward amount
- Cooldown timer if not ready

### ✅ Cooldown Management
- Displays "You can claim again in X hours, Y minutes"
- GUI lore updates with remaining time
- Prevents claiming before 24-hour cooldown expires

### ✅ Weekly Bonuses
- Automatic bonus at 7-day streak
- Default bonus: $5,000 (configurable)
- Special sound effect plays
- Celebratory particle effects
- Announcement message to player
- Streak resets to 1 after bonus

### ✅ Particle & Sound Effects
- Configurable sound on claim (default: LEVEL_UP)
- Configurable particles on claim (default: VILLAGER_HAPPY)
- Enhanced effects for weekly bonuses
- Can be disabled in config

### ✅ Data Persistence
- YAML-based player data storage
- Stores last claim timestamp and current streak
- Automatic saving on plugin disable
- Efficient caching system

### ✅ Configuration System
- Fully customizable rewards
- Color-coded messages with placeholder support
- Enable/disable particles and sounds
- Customizable GUI title and messages

## Installation

### Requirements
- Spigot 1.12.2 or compatible server
- Vault plugin (for economy support)
- An economy plugin (EssentialsX, CMI, etc.)
- Java 8 or higher

### Setup Steps

1. **Download/Build the Plugin**
- Clone or download this repository
- Run `mvn clean package` to build
- The compiled JAR will be in `target/` directory

2. **Install the Plugin**
- Place `DailyRewardsPlus.jar` in your server's `plugins/` directory
- Restart the server

3. **Verify Installation**
- Check server console for "DailyRewardsPlus has been enabled!"
- Verify Vault is installed and hooked

4. **Configure (Optional)**
- Edit `plugins/DailyRewardsPlus/config.yml`
- Use `/dailyreload` to apply changes

## Commands

| Command | Permission | Description |
|---------|-----------|-------------|
| `/daily` | `daily.use` | Opens the daily reward GUI menu |
| `/dailyreload` | `daily.admin` | Reloads configuration and player data |

## Permissions

- `daily.use` - Allows players to use the `/daily` command (default: true)
- `daily.admin` - Allows use of admin commands (default: OP only)

## Configuration

### config.yml Structure

```yaml
base-reward: 500 # Base reward amount
weekly-bonus: 5000 # Weekly bonus amount
enable-particles: true # Enable particle effects
enable-sounds: true # Enable sound effects
gui-title: "&aDaily Rewards" # GUI title with color codes

messages:
first-claim: "..." # First claim message
daily-claim: "..." # Daily claim message
weekly-claim: "..." # Weekly bonus message
cooldown: "..." # Cooldown warning message
streak-reset: "..." # Streak reset message
```

### Message Placeholders
- `%reward%` - Reward amount
- `%streak%` - Current streak count
- `%hours%` - Hours until next claim
- `%minutes%` - Minutes until next claim

### Color Codes
Use `&` followed by color code for colored text:
- `&a` - Green
- `&c` - Red
- `&6` - Gold
- `&e` - Yellow
- `&7` - Gray
- `&l` - Bold
- `&o` - Italic

## Data Storage

Player data is automatically stored in `plugins/DailyRewardsPlus/playerdata.yml`:

```yaml
players:
"PlayerName":
lastClaim: 1702414800000 # Timestamp of last claim (milliseconds)
streak: 5 # Current streak count
```

Data is automatically saved:
- When a player claims a reward
- When the server shuts down
- Use `/dailyreload` to reload from disk

## Project Structure

```
DailyRewardsPlus/
├── src/main/java/com/example/dailyrewards/
│ ├── DailyRewardsPlus.java # Main plugin class
│ ├── commands/
│ │ └── DailyCommand.java # Command handler
│ ├── gui/
│ │ └── RewardGUI.java # GUI creation and management
│ ├── managers/
│ │ ├── ConfigManager.java # Configuration management
│ │ ├── DataManager.java # Player data persistence
│ │ └── RewardManager.java # Reward logic and distribution
│ └── listeners/
│ └── InventoryListener.java # GUI click handling
├── src/main/resources/
│ ├── plugin.yml # Plugin manifest
│ └── config.yml # Default configuration
└── pom.xml # Maven build configuration
```

## Code Details

### DailyRewardsPlus (Main Class)
- Plugin lifecycle management
- Economy setup via Vault
- Manager initialization
- Command and listener registration

### RewardManager
- Streak calculation and validation
- Reward amount calculation
- Cooldown checking
- Sound and particle effects
- Weekly bonus distribution

### RewardGUI
- Inventory creation (27 slots)
- Item meta with dynamic lore
- Real-time information display
- Color code translation

### DataManager
- YAML file I/O
- Player data caching
- Automatic persistence
- Data reload functionality

### InventoryListener
- GUI click event handling
- Slot validation
- Claim trigger logic

### ConfigManager
- Configuration value retrieval
- Default value fallbacks
- Dynamic reloading

## API Compatibility

- **Minecraft Version:** 1.12.2
- **Bukkit/Spigot:** 1.12.2-R0.1
- **Java:** 1.8+
- **Vault:** 1.7+

## Dependencies

### Build Dependencies
- spigot-api 1.12.2-R0.1-SNAPSHOT
- bukkit 1.12.2-R0.1-SNAPSHOT
- VaultAPI 1.7

### Runtime Dependencies
- Vault (required)
- Any Vault-compatible economy plugin

## Building from Source

### Prerequisites
- JDK 8 or higher
- Apache Maven 3.6+

### Build Steps

```bash
cd DailyRewardsPlus
mvn clean package
```

The compiled JAR will be at `target/DailyRewardsPlus-1.0.0.jar`

## Troubleshooting

### Plugin doesn't enable
- Check that Vault is installed
- Verify Java version (requires 1.8+)
- Check server console for error messages

### Vault economy not found
- Install Vault plugin
- Install an economy plugin (EssentialsX, CMI, etc.)
- Restart server

### GUI not opening
- Verify player has `daily.use` permission
- Check that config.yml is valid YAML
- Look for errors in server console

### Rewards not being given
- Verify economy plugin is running
- Check that player account exists in economy
- Look for economy errors in console

## Configuration Examples

### Higher Base Rewards
```yaml
base-reward: 1000
weekly-bonus: 10000
```

### Disable Effects
```yaml
enable-particles: false
enable-sounds: false
```

### Custom Messages
```yaml
messages:
daily-claim: "&b[Daily Rewards] &aYou earned $%reward% | Streak: %streak% "
weekly-claim: "&6[WEEKLY BONUS] &eYou earned $%reward%! "
```

## Performance

- Efficient player data caching
- Lightweight particle/sound effects
- No database overhead (YAML storage)
- Minimal CPU impact
- Quick claim processing

## Support & Contributing

For issues, bugs, or feature requests, please refer to the documentation above.

## License

This plugin is provided as-is for Spigot server use.

## Version History

### v1.0.0 (2025-12-12)
- Initial release
- Full daily reward system
- GUI menu with real-time updates
- Weekly bonuses with effects
- Complete configuration system
- Data persistence with caching