Build addons

Abilities

Register abilities and connect them to the player actions handled by Foundry.

On this page

Define an ability

Implement Ability with a non-blank ID and an activate(context) function. cooldownSeconds defaults to 0, which means no cooldown. Positive values set a per-player cooldown after activation.

kotlin
class GreetingAbility : Ability {
    override val id = "example:hello"
    override val cooldownSeconds = 3L

    override fun activate(context: AbilityContext) {
        context.player.sendMessage("Hello from Foundry!")
    }
}

Register and bind

Register the ability during addon startup, then assign its ID to a player and an Action. Foundry stores player bindings in the player's persistent data container.

kotlin
api.abilities.register(GreetingAbility())
api.playerAbilities.assign(player, Action.RIGHT_CLICK, "example:hello")

Supported actions

ActionInput
LEFT_CLICKMain-hand left click, not sneaking
RIGHT_CLICKMain-hand right click, not sneaking
SHIFT_LEFT_CLICKMain-hand left click while sneaking
SHIFT_RIGHT_CLICKMain-hand right click while sneaking
OFFHAND_LEFT_CLICKOffhand left click, not sneaking
OFFHAND_RIGHT_CLICKOffhand right click, not sneaking
OFFHAND_SHIFT_LEFT_CLICKOffhand left click while sneaking
OFFHAND_SHIFT_RIGHT_CLICKOffhand right click while sneaking

Item ability data

ItemAbilityService stores or retrieves an ability ID in an ItemStack's persistent item metadata. It does not currently make that item activate the ability; the interaction listener only checks player action bindings.

kotlin
api.itemAbilities.assign(item, "example:hello")
val abilityId: String? = api.itemAbilities.get(item)
api.itemAbilities.remove(item)