# 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.

version: 5.0.0
updateCheckerEnabled: true
effectDestination: ORIGIN
permissionMode: BOTH
forceFacingUpwards: true
allowElevatorDispense: false
disabledWorlds:
  - example_world

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. Options are: ORIGIN, DESTINATION, BOTH.
permissionMode	BOTH	Controls whether permission to use the elevator is determined by the origin Elevator, Destination Elevator, or both. 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.

protectionHooks:
  GriefPrevention:
    allowCustomization: true
    blockNonMemberUseDefault: true

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:

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.

locale:
  cantCreateMessage: '&b&lELEVATORS&f You do not have permission to create an Elevator!'
  cantDyeMessage: '&c&lELEVATORS&f You do not have permission to dye this Elevator!'
  cantUseMessage: '&b&lELEVATORS&f You do not have permission to use an Elevator!'
  cantGiveMessage: '&b&lELEVATORS&f You do not have permission to give Elevators!'
  cantAdministrateMessage: '&c&lELEVATORS&f You do not have permission to administrate Elevators!'
  cantReloadMessage: '&b&lELEVATORS&f You do not have permission to reload Elevators!'
  notEnoughRoomGiveMessage: '&b&lELEVATORS&f You do not have enough space in your inventory! The Elevator is on the ground in front of you!'
  givenElevatorMessage: '&b&lELEVATORS&f You have been given an Elevator!'
  worldDisabledMessage: '&b&lELEVATORS&f Elevators have been disabled in this world!'
  elevatorChangedKickedOut: '&c&lELEVATORS&f The elevator has been changed or no longer exists. Leaving menu...'
  chatInputBackOut: '&7Type "cancel" to back out of chat input.'
  chatInputBackOutAllowReset: '&7Type "cancel" to back out of chat input or type "reset" to reset.'
  enterDisplayName: '&c&lELEVATORS&f Enter a new display name into the chat.'
  enterRecipeName: '&c&lELEVATORS&f Enter a new recipe name into the chat.'
  enterRecipePermission: '&c&lELEVATORS&f Enter the new recipe permission node into the chat.'
  enterFloorName: '&c&lELEVATORS&f Enter a new floor name into the chat.'
  enterTitle: '&c&lELEVATORS&f Enter a new title into the chat.'
  enterSubtitle: '&c&lELEVATORS&f Enter a new subtitle into the chat.'
  enterMessage: '&c&lELEVATORS&f Enter a new message into the chat.'
  enterElevatorKey: '&c&lELEVATORS&f Enter a new elevator key into the chat.'
  nonUniqueElevatorKey: '&c&lELEVATORS&f The elevator key must be unique.'
  nonUniqueRecipeName: '&c&lELEVATORS&f The elevator recipe key must be unique for this elevator type.'
  enterCommand: '&c&lELEVATORS&f Enter a new command into the chat.'

Key	Description
cantCreateMessage	Sent to the player whenever trying to craft an elevator but lacks permission.
cantDyeMessage	Sent to the player whenever trying to dye an elevator but lacks permission.
cantUseMessage	Sent to the player whenever trying to use an elevator but lacks permission.
cantGiveMessage	Sent to the player whenever trying to use `/ele give` but lacks permission.
cantAdministrateMessage	Sent to the player whenever trying to use `/ele admin` but lacks permission.
cantReloadMessage	Sent to the player whenever 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.
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`
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:

effects:
  CREEPER:
    file: Creeper.png
    scale: 1
    duration: 1.0
    useHolo: false
    background: '#FFFFFF'

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:

elevators:
  DEFAULT:
    displayName: Elevator
    usePermission: elevators.use
    dyePermission: elevators.dye
    maxDistance: 20
    maxSolidBlocks: -1
    maxStackSize: 16
    classCheck: true
    stopObstruction: true
    supportDying: true
    checkColor: true
    checkPerms: true
    canExplode: false
    hologramLines: []
    loreLines: []
    actions:
      up:
      - 'sound: volume=1.0 sound=ENTITY_BLAZE_SHOOT pitch=2.0'
      down:
      - 'sound: volume=1.0 sound=ENTITY_BLAZE_SHOOT pitch=2.0'
    disabledSettings:
    - change-holo
    - sound/sound
    - action-bar/message
    - boss-bar/message
    - message-player/message
    - title/title
    - title/subtitle
    - effect/effect
    recipes:
      CLASSIC:
        amount: 1
        craftPermission: elevators.craft.classic
        defaultOutputColor: WHITE
        supportMultiColorOutput: true
        supportMultiColorMaterials: true
        recipe:
        - www
        - wew
        - www
        materials:
          w: minecraft:white_wool
          e: minecraft:ender_pearl

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:

displayName: Elevator
usePermission: elevators.use.default
dyePermission: elevators.dye.default
maxDistance: 20
maxSolidBlocks: -1
maxStackSize: 16
classCheck: true
stopObstruction: true
supportDying: true
checkColor: true
checkPerms: true
canExplode: false
hologramLines: []
loreLines: []

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. If set, this plugin will try to use hooked Hologram plugins to display text above the elevator.
loreLines	[]	This is a YAML String Array. 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.

The Elevator Actions Node is split between an up and a down YAML String Array. Here is the default:

actions:
  up:
  - 'sound: volume=1.0 sound=ENTITY_BLAZE_SHOOT pitch=2.0'
  down:
  - 'sound: volume=1.0 sound=ENTITY_BLAZE_SHOOT pitch=2.0'

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

Example:

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

# Explanation

effect: name=HELIX

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

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

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.

This Config Node is a YAML String Array. 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:

disabledSettings:
- change-holo
- sound/sound
- action-bar/message
- boss-bar/message
- message-player/message
- title/title
- title/subtitle
- effect/effect

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

# Elevator Recipes

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

recipes:
  CLASSIC:
    amount: 1
    craftPermission: elevators.craft.classic
    defaultOutputColor: WHITE
    supportMultiColorOutput: true
    supportMultiColorMaterials: true
    recipe:
    - www
    - wew
    - www
    materials:
      w: minecraft:white_wool
      e: minecraft:ender_pearl

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: minecraft:white_wool e: minecraft:ender_peal	Define characters as Minecraft materials for use with the next Key.
recipe	www wew www	Using the characters defined in the `materials` key, recreate a 3x3 crafting grid using a YAML String Array. You can use a space to represent nothing in the slot.