> 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

This plugin allows you to set up infinite nested categories and discoveries to reward players for exploring your world

{% embed url="<https://youtu.be/FItxKsvmW_g>" %}

## 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 <player>`\
  Opens the discovery menu for a specific player\
  Permission: `santumdiscovery.admin`
* `/santumdiscoveries lock <category/discovery> <player>`\
  Locks a category or discovery for a specific player\
  Permission: `santumdiscovery.admin`
* `/santumdiscoveries unlock <category/discovery> <player>`\
  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_<x>_<y>_<z>_<world>_<radius>%`\
  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_<category>%`\
  Total amount of discoveries inside a specific category
* `%santumdiscovery_amount_unlocked_<category>%`\
  Amount of unlocked discoveries by the player inside a category
* `%santumdiscovery_if_unlocked_category_<category>%`\
  Returns true if the player unlocked the category
* `%santumdiscovery_if_unlocked_<discovery>%`\
  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 <gui|reload|unlock|lock> ..."
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 <player> o /santumdiscoveries gui <category> <player>"
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 <category> [discovery] <player>"
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 <category> [discovery] <player>"
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"
```