# Custom Elevator Actions

The ElevatorAction Builder API allows developers to define custom elevator behavior that is triggered when an elevator is used. You can define actions, variables, icons, click logic, and execution behavior in a modular and extensible way.

# Getting Started

To begin creating a custom ElevatorAction, use:

ElevatorAction.builder("your-action-key")

This initializes the builder with a unique actionKey that will identify your action. The best time to register an ElevatorAction is whenever ElevatorRegisterActionsEvent is called on the Elevator Plugin startup.

# Builder Methods

The builder provides additional lifecycle hooks:

Method	Description
`.onExecute()`	Called when the action is invoked (e.g., during elevator use)
`.onCheckConditions()`	Called when the action is invoked (e.g., during elevator use). Determines if player can use the elevator.
`.addVariable()`	Allows for the addition of variables to the action
`.onInit()`	Optional setup logic when the action is registered
`.register()`	Finalizes and registers the action. Can take either an `ItemStack` or a `(ChatColor, DisplayName, Material)` trio to define the GUI icon

# Handling Execution

Use .onExecute(executeContext -> { ... }) to define what will happen when the action occurs. Within the lambda, you will deal a ElevatorActionExecuteContext object.

# Handling ConditionCheck

Use .onCheckConditions(executeContext -> { boolean }) to define whether a player is allowed to use an elevator. Within the lambda, you will deal a ElevatorActionExecuteContext object.

# ElevatorActionExecuteContext

The execution context has four methods that will help you develop your action:

Method	Description
`.getVariable()`	Returns the value of the variable with the provided alias
`.getAction()`	Returns the ElevatorAction object that this builder creates
`.getPlayer()`	Returns the player who has executed the action
`.getEventData()`	EventData contains the Origin elevator, Destination elevator, and Direction

# Defining Variables

Use .addVariable(defaultValue, variable -> { ... }) to define parameters your action needs. Within the lambda, you will configure a ElevatorActionVariableBuilder object.

# Required Fields

Each variable must define the following:

Alias – One or more strings the action string can use (e.g., amount, amnt)
Conversion – A method that converts a String to your intended data type
Icon Type – A Material representing the icon in GUI
Display Name – The visible name for the icon
Setting Name – Used to associate this variable with settings. Will default to the first provided alias if not explicitly set.

variable.setAlias("amount", "amnt", "a");
variable.setConversion(Integer::valueOf);
variable.setIconType(Material.EXPERIENCE_BOTTLE);
variable.setDisplayName("Give Experience");
variable.setSettingName("amount");

# Optional Enhancements

setIconDescription(String) – Adds a description to the GUI item
addAction(String clickType, String actionDescription) – Adds lore-style hover actions
onClick(Consumer<ElevatorActionExecuteContext>) – Handles icon click events
allowPerEleCustomization() – Enables the variable to appear in the per-elevator settings menu

# Handling Variable Setting Click

Use .onClick(clickContext -> { ... }) to define what will happen when the variable setting icon is clicked. Within the lambda, you will deal a ElevatorSettingClickContext object.

# ElevatorSettingClickContext

The click context has five methods that will help you develop your action:

Method	Description
`.setValue()`	Sets the value of the variable
`.close()`	Will reopen the menu that had invoked this setting click
`.getCurrentValue()`	Returns the current value of the variable
`.getClickEvent()`	Returns the InventoryClickEvent that had invoked this setting click
`.getPlayer()`	Returns the Player who had invoked this setting click

# Example: Give Experience Action

ElevatorAction.builder("give-exp")
	.addVariable(1, variable -> {
		variable.setAlias("amount","amnt","a");
		variable.setConversion(Integer::valueOf);
		variable.setIconDescription("This option controls the amount of exp given to the player");
		variable.setIconType(Material.EXPERIENCE_BOTTLE);
		variable.setDisplayName("Give Experience");
		variable.setSettingName("amount");
		variable.addAction("Left Click", "Increase Amount");
		variable.addAction("Right Click", "Decrease Amount");
		variable.addAction("Shift Click", "Reset Amount");
		variable.onClick(data -> {
			if(data.getClickEvent().isShiftClick()) {
				data.setValue(1);
				data.close();
				return;
			}

			int newValue = data.getCurrentValue() + (data.getClickEvent().isLeftClick() ? 1 : -1);
			newValue = Math.min(Math.max(newValue, -1), 500);
			data.setValue(newValue);
			data.close();
		});
	})
	.addVariable(true, variable -> {
		variable.setAlias("mending", "mend", "m");
		variable.setConversion(Boolean::parseBoolean);
		variable.setIconDescription("This option controls whether the given exp can be used to mend gear");
		variable.setIconType(Material.STONE_PICKAXE);
		variable.setDisplayName("Allow Mending");
		variable.setSettingName("mending");
		variable.addAction("Left Click", "Toggle Mending");
		variable.onClick(data -> {
			data.setValue(!data.getCurrentValue());
			data.close();
		});
	})
	.onExecute(data -> {
		data.getPlayer().giveExp(data.getVariable("amount"), data.getVariable("mending"));
	})
	.register(ChatColor.GOLD.toString(), "Give Experience", Material.EXPERIENCE_BOTTLE);

🧪 Want to contribute more hooks? Feel free to fork the plugin and submit PRs via GitHub!