SantumAchievements is a Minecraft plugin that allows you to create skill trees, quests, or achievements using the native Minecraft advancements interface (L key) The entire system is completely virtual and dynamic, meaning it doesn't modify server files (datapacks) or interfere with Vanilla game advancements

The plugin is based on packet interception and transmission using the PacketEvents API, ensuring optimal performance and seamless compatibility with the Minecraft client

Main Features

• Native Minecraft Interface: Forget about boring chest or inventory menus Use the native tree system that players already know
  
  
• 100% Virtual: Doesn't create DataPacks or temporary files Everything is sent via network packets directly to the client
  
  
• Tab Support: Create multiple categories (e.g. Mining, Combat, Exploration) in separate files
  
  
• Precise Positioning (Offsets): Full control over the grid Configure the exact position of each achievement using coordinates relative to its parent (offset-x and offset-y)
  
  
• Native Notifications (Toasts): Visual alerts with original Minecraft icon, title, and sound when a player unlocks an achievement
  
  
• PlaceholderAPI Integration: Full support for PAPI variables (%player_name%, %statistic_kill_entity:ZOMBIE%, etc) in both titles and descriptions (lores)
  
  
• Automatic Conditions: You can define conditions so that achievements are unlocked automatically as the player plays and meets the requirements
  
  
• Spam Prevention: Optimized internal logic to prevent alerts from popping up when players connect, change worlds, or open the menu Alerts only pop up when a new achievement is granted

Requirements

• Bukkit/Spigot/Paper based server (Tested on Paper 1.21.8)
  
  
• Java 21
  
  
• PacketEvents (Integrated via shade or installed as a plugin on the server)
  
  
• PlaceholderAPI (Required)

Important Note: For variables like %player_name% to work, you must download the corresponding extensions in PAPI (e.g: /papi ecloud download Player)

Custom Variables (PlaceholderAPI)
The plugin exports its own variables so you can use them in other plugins (like menus, scoreboards, chat, etc):

• %santumachievements_<achievement_id>_unlocked%: Returns yes if the player has the achievement unlocked, and no otherwise
  • Example: %santumachievements_golpe_critico_unlocked%

Commands
The plugin includes a set of basic administration and usage commands:

• /logros - Guidance command so the player knows to press the L key
  
  
• /santumachievements grant <player> <achievement> - Manually grants an achievement to a player (Shows the Toast alert)
  
  
• /santumachievements revoke <player> <achievement> - Revokes/removes an achievement from a player
  
  
• /santumachievements reload - Reloads the configuration, achievements, and synchronizes the interface in real-time for all connected players

Configuration
1 tabs.yml
In this file you define the main tabs of the menu

2 Achievement Files (yourname.yml) Multi SubFolder System
Achievements can be organized in different .yml files within the plugin folder

Example of configuring an achievement with the positioning system:


Text Types (Lores)

• lore-locked: Shown only when the achievement has not been unlocked
  
  
• lore-unlocked: Shown only when the achievement has already been unlocked
  
  
• lore: Shown always, whether locked or unlocked

Actions (Commands)
When an achievement is unlocked, you can execute actions using the commands list:

• console_command: The command is executed by the server console
  
  
• player_command_as_op: The player executes the command having temporary OP permissions
  
  
• player_command: The player executes the command normally
  
  
• message: Sends a normal message through the chat to the player
  
  
• centered_message: Sends a centered message in the player's chat

Coordinate System (offset-x and offset-y)
The plugin uses a relative displacement system based on the parent achievement's position:

• offset-x: Positive numbers move the achievement to the right, negative to the left
  
  
• offset-y: Positive numbers move the achievement up, negative down

(If not specified, the default value is to place the child to its right: offset-x: 1, offset-y: 0)