# Discoveries/Categories Tutorial

In this page you will find all properties of discoveries/categories configuration files. Everytime you modify something in these files you must reload the plugin using `/codex reload`.

## Inventory Items

The format of each item is the following:

```yaml
inventory_items:
  <type>:
    <item>
```

{% hint style="warning" %}
Remember that the `item` to be displayed has the properties listed [**HERE**](https://ajneb97.gitbook.io/codex/items-tutorial).
{% endhint %}

{% hint style="success" %}
You can use PlaceholderAPI variables on the name and lore of all these items.
{% endhint %}

### 1. Category

Each category will be represented by its own item in the main inventory. You can tell the players on this item the amount of discoveries the category has and information of the category.

```yaml
category:
  id: MAP
  name: "&7Category: #6bcbfe&lWorld Regions"
  lore:
  - "#eeeeeeDifferent regions you've explored will"
  - "#eeeeeebe displayed here."
  - ""
  - "&7Unlocked: %unlocked% &8[%progress_bar%&8] &8(&7%percentage%&8)"
```

{% hint style="success" %}
**Variables:**

* `%unlocked%` (Will be replaced with the following messages.yml messages depending of the status of discoveries found: currentUnlockedDiscoveriesColorNone, currentUnlockedDiscoveriesColorAll, currentUnlockedDiscoveriesColorIncomplete)
* `%progress_bar%` (A progress bar showing the progress of the discoveries unlocked from this category)
* `%percentage%` (Percertage of the discoveries unlocked from this category)
  {% endhint %}

### 2. Discovery Unlocked

The item displayed on the **category inventory** when the discovery has been unlocked.

```yaml
discovery_unlocked:
  id: PAPER
  name: "%name%"
  lore:
  - "%description%"
  - ""
  - "&8Discovered on %date%"
```

{% hint style="success" %}
**Variables:**

* `%name%` (Name of the discovery)
* `%description%` (Description of the discovery)
* `%date%` (Date the discovery was unlocked)
  {% endhint %}

### 3. Discovery Blocked

The item displayed on the category inventory when the discovery has not been found.

```yaml
discovery_blocked:
  id: GRAY_DYE
  name: "&c??"
  lore:
  - "&7You haven't unlocked this discovery yet."
```

## Rewards

Rewards are given through actions. All Actions can be found [**HERE**](https://ajneb97.gitbook.io/codex/actions).

### Per Discovery

Default actions to be executed when the player finds a discovery from this category.

```yaml
rewards:
    per_discovery:
      - "centered_message: #6bcbfe&m00                                                 00"
      - "centered_message: "
      - "centered_message: #eeeeee&lCODEX UPDATED"
      - "centered_message: &7World Regions: %name%"
      - "centered_message: "
      - "centered_message: &7Check it now by using #eeeeee/codex"
      - "centered_message: "
      - "centered_message: &7Rewards: &a+50XP"
      - "centered_message: "
      - "centered_message: #6bcbfe&m00                                                 00"
      - "title: 20;60;20;#eeeeee&lCODEX UPDATED;&7Region: %name%"
      - "playsound: BLOCK_GILDED_BLACKSTONE_STEP;10;0.1"
      - "console_command: xp give %player% 50"
```

{% hint style="success" %}
**Variables:**

* `%name%` (Name of the discovery)
* `%player%` (Name of the player)
  {% endhint %}

### All Discoveries

Default actions to be executed when the player finds all discoveries from this category.

<pre class="language-yaml"><code class="lang-yaml">rewards:
    all_discoveries:
      - "centered_message: #6bcbfe&#x26;m00                                                 00"
      - "centered_message: "
      - "centered_message: #eeeeee&#x26;lCODEX CATEGORY COMPLETED"
      - "centered_message: &#x26;7World Regions"
      - "centered_message: "
<strong>      - "centered_message: &#x26;7Congratulations!"
</strong>      - "centered_message: "
      - "centered_message: &#x26;7Rewards: &#x26;a+5000XP"
      - "centered_message: "
      - "centered_message: #6bcbfe&#x26;m00                                                 00"
      - "title: 20;60;20;#eeeeee&#x26;lCODEX CATEGORY COMPLETED;&#x26;7World Regions"
      - "playsound: BLOCK_GILDED_BLACKSTONE_STEP;10;0.1"
      - "console_command: xp give %player% 5000"
</code></pre>

{% hint style="success" %}
**Variables:**

* `%player%` (Name of the player)
  {% endhint %}

## Discoveries

Discoveries must be added below the `discoveries` section using the following format.

```yaml
discoveries:
  <discovery_id>:
    name: <name>
    description:
    - <description lines>
```

### Name

Name of the discovery. Used to be displayed on inventories and messages.

```yaml
name: "#6bcbfe&lShadow Swamp"
```

### Description

Description of the discovery. Used to be displayed on inventories and messages.

```yaml
description:
      - "#eeeeeeAn abomination found on the Shadow Swamp. It's"
      - "#eeeeeevery difficult to beat."
      - ""
      - "&7Drops:"
      - "&8❱ #eeeeeeShadow Elixir &8(25%)"
      - "&8❱ #eeeeeeIron Ingot &8(90%)"
```

### Discovered On

Determines how can this discovery be unlocked.

#### WorldGuard Region

The discovery is unlocked when entering a WorldGuard (<https://dev.bukkit.org/projects/worldguard>) region.

{% hint style="info" %}
Set the `type` option to **WORLDGUARD\_REGION**.

**`value.region_name:`** Name of the region.
{% endhint %}

```yaml
discovered_on:
  type: WORLDGUARD_REGION
  value:
    region_name: shadow_swamp
```

#### Residence Region

The discovery is unlocked when entering a Residence (<https://www.spigotmc.org/resources/residence-1-7-10-up-to-1-21.11480/>) region.

{% hint style="info" %}
Set the `type` option to **RESIDENCE\_REGION**.

**`value.region_name:`** Name of the region.
{% endhint %}

```yaml
discovered_on:
  type: RESIDENCE_REGION
  value:
    region_name: rolbic_town
```

#### Mob Kill

The discovery is unlocked when killing a vanilla entity.

{% hint style="info" %}
Set the `type` option to **MOB\_KILL**.

**`value.mob_type:`**&#x54;ype of the mob/entity. All entity types here: <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/entity/EntityType.html>

**`value.mob_name:`** Optional. Custom name of the mob/entity. Don't use color codes.
{% endhint %}

```yaml
discovered_on:
  type: MOB_KILL
  value:
    mob_type: ZOMBIE
    mob_name: Shadow Warrior
```

#### Mythic Mob Kill

The discovery is unlocked when killing a MythicMobs (<https://www.spigotmc.org/resources/5702/>) mob.

{% hint style="info" %}
Set the `type` option to **MYTHIC\_MOB\_KILL**.

**`value.mob_type:`**&#x49;d of the MythicMobs mob. You can use ";" to include multiple ids.
{% endhint %}

{% tabs %}
{% tab title="Example 1" %}

```yaml
discovered_on:
  type: MYTHIC_MOB_KILL
  value:
    mob_type: forest_corrupter
```

{% endtab %}

{% tab title="Example 2" %}

```yaml
discovered_on:
  type: MYTHIC_MOB_KILL
  value:
    mob_type: crab;super_crab;mega_crab
```

{% endtab %}
{% endtabs %}

#### Elite Mob Kill

The discovery is unlocked when killing a EliteMobs (<https://www.spigotmc.org/resources/elitemobs.40090/>) mob.

{% hint style="info" %}
Set the `type` option to **ELITE\_MOB\_KILL**.

**`value.mob_type:`**&#x49;d of the EliteMobs mob (name of the file without .yml). You can use ";" to include multiple ids.
{% endhint %}

```yaml
discovered_on:
  type: ELITE_MOB_KILL
  value:
    mob_type: ember
```

### Click Actions

Actions to be executed when the player clicks on the inventory item associated with this discovery, when the discovery has been found. All actions [**HERE**](https://ajneb97.gitbook.io/codex/actions). Optional.

```yaml
click_actions:
- "console_command: warp shadow_swamp %player%"
```

### Click Actions Cooldown

Adds a cooldown (in seconds) to execute the defined actions when clicking on the discovery item.

```yaml
click_actions_cooldown: 60
```

### Custom Inventory Items

You can replace the [**Category Inventory Items**](#inventory-items) with custom ones used only for this discovery.

#### Discovery Unlocked

The item displayed on the [**category inventory**](https://ajneb97.gitbook.io/codex/inventory-tutorial) when THIS discovery has been unlocked. All variables from [**HERE**](#id-2.-discovery-unlocked) applies.

```yaml
inventory_items:
  discovery_unlocked:
    id: PAPER
    name: "%name%"
    lore:
    - "%description%"
    - ""
    - "&8Discovered on %date%"
    - ""
    - "&a&lCLICK &ato teleport."
```

#### Discovery Blocked

The item displayed on the [**category inventory**](https://ajneb97.gitbook.io/codex/inventory-tutorial) when THIS discovery has not been found. All variables from [**HERE**](#id-3.-discovery-blocked) applies.

```yaml
inventory_items:
  discovery_blocked:
    id: GRAY_DYE
    name: "&c??"
    lore:
    - "&7You haven't unlocked this discovery yet."
    - ""
    - "&7Hint: A very important city."
```

### Custom Rewards

You can replace the [**Per Discovery Rewards**](#per-discovery) with custom ones only for this discovery.

```yaml
rewards:
- "centered_message: #6bcbfe&m00                                                 00"
- "centered_message: "
- "centered_message: #eeeeee&lCODEX UPDATED"
- "centered_message: &7World Regions: %name%"
- "centered_message: "
- "centered_message: &7Check it now by using #eeeeee/codex"
- "centered_message: "
- "centered_message: &7Rewards: &a+300XP&7, &a$5.000"
- "centered_message: "
- "centered_message: #6bcbfe&m00                                                 00"
- "title: 20;60;20;#eeeeee&lCODEX UPDATED;&7Region: %name%"
- "playsound: BLOCK_GILDED_BLACKSTONE_STEP;10;0.1"
- "console_command: xp give %player% 300"
- "console_command: eco give %player% 5000"
      
```


---

# Agent Instructions: 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://ajneb97.gitbook.io/codex/categories-tutorial.md?ask=<question>
```

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.