### Custom Price System Configuration (YAML Example)

Source: https://context7.com/auxilor/ecobits/llms.txt

Illustrates how to configure custom prices for items using EcoBits currencies in other economy-based plugins. This format allows specifying currency requirements for purchases, such as 'crystals:100'. The PriceFactoryCurrency handles affordability checks, deductions, rewards, and multiplier integration.

```yaml
# In other eco plugins, use currencies as prices:
# price: "crystals:100" - Requires 100 crystals
# price: "crystals:50.5" - Requires 50.5 crystals (if decimal enabled)

# Example configuration in other eco plugins:
/*
items:
  diamond_sword:
    price: "crystals:500"

  enchanted_book:
    price: "crystals:250.5"
*/

# The PriceFactoryCurrency handles:
# - Checking if player can afford
# - Deducting currency on purchase
# - Adding currency on reward
# - Respecting multipliers
# - Integration with placeholder system
```

--------------------------------

### Register and Retrieve Currencies with EcoBits API

Source: https://context7.com/auxilor/ecobits/llms.txt

Provides functions to interact with the currency registry in EcoBits. It shows how to retrieve all registered currencies, iterate through their properties, get a specific currency by its ID, and reload currency configurations from the plugin. This is essential for dynamic currency management and updates.

```kotlin
import com.willfp.ecobits.currencies.Currencies
import com.willfp.ecobits.currencies.Currency
import com.willfp.ecobits.EcoBitsPlugin

fun listAllCurrencies() {
    // Get all currencies
    val allCurrencies = Currencies.values()

    println("Registered currencies: ${allCurrencies.size}")
    allCurrencies.forEach { currency ->
        println("ID: ${currency.id}")
        println("Name: ${currency.name}")
        println("Default: ${currency.default}")
        println("Max: ${currency.max ?: "No limit"}")
        println("Payable: ${currency.isPayable}")
        println("Decimal: ${currency.isDecimal}")
        println("Vault: ${currency.isRegisteredWithVault}")
        println("Local: ${currency.isLocal}")
        println("---")
    }
}

fun getCurrencyByID(currencyId: String): Currency? {
    return Currencies.getByID(currencyId)
}

// Update currencies from config (usually called on reload)
fun reloadCurrencies(plugin: EcoBitsPlugin) {
    Currencies.update(plugin)
    println("Currencies reloaded from config")
}
```

--------------------------------

### Get Leaderboard Rankings with Caching - Kotlin

Source: https://context7.com/auxilor/ecobits/llms.txt

Retrieves and displays top players for a specific currency using the EcoBits leaderboard system. Includes automatic caching based on the configured cache-expire-after value (default 300 seconds). The first call fetches from the database and caches the result; subsequent calls within the cache period use the cached data.

```kotlin
import com.willfp.ecobits.currencies.Currencies
import com.willfp.ecobits.currencies.LeaderboardPlace
import org.bukkit.Bukkit

fun displayLeaderboard(currencyId: String, topCount: Int = 10) {
    val currency = Currencies.getByID(currencyId) ?: return

    println("Top $topCount players for ${currency.name}:")

    for (place in 1..topCount) {
        val leaderboardPlace = currency.getLeaderboardPlace(place)

        if (leaderboardPlace != null) {
            val playerName = leaderboardPlace.player.name ?: "Unknown"
            val amount = leaderboardPlace.amount.formatWithExtension()
            println("#$place: $playerName - $amount")
        } else {
            println("#$place: [Empty]")
        }
    }
}

fun checkLeaderboardCaching() {
    val currency = Currencies.getByID("crystals") ?: return

    val first = currency.getLeaderboardPlace(1)
    val firstAgain = currency.getLeaderboardPlace(1)

    println("First place: ${first?.player?.name} with ${first?.amount}")
}
```

--------------------------------

### Get Player Balance with EcoBits API

Source: https://context7.com/auxilor/ecobits/llms.txt

Retrieves a player's balance for a specific currency using the EcoBits API. It demonstrates how to get a currency by its ID and then fetch the player's balance, including formatted and comma-separated representations. Handles cases where the currency might not be found or for offline players.

```kotlin
import com.willfp.ecobits.currencies.Currencies
import com.willfp.ecobits.currencies.getBalance
import org.bukkit.Bukkit
import org.bukkit.entity.Player

fun checkPlayerBalance(player: Player) {
    // Get currency by ID
    val crystalsCurrency = Currencies.getByID("crystals")

    if (crystalsCurrency != null) {
        // Get player's balance
        val balance = player.getBalance(crystalsCurrency)
        player.sendMessage("Your balance: ${balance.toPlainString()} ${crystalsCurrency.name}")

        // Check formatted balance
        val formatted = balance.formatWithExtension() // e.g., "1.5k" or "2.3M"
        player.sendMessage("Formatted: $formatted")

        // Check with commas
        val withCommas = balance.formatWithCommas() // e.g., "1,234.56"
        player.sendMessage("With commas: $withCommas")
    } else {
        player.sendMessage("Currency not found!")
    }
}

// Get balance for offline player
fun checkOfflineBalance(playerName: String) {
    val offlinePlayer = Bukkit.getOfflinePlayer(playerName)
    val currency = Currencies.getByID("crystals")

    if (currency != null && (offlinePlayer.hasPlayedBefore() || offlinePlayer.isOnline)) {
        val balance = offlinePlayer.getBalance(currency)
        println("$playerName has ${balance.toPlainString()} ${currency.name}")
    }
}
```

--------------------------------

### Configure Currencies in config.yml

Source: https://context7.com/auxilor/ecobits/llms.txt

Defines various virtual currencies for the EcoBits plugin. Each currency has unique properties such as ID, display name, starting balance, maximum limit, transferability, decimal support, Vault integration, server-specific scope, and associated commands. This configuration allows for flexible and distinct economic systems within a Minecraft server.

```yaml
server-id: "main" # Server identifier for multi-server setups

cache-expire-after: 300 # Leaderboard cache duration in seconds

currencies:
  - id: crystals # Unique currency identifier
    name: "&bCrystals ❖" # Display name with color codes
    default: 0 # Starting balance for new players
    max: -1 # Maximum balance (-1 for unlimited)
    payable: false # Allow player-to-player transfers
    decimal: true # Enable decimal amounts
    vault: false # Register with Vault API (only one currency)
    local: false # Server-specific currency (doesn't sync)
    commands: # Dedicated commands for this currency
      - crystals
      - ecocrystals

  - id: tokens
    name: "&6Tokens ⭐"
    default: 100
    max: 1000000
    payable: true
    decimal: false
    vault: true # This currency registers with Vault
    local: false
    commands:
      - tokens
      - ecotokens

  - id: serverpoints
    name: "&eServer Points"
    default: 0
    max: -1
    payable: true
    decimal: false
    vault: false
    local: true # Doesn't sync between servers
    commands:
      - points
      - serverpoints
```

--------------------------------

### EcoBits Plugin Dependencies and Configuration

Source: https://context7.com/auxilor/ecobits/llms.txt

Lists the required and optional dependencies for the EcoBits plugin in a Gradle build file and outlines the plugin's core information for the Spigot server's plugin.yml. It specifies the core 'eco' framework, and optional integrations with PlaceholderAPI for dynamic text and Vault for economy API compatibility.

```kotlin
// build.gradle.kts dependencies:
dependencies {
    compileOnly("com.willfp:eco:6.77.0") // Core eco framework
    compileOnly("me.clip:placeholderapi:2.11.6") // Optional placeholder support
    compileOnly("com.github.MilkBowl:VaultAPI:1.7") // Optional Vault support
}
```

```yaml
# plugin.yml:
name: EcoBits
version: 1.10.0
main: com.willfp.ecobits.EcoBitsPlugin
api-version: 1.21
depend:
  - eco
softdepend:
  - PlaceholderAPI
  - Vault
```

--------------------------------

### Give Currency Command - Administrative

Source: https://context7.com/auxilor/ecobits/llms.txt

Administrative command to grant currency to players with optional dynamic currency-specific command aliases. Command can be executed from console or by players with appropriate permissions. Supports both the main /ecobits give syntax and currency-specific shortcuts if configured.

```kotlin
// Command usage from console or player with permission:
// /ecobits give <player> <currency> <amount>
// Example: /ecobits give Steve crystals 500

// Programmatic access:
import com.willfp.ecobits.commands.CommandGive
import com.willfp.ecobits.EcoBitsPlugin

// Dynamic currency-specific commands
// If currency has commands: ["crystals", "ecocrystals"] in config
// Players can use: /crystals give <player> <amount>
// Example: /crystals give Alex 100
```

--------------------------------

### Vault Economy API Usage (Kotlin)

Source: https://context7.com/auxilor/ecobits/llms.txt

Demonstrates how to use the Vault Economy API with Kotlin to manage player balances, withdrawals, deposits, and currency formatting. Requires Vault and a compatible economy plugin. Handles player interactions and checks transaction success.

```kotlin
import net.milkbowl.vault.economy.Economy
import org.bukkit.Bukkit
import org.bukkit.plugin.RegisteredServiceProvider

fun useVaultAPI() {
    val rsp: RegisteredServiceProvider<Economy>? =
        Bukkit.getServer().servicesManager.getRegistration(Economy::class.java)

    if (rsp != null) {
        val economy: Economy = rsp.provider

        val player = Bukkit.getPlayer("Steve")
        if (player != null) {
            // Check balance
            val balance = economy.getBalance(player)
            println("Balance: $balance")

            // Check if player can afford
            if (economy.has(player, 100.0)) {
                // Withdraw money
                val response = economy.withdrawPlayer(player, 100.0)
                if (response.transactionSuccess()) {
                    println("Withdrawn 100, new balance: ${response.balance}")
                } else {
                    println("Transaction failed: ${response.errorMessage}")
                }
            }

            // Deposit money
            val depositResponse = economy.depositPlayer(player, 50.0)
            if (depositResponse.transactionSuccess()) {
                println("Deposited 50, new balance: ${depositResponse.balance}")
            }

            // Format currency
            val formatted = economy.format(1500.0) // Returns "1.5k"

            // Get currency name
            println("Currency: ${economy.currencyNameSingular()}")
        }
    }
}

// Note: Only ONE currency can be registered with Vault
// Set vault: true in config.yml for desired currency
// Bank operations return NOT_IMPLEMENTED (not supported)
```

--------------------------------

### PlaceholderAPI Placeholders for EcoBits (Kotlin)

Source: https://context7.com/auxilor/ecobits/llms.txt

Lists available PlaceholderAPI placeholders for displaying EcoBits currency data. These placeholders allow other plugins to access raw balance, formatted balance, comma-separated values, integer amounts, currency metadata, and leaderboard information.

```kotlin
// Balance placeholders:
// %ecobits_<currency_id>% - Raw balance (e.g., "1234.56")
// %ecobits_crystals% - Example: "1234.56"

// Formatted balance:
// %ecobits_<currency_id>_formatted% - With extension (e.g., "1.2k", "3.4M")
// %ecobits_crystals_formatted% - Example: "1.2k"

// With commas:
// %ecobits_<currency_id>_commas% - Comma-separated (e.g., "1,234.56")
// %ecobits_crystals_commas% - Example: "1,234.56"

// Integer only:
// %ecobits_<currency_id>_integer% - Whole number (e.g., "1234")
// %ecobits_crystals_integer% - Example: "1234"

// Currency metadata:
// %ecobits_<currency_id>_name% - Display name
// %ecobits_crystals_name% - Example: "§bCrystals ❖"

// %ecobits_<currency_id>_max% - Maximum balance
// %ecobits_crystals_max% - Example: "1000000"

// Leaderboard placeholders:
// %ecobits_top_<currency>_<place>_name% - Player name
// %ecobits_top_crystals_1_name% - Example: "Steve"

// %ecobits_top_<currency>_<place>_amount% - Formatted amount
// %ecobits_top_crystals_1_amount% - Example: "1.2k"

// %ecobits_top_<currency>_<place>_amount_raw% - Raw amount
// %ecobits_top_crystals_1_amount_raw% - Example: "1234.56"

// Empty placeholders when no data:
// Configured in lang.yml:
// top.name-empty: "None"
// top.amount-empty: "0"
```

--------------------------------

### Administrative Currency Management Commands

Source: https://context7.com/auxilor/ecobits/llms.txt

Comprehensive administrative commands for managing player currencies including setting exact balance, taking currency, silent operations without notifications, resetting to defaults, and plugin reload. All commands require appropriate administrative permissions.

```kotlin
// Set exact balance:
// /ecobits set <player> <currency> <amount>
// Example: /ecobits set Steve crystals 1000

// Take currency:
// /ecobits take <player> <currency> <amount>
// Example: /ecobits take Steve crystals 50

// Silent give (no notification):
// /ecobits givesilent <player> <currency> <amount>

// Silent take (no notification):
// /ecobits takesilent <player> <currency> <amount>

// Reset to default:
// /ecobits reset <player> <currency>
// Example: /ecobits reset Steve crystals

// Reload plugin:
// /ecobits reload
```

--------------------------------

### Set and Adjust Player Currency Balances with EcoBits API

Source: https://context7.com/auxilor/ecobits/llms.txt

Demonstrates how to manage player currency balances using the EcoBits API. This includes setting an absolute balance, adjusting it by adding or removing amounts, and handling constraints such as maximum balance limits and decimal support. It ensures balances adhere to currency configurations.

```kotlin
import com.willfp.ecobits.currencies.Currencies
import com.willfp.ecobits.currencies.setBalance
import com.willfp.ecobits.currencies.adjustBalance
import org.bukkit.entity.Player
import java.math.BigDecimal

fun manageCurrency(player: Player) {
    val currency = Currencies.getByID("crystals") ?: return

    // Set absolute balance (respects max and min constraints)
    player.setBalance(currency, BigDecimal("1000.50"))

    // Add currency (positive adjustment)
    player.adjustBalance(currency, BigDecimal("250"))

    // Remove currency (negative adjustment)
    player.adjustBalance(currency, BigDecimal("-100"))

    // Handle max balance constraints
    if (currency.max != null) {
        val currentBalance = player.getBalance(currency)
        if (currentBalance >= currency.max) {
            player.sendMessage("You've reached the maximum balance of ${currency.max}")
        }
    }

    // Validate decimal support
    if (!currency.isDecimal) {
        // Only use whole numbers
        player.setBalance(currency, BigDecimal("500"))
    } else {
        // Decimals allowed
        player.setBalance(currency, BigDecimal("500.75"))
    }
}
```

--------------------------------

### Balance Command - Check Currency Balance

Source: https://context7.com/auxilor/ecobits/llms.txt

Retrieves player currency balance with support for checking own balance or other players' balances (with permission). Supports both main command syntax and currency-specific command aliases configured in the plugin.

```kotlin
// Check own balance:
// /ecobits balance <currency>
// Example: /ecobits balance crystals

// With currency-specific command:
// /crystals balance
// /crystals bal

// Check other player's balance (requires permission):
// /ecobits balance <currency> <player>
// Example: /ecobits balance crystals Steve
```

--------------------------------

### Pay Command - Player-to-Player Currency Transfer

Source: https://context7.com/auxilor/ecobits/llms.txt

Enables players to transfer currency to other players with comprehensive validation. Requires currency to have isPayable set to true. Includes error handling for insufficient balance, recipient max balance limits, decimal validation, and self-payment prevention. Online recipients receive notifications.

```kotlin
// Command usage (requires currency.isPayable = true):
// /ecobits pay <player> <currency> <amount>
// Example: /ecobits pay Alex crystals 250

// With currency-specific command:
// /crystals pay <player> <amount>
// Example: /crystals pay Alex 250

// Error handling:
// - Validates sender has sufficient balance
// - Checks if recipient can receive (max balance)
// - Validates currency is payable
// - Rejects decimal amounts if currency.isDecimal = false
// - Prevents self-payment
// - Notifies recipient if online
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.