API reference

The entry point is zone.vao.claimo.ClaimoApi. It exposes requirement registration, reward actions, read-only stats, usage and cooldown data, voucher items, programmatic voucher management, and a redeem flow that reports its outcome.

`ClaimoApi`

Member	Purpose
`registerRequirement(type, factory)`	Register a requirement type.
`registerRequirement(type, factory, inputs)`	Register a type and declare its creator input fields.
`unregisterRequirement(type)`	Remove a registered type.
`requirements`	The `RequirementRegistry` (`isRegistered`, `types`, …).
`stats`	`ClaimoStats` — read-only player statistics.
`vouchers()`	List loaded vouchers.
`voucher(id)`	Look one voucher up by id.
`redeem(player, voucherId)`	Run the full redeem flow programmatically.
`redeemWithResult(player, voucherId)`	Like `redeem`, but returns a `CompletableFuture<RedeemResult>` with the outcome.
`globalUses(voucherId)`	Total redemptions of a code across all players.
`playerUses(player, voucherId)`	A player’s redemptions of a code.
`cooldownRemaining(player, voucherId)`	Milliseconds until the player may redeem again (0 = ready).
`clearCooldown(player, voucherId)`	Drop a player’s stored cooldown for a code.
`buildVoucherItem(voucherId, amount)`	Build the code’s `ItemStack` form, or null without an `item` section.
`giveVoucherItem(player, voucherId, amount)`	Hand the item form to an online player.
`queueVoucherItem(playerName, voucherId, amount)`	Give now if online, otherwise deliver on next join.
`createVoucher(id, settings)`	Write a new voucher file from a map of yaml keys and reload.
`deleteVoucher(id)`	Delete a voucher file and reload.
`generateCodes(templateId, amount)`	Clone a code into hidden one-time copies; returns the new ids.
`registerRewardAction(name, action)`	Register a custom reward run by `action:<name>` cmd lines.
`unregisterRewardAction(name)`	Remove a registered reward action.
`reload()`	Reload config and voucher files.

Redeem outcomes

redeemWithResult completes with a RedeemResult once the (possibly async) flow ends: SUCCESS, NOT_FOUND, EXPIRED, NOT_STARTED, ON_COOLDOWN, LIMIT_REACHED, CANNOT_AFFORD, PAYMENT_UNAVAILABLE, AWAITING_CONFIRMATION, REQUIREMENTS_NOT_MET, CANCELLED or PLAYER_OFFLINE.

Reward actions

A registered reward action turns a voucher cmd line into a callback instead of a dispatched command — rewards that aren’t commands at all:

ClaimoApi.registerRewardAction("discord-role") { player, args ->
    discord.assignRole(player.uniqueId, args)
}

cmd:
  - "give %player% diamond 3"        # still a normal command
  - "action:discord-role vip"        # runs the addon callback with args "vip"

The action runs on the redeeming player’s scheduler thread (Folia-safe); %player% and PlaceholderAPI placeholders in the line are resolved before your callback sees args. An unknown action name logs a console warning and is skipped.

`ClaimoStats`

Read-only player statistics, reachable via ClaimoApi.stats:

Method	Returns
`blocksMined(player)`	Total blocks the player has broken.
`blocksMined(player, whitelist, blacklist)`	Total broken, filtered by material lists.
`playtimeSeconds(player)`	The player’s total play-time in seconds.

Requirement building blocks

These types live in the zone.vao.claimo.requirement package:

Type	Role
`Requirement`	The check you implement — `check(context)` returns a `CompletableFuture<RequirementResult>`.
`RequirementContext`	Passed to `check` — exposes the `player`.
`RequirementResult`	`satisfied(description)` / `unsatisfied(description)`.
`RequirementConfig`	The parsed config for one requirement entry — `getString`, `getInt`, `getLong`, `getDouble`, `getBoolean`, `getStringList`, `has`.
`RequirementInput`	Creator field descriptors: `TextInput`, `NumberInput`, `BoolInput`.
`RequirementRegistry`	The live registry — `register`, `isRegistered`, `types`, `inputs(type)`.

Where things live

Full example

Putting registration, an event listener and stats together:

import org.bukkit.plugin.java.JavaPlugin
import zone.vao.claimo.ClaimoApi
import zone.vao.claimo.requirement.RequirementInput

class MyAddon : JavaPlugin() {
    override fun onEnable() {
        ClaimoApi.registerRequirement(
            "tiktok_follow",
            { cfg -> TikTokFollowRequirement(cfg.getString("account")!!) },
            listOf(RequirementInput.TextInput("account", "TikTok account")),
        )
        server.pluginManager.registerEvents(RedeemStats(), this)
    }

    override fun onDisable() {
        ClaimoApi.unregisterRequirement("tiktok_follow")
    }
}