RedeemVelocity Documentation
Welcome to the RedeemVelocity documentation! This guide provides comprehensive information on installing, configuring, and using the RedeemVelocity plugin for Velocity-powered Minecraft servers. Whether you're a server administrator looking to manage redeemable codes or a server owner interested in enhancing player engagement, this documentation has you covered.
Introduction
RedeemVelocity is a powerful and user-friendly plugin designed for Velocity proxy servers in the Minecraft ecosystem. It enables server administrators to create, manage, and distribute redeemable codes that grant players temporary permissions groups via LuckPerms. Ideal for promotions, rewards, and managing in-game perks, RedeemVelocity ensures efficient and secure distribution of rewards to your player base.

Features

• Create Redeem Codes: Generate unique 6-digit codes linked to specific LuckPerms groups, with customizable duration and usage limits.
• Redeem Codes: Allow players to redeem codes to receive temporary group permissions, enhancing their in-game experience.
• List Active Codes: View all currently active redeem codes, including details like associated group, usage limits, and expiration status.
• Remove Redeem Codes: Administrators can revoke existing codes to prevent further usage.
• Ban Players from Redeeming: Restrict specific players from using redeem codes to maintain controlled distribution.
• Permission-Based Access: Secure command execution with specific permission nodes, ensuring only authorized personnel can manage redeem codes.
• Tab Completion: Enhance user experience with intuitive tab completions for commands and arguments.
• Thread-Safe Operations: Utilizes concurrent data structures to ensure stability in high-traffic environments.

Installation
Prerequisites

• Velocity Proxy Server: Ensure you have a running Velocity proxy server. If not, you can download it from the official Velocity website.
• LuckPerms Plugin: RedeemVelocity integrates with LuckPerms for group management. Install LuckPerms from the LuckPerms GitHub repository.

Steps

1. Download RedeemVelocity:
   
   • Obtain the latest RedeemVelocity JAR file from the official distribution source provided by the plugin author.
2. Add to Plugins Directory:
   
   • Place the RedeemVelocity.jar file into the plugins directory of your Velocity server.
3. Verify Dependencies:
   
   • Ensure that LuckPerms is installed and properly configured in your plugins directory.
4. Start/Restart Velocity Server:
   
   • Restart your Velocity proxy server to load the RedeemVelocity plugin. Upon successful initialization, the plugin will generate necessary data directories if applicable.

Configuration
RedeemVelocity operates primarily through in-memory storage for redeem codes and banned players. Currently, there are no external configuration files required. All management of redeem codes and player bans is handled using the provided commands.

Note: Since redeem codes are stored in memory, they will be reset upon server restart. For persistent storage, consider extending the plugin to save data to disk or integrate with a database in future updates.

Commands
RedeemVelocity introduces a primary command /redeem with several subcommands to manage redeem codes effectively. Below is a detailed breakdown of each subcommand:

1. Create a Redeem Code
/redeem create <lp-group> <time> <usage>

• Description: Generates a new unique 6-digit redeem code.
• Parameters:
  • <lp-group>: The LuckPerms group to assign upon redemption (e.g., vip, mvp).
  • <time>: Duration for which the group will be active. Supported formats:
    • s for seconds (e.g., 10s)
    • m for minutes (e.g., 5m)
    • d for days (e.g., 2d)
    • mo for months (approximated as 30 days, e.g., 1mo)
    • y for years (approximated as 365 days, e.g., 1y)
  • <usage>: Maximum number of times the code can be used.
• Permissions Required: redeemvelo.create
• Example:
  /redeem create vip 7d 100
  
  Creates a code that grants the vip group for 7 days, usable up to 100 times.

2. Use a Redeem Code
/redeem use <6-digit-code>

• Description: Allows players to redeem a code to receive the associated group permissions.
• Parameters:
  • <6-digit-code>: The unique code provided by the administrator.
• Permissions Required: Available to all players by default.
• Example:
  /redeem use 123456
  
  Redeems the code 123456 for the player.

3. List All Active Redeem Codes
/redeem list

• Description: Displays all currently active redeem codes along with their details.
• Permissions Required: redeemvelo.list
• Example:
  /redeem list
  
  Shows a list of all active redeem codes.

4. Remove a Redeem Code
/redeem remove <6-digit-code>

• Description: Deletes a specific redeem code, preventing any further use.
• Parameters:
  • <6-digit-code>: The unique code to be removed.
• Permissions Required: redeemvelo.remove
• Example:
  /redeem remove 123456
  
  Removes the code 123456 from the active list.

5. Ban a Player from Using Redeem Codes
/redeem ban <player>

• Description: Prevents a specified player from using any redeem codes.
• Parameters:
  • <player>: The username of the player to be banned.
• Permissions Required: redeemvelo.ban
• Example:
  /redeem ban PlayerName
  
  Bans PlayerName from using redeem codes.

Permissions
RedeemVelocity utilizes specific permission nodes to control access to its commands and functionalities. It's recommended to manage these permissions using a permissions management plugin like LuckPerms.

Permission Nodes

• Create Redeem Codes: redeemvelo.create
• List Redeem Codes: redeemvelo.list
• Remove Redeem Codes: redeemvelo.remove
• Ban Players from Redeeming: redeemvelo.ban
• Use Redeem Codes: Available to all players by default. To restrict, manage permissions accordingly.

Assigning Permissions
Use your permissions management plugin to assign the above permission nodes to the appropriate user groups or individual players. For example, using LuckPerms:

/lp group admin permission set redeemvelo.create true
/lp group admin permission set redeemvelo.list true
/lp group admin permission set redeemvelo.remove true
/lp group admin permission set redeemvelo.ban true

Usage Examples
Creating a Redeem Code
Command:

/redeem create vip 7d 100

Outcome:

• Generates a unique 6-digit code (e.g., 654321).
• Associates the code with the vip LuckPerms group.
• Sets the code to expire in 7 days.
• Limits usage to 100 times.
• Sends a confirmation message to the administrator:
  §a§lCreated redeem code: 654321
  §7Group: vip, Expires in: 7d, Usage: 100
  

Redeeming a Code as a Player
Command:

/redeem use 654321

Outcome:

• Checks if the code 654321 is valid, not expired, and within usage limits.
• Assigns the vip group to the player for 7 days via LuckPerms.
• Increments the usage count of the code.
• Sends a success message to the player:
  §a§lYou successfully activated vip for 604800s
  

Listing Active Redeem Codes
Command:

/redeem list

Outcome:

• Displays a list of all active redeem codes with details:
  §a§lActive Redeem Codes:
  §7Code: §f654321 §7Group: §fvip §7Usage: §f1/100 §7Expired: false
  

Removing a Redeem Code
Command:

/redeem remove 654321

Outcome:

• Removes the code 654321 from the active list.
• Sends a confirmation message to the administrator:
  §aRemoved redeem code: 654321
  

Banning a Player from Redeeming
Command:

/redeem ban PlayerName

Outcome:

• Adds PlayerName to the banned players list.
• Sends a confirmation message to the administrator:
  §cBanned player PlayerName from using redeem codes.
  

Attempting to Redeem After Ban:

• If PlayerName tries to redeem any code:
  §cYou are banned from using redeem codes!
  

Technical Details
Code Structure

• Main Class: redeemvelocity
  
  • Manages plugin initialization and command registration.
  • Stores redeem codes and banned players using thread-safe data structures.
• RedeemCode Class:
  
  • Holds information about each redeem code, including associated group, expiry time, maximum usage, and current usage count.
• Command Handling:
  
  • Implements the /redeem command with subcommands (create, use, list, remove, ban).
  • Utilizes permission checks to restrict access to sensitive commands.
  • Provides tab completion for commands and arguments to enhance user experience.

Data Management

• Redeem Codes:
  
  • Stored in a ConcurrentHashMap<String, RedeemCode> for thread-safe operations.
  • Each code is a unique 6-digit number.
  • Codes are ephemeral and reset upon server restart.
• Banned Players:
  
  • Stored in a synchronized HashSet<UUID> to prevent concurrent modification issues.
  • Bans persist only in memory and are cleared upon server restart.

Time Parsing

• Supports flexible time formats (s, m, d, mo, y) by parsing input strings and converting them into milliseconds.
• Approximates months as 30 days and years as 365 days for duration calculations.

Group Management

• Integrates with LuckPerms to assign and manage player groups.
• Executes LuckPerms commands asynchronously to prevent server lag:
  lpv user <username> parent addtemp <group> <duration>
  

Concurrency

• Utilizes ConcurrentHashMap and synchronized sets to ensure data integrity in multi-threaded environments.
• Handles command executions and data modifications in a thread-safe manner to prevent race conditions.

Troubleshooting
Common Issues

1. Commands Not Recognized:
   
   • Solution: Ensure that the RedeemVelocity plugin is correctly placed in the plugins directory and that the server has been restarted after adding the plugin.
2. Permission Denied Errors:
   
   • Solution: Verify that the user has the necessary permission nodes assigned via your permissions management plugin.
3. Codes Not Redeeming:
   
   • Solution: Check if the code exists, is not expired, and hasn't exceeded its usage limit. Use the /redeem list command to view active codes.
4. Banned Players Unable to Redeem:
   
   • Solution: Ensure that the player's UUID is correctly added to the banned players set. Remember that bans are temporary and reset upon server restart.
5. LuckPerms Integration Issues:
   
   • Solution: Confirm that LuckPerms is installed and properly configured. Ensure that the lpv command used in RedeemVelocity aligns with your LuckPerms setup.

Logs and Debugging

• Check the server console and logs for any error messages related to RedeemVelocity.
• Enable debug logging if necessary by modifying the plugin code to include more detailed log statements.

Support
For support, updates, or to report issues with RedeemVelocity, please join our Discord Server. Our community and the plugin author are available to assist you with any questions or problems you may encounter.

Changelog
Version 1.0.0

• Initial release of RedeemVelocity.
• Features include creating, using, listing, removing redeem codes, and banning players from redeeming.

License
RedeemVelocity is released under a proprietary license. All rights reserved. Redistribution or modification without explicit permission is prohibited.

Acknowledgements

• LuckPerms: For providing a robust permissions management system.
• Velocity Community: For their continuous support and contributions to the Velocity ecosystem.

Thank you for choosing RedeemVelocity! We hope this plugin enhances your server management and player engagement. For any further assistance, please refer to the Support section or join our Discord community.