JECurrency Documentation
Complete Usage Guide & Configuration Manual
Quick Start Guide
First Installation
- Download & Install: Place JECurrency.jar in your plugins/ folder
- Start Server: Boot your server to generate initial configuration files
- Check Console: Verify successful loading (look for JECurrency startup messages)
- Test Commands: Run /currencies in-game to open the management GUI
Creating Your First Currency
- Execute /currencies in-game
- Click the "Create Currency" button (requires currencies.command.create permission)
- Follow the anvil-based creation wizard:
- Identifier: Enter a unique name (e.g., "coins", "gems", "tokens")
- Symbol: Choose a display symbol (e.g., "$", "", "")
- Icon: Select a Material for GUI representation
- Prefix/Suffix: Optional formatting for balance displays
- Confirm creation - all online players automatically receive accounts
Player Usage Guide
Checking Balances
Code (Text):
/currency # View all your balances
/currency coins # View specific currency balance
/currency JExcellence # View another player's balances (with permission)
/currency gems JExcellence # View specific player's specific currency
Currency Management GUI
Access the main interface with
/currencies:
Overview Tab:
- Browse all available currencies with pagination
- View currency details (symbol, balances, player count)
- Access leaderboards for each currency
- Quick balance checks and comparisons
Create Tab: (Admin Only)
- Interactive currency creation wizard
- Real-time validation of inputs
- Preview currency appearance before creation
- Automatic player account provisioning
Edit Tab: (Admin Only)
- Modify existing currency properties
- Update symbols, icons, prefixes, suffixes
- Changes apply immediately to all players
- Validation prevents conflicts
Delete Tab: (Admin Only)
- Safe currency removal with impact assessment
- Preview affected players and total balances
- Multiple confirmation steps prevent accidents
- Complete cleanup of all related data
Transaction Logs
Use
/currencylog to access comprehensive logging:
Code (Text):
/currencylog view # Browse transaction history
/currencylog view 2 # Jump to specific page
/currencylog filter # Open interactive filter menu
/currencylog filter player JExcellence # Filter by specific player
/currencylog filter currency coins # Filter by currency type
/currencylog filter operation deposit # Show only deposits
/currencylog clear # Remove all active filters
/currencylog stats # View transaction statistics
/currencylog export # Export logs to file (admin only)
⚙️ Configuration Guide
️ Database Configuration
JECurrency supports multiple database backends. Configure in
hibernate.properties:
H2 Database (Default - File-based):
Code (Text):
hibernate.connection.driver_class=org.h2.Driver
hibernate.connection.url=jdbc:h2:./plugins/JECurrency/database/currency
hibernate.connection.username=sa
hibernate.connection.password=
hibernate.dialect=org.hibernate.dialect.H2Dialect
hibernate.hbm2ddl.auto=update
MySQL Configuration:
Code (Text):
hibernate.connection.driver_class=com.mysql.cj.jdbc.Driver
hibernate.connection.url=jdbc:mysql://localhost:3306/jecurrency
hibernate.connection.username=your_username
hibernate.connection.password=your_password
hibernate.dialect=org.hibernate.dialect.MySQLDialect
hibernate.hbm2ddl.auto=update
PostgreSQL Configuration:
Code (Text):
hibernate.connection.driver_class=org.postgresql.Driver
hibernate.connection.url=jdbc:postgresql://localhost:5432/jecurrency
hibernate.connection.username=your_username
hibernate.connection.password=your_password
hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
hibernate.hbm2ddl.auto=update
Translation Configuration
Basic Translation Setup:
- Navigate to plugins/JECurrency/translations/
- Edit translation.yml:
Code (Text):
defaultLanguage: en
supportedLanguages: [en, de, fr, es] # Add your languages
- Create language files (e.g., fr.yml, es.yml)
- Use /r18n reload to apply changes
Custom Language File Example:
Code (Text):
# fr.yml - French translations
currency:
balance:
own: "<gradient:#FFD700:#FFA500> Vos soldes:</gradient>"
other: "<gradient:#FFD700:#FFA500> Soldes de %player%:</gradient>"
create:
success: "<green>✅ Devise '%currency%' créée avec succès!</green>"
error: "<red>❌ Erreur lors de la création de la devise</red>"
gui:
title:
overview: "Aperçu des Devises"
create: "Créer une Devise"
edit: "Modifier la Devise"
Translation Management Commands:
Code (Text):
/r18n reload # Reload all translation files
/r18n missing # Check for missing translation keys
/r18n missing fr # Check missing keys for French
/r18n missing fr 2 # Browse missing keys (page 2)
Permission System
Player Permissions
Code (Text):
# Basic currency access
currency.command # View own balances
currency.command.other # View other players' balances
# Currency management GUI
currencies.command # Access /currencies GUI
currencies.command.overview # View currency overview tab
Administrative Permissions
Code (Text):
# Currency management
currencies.command.create # Create new currencies
currencies.command.update # Edit existing currencies
currencies.command.delete # Delete currencies
# Advanced administration
jecurrency.admin.reset # Reset player balances
jecurrency.admin.delete # Administrative currency deletion
jecurrency.admin.export # Export transaction logs
jecurrency.admin.* # All administrative permissions
# Logging system
pcurrencylog.command # Access transaction logs
Translation Permissions
Code (Text):
r18n.reload # Reload translation files
r18n.missing # Check missing translation keys
️ Console Administration
Direct Balance Management
Console-only commands for server administration:
Code (Text):
# Deposit currency to players
cdeposit JExcellence coins 1000
cdeposit PlayerName gems 500
# Withdraw currency from players
cwithdraw JExcellence coins 250
cwithdraw PlayerName gems 100
Usage Examples:
- Daily Rewards: cdeposit %player% dailycoins 100
- Event Prizes: cdeposit WinnerName eventTokens 500
- Punishment: cwithdraw RuleBreaker coins 1000
- Shop Purchases: cwithdraw %player% gems 50
Advanced Configuration
Performance Optimization
Database Connection Pooling:
Code (Text):
# Add to hibernate.properties for better performance
hibernate.connection.pool_size=10
hibernate.c3p0.min_size=5
hibernate.c3p0.max_size=20
hibernate.c3p0.timeout=300
hibernate.c3p0.max_statements=50
hibernate.c3p0.idle_test_period=3000
Caching Configuration:
Code (Text):
# Enable second-level cache for better performance
hibernate.cache.use_second_level_cache=true
hibernate.cache.region.factory_class=org.hibernate.cache.caffeine.CaffeineCacheRegionFactory
hibernate.cache.use_query_cache=true
Security Best Practices
- Database Security: Use strong passwords and limit database user permissions
- Permission Groups: Create role-based permission groups for different staff levels
- Regular Backups: Backup your database regularly, especially before major updates
- Log Monitoring: Regularly review transaction logs for suspicious activity
Developer Integration
API Usage Examples
Basic Integration Setup:
Code (Text):
public class MyEconomyPlugin extends JavaPlugin {
private CurrencyAdapter currencyAdapter;
@Override
public void onEnable() {
// Get the adapter
currencyAdapter = Bukkit.getServicesManager().load(CurrencyAdapter.class);
if (currencyAdapter == null) {
getLogger().warning("JECurrency not found!");
return;
}
getLogger().info("Successfully hooked into JECurrency!");
}
}
Advanced Balance Operations:
Code (Text):
// Check if player has enough balance
public CompletableFuture<Boolean> hasEnoughBalance(OfflinePlayer player, String currencyId, double amount) {
return currencyAdapter.getBalance(player, currencyId)
.thenApply(balance -> balance >= amount);
}
// Transfer money between players
public CompletableFuture<Boolean> transferMoney(OfflinePlayer from, OfflinePlayer to, String currencyId, double amount) {
return currencyAdapter.withdraw(from, currencyId, amount)
.thenCompose(withdrawResult -> {
if (withdrawResult.isSuccess()) {
return currencyAdapter.deposit(to, currencyId, amount)
.thenApply(depositResult -> depositResult.isSuccess());
}
return CompletableFuture.completedFuture(false);
});
}
Event Listening:
Code (Text):
@EventHandler
public void onBalanceChange(BalanceChangeEvent event) {
Player player = event.getPlayer();
Currency currency = event.getCurrency();
double oldBalance = event.getOldBalance();
double newBalance = event.getNewBalance();
// React to balance changes
if (newBalance > oldBalance) {
player.sendMessage("You received " + (newBalance - oldBalance) + " " + currency.getSymbol());
}
}
@EventHandler
public void onCurrencyCreate(CurrencyCreatedEvent event) {
Currency currency = event.getCurrency();
Player creator = event.getInitiator();
// Announce new currency creation
Bukkit.broadcastMessage("New currency created: " + currency.getIdentifier());
}
️ Troubleshooting Guide
❗ Common Issues & Solutions
Plugin Won't Load:
- Check Java Version: Ensure you're running Java 21+
- Verify Bukkit/Spigot Version: Must be 1.19 or higher
- Check Dependencies: InventoryFramework should auto-inject
- Review Console Logs: Look for specific error messages
Database Connection Issues:
- Verify Credentials: Check username/password in hibernate.properties
- Test Connection: Ensure database server is accessible
- Check Drivers: Ensure JDBC drivers are available
- Firewall Settings: Verify database port is open
GUI Not Opening:
- Check Permissions: Ensure player has currencies.command
- InventoryFramework: Verify the framework loaded correctly
- Resource Pack: Some custom items may require resource packs
- Client Version: Ensure client supports the server version
Translation Issues:
- File Encoding: Ensure translation files are UTF-8 encoded
- YAML Syntax: Validate YAML formatting in translation files
- Missing Keys: Use /r18n missing to identify gaps
- Reload Required: Use /r18n reload after changes
Debug Information
When reporting issues, please provide:
- Server Version: Bukkit/Spigot version and build number
- Java Version: Java runtime version
- Plugin Version: JECurrency version (Free/Premium)
- Error Logs: Complete console error messages
- Configuration: Relevant config file contents
- Steps to Reproduce: Detailed reproduction steps
Best Practices
️ Server Setup Recommendations
- Regular Backups: Schedule automatic database backups
- Monitoring: Set up log monitoring for unusual activity
- Testing Environment: Test configuration changes on a development server
- Permission Hierarchy: Use inheritance to simplify permission management
- Documentation: Document your custom currencies and their purposes
Currency Design Tips
- Meaningful Names: Use descriptive identifiers (coins, gems, tokens)
- Consistent Symbols: Choose symbols that fit your server theme
- Balanced Economy: Plan currency values and exchange rates carefully
- Player Education: Clearly communicate currency purposes to players
- Regular Review: Monitor currency usage and adjust as needed
Quick Reference
Essential Commands Cheat Sheet
Code (Text):
# Player Commands
/currency # View balances
/currencies # Open management GUI
/currencylog view # View transaction logs
# Admin Commands (Console)
cdeposit <player> <currency> <amount> # Add money
cwithdraw <player> <currency> <amount> # Remove money
# Translation Commands
/r18n reload # Reload translations
/r18n missing # Check missing keys
Need more help? Join our Discord community!</B]
Discord: https://discord.gg/m5XpbdQv6V
Documentation for JECurrency v2.0.0 | Last Updated: 2024 | For support visit our Discord