> For the complete documentation index, see [llms.txt](https://donkolia.gitbook.io/minesantum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://donkolia.gitbook.io/minesantum/santumachievements.md). # SantumAchievements {% embed url="" %} 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](https://github.com/retrooper/packetevents) (Integrated via shade or installed as a plugin on the server) * [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) (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__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 ` - Manually grants an achievement to a player (Shows the Toast alert) * `/santumachievements revoke ` - Revokes/removes an achievement from a player * `/santumachievements reload` - Reloads the configuration, achievements, and synchronizes the interface in real-time for all connected players *(The administrative permission is `santumachievements.admin`)* ## Configuration ### `tabs.yml` In this file you define the main tabs of the menu. ```yaml tabs: guerrero: # Tab ID icon: "DIAMOND_SWORD" title: "&c&lPath of the Warrior" background: "minecraft:block/stone" lore: # Optional: Description when hovering the mouse - "&aWelcome, &e%player_name%&a!" - "&7Your current level is: &b%player_level%" ``` ### Achievement Files (`logros.yml`) Achievements can be organized in different `.yml` files within the plugin folder. Example of configuring an achievement with the positioning system: ```yaml achievements: # Parent Achievement (Tab Root) golpe_fuerte: tab: "guerrero" parent: null icon: "IRON_SWORD" title: "Strong Strike" unlocked_with_grant_command: no lore: - "&6The basic skill of a warrior" - "&eBase damage increased" - "&7Requirement: &cLevel 5" conditions: - "%player_level% >= 5" # Child Achievement golpe_critico: tab: "guerrero" parent: "golpe_fuerte" unlocked_with_grant_command: yes icon: "DIAMOND_SWORD" title: "Critical Strike %player_name%" lore-locked: - "&c[LOCKED]" - "&7You need to unlock Strong Strike" lore-unlocked: - "&a[UNLOCKED]" lore: - "&cYour strength increases significantly" - "&eYour critical strikes are more lethal" offset-x: 1 # Moves the achievement 1 grid to the right offset-y: -1 # Moves the achievement 1 grid down conditions: - "%player_level% >= 10" - "%player_world% == World_NaMe" commands: - console_command: "eco give %player_name% %player_level%*5" ##PlaceholderAPI With Maths - player_command_as_op: "eco give %player_name% 5000" - player_command: "help" - message: "&aYou have unlocked the Critical Strike achievement!" - centered_message: "&e5000 reward received" ``` ### 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 ### Achievements granted by Command If this setting is set to “yes,” it overrides the conditions, and the achievement is unlocked only via command. ```yaml logro_secreto: tab: "guerrero" title: "Logro Secreto" unlocked_with_grant_command: yes ``` ### 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`)* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://donkolia.gitbook.io/minesantum/santumachievements.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.