> 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/santumdiscovery.md). # SantumDiscovery {% embed url="" %} ## Core Features * **Smart GUI System**\ A dynamic, multi-page inventory system that adapts to your configuration automatically.\ Players can browse categories and check their discoveries in an intuitive menu. * **Advanced Renaming System (UUID Magic)**\ Never lose player progress again.\ Every category and discovery generates a hidden UUID automatically.\ You can rename your configuration files and keys as much as you want without resetting player progress. * **H2 Database Integration**\ Player data is safely and swiftly stored in a high-performance local database.\ This prevents lag spikes during server saves. * **PlaceholderAPI Support**\ Fully compatible with PAPI placeholders for conditions and checking progress.\ You can even use placeholders inside the GUI names and lore. * **Custom Action Engine**\ Trigger unique effects when players unlock a discovery or click an item.\ Includes titles, action bars, sounds, messages, teleports, and console commands. * **Infinite Subfolders System** Create infinite folders and .yml ## Commands and Permissions * `/santumdiscoveries gui `\ Opens the discovery menu for a specific player\ Permission: `santumdiscovery.admin` * `/santumdiscoveries lock `\ Locks a category or discovery for a specific player\ Permission: `santumdiscovery.admin` * `/santumdiscoveries unlock `\ Unlocks a category or discovery for a specific player\ Permission: `santumdiscovery.admin` * `/santumdiscoveries reload`\ Reloads the configuration and messages\ Permission: `santumdiscovery.admin` ## Placeholders You can use the following placeholders anywhere in your server: * `%santumdiscovery_____%`\ Returns true if the player is within the radius of those coordinates * `%santumdiscovery_amount_discoveries%`\ Total amount of loaded discoveries * `%santumdiscovery_amount_discoveries_unlocked%`\ Amount of discoveries unlocked by the player * `%santumdiscovery_amount_%`\ Total amount of discoveries inside a specific category * `%santumdiscovery_amount_unlocked_%`\ Amount of unlocked discoveries by the player inside a category * `%santumdiscovery_if_unlocked_category_%`\ Returns true if the player unlocked the category * `%santumdiscovery_if_unlocked_%`\ Returns true if the player unlocked the discovery ## Configuration Guide Here is a detailed explanation of what each setting does inside the configuration files. {% hint style="warning" %} Do not touch the `uuid` field once generated, as it links the file to the database {% endhint %} ### Category Settings (categories.yml) ```yaml gui: slots_by_default_per_page: 54 category_1: uuid: "0af32bb5-2d7c-45b2-90a9-3244aedb452f" # ¡DON'T TOUCH! material_normal: BELL material_unlocked: BIRCH_BOAT page: 1 slot: 20 unlock_with_command: false name_normal: "&7Category: &6lWorld Regions" name_unlocked: "&7Category: &6lWorld Regions" lore_normal: - "&cTienes bloqueado esto" - "&cdisplayed here" lore_unlocked: - "&aTienes desbloqueado esto" - "&cdisplayed here" unlock_conditions: - "%player_world% == spawn" - "%player_level%+2 != 2" ``` * **uuid**\ The unique identifier used by the database to track player progress safely * **material\_normal**\ The item shown in the GUI when the category is still locked * **material\_unlocked**\ The item shown in the GUI once the category has been unlocked * **page**\ The GUI page number where this category will be displayed * **slot**\ The exact inventory slot (0-53) where the category icon will sit * **unlock\_with\_command**\ If set to true, this category can only be unlocked via admin commands * **name\_normal**\ The display name of the item when it is locked * **name\_unlocked**\ The display name of the item when it is unlocked * **lore\_normal**\ The text description of the item when it is locked * **lore\_unlocked**\ The text description of the item when it is unlocked * **unlock\_conditions**\ A list of PlaceholderAPI mathematical conditions required to automatically unlock this category ### Discovery Settings (discoveries folder) ```yaml ciudad_perdida: uuid: "1b4e28ba-2fa1-11d2-883f-0016d3cca427" # ¡DON'T TOUCH! material_normal: BIRCH_BUTTON material_discovered: BIRCH_BOAT unlock_with_command: false category: "mundo_1" page: 1 slot: 25 name_normal: "&7Discovery: &6Ciudad Perdida" name_discovered: "&7Discovery: &6Ciudad Perdida" lore_normal: - "&cTodavía no has viajado lo suficiente" - "&cdisplayed here" lore_discovered: - "&aHas encontrado la ciudad perdida" - "&cdisplayed here" unlock_coordinates_radius: world: world X: -40 Y: 120 Z: 84 radius: 10 discovered_conditions: - "%player_world% == spawn" - "%player_level%+2 != 2" discovered_actions: - "message: &a¡Has descubierto la ciudad perdida!" - "title: 20;40;20;&6Ciudad Perdida;&eDescubierta" click_conditions: - "%player_world% == spawn" click_actions: - "as_console: say %player_name% viajó a la ciudad perdida" - "as_player: me he viajado a la ciudad perdida" - "as_op: say Soy admin temporalmente" - "message: &aHaciendo warp a Survival..." - "teleport: lobby;0;60;0;90;0" - "centered_message: &eViajando a la ciudad perdida." - "title: 20;40;20;&6Ciudad Perdida;&eViajando..." click_actions_conditions_reject: - "as_console: say %player_name% falló los requisitos" - "as_player: me no cumple los requisitos" - "as_op: say no cumple" - "message: &cNecesitas cumplir los requisitos." - "centered_message: &4Acción rechazada" ``` * **uuid**\ The unique identifier that prevents progress loss if you rename the file * **material\_normal**\ The item shown in the GUI when the discovery has not been found yet * **material\_discovered**\ The item shown in the GUI when the player has already found the discovery * **unlock\_with\_command**\ If set to true, players cannot unlock this discovery by walking into the radius * **category\_id**\ The exact ID of the category where this discovery belongs * **page**\ The GUI page number inside its category menu * **slot**\ The exact inventory slot (0-53) for the discovery icon * **name\_normal**\ The display name of the discovery when it is locked * **name\_discovered**\ The display name of the discovery when it is unlocked * **lore\_normal**\ The description text when the discovery is locked * **lore\_discovered**\ The description text when the discovery is unlocked * **unlock\_coordinates\_radius**\ Contains the `world`, `x`, `y`, `z`, and `radius` parameters to automatically trigger the discovery when a player approaches the location * **discovered\_conditions**\ A list of conditions the player must meet to be able to discover the location * **discovered\_actions**\ A list of custom actions triggered the exact moment the player unlocks the discovery * **click\_conditions**\ A list of conditions required to click the item in the GUI * **click\_actions**\ A list of actions triggered when the player clicks the unlocked discovery in the GUI * **click\_actions\_conditions\_reject**\ A list of actions triggered if the player clicks the discovery but fails to meet the `click_conditions` ## Available Actions When configuring actions (like `discovered_actions` or `click_actions`), you can use these formats: * `message: Your text here`\ Sends a chat message to the player * `centered_message: Your text here`\ Sends a perfectly centered chat message to the player * `as_console: give %player_name% diamond 1`\ Executes a command from the server console * `as_player: spawn`\ Forces the player to execute a command * `as_op: give %player_name% diamond 1`\ Forces the player to execute a command as a temporary operator * `title: 10;70;20;Title Text;Subtitle Text`\ Sends a screen title with fade-in, stay, and fade-out ticks * `teleport: world;0.0;64.0;0.0;90.0;0.0`\ Teleports the player to a specific world, coordinates, yaw, and pitch ### Messages ```yaml # Mensajes del plugin SantumDiscovery prefix: "&8[&eSantumDiscovery&8]" no_permission: "&cNo tienes permiso para usar este comando." usage: "&eUso: /santumdiscoveries ..." reloaded: "&aConfiguración y mensajes recargados correctamente." player_not_found: "&cJugador no encontrado." only_players_gui: "&cSolo los jugadores pueden abrir la interfaz." gui_usage: "&eUso: /santumdiscoveries gui o /santumdiscoveries gui " category_unlocked: "&aCategoría %category% desbloqueada para %player%." discovery_unlocked: "&aDiscovery %discovery% de la categoría %category% desbloqueada para %player%." unlock_usage: "&eUso: /santumdiscoveries unlock [discovery] " category_locked: "&aCategoría %category% bloqueada para %player%." discovery_locked: "&aDiscovery %discovery% de la categoría %category% bloqueada para %player%." lock_usage: "&eUso: /santumdiscoveries lock [discovery] " cannot_use_command: "&cEsta categoría o descubrimiento no permite ser alterado por comando." gui: title_categories: "Categories - Page %page%" title_discoveries: "%category_name% - Page %page%" btn_prev_page: "&ePágina Anterior" btn_next_page: "&eSiguiente Página" btn_back_categories: "&cVolver a Categorías" ``` --- # 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: ``` GET https://donkolia.gitbook.io/minesantum/santumdiscovery.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.