AdvancementLib

AdvancementLib

AdvancementLib is a modern, fluent Java library for creating custom advancements in PaperMC Minecraft plugins.
It lets you easily register and manage advancements that respond to any Bukkit event, using a powerful builder-based API.

---

✨ Features

• Register custom triggers: Listen for any Bukkit event (e.g., block break, entity death, player action) as an advancement trigger.
• Custom conditions: Define your own logic to decide when an advancement should progress or be granted—perfect for unique gameplay challenges.
• Support for vanilla & custom advancements: Grant both built-in Minecraft advancements and your own custom ones.
• Progress tracking: Easily set multistep advancements (e.g., "break 100 blocks") with automatic progress tracking per player.
• Builder API: Use a fluent builder to configure triggers, conditions, and progress logic.
• Custom progress increments: Determine how much progress each event grants (default is 1, but can be customized).

---

🚀 Getting Started

1. Add as a Dependency

Add AdvancementLib as a dependency in your project using your preferred build tool or project setup method.

Note: Add the PaperMC repository if not already present.

2. Basic Usage

Register an Advancement

import io.github.lambdaphoenix.advancementLib.AdvancementAPI;

AdvancementAPI api = new AdvancementAPI(plugin);

api.register(BlockBreakEvent.class)
    .advancementKey("myplugin:break_10_stone")
    .condition(
        (player, event) -> event.getBlock().getType() == Material.STONE
    )
    .targetValue(10)
    .grantMode(GrantMode.ALL_AT_ONCE)
    .build();

Grant Modes

• ALL_AT_ONCE: Grants the advancement when the target is reached.
• STEP_BY_STEP: Grants one criterion at a time (shows progress bar in-game).

Custom Player Extractor

api.register(CustomEvent.class)
    .advancementKey("myplugin:custom_event")
    .playerExtractor(event -> event.getWhoDidIt())
    .build();

📚 API Highlights & Documentation

• AdvancementAPI – Main entry point for registering advancements.
• AdvancementRegisterBuilder – Fluent builder for all advancement options.
• GrantMode – Enum for grant behavior: all at once or step-by-step.
• PlayerExtractor – Interface for mapping any event to a Player.

The latest Javadoc is automatically published to GitHub Pages:

View the Javadoc here