Suggestion: Public API for Custom Advancements

Is your feature request related to a problem?

Yes, this request is related to the lack of a safe and stable way to create and manage custom advancements at runtime in the current API.

Currently, the only available method is UnsafeValues#loadAdvancement, which:

Is marked as unsafe and not guaranteed to work across versions.

May break due to implementation changes.

Requires raw JSON strings, making dynamic or programmatic usage cumbersome.

Is not designed for public, long-term plugin use.

This makes it very difficult for plugin developers to:

Dynamically create progression systems, tutorials, or achievements.

Build gameplay mechanics that integrate with the advancement UI (toasts, tabs, etc.).

Offer flexible and immersive experiences without relying on datapacks or manual advancement files.

A dedicated public API would solve this by allowing safe, readable, and version-resilient management of advancements, improving developer experience and enabling richer gameplay features on Paper servers.

Describe the solution you'd like.

I would like to see a public API in Paper for creating, modifying, and managing custom advancements at runtime.

This API should allow plugin developers to:

Define advancements using a builder-style syntax (e.g. title, description, icon, background, parent, criteria).

Register and unregister advancements programmatically without relying on JSON files or server reloads.

Manage player progress (grant/revoke specific criteria or entire advancements).

Listen for events like PlayerAdvancementDoneEvent for custom handling.

The goal is to provide a version-safe, developer-friendly alternative to UnsafeValues#loadAdvancement, aligning with Paper’s standard of offering stable APIs for core Minecraft features.

Describe alternatives you've considered.

1. UnsafeValues#loadAdvancement
   This method allows loading advancements from JSON strings but is marked as unsafe and may break between Minecraft versions. It is not intended for long-term or public use and lacks proper error handling or type safety.

2. Predefined advancements via datapacks
   While functional, datapacks require static JSON files and server reloads to apply changes. They cannot be easily modified or generated at runtime by plugins, making them unsuitable for dynamic gameplay systems.

3. Reflection and NMS-based solutions
   These approaches are version-dependent, fragile, and discouraged by Paper's own development guidelines. They add maintenance burden and can break silently with version updates.

Other

Custom advancements are a powerful native Minecraft mechanic that can greatly enhance gameplay when made accessible to plugin developers. Features like toast messages, advancement tabs, and progress tracking are already deeply integrated into the vanilla client, making them ideal for immersive tutorials, RPG systems, milestone rewards, and more.

Given that Paper already exposes many core systems (e.g. boss bars, scoreboards, attributes) in a developer-friendly way, advancements are one of the last major areas still limited to unsafe or static solutions.

Providing a public API for advancements would:

Align Paper with modern plugin development practices.

Encourage innovative server-side systems that are fully client-integrated.

Reduce the need for risky workarounds and external tooling.

I’d be happy to assist in API design discussions or testing if this feature moves forward.

Start by reviewing the existing UnsafeValues#loadAdvancement entry point and the mentioned PlayerAdvancementDoneEvent. Clarify the scope and design of a stable public API for defining, registering, unregistering, and managing advancement progress. Done requires an agreed API design that covers the requested runtime operations and event behavior.