Skip to main content

Developer API

CocoVouchers provides a comprehensive API for developers to integrate with the plugin, create custom actions, and manage vouchers programmatically.

Getting the API​

import me.upoka.cocoVouchers.api.CocoVouchersAPI;

// Get API instance
CocoVouchersAPI api = CocoVouchers.getAPI();

API Methods​

Voucher Management​

Create Voucher​

/**
 * Create a new voucher from template
 * @param name Voucher name
 * @return true if created successfully
 */
boolean createVoucher(String name);

Example:

boolean created = api.createVoucher("custom_reward");
if (created) {
    // Voucher created successfully
}

Delete Voucher​

/**
 * Delete a voucher
 * @param name Voucher name
 * @return true if deleted successfully
 */
boolean deleteVoucher(String name);

Get Voucher​

/**
 * Get a voucher by name
 * @param name Voucher name
 * @return Optional containing the voucher if found
 */
Optional<Voucher> getVoucher(String name);

Example:

api.getVoucher("vip_crate").ifPresent(voucher -> {
    String displayName = voucher.getItem().getItemMeta().getDisplayName();
    // Use voucher data
});

Get All Vouchers​

/**
 * Get all loaded vouchers
 * @return List of all vouchers
 */
List<Voucher> getAllVouchers();

Player Operations​

Give Voucher​

/**
 * Give a voucher to a player
 * @param player Target player
 * @param voucherName Voucher name
 * @param amount Amount to give
 * @return true if given successfully
 */
boolean giveVoucher(Player player, String voucherName, int amount);

Example:

Player player = Bukkit.getPlayer("Notch");
if (player != null) {
    api.giveVoucher(player, "diamond_crate", 5);
}

Check if Item is Voucher​

/**
 * Check if an ItemStack is a voucher
 * @param item ItemStack to check
 * @return Optional containing the voucher if it is one
 */
Optional<Voucher> isVoucher(ItemStack item);

Example:

ItemStack itemInHand = player.getInventory().getItemInMainHand();
api.isVoucher(itemInHand).ifPresent(voucher -> {
    player.sendMessage("You're holding: " + voucher.getName());
});

Use Voucher​

/**
 * Programmatically use a voucher for a player
 * @param player Player using the voucher
 * @param voucher Voucher to use
 * @return CompletableFuture that completes when actions finish
 */
CompletableFuture<Boolean> useVoucher(Player player, Voucher voucher);

Example:

api.getVoucher("reward").ifPresent(voucher -> {
    api.useVoucher(player, voucher).thenAccept(success -> {
        if (success) {
            // Voucher used successfully
        }
    });
});

Custom Actions​

Register custom action types that can be used in voucher configurations.

Register Action Factory​

/**
 * Register a custom action factory
 * @param identifier Action identifier (case-insensitive)
 * @param factory Factory that creates the action from value
 */
void registerActionFactory(String identifier, Function<String, VoucherAction> factory);

Example:

api.registerActionFactory("FIREWORK", value -> new VoucherAction() {
    @Override
    public void execute(Player player) {
        // Parse value and spawn firework
        Location loc = player.getLocation();
        // Firework logic here
    }
});

Usage in voucher.yml:

actions:
  - "[FIREWORK] RED,BALL,5"

Unregister Action Factory​

/**
 * Remove a registered action factory
 * @param identifier Action identifier
 */
void unregisterActionFactory(String identifier);

Get Registered Actions​

/**
 * Get all registered action type identifiers
 * @return Set of registered identifiers
 */
Set<String> getRegisteredActionTypes();

Custom Requirements​

Register custom requirement types.

Register Requirement Factory​

/**
 * Register a custom requirement factory
 * @param identifier Requirement identifier
 * @param factory Factory creating requirement from value and inverse flag
 */
void registerRequirementFactory(String identifier, 
    BiFunction<String, Boolean, VoucherRequirement> factory);

Example:

api.registerRequirementFactory("LEVEL", (value, inverse) -> new VoucherRequirement() {
    @Override
    public boolean check(Player player) {
        int required = Integer.parseInt(value);
        boolean hasLevel = player.getLevel() >= required;
        return inverse ? !hasLevel : hasLevel;
    }
    
    @Override
    public String getFailureMessage(Player player) {
        return "You need level " + value + " to use this!";
    }
});

Usage in voucher.yml:

requirements:
  - "[LEVEL] 30"
  - "[!LEVEL] 100"  # Inverse - must be below 100

Maven Dependency​

<repository>
    <id>cocostudios</id>
    <url>https://repo.cocostudios.net/releases</url>
</repository>

<dependency>
    <groupId>me.upoka</groupId>
    <artifactId>CocoVouchers</artifactId>
    <version>1.0</version>
    <scope>provided</scope>
</dependency>

Gradle Dependency​

repositories {
    maven { url 'https://repo.cocostudios.net/releases' }
}

dependencies {
    compileOnly 'me.upoka:CocoVouchers:1.0'
}

Complete Example​

public class MyPlugin extends JavaPlugin {
    
    @Override
    public void onEnable() {
        // Wait for CocoVouchers to load
        Bukkit.getScheduler().runTaskLater(this, () -> {
            CocoVouchersAPI api = CocoVouchers.getAPI();
            
            // Register custom action
            api.registerActionFactory("HEAL", value -> player -> {
                double amount = Double.parseDouble(value);
                double newHealth = Math.min(player.getHealth() + amount, 
                    player.getMaxHealth());
                player.setHealth(newHealth);
            });
            
            // Register custom requirement
            api.registerRequirementFactory("HEALTH", (value, inverse) -> {
                double required = Double.parseDouble(value);
                return new VoucherRequirement() {
                    @Override
                    public boolean check(Player player) {
                        boolean hasHealth = player.getHealth() >= required;
                        return inverse ? !hasHealth : hasHealth;
                    }
                    
                    @Override
                    public String getFailureMessage(Player player) {
                        return "You need " + required + " health!";
                    }
                };
            });
            
            getLogger().info("Custom actions registered!");
        }, 1L);
    }
    
    @Override
    public void onDisable() {
        CocoVouchersAPI api = CocoVouchers.getAPI();
        api.unregisterActionFactory("HEAL");
        api.unregisterRequirementFactory("HEALTH");
    }
}

Usage:

requirements:
  - "[HEALTH] 10"
actions:
  - "[HEAL] 20"