Mint

Mint

Economy API with asynchronous transactions, themes, and preferences system

Getting Started

Gradle

repositories {
    maven("https://gitlab.com/api/v4/projects/77453344/packages/maven")
}

dependencies {
    compileOnly("dev.mintychochip:mint-api:1.4")
}

Maven

<repository>
   <id>gitlab</id>
   <url>https://gitlab.com/api/v4/projects/77453344/packages/maven</url>
</repository>

<dependency>
   <groupId>dev.mintychochip</groupId>
   <artifactId>mint-api</artifactId>
   <version>1.4</version>
   <scope>provided</scope>
</dependency>

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:

Check if a service is loaded before using:

if (!Mint.THEME_SERVICE.isLoaded()) {
    // Theme service is not available
    return;
}
ThemeService service = Mint.THEME_SERVICE.get();

Getting the Economy Service

EconomyService service = Mint.ECONOMY.get();
if (service == null) {
    return; // No implementation loaded
}

Economy Providers

Register your EconomyService implementation with priority:

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:

   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().

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:

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

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, "<accent>Welcome</accent> <primary>to the server!</primary>");
themeService.sendThemedActionBar(player, "<neutral>Balance:</neutral> <accent>$100</accent>");
themeService.sendThemedTitle(player, "<accent>Welcome</accent>", "<secondary>Enjoy your stay!</secondary>");

// More complex examples with nested tags
String message = "<info>⚠</info> <error>Error:</error> <secondary>You don't have permission for</secondary> <accent>/tp</accent>";
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.

Best Practices

// Good: Use appropriate tags for message type
themeService.sendThemedMessage(player, "<success>Your home was set!</success>");

// Good: Combine tags for complex messages
String complexMsg = "<info>⚠</info> <error>Error:</error> <secondary>You don't have permission for</secondary> <accent>/tp</accent>";
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>Error:</error> <secondary>You don't have permission for</secondary> <accent>/tp</accent>";
themeService.sendThemedMessage(player, safeMsg);

Managing Themes

Theme Management for Developers

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<Theme> themes = themeService.getAllThemes();
for (Theme theme : themes) {
    System.out.println("- " + theme.name() + ": " + theme.displayName());
}

// Get a specific theme by name
Optional<Theme> 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

// Color role registry for player prefixes
Registry<String, ColorRole> 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, "<accent>You are now a VIP!</accent>");

// Various message types
themeService.sendThemedMessage(player, "<info>Welcome to the server!</info>");
themeService.sendThemedActionBar(player, "<neutral>Loading...</neutral>");
themeService.sendThemedTitle(
    player,
    "<accent>Welcome</accent>",
    "<secondary>Enjoy your stay!</secondary>"
);

Player Theme Management

Players can manage their themes through commands:

# 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

PreferenceService prefService = Mint.PREFERENCE_SERVICE.get();

// Define a preference
Preference<String> 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

Registering Custom Types

// 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.

// Register a preference for display in the UI
Preference<Integer> maxHomesPref = new Preference<>() {
    Plugin plugin() { return MyPlugin.getInstance(); }
    String displayName() { return "max-homes"; }
    Integer getDefault() { return 3; }
    PreferenceType<Integer> type() { return PreferenceTypes.INTEGER; }
};

prefService.registerDisplayable(maxHomesPref);

Commands

Player Commands

Economy Commands

Theme Commands

Preferences Commands

Admin Commands