PaperMC
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.
-
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.
-
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.
-
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.
if you used AI to generate this, please don't;
Advancements are on the todo list of stuff that would be nice to expose but is blocked by a bunch of other things which need to be done first; This API will not be "safe" as it's exposing raw underlying mojang data stuff which is subject to change and frequently changes, so there would be 0 safety assurance attached to it across versions
I totally understand where you're coming from. I'm a developer myself and fully aware that this area is technically complex and built on top of raw Mojang internals that change frequently.
I used ChatGPT just to help me write things out more clearly and thoroughly, not because I don’t understand what I’m asking for. I simply didn’t feel like spending a bunch of time manually wording everything when I already know what I mean and what I need. The request itself is genuine, and I do understand the implications as someone who would actually use the API.
Appreciate the context and the fact that it's on the todo list!
ChatGPT spewed a whole bunch of text formatted in a manner which is hard to read, if this wasn't already a known desire, this would likely have just been closed for the sake of it being a mess to read.