# How to Start

## Requirements <a href="#requirements" id="requirements"></a>

**1) Spigot/Paper**

{% hint style="info" %}
You need Spigot or Paper for the plugin to work. Don't use Craftbukkit.
{% endhint %}

**2) PlaceholderAPI**

{% hint style="info" %}
This dependency is optional. It will allow you to add requirements to unlock categories, and provide some useful variables.

<https://www.spigotmc.org/resources/placeholderapi.6245/>
{% endhint %}

## Installation <a href="#installation" id="installation"></a>

To install the plugin on your server just place the MineWords.jar file inside your plugins folder. Remember to use a Spigot/Paper server. Default categories and levels will be generated in the `levels` folder.

## How to Play <a href="#how-to-play" id="how-to-play"></a>

### The Inventory <a href="#the-inventory" id="the-inventory"></a>

To start playing you need to use the `/minewords` command. This will open the game main inventory. Here you will find the different categories. Categories are just a way to group levels by difficulty and maintain everything more organized. This inventory is completely [**configurable**](/minewords/inventory.yml-tutorial.md) and you can even add requirements to unlock categories.

<figure><img src="/files/Ho7HdFh75qLav76gZ51s" alt=""><figcaption></figcaption></figure>

Selecting a category will open an inventory with all of the levels from that category. Players need to complete levels in order to continue to the next ones. There is a [**permission**](/minewords/commands-and-permissions.md#permissions) to bypass this requirement. These inventories are also [**completely configurable**](/minewords/inventory.yml-tutorial.md).

<figure><img src="/files/Ul01oXQNIJHyJGAQy0Xl" alt=""><figcaption></figcaption></figure>

Click on the unlocked level to start playing. Opening a level will remove your inventory, but don't worry, your items will be safely stored (even if the server crashes). When exiting the level you'll get them back.

<figure><img src="/files/X163MgwMl8hU85Kuz2U5" alt=""><figcaption></figcaption></figure>

### The Main Game

Playing the game is very straightforward. Follow the next steps:

* Click on the first slot of each line to select a word and start guessing.
* Hovering on the slot (the gray glass panel) will show a hint (a description) of the word.
* You can use the characters/letters on your inventory to write a word. If the word is correct, the word will transform into color green.
* You can use The "Scroll Up" and "Scroll Down" buttons to move around the level and show the next or previous words. If you want to quit the game, press the nether star.

<figure><img src="/files/blolRXETvgfIKCiH96yQ" alt=""><figcaption></figcaption></figure>

Some levels can have a **hidden word**. This word is positioned vertically on the inventory, doesn't provide a description, and is represented by the color yellow. This hidden word is completely configurable, you can choose if you want one for the level or not.

<figure><img src="/files/yKp7YJyQ4D1CJ09ubQi3" alt=""><figcaption></figcaption></figure>

The player will receive configurable rewards when completing a level or the whole category.

### Word of the Day

The second game mode can be accesed through the main inventory and will open an inventory where players will need to find the hidden daily word.

<figure><img src="/files/Miu8OBoo7i2ok397l7Vg" alt=""><figcaption></figcaption></figure>

A similar logic as the main game applies, players need to use the character/letters items to write a word and start guessing.

* When certain of a word, the "enter" button must be pressed (emerald block by default).
* The color of the letters on the word will change depending on how close the guess was.
  * Color Green: It means that the letter is on the same position on the word.
  * Color Yellow: It means that the letter is on the word but on a different position.
  * Color Gray: It means that the letter is not on the word.
* The player has 6 opportunities to guess the word correctly.

<figure><img src="/files/xDqQtpy2n1uCffS6wBQB" alt=""><figcaption></figcaption></figure>

## Create your First Level

To start creating a level you need to go to the levels folder of the plugin and open one of the category files. You can even create your own category file, but in this example I will open the **easy.yml** file.

Copy one of the levels, for example the third one, and paste it below, changing its number.

```yaml
  3:
    level:
      - "--RUDE--"
      - "-FALCON-"
      - "-DREAM--"
      - "--SOAP--"
    words:
      1:
        - "&7Lacking manners or politeness."
      2:
        - "&7Bird of prey known for its speed."
      3:
        - "&7A series of thoughts or images during sleep."
      4:
        - "&7Used for washing and cleaning."
  4:
    level:
    words:
```

On the "level" option, you need to set a list of words to discover. Each list element MUST have 8 characters, since this is the size of each word line on the inventory. That doesn't mean the word must have 8 letters.

For example, I want the first word to be "CLOSE". Since this word has only 5 letters, I must fill the line with the "-" symbol. You can put these symbols left or right of the word, it is up to you. The "-" symbols will be replaced with barriers (or the [**no\_letter item**](/minewords/config.yml-tutorial.md#no-letter)) on the inventory.

```yaml
4:
  level:
  - "-CLOSE--"
  words:
```

Now that I have one word, let's add a description or hint to it, on the "words" option. Since its the first word, I put the description under the "1" path.

```yaml
4:
  level:
  - "-CLOSE--"
  words:
    1:
     - "&7Antonym of 'far'"
```

Now I can start adding new words to the level. If you want to add a hidden vertical word, be careful how you organize your words. I want the hidden word to be "SUN", so let's see how to arrange that.

```yaml
4:
  level:
  - "-CLOSE--"
  - "-CURE---"
  - "-VIOLIN-"
  words:
    1:
     - "&7Antonym of 'far'"
    2:
     - "&7Remedy for an illness"
    3:
     - "&7Stringed musical instrument played with a bow"
```

Currently, the possible vertical words I got are: "CCV", "LUI", "ORO", "SEL". Let's move the words to make the word "SUN".

```yaml
4:
  level:
  - "--CLOSE-"
  - "----CURE"
  - "VIOLIN--"
  words:
    1:
     - "&7Antonym of 'far'"
    2:
     - "&7Remedy for an illness"
    3:
     - "&7Stringed musical instrument played with a bow"
```

There it is! On column 6. Now, the only thing missing is defining that the sixth column will be a hidden word.

```yaml
4:
  level:
  - "--CLOSE-"
  - "----CURE"
  - "VIOLIN--"
  words:
    1:
     - "&7Antonym of 'far'"
    2:
     - "&7Remedy for an illness"
    3:
     - "&7Stringed musical instrument played with a bow"
    hidden:
      column: 6
```

My level is ready, now I have to go to the **inventory.yml** file, to the `category_easy` inventory, and place the level where I desire. This is done by using the **type: "level: 4"** item on the slot you want.

```yaml
category_easy:
    slots: 45
    title: "&4&lMineWords &8- #0eff9c&lEASY"
    37-44:
      item:
        id: BLACK_STAINED_GLASS_PANE
        name: " "
    36:
      item:
        id: ARROW
        name: "&7Go back"
      open_inventory: main_inventory
    10:
      type: "level: 1"
    11:
      type: "level: 2"
    12:
      type: "level: 3"
    13:
      type: "level: 4"
```

The level is ready to be played!

<figure><img src="/files/1lnnuvhILJMNCXP4WCn8" alt=""><figcaption></figcaption></figure>


---

# 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/minewords/how-to-start.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.