# Configuration

Nearly every possible setting for Elevators can be altered via the `/ele admin` command; Please check there first if you are not comfortable messing with the configuration file directly.

All configuration should be well commented; however, this page may go into more detail.

## Root Configuration

At the top of your `config.yml`, you will see what is referred to as the Config Root. This controls general aspects of the Elevators plugin.

:::code source="static/configRoot.yml" :::

{.compact}
Key                   | Default Value         | Description
---                   | ---                   | ---
version               | 5.0.0                 | This should not be messed with. This helps with config conversion when moving to a new version of Elevators.
updateCheckerEnabled  | true                  | If enabled, players with the update permission will receive a message if a new Elevators version is available.
effectDestination     | ORIGIN                | Controls whether effects and sounds should play at origin Elevator, Destination Elevator, or at both.<br>Options are: ORIGIN, DESTINATION, BOTH.
permissionMode        | BOTH                  | Controls whether permission to use the elevator is determined by the origin Elevator, Destination Elevator, or both.<br>Options are: ORIGIN, DESTINATION, BOTH.
forceFacingUpwards    | true                  | If this is set to true, all Elevators will face upwards when placed. If false, they will face in the direction the player is facing.
allowElevatorDispense | false                 | If this is set to true, elevators will be able to be placed by Dispensers. Keep in mind that this will bypass the elevator placement permission.
disabledWorlds        | -example_world        | Any world's with their names listed under this key will have Elevators disabled.

## Protection Hooks

Whenever Elevators recognizes a Protection Plugin that it has built in support for, it will generate a new entry inside this Config Node.

:::code source="static/configProtectionHooks.yml" :::

In the example above, Elevators has detected the plugin "GriefPrevention" and had created a new entry. In each entry, you will find the following options:

{.compact}
Key                       | Default Value | Description
---                       | ---           | ---
allowCustomization        | true          | If this is true, players will be able to toggle the protection check on or off for individual Elevators through the Elevator Settings menu.
blockNonMemberUseDefault  | true          | If enabled, only trusted / members or those with bypass perms will be able to use the elevator unless the protection check is disabled.

## Locale

This Config Node contains the messages that will be sent to the players under specific circumstances. Every message in Elevators is customizable aside from the command help text.

:::code source="static/configLocale.yml" :::

{.compact}
Key                        | Description
---                        | ---
cantCreateMessage          | Sent to the player when trying to craft an elevator but lacks permission.
cantDyeMessage             | Sent to the player when trying to dye an elevator but lacks permission.
cantUseMessage             | Sent to the player when trying to use an elevator but lacks permission.
cantGiveMessage            | Sent to the player when trying to use `/ele give` but lacks permission. 
cantAdministrateMessage    | Sent to the player when trying to use `/ele admin` but lacks permission.
cantReloadMessage          | Sent to the player when trying to use `/ele reload` but lacks permission.
notEnoughRoomGiveMessage   | Sent to the player when given an elevator, but some had to be dropped on the ground due to lack of inventory space.
givenElevatorMessage       | Sent to the player when given an eleavtor succesfully.
worldDisabledMessage       | Sent to the player when trying to interact with an Elevator in a disabled world.
elevatorCooldownMessage    | Sent to the player when trying to use an Elevator with a cooldown that has not yet expired.
elevatorChangedKickedOut   | Sent to the player when in an Elevator UI and a change has been made to the Elevator Type through either reload or `/ele admin`
chatInputBackOut           | Sent to the player to inform them they can type `cancel` to back out of a chat input.
chatInputBackOutAllowReset | Sent to the player to inform them they can type `cancel` to back out of a chat input, or `reset` to choose default.
enterDisplayName           | Sent to the player to inform them to enter a new Elevator Display Name. This is through `/ele admin`
enterElevatorKey           | Sent to the player to inform them to enter a new Elevator Key. This is through `/ele admin`
enterRecipeName            | Sent to the player to inform them to enter a new Elevator Recipe Name. This is through `/ele admin`
enterRecipePermission      | Sent to the player to inform them to enter a new Elevator Recipe permission node. This is through `/ele admin`
enterUsePermission         | Sent to the player to inform them to enter a new Elevator Use permission node. This is through `/ele admin`
enterDyePermission         | Sent to the player to inform them to enter a new Elevator Dye permission node. This is through `/ele admin`
nonUniqueElevatorKey       | Sent to the player to inform them that an Elevator with the key entered already exists.
nonUniqueRecipeName        | Sent to the player to inform them that the Elevator Recipe Name already exists for the chosen Elevator Type.
enterFloorName             | Sent to the player to inform them to enter a new name for their elevator floor. This is through right-click interaction.
enterTitle                 | Sent to the player to inform them to enter a new Title message for the Title Action. This can be through `/ele admin` or right-click interaction if action is set customizable.
enterSubtitle              | Sent to the player to inform them to enter a new SubTitle message for the Title Action. This can be through `/ele admin` or right-click interaction if action is set customizable.
enterMessage               | Sent to the player to inform them to enter a new message for the Message Action. This can be through `/ele admin` or right-click interaction if action is set customizable.
enterCommand               | Sent to the player to inform them to enter a new command for the Command Action. This is through `/ele admin`

## Effects

This Config Node contains custom effects made through images. You can find a folder named `effects` in the `plugins/Elevators` directory. Here you can place images that you wish to turn into effects.

The effect system will turn each pixel from the image into either a hologram character or a particle dust effect. For the sake of your player base, please keep image effects on the smaller side.

A default effect called "creeper" already exists in the Effects Config Node. Here is the default setup:

:::code source="static/configEffects.yml" :::

{.compact}
Key         | Default Value | Description
---         | ---           | ---
file        | Creeper.png   | This is the path to the effect image. The starting path is in the `plugins/Elevators/effects/` directory.
scale       | 1             | This can be used to scale up the image to the desired size. Like mentioned before, please be generous. Minimum value is 1.
duration    | 1.0           | This is used to set how long the effect will be present for. This is in seconds.
useHolo     | false         | If this is true, the effect system will attempt to use a detected hologram hook for the effect rather than using partcle dust effects.
background  | #FFFFFF       | This is a HEX code. Any color of this value in the image will be made transparent in the played effect.

## Elevators

This Config Node is where you define new Elevator types. There is a lot to this config node, so this documentation will break it down into smaller sections.

Your default Elevators Config Node will look like this:

:::code source="static/configElevators.yml" :::

Multiple types of Elevators are able to be created, each with different settings, effects, and actions; however, there will always be a `DEFAULT`. If a `DEFAULT` is missing, one will be made. If you ever delete an Elevator Type from this config, or for some reason an Elevator is not recognized in the game, this plugin will assume it is of the `DEFAULT` type.

### Elevator Root

At the top of the Elevator Config Node, you will see what is referred to as the Elevator Root. Here is the default Elevator Root:

:::code source="static/configElevatorRoot.yml" :::

{.compact}
Key             | Default Value         | Description
---             | ---                   | ---
displayName     | Elevator              | The Display Name of the item when given or picked up.
usePermission   | elevators.use.default | The permission node required to use the elevator. You can specify specific colors like so: `elevators.use.default.black`.
dyePermission   | elevators.dye.default | The permission node required to dye the elevator item. You can specify specific colors like so: `elevators.dye.default.black`.
maxDistance     | 20                    | The maximum distance an Elevator will search for the next floor. Set to -1 to allow infinite distance.
maxSolidBlocks  | -1                    | The maximum number of solid blocks that can be between one floor of an elevator and another. Set to -1 to allow infinite solid blocks.
maxStackSize    | 16                    | The Maximum Stack Size of an Elevator ItemStack.
classCheck      | true                  | If this is set to true, the elevator will only search for destination elevators of the same type.
stopObstruction | true                  | If this is set to true, the elevator will skip floors that are deemed obstructed when searching for a destination.
supportDying    | true                  | If this is set to true, Elevator items of this type will be able to be dyed so long as the user has the permission node set earlier in this config.
checkColor      | true                  | If this is set to true, the elevator will only search for destination elevators of the same color.
checkPerms      | true                  | If this is set to true, the elevator will check for permissions for use and dying. This option is mostly for smaller servers that don't want to setup a permissions system.
canExplode      | false                 | If this is set to true, Elevators can explode through Creeper explosions or TNT.
hologramLines   | []                    | This is a [YAML String Array](https://www.educative.io/answers/how-to-represent-arrays-in-yaml). If set, this plugin will try to use hooked Hologram plugins to display text above the elevator.
loreLines       | []                    | This is a [YAML String Array](https://www.educative.io/answers/how-to-represent-arrays-in-yaml). If set, the text will appear as lore for the Elevator item.

### Elevator Actions

**Elevator Actions** are used to perform effects, commands, or send messages when using an Elevator. For more information about **Elevator Actions**, check out the [Elevator Actions Guide](/ElevatorActions/).

The Elevator Actions Node is split between an up and a down [YAML String Array](https://www.educative.io/answers/how-to-represent-arrays-in-yaml). Here is the default:

:::code source="static/configElevatorActions.yml" :::

You can create actions by using a simple format:
`<Action Key>: <variable>=<value> <variable>=<value> ...`

Example:

```yaml
up:
  - 'effect: name=HELIX'
down:
  - 'message-player: message=You're going down!'
```

#### Explanation

```yaml
effect: name=HELIX
```

- `effect` is the **Action Key**
- `name` is a **variable**
- `HELIX` is the value assigned to that variable

```yaml
message-player: message=You're going down!
```

- `message-player` is the **Action Key**
- `message` is a **variable**
- `You're going down!` is the value assigned to that variable
 
Each **Action Key** supports specific variables. You can find the list of valid Action Keys and the variables they support in the [Elevator Actions Guide](/ElevatorActions/) 
 
!!!warning Do Not Edit Identifier
If a variable named `identifier` is present, **do not change it**. This is used by the plugin to let players customize the action on individual elevators.
!!!

### Disabled Elevator Settings

**Elevator Settings** are used to toggle or edit characteristics of Elevators. For more information about **Elevator Settings**, check out the [Elevator Settings Guide](/ElevatorSettings/).

This Config Node is a [YAML String Array](https://www.educative.io/answers/how-to-represent-arrays-in-yaml). Entries in this array will disable the Elevator Settings from being able to be configured on an individual Elevator level through right-click interaction.
Here is the default:

:::code source="static/configElevatorDisabledSettings.yml" :::

**Elevator Actions** may have their own settings based on their **variables**. To disable settings belonging to an **Elevator Action**, use the following format:
`<Action Key>/<Variable Setting>`
Example:
`boss-bar/color`

In this example:
 - `boss-bar` is the **Action Key**
 - `color` is the **Variable Setting**

Each **Action Key** supports specific variables. You can find the list of valid Action Keys and the variables they support in the [Elevator Actions Guide](/ElevatorActions/) 

### Elevator Recipes

Multiple recipes can be defined for a singular Elevator Type. Here is the default Recipe Node:

:::code source="static/configElevatorRecipes.yml" :::

{.compact}
Key                        | Default Value                                                | Description
---                        | ---                                                          | ---
amount                     | 1                                                            | This is the number of Elevators the recipe will output.
craftPermission            | elevators.craft.default                                      | This is the permission node required to craft with this recipe. If `supportMultiColorMaterials` is true a wildcard or dye-color needs to be appended to this permission for proper permission checks.
defaultOutputColor         | WHITE                                                        | This is the default output color of the recipe. If `supportMultiColorOutput` is false, this color will be used for the output.
supportMultiColorOutput    | true                                                         | If this is false, all variations of this recipe will be of the `defaultOutputColor`.
supportMultiColorMaterials | true                                                         | If this is enabled, a new recipe variation will be created of this recipe for each possible dye-color.
materials                  | w:&nbsp;minecraft:white_wool<br>e:&nbsp;minecraft:ender_peal | Define characters as Minecraft materials for use with the next Key.
recipe                     | www<br>wew<br>www                                            | Using the characters defined in the `materials` key, recreate a 3x3 crafting grid using a [YAML String Array](https://www.educative.io/answers/how-to-represent-arrays-in-yaml). You can use a space to represent nothing in the slot.