> For the complete documentation index, see [llms.txt](https://ajneb97.gitbook.io/thesearch/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajneb97.gitbook.io/thesearch/searches-tutorial.md).

# Searches Tutorial

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

## Permission Required

If enabled, players will need the (`thesearch.search.<search>`) permission to interact with this search.

```yaml
permission_required: true
```

## Actions

Searches have different categories of actions: **Default actions**, **Last actions, Already found actions,  Reach amount actions** and **Object actions**. These actions have the same properties but will be executed in different cases.

### Types of Action

#### **Default Actions**

Actions that will execute when a player finds an object of this Search.

```yaml
# Example of Default Actions
default_actions:
  find_chat_message:
  - '{centered}&7&m                                                  '
  - ''
  - '{centered}&aYou have discovered a &e&lHidden Treasure&a! &7(&e%current%&8/&e%total%&7)'
  - ''
  - '{centered}&7&m                                                  '
```

#### **Last Actions**&#x20;

Actions that will execute when the players finds the last object of this Search.

```yaml
# Example of Last Actions
last_actions:
  find_chat_message:
  - '{centered}&7&m                                                  '
  - ''
  - '{centered}&c&lCONGRATS!'
  - '{centered}&aYou have discovered all the &e&lHidden Treasures'
  - '{centered}&ain the lobby!'
  - '{centered}&7Reward: &a$10.000'
  - ''
  - '{centered}&7&m                                                  '
```

#### **Object Actions**

Actions that will execute on individual objects.

```yaml
# Example of Object Actions
# When the player finds this block, default actions will be replaced
# with these ones. If you don't want object actions, delete the entire
# "actions" section.
to_find:
  '1':
    type: 'block: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNmNlZjlhYTE0ZTg4NDc3M2VhYzEzNGE0ZWU4OTcyMDYzZjQ2NmRlNjc4MzYzY2Y3YjFhMjFhODViNyJ9fX0='
    location: 40.0;68.0;0.0;Christmas1
    actions:
      find_chat_message:
      - '{centered}&7&m                                                  '
      - ''
      - '{centered}&c&lUnique message for this specific block'
      - '{centered}&e%remaining% &7remaining.'
      - ''
      - '{centered}&7&m                                                  '
      find_sound: ENTITY_PLAYER_LEVELUP;10;1
```

#### **Reach amount Actions**&#x20;

Actions that will execute when a player reaches certain amount of find objects on a search.

```yaml
# Example of Reach amount Actions.
# These actions will be executed when the player has found 2 objects
# on this search.
reach_amount_actions:
  # Amount of objects needed to execute actions. You can add as many sections
  # you need.
  2:
    # Actions.
    find_chat_message:
    - '{centered}&7&m                                                  '
    - ''
    - '{centered}&bYou are almost there! Only 1 present remaining!'
    - ''
    - '{centered}&7&m                                                  '
```

#### **Already found Actions**&#x20;

Actions that will execute when a player tries to interact with an already found object of this Search.

```yaml
# Example of Already found Actions
already_found_actions:
  find_chat_message:
  - '{centered}&7&m                                                  '
  - ''
  - '{centered}&cYou have already found this block!'
  - ''
  - '{centered}&7&m                                                  '
  find_sound: BLOCK_NOTE_BLOCK_PLING;10;0.1
```

{% hint style="info" %}
If you don't want a certain action, you can remove the option from the config.
{% endhint %}

### Find Chat Message

This is the chat message to be sent to the player when finding an object from this Search.

```yaml
# Available variables:
# %current% -> shows the number of objects a player has found.
# %total% -> shows the total objects of this search.
# %remaining% -> shows the remaining objects to find on this search.
# %object_x%, %object_y%, %object_z% -> location of the object.
# PlaceholderAPI variables
default_actions:
  find_chat_message:
  - '{centered}&4&m<<                                                  >>'
  - ''
  - '{centered}&fYou have discovered a &a&lChristmas Present&f! &7(&e%current%&8/&e%total%&7)'
  - ''
  - '{centered}&4&m<<                                                  >>'
```

**Some Considerations:**

* You can use the `{centered}` tag before a text to make it centered.
* You can use HEX color codes using `#000000Text`

### Find Title Message

This is the title on screen to be sent to the player when finding an object from this Search.&#x20;

```yaml
# Available variables:
# %current% -> shows the number of objects a player has found.
# %total% -> shows the total objects of this search.
# %remaining% -> shows the remaining objects to find on this search.
# %object_x%, %object_y%, %object_z% -> location of the object.
# PlaceholderAPI variables
default_actions:
  find_title_message:
    # Title and subtitle messages.
    # Use 'none' to set it empty.
    title: '&cChristmas Present Found!'
    subtitle: '&7(&a%current%&8/&a%total%&7)'
    
    # Times of title transitions in ticks (20 ticks = 1 second).
    fadeIn: 20
    stay: 40
    fadeOut: 20
```

### Find Sound

Sound to be sent to the player when finding an object from this Search.

```yaml
# You must use the following format:
# find_sound: <sound_name>;<volume>;<pitch>
# 1.16 Sounds: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Sound.html
# 1.8 Sounds: https://github.com/Attano/Spigot-1.8/blob/master/org/bukkit/Sound.java
# You can also use resource pack sounds.
default_actions:
  find_sound: BLOCK_NOTE_BLOCK_PLING;10;1.8
```

### Find Effects

Effects to be displayed ONLY to the player when finding an object from this Search. Check [**HERE**](/thesearch/find-effects.md).

### Random Find Effects

Enable this option if you want to select a random find effect from the `find_effects` list when a player finds an object.

```yaml
find_effects_are_random: true
```

### Find Commands

Console commands to be sent to the player when finding an object from this Search.

```yaml
# Available variables:
# %current% -> shows the number of objects a player has found.
# %total% -> shows the total objects of this search.
# %remaining% -> shows the remaining objects to find on this search.
# %object_x%, %object_y%, %object_z% -> location of the object.
# %player% -> name of the player finding the object.
default_actions:
  find_commands:
  - eco give %player% 10000
```

## Display Particles

These particles will be displayed for players that haven't found an object (block or entity) yet.

```yaml
display_particles:
  # Whether particles should be displayed or not.
  enabled: true
  
  # The time (in ticks) in which these particles will appear.
  speed: 5
  
  # You can add multiple particles
  list_of_particles:
    particle1:
      # The particle to display.
      # 1.16 Particles:
      # https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Particle.html
      # 1.8 Particles: 
      # https://github.com/Attano/Spigot-1.8/blob/master/net/minecraft/server/v1_8_R3/EnumParticle.java
      # If you want to use a colored redstone particle you need to 
      # follow this format:
      # particle: REDSTONE;<color>
      # You can found all minecraft color values here:
      # https://minecraftcommand.science/armor-color 
      particle: FLAME
      
      # You can also display a CUSTOM THESEARCH particle.
      # If you set a custom particle, you don't need to specify the
      # previous "particle" option.
      # More info about this option in the next section.
      custom_particle:
        form: ORBIT;0.5
        particle: VILLAGER_HAPPY
        amount: 60
      
      # This is the particle speed (propagation), set it to 0.01 if you want
      # the particle to be static.
      speed: 0.01
      
      # These options will add a translation to the particle in the
      # respective coordinate.
      # You can use the %random_<min>_<max>% variable to select a random
      # value between two numbers. Example: "%random_-0.3_0.3%"
      offset_x: 0
      offset_y: 2.5
      offset_z: 0
```

### Custom Particle

You can display TheSearch particles with custom forms/shapes. For this to work you need to add the `custom_particle` option.

```yaml
# This will create a circle particle around the object with a radius of 0.5
# blocks, 60 particles in total and using the VILLAGER_HAPPY particle.
custom_particle:
  form: CIRCLE;0.5
  particle: VILLAGER_HAPPY
  amount: 60
```

#### Form

For now there are only 2 forms; CIRCLE and ORBIT

| Form       | Usage                                                                       |                                                                                                                                                            |
| ---------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Circle** | <p><code>form: CIRCLE;\<radius></code><br><code>form: CIRCLE;0.5</code></p> | Creates a circle of particles.                                                                                                                             |
| **Orbit**  | <p><code>form: ORBIT;\<radius></code><br><code>form: ORBIT;1</code></p>     | Creates a particle orbiting the object in a circular shape. The speed of the orbit is defined by the amount of particles. More particles mean lower speed. |

#### Particle

The particle to display.

```yaml
# 1.16 Particles:
# https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Particle.html
# 1.8 Particles: 
# https://github.com/Attano/Spigot-1.8/blob/master/net/minecraft/server/v1_8_R3/EnumParticle.java
# If you want to use a colored redstone particle you need to 
# follow this format:
# particle: REDSTONE;<color>
# You can found all minecraft color values here:
# https://minecraftcommand.science/armor-color 
particle: VILLAGER_HAPPY
```

#### Amount

The amount of particles to display.

```yaml
amount: 60
```

## Sound Clue

This option allows you to play a sound to players near objects of the search to find them easier.

```yaml
# If you don't want this option, just delete it.
sound_clue:
  # Delay of the sound in ticks (20 ticks = 1 second)
  delay: 60
  
  # An appropiate value for the sound volume is 2.
  volume: 2
  
  # Sound to play.
  # 1.16 Sounds: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Sound.html
  # 1.8 Sounds: https://github.com/Attano/Spigot-1.8/blob/master/org/bukkit/Sound.java
  # You can also use resource pack sounds.
  sound_name: BLOCK_NOTE_BLOCK_PLING
  
  # Pitch of the sound.
  pitch: 1.5
```

## Action Bar Clue

This option allows you to display a message on the actionbar to players near objects of the search to find them easier.

```yaml
# If you don't want this option, just delete it. 
actionbar_clue:
  # Delay of the message in ticks (20 ticks = 1 second)
  delay: 20
  
  # Message to display in the action bar.
  # You can use the %distance% variable to show the distance between
  # the object to find and the player.
  message: "&fThere is a halloween head &6%distance% blocks &faway!"
  
  # Minimum distance to the object to start displaying the clue message.
  min_distance: 15
```

## Boss Bar Clue

This option allows you to display a message on the bossbar to players near objects of the search to find them easier.

```yaml
# If you don't want this option, just delete it.
bossbar_clue:
  # Delay of the message in ticks (20 ticks = 1 second)
  delay: 20
  
  # Message to display in the boss bar.
  # You can use the %distance% variable to show the distance between
  # the object to find and the player.
  message: <white>Hay una cabeza a <dark_red>%distance% <white>bloques
  
  # Minimum distance to the object to start displaying the clue message.
  min_distance: 10
  
  # Color of the boss bar.
  # All colors: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/boss/BarColor.html
  color: RED
  
  # Style of the boss bar.
  # All styles: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/boss/BarStyle.html
  style: SEGMENTED_6
```