# Levels/Categories Tutorial

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

## On Level Selection Title

The title of the opened inventory when inside the level selection of this category.

```yaml
on_level_selection_title: "&8[&b&lEasy&8] &6&lLevels"
```

## On Game Title

The title of the opened inventory when playing on a level of this category.

```yaml
on_game_title: "&8[&b&lEasy&8] &6Level %level%"
```

## Inventory Items

The format of each item is the following:

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

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

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

### Category Items

Each category will be represented by its own item in the main inventory. This item will vary depending on the current state of the category. For now there are two possible states.

#### 1. Category

The item displayed by default. You can tell the players on this item the amount of levels the category has, the difficulty of them, and maybe the possible rewards.

```yaml
inventory_items:
  category:
    id: PURPLE_TERRACOTTA
    name: "&8[&5&lVery Hard&8] &6&lLevels"
    lore:
      - "&78x6 and 9x6 Levels"
      - "&840 Levels"
      - ""
      - "&7Rewards:"
      - "&8- &a$110 &7on each level."
      - "&8- &e11XP &7on each level."
      - ""
      - "&eStatus: &8[%progress%&8] %percentage%%"
```

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

* `%progress%` (A progress bar showing the progress of the levels completed from this category)
* `%percentage%` (Percertange of the levels completed from this category)
  {% endhint %}

#### 2. Category No Requirements

The item displayed when the player doesn't have the necessary requirements to play on this category. You should tell the players on this item, what requirements are needed.&#x20;

```yaml
inventory_items:    
  category_no_requirements:
    id: GRAY_DYE
    name: "&8[&5&lVery Hard&8] &6&lLevels"
    lore:
      - "&78x6 and 9x6 Levels"
      - "&840 Levels"
      - ""
      - "&cYou must complete the HARD"
      - "&clevels first."
```

### Level Items

Each level of this category will be represented on the **level section inventory** by its own item. This item will vary depending on the current state of the level. These are the possible states.

#### 1. Level Unlocked

The item displayed when the level is ready to be played.

```yaml
inventory_items:     
  level_unlocked:
    id: YELLOW_TERRACOTTA
    name: "&2Level %level%"
    lore:
      - "&7Type: &e%type%"
      - "&7Status: &6[UNLOCKED]"
```

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

* `%level%` (Number of this level)
* `%type%` (Type/Form of this level)
  {% endhint %}

#### 2. Level Blocked

The item displayed when the level is blocked, which means the previous level has not been completed.

```yaml
inventory_items:  
  level_blocked:
    id: CYAN_TERRACOTTA
    name: "&2Level %level%"
    lore:
      - "&7Type: &a%type%"
      - "&7Status: &c[BLOCKED]"
```

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

* `%level%` (Number of this level)
* `%type%` (Type/Form of this level)
  {% endhint %}

#### 3. Level Completed

The item displayed when the level has been completed.

```yaml
inventory_items:  
  level_completed:
    id: LIME_TERRACOTTA
    name: "&2Level %level%"
    lore:
      - "&7Type: &e%type%"
      - "&7Status: &a[COMPLETED]"
      - ""
      - "&7Completed in: &e%time%(s)"
```

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

* `%level%` (Number of this level)
* `%type%` (Type/Form of this level)
* `%time%` (Time taken to complete the level)
  {% endhint %}

## Modify Levels Amount

Whether the amount value of the [**Level Items**](#level-items) should be changed depending on the number of the level. Be careful if your category has more than 64 levels!

```yaml
modify_levels_amount: true
```

## Rewards

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

### Per Level

Default actions to be executed when the player finishes a level from this category.

```yaml
rewards:
  per_level:
    - "playsound: ENTITY_PLAYER_LEVELUP;1;1"
    - "message: &7Level &b%level% &7completed in &b%time%(s)&7. You earned &a$110 &7and &e11 XP&7."
    - "console_command: eco give %player% 110"
    - "console_command: xp give %player% 11"
```

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

* `%level%` (Number of the current level)
* `%time%` (Time taken to complete the level)
  {% endhint %}

### All Levels

Default actions when the player finishes all levels from this category.

```yaml
rewards: 
  all_levels:
    - "centered_message: &b&m                  &b[ VERY HARD LEVELS COMPLETED! ]&b&m                  "
    - "centered_message: "
    - "centered_message: &eYou completed the VERY HARD category, take these rewards:"
    - "centered_message: &7- &a$25000"
    - "centered_message: &7- &e2500XP"
    - "centered_message: "
    - "centered_message: &b&m                  &b[ VERY HARD LEVELS COMPLETED! ]&b&m                  "
    - "console_command: eco give %player% 25000"
    - "console_command: xp give %player% 2500"
```

## Requirements

Requirements needed to unlock this category. You can add multiple requirements/conditions. More info [**HERE**](https://ajneb97.gitbook.io/connecttheblocks/requirements).

<pre class="language-yaml"><code class="lang-yaml">requirements:
<strong>  - "%player_has_permission_ctb.very_hard% == yes"
</strong>  - "%connecttheblocks_category_completed_hard% == true"
</code></pre>

## No Requirements Error Message

Message to be sent to the player when requirements are not satisfied.

```yaml
no_requirements_error_message: "&cYou must complete the HARD levels first."
```

## Levels

Levels are automatically saved on this file when creating them using `/ctb createlevel`.

### Type

The type/form of the level. You should not modify this property manually. Types are defined in the **level\_inventory\_types** configuration on the inventory.yml file.

```yaml
type: 5x5
```

### Blocks

The position of default blocks. You should not modify this property manually. Blocks are defined in the **game\_blocks** configuration on the config.yml file.

```yaml
blocks:
  - red;29;15
  - blue;20;13
  - green;12;6
  - yellow;38;42
```

### Rewards

Allows you to set custom rewards for this level only. Will replace the default [**per level rewards**](#per-level) from this category.

```yaml
rewards:
  - "playsound: ENTITY_PLAYER_LEVELUP;1;1"
  - "message: &7Congrats on finishing your first level! You earned &a$500 &7and &e1 diamond&7."
  - "console_command: eco give %player% 500"
  - "console_command: give %player% diamond 1"
```

### Inventory Rewards

Enable this option is you want to give items to the player as reward.

```yaml
inventory_rewards: true
```

### Custom Inventory Items

You can replace the [**Level Items**](#level-items) with custom ones used only for this level.

#### Level Unlocked

The item displayed when the level is ready to be played. All variables from [**HERE**](#id-1.-level-unlocked) apply.

```yaml
inventory_items:     
  level_unlocked:
    id: YELLOW_TERRACOTTA
    name: "&2Level %level%"
    lore:
      - "&7Type: &e%type%"
      - "&7Status: &6[UNLOCKED]"
      - ""
      - "&7This item will replace the default item"
      - "&7only for this level."
```

#### Level Blocked

The item displayed when the level is blocked, which means the previous level has not been completed. All variables from [**HERE**](#id-2.-level-blocked) apply.

```yaml
inventory_items:  
  level_blocked:
    id: CYAN_TERRACOTTA
    name: "&2Level %level%"
    lore:
      - "&7Type: &a%type%"
      - "&7Status: &c[BLOCKED]"
      - ""
      - "&7&oRage, rage, against the dying of the light."
```

#### Level Completed

The item displayed when the level has been completed. All variables from [**HERE** ](#id-3.-level-completed)apply.

```yaml
inventory_items:  
  level_completed:
    id: LIME_TERRACOTTA
    name: "&2Level %level%"
    lore:
      - "&7Type: &e%type%"
      - "&7Status: &a[COMPLETED]"
      - ""
      - "&7Completed in: &e%time%(s)"
      - ""
      - "&7This is a custom item for this level only."
```


---

# 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/connecttheblocks/levels-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.