Gardin's Advancement

This is my first time uploading something here; honestly, I'm a bit nervous.
Gardin's Advancement

Dependencies:
PlaceholderAPI
https://www.spigotmc.org/resources/placeholderapi.6245/
UltimateAdvancementAPI
https://www.spigotmc.org/resources/ultimateadvancementapi-1-15-26-1-2.95585/

You don't want to write your own data packs because they are too complicated.
You want a plugin that allows you to add custom vanilla-style advancements to your server through a much more user-friendly YAML configuration.
However, traditional advancement systems have always relied on event listeners implemented by plugin developers.
This creates limitations for server owners:
Traditional achievement plugins usually detect player actions through event listeners.
The problem is that when another plugin introduces new items, skills, or gameplay systems, the achievement system cannot recognize these new features unless a specific compatibility integration has been developed.
Nowadays, PlaceholderAPI has become widely adopted across the Minecraft plugin ecosystem. More and more plugins use placeholders as a way to expose their internal data and states.
Therefore, using placeholders as advancement conditions is a natural solution.
It keeps the advancement system lightweight while providing compatibility with any plugin that exposes PlaceholderAPI values.

Gardin's Advancement is designed around this concept.

Gardin's Advancement uses PlaceholderAPI as a unified data interface.
Instead of depending on a large number of event listeners, the plugin uses Placeholder expressions as its universal condition system.
As long as a plugin provides PlaceholderAPI support, it can directly participate in advancement checks without requiring additional compatibility modules.
Example:
This configuration means:
- The player's level is 15 or higher.
- The player is currently jailed in Towny.
Only when both conditions are satisfied will the player receive the corresponding advancement.
With this design, theoretically any plugin supporting PlaceholderAPI can directly become a source of advancement conditions.
We also support progress bars.
Currently, only one variable is supported.
This will display an advancement progress bar.
When the player's level reaches 10, the advancement will be completed automatically.
Please note:
Due to the limitation of the vanilla system, only integer values are supported.
If your Placeholder returns a non-numeric value, it will always be treated as 0.
If your Placeholder returns a floating-point number, it will be rounded down automatically.
The condition system and progress bar system can be used together or independently.


For more complex logic, you can combine PlaceholderAPI's JavaScript expansion or other scripting plugins to create custom conditions.

Supported Expressions
Gardin's Advancement supports the following expressions:

• !
• <
• >
• ==
  
• !=
• >=
• <=
• &&
• ||
• ()

Example Configuration
> Note: Minecraft only supports one root advancement per advancement tab.
> The root advancement acts as the title of the tab, and its icon is used as the tab icon.
Branch System
Advancement trees inevitably become harder to read and maintain as they grow. To solve this problem, Gardin's Advancement introduces the branch system, allowing you to encapsulate parts of your advancement tree into independent branches. You only need to define a branch structure like this:

Then, you can mount this branch under any advancement node in a tab:


The mounted branch will be generated under branch_anchor as its parent node in the current tab.

Notes

• Branches cannot be reused. Each branch can only be mounted once.
• Nodes inside a branch share the same ID namespace as the parent tab after mounting.
• Avoid using duplicate advancement IDs within the same tab to prevent conflicts.
  

Performance
This plugin pre-compiles condition expressions on startup and generates a variable index that maps placeholders to related advancements. This avoids repeatedly reading the same placeholders.
During placeholder checks, conditions are only evaluated when the placeholder value changes compared to the cached value.
When an advancement is completed, the plugin automatically checks placeholder usage. If a placeholder is no longer required, it will be removed from the tracking system.
Therefore, using the same placeholder multiple times will not cause significant performance issues. Progressive advancement chains such as:
can be freely used without worrying about additional performance costs.
Due to this caching mechanism, advancement trees cannot be hot-reloaded.
The `/reload` command only updates:

• check-interval-ticks
• Debug settings

Changes to advancement structures require a server restart.

Important Notice
If you need an advancement system based on instant event triggers
(for example: triggering immediately when a player breaks a block or kills an entity), this plugin may not be suitable for your needs.
Gardin's Advancement is not designed to replace event-based achievement systems.
Instead, it provides a lightweight and universal condition checking framework based on PlaceholderAPI.
Icon Support

• craftengine