# Mint Economy API with asynchronous transactions, themes, and preferences system # Getting Started ## Gradle ```kotlin repositories { maven("https://gitlab.com/api/v4/projects/77453344/packages/maven") } dependencies { compileOnly("dev.mintychochip:mint-api:1.4") } ``` ## Maven ```xml gitlab https://gitlab.com/api/v4/projects/77453344/packages/maven dev.mintychochip mint-api 1.4 provided ``` # API Versioning Mint uses **major.minor** semantic versioning. Depend on `major.minor` instead of `major.minor.patch` to automatically receive compatible patches without recompilation. Major versions may break compatibility; minor versions add features; patches fix bugs. # Developer API ## Available Services Mint provides multiple services through a centralized service holder: | Service | API Class | Purpose | |---------|-----------|---------| | Economy | `Mint.ECONOMY` | Asynchronous economy transactions | | Theme | `Mint.THEME_SERVICE` | Player text themes with color customization | | Preferences | `Mint.PREFERENCE_SERVICE` | Persistent player preferences | Check if a service is loaded before using: ```java if (!Mint.THEME_SERVICE.isLoaded()) { // Theme service is not available return; } ThemeService service = Mint.THEME_SERVICE.get(); ``` ### Getting the Economy Service ```java EconomyService service = Mint.ECONOMY.get(); if (service == null) { return; // No implementation loaded } ``` ## Economy Providers Register your `EconomyService` implementation with priority: ```java EconomyService impl = new MyEconomyService(); Mint.ECONOMY.register(impl, ServiceHolder.Priority.NORMAL); ``` Multiple implementations can coexist; the highest-priority service is selected. ## Consumers Plugins that depend on the economy service: 1. Add `mint-api` as a **`compileOnly`** dependency 2. Check if an implementation is available before using: ```java if (!Mint.ECONOMY.isLoaded()) { // No implementation is available return; } EconomyService service = Mint.ECONOMY.get(); ``` 3. **Do not shade or relocate the API** - this breaks the service holder pattern ### Using Transactions Transactions provide atomic, multi-operation support with `deposit()`, `withdraw()`, `set()`, `transferTo()`, and `transferFrom()`. ```java TransactionContext ctx = TransactionContext.create( TransactionContext.Actor.player(player), "Payment for service" ); Transaction txn = service.beginTransaction(accountId, ctx); BigDecimal actualDeposited = txn.deposit(new BigDecimal("100.00")); txn.commit() .thenAccept(result -> { // Success - actualDeposited may be less than requested if limits apply }) .exceptionally(ex -> { // Handle failure return null; }); ``` ## Theme API The Theme API provides a powerful, dynamic text styling system that allows plugins to create cohesive, customizable user experiences. Available since version 1.3. ### Overview The Theme system consists of three main components: 1. **Color Themes** - Predefined color palettes that users can switch between 2. **Theme Tags** - Special markup that gets replaced with theme-specific colors 3. **Color Roles** - Player-specific color mappings for titles and prefixes ### Why Use the Theme API? - **Consistent Branding** - All plugin messages follow the same color scheme - **User Customization** - Players can choose themes that match their preferences - **Easy Implementation** - Just use theme tags instead of hardcoded colors - **Automatic Updates** - Theme changes apply everywhere at once - **Accessibility** - Easy to create high-contrast or colorblind-friendly themes ### Creating and Using Themes #### Server Administrators Define themes in your config.yml: ```yaml theme: themes: modern: name: "Modern Blue" colors: accent: "#4A90E2" # Primary accent color primary: "#FFFFFF" # Main text color secondary: "#B8B8B8" # Subtle text color neutral: "#7F8C8D" # Neutral/gray color success: "#27AE60" # Success/green color error: "#E74C3C" # Error/red color warning: "#F39C12" # Warning/yellow color info: "#3498DB" # Info/blue color darkmode: name: "Dark Mode" colors: accent: "#FF6B6B" primary: "#E0E0E0" secondary: "#B0B0B0" neutral: "#606060" success: "#4ECDC4" error: "#FF6B6B" warning: "#FFE66D" info: "#4ECDC4" ``` #### Plugin Developers ```java ThemeService themeService = Mint.THEME_SERVICE.get(); // Check if the service is available if (themeService == null || !themeService.isLoaded()) { // Fallback to default formatting player.sendMessage("Welcome to the server!"); return; } // Send themed messages - the same text works with all themes! themeService.sendThemedMessage(player, "Welcome to the server!"); themeService.sendThemedActionBar(player, "Balance: $100"); themeService.sendThemedTitle(player, "Welcome", "Enjoy your stay!"); // More complex examples with nested tags String message = "⚠ Error: You don't have permission for /tp"; themeService.sendThemedMessage(player, message); // Get player's current theme for custom logic Theme currentTheme = themeService.getPlayerCurrentTheme(player.getUniqueId()); String themeName = currentTheme.name(); ``` ### Available Theme Tags Theme tags are special markup that gets replaced with colors from the current theme. They make your plugin messages automatically adapt to the user's selected theme. | Tag | Purpose | Example | Best Used For | |-----|---------|---------|---------------| | `` | Primary accent color | `Important` | Emphasis, highlights, key information | | `` | Primary text color | `Main text` | Regular messages, most text content | | `` | Secondary text color | `Subtle info` | Metadata, timestamps, less important text | | `` | Neutral/gray color | `Metadata` | Neutral information, separators | | `` | Success/green color | `Completed` | Success messages, confirmations | | `` | Error/red color | `Failed` | Error messages, warnings, failures | | `` | Warning/yellow color | `Attention` | Caution messages, important notices | | `` | Info/blue color | `Notice` | Informational messages, updates | #### Best Practices ```java // Good: Use appropriate tags for message type themeService.sendThemedMessage(player, "Your home was set!"); // Good: Combine tags for complex messages String complexMsg = "⚠ Error: You don't have permission for /tp"; themeService.sendThemedMessage(player, complexMsg); // Bad: Using hardcoded colors (breaks theme consistency) // player.sendMessage(ChatColor.RED + "Error: " + ChatColor.WHITE + "You don't have permission"); // Good: Theme-neutral approach String safeMsg = "Error: You don't have permission for /tp"; themeService.sendThemedMessage(player, safeMsg); ``` ### Managing Themes #### Theme Management for Developers ```java ThemeService themeService = Mint.THEME_SERVICE.get(); // Get player's current theme (returns default if none selected) Theme current = themeService.getPlayerCurrentTheme(player.getUniqueId()); System.out.println("Current theme: " + current.name()); // Set a specific theme for a player themeService.setTheme(player.getUniqueId(), "DarkMode"); // Get all available themes List themes = themeService.getAllThemes(); for (Theme theme : themes) { System.out.println("- " + theme.name() + ": " + theme.displayName()); } // Get a specific theme by name Optional optionalTheme = themeService.get("ModernBlue"); if (optionalTheme.isPresent()) { Theme theme = optionalTheme.get(); // Use theme info } // Get the default theme Theme defaultTheme = themeService.getDefaultTheme(); ``` #### Advanced Theme Features ```java // Color role registry for player prefixes Registry colorRegistry = themeService.getColorRoleRegistry(); // Check if a role exists if (colorRegistry.contains("vip")) { ColorRole vipRole = colorRegistry.get("vip"); // Use the role } // Send themed messages with automatic role resolution themeService.sendThemedMessage(player, "You are now a VIP!"); // Various message types themeService.sendThemedMessage(player, "Welcome to the server!"); themeService.sendThemedActionBar(player, "Loading..."); themeService.sendThemedTitle( player, "Welcome", "Enjoy your stay!" ); ``` #### Player Theme Management Players can manage their themes through commands: ```bash # View current theme /theme # Switch to a specific theme /theme DarkMode /theme ModernBlue /theme Default ``` The Theme API automatically: - Falls back to the default theme if a player's selected theme is removed - Handles theme migrations when themes are renamed or deleted - Maintains consistent theming across all Mint-powered plugins ## Preferences API The Preferences API provides persistent player preferences with type safety and automatic serialization. ### Basic Usage ```java PreferenceService prefService = Mint.PREFERENCE_SERVICE.get(); // Define a preference Preference themePreference = Preference.builder( MINT_PLUGIN, "theme", PreferenceTypes.STRING(), "" ).displayName(Component.text("Theme")).build(); Mint.PREFERENCE_SERVICE.register(themePreference); // Access a preference Player somePlayer; String preferrenceString = Mint.PREFERENCE_SERVICE.get().get(somePlayer.getUniqueId(),themePreference); ``` ### Built-in Preference Types | Type | Class | Description | |------|-------|------------| | String | `StringPreferenceType` | Text preferences | | Integer | `IntegerPreferenceType` | Whole number preferences | | Boolean | `BooleanPreferenceType` | True/false preferences | | Double | `DoublePreferenceType` | Decimal number preferences | | Float | `FloatPreferenceType` | Float number preferences | | Long | `LongPreferenceType` | Long integer preferences | | Short | `ShortPreferenceType` | Short integer preferences | | Byte | `BytePreferenceType` | Byte preferences | | UUID | `UUIDPreferenceType` | UUID preferences | | Character | `CharacterPreferenceType` | Single character preferences | | String List | `StringListPreferenceType` | List of strings | | Enum | `EnumPreferenceType` | Enum values | | Bukkit Location | `LocationPreferenceType` | Minecraft location data | | Bukkit ItemStack | `ItemStackPreferenceType` | Minecraft items | | Bukkit Material | `MaterialPreferenceType` | Minecraft block/material | | Bukkit Registry | `RegistryPreferenceType` | Registry entries | ### Registering Custom Types ```java // Register a custom preference type MyCustomType customType = new MyCustomType(); prefService.registerType(customType); // Register with class mapping prefService.registerType(customType, MyCustomClass.class); ``` ### Preferences UI Preferences are automatically organized in a GUI when players use `/prefs`. The UI groups preferences by type and plugin namespace. ```java // Register a preference for display in the UI Preference maxHomesPref = new Preference<>() { Plugin plugin() { return MyPlugin.getInstance(); } String displayName() { return "max-homes"; } Integer getDefault() { return 3; } PreferenceType type() { return PreferenceTypes.INTEGER; } }; prefService.registerDisplayable(maxHomesPref); ``` # Commands ## Player Commands ### Economy Commands | Command | Description | Permission | |---------|-------------|-----------| | `/mint` | Display plugin version and registered service | None | | `/bal` | Check your balance | `mint.bal` | | `/bal ` | Check another player's balance | `mint.bal.others` | | `/pay ` | Send money to another player | `mint.pay` | | `/baltop` | View top 10 richest players | `mint.baltop` | ### Theme Commands | Command | Description | Permission | |---------|-------------|-----------| | `/theme` | View your current theme | `mint.theme` | | `/theme ` | Set your theme to the specified name | `mint.theme` | ### Preferences Commands | Command | Description | Permission | |---------|-------------|-----------| | `/prefs` | Open preferences GUI | `mint.prefs` | | `/prefs ` | View preferences for a specific plugin | `mint.prefs` | | `/preferences` | Alias for `/prefs` | `mint.prefs` | ## Admin Commands | Command | Description | Permission | |---------|-------------|-----------| | `/eco give ` | Give money to a player | `mint.admin.eco` | | `/eco take ` | Take money from a player | `mint.admin.eco` | | `/eco set ` | Set a player's balance | `mint.admin.eco` | | `/eco reset ` | Reset a player's balance to zero | `mint.admin.eco` |

mintychochip

mintychochip's Plugins

Mint by mintychochip

Alchemica by mintychochip

mintychochip's Organizations

Stars

Watching

Mint by

Alchemica by