Package me.keehl.elevators.api.models

Class ElevatorEffect

  • All Implemented Interfaces:
    IElevatorEffect
    public abstract class ElevatorEffect
extends java.lang.Object
implements IElevatorEffect
    Convenience base class for implementing custom IElevatorEffects.

    Third-party developers may extend this class to create custom effects while reusing common helpers such as effect location and dye-based particle color.

    Key normalization

    The provided effectKey is normalized to uppercase for consistency. Consumers should treat effect keys as case-insensitive.

    Threading

    Effects typically interact with the world (particles/sounds). Implementations should assume playEffect(IElevatorEventData, IElevator) is called from the server thread. Will run on location threads if in a Folia environment

    • Constructor Summary

      Constructors 
      Constructor Description
      ElevatorEffect​(@NotNull java.lang.String effectKey, @NotNull org.bukkit.inventory.ItemStack icon)
      Creates a new effect with a server-wide identifying key and an icon.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      @NotNull java.lang.String getEffectKey()
      Returns the server-wide key that identifies this effect.
      protected @NotNull org.bukkit.Location getEffectLocation​(@NotNull IElevator elevator)
      Returns the base location where effects should be played.
      @NotNull org.bukkit.inventory.ItemStack getIcon()
      Returns the icon used to represent this effect in UIs.
      protected @NotNull org.bukkit.Color getParticleColor​(@NotNull IElevator elevator)
      Returns the particle color derived from the elevator's dye color.
      abstract void playEffect​(@NotNull IElevatorEventData teleportResult, @NotNull IElevator elevator)
      Plays this effect for the given event and elevator.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • ElevatorEffect

        public ElevatorEffect​(@NotNull
                      @NotNull java.lang.String effectKey,
                      @NotNull
                      @NotNull org.bukkit.inventory.ItemStack icon)
        Creates a new effect with a server-wide identifying key and an icon.

        Contract:

        • effectKey and icon must be non-null.
        • effectKey is stored in uppercase.
        Parameters:
        effectKey - non-null identifying key for this effect
        icon - non-null icon used for UI display
        Throws:
        java.lang.NullPointerException - if any argument is null

    • Method Detail

      • getEffectLocation

        @NotNull
protected @NotNull org.bukkit.Location getEffectLocation​(@NotNull
                                                         @NotNull IElevator elevator)
        Returns the base location where effects should be played.

        The default implementation returns a clone of IElevator.getLocation() to avoid mutating the elevator's underlying location.

        Subclasses may override to offset the effect location (for example, above the shulker box).

        Parameters:
        elevator - non-null elevator instance
        Returns:
        non-null effect location
        Throws:
        java.lang.NullPointerException - if elevator is null

      • getParticleColor

        @NotNull
protected @NotNull org.bukkit.Color getParticleColor​(@NotNull
                                                     @NotNull IElevator elevator)
        Returns the particle color derived from the elevator's dye color.

        The default implementation uses IElevator.getDyeColor() to derive an RGB Color.

        Parameters:
        elevator - non-null elevator instance
        Returns:
        non-null particle color
        Throws:
        java.lang.NullPointerException - if elevator is null

      • getEffectKey

        @NotNull
public final @NotNull java.lang.String getEffectKey()
        Returns the server-wide key that identifies this effect.
        Specified by:
        getEffectKey in interface IElevatorEffect
        Returns:
        the non-null effect key

      • getIcon

        @NotNull
public final @NotNull org.bukkit.inventory.ItemStack getIcon()
        Returns the icon used to represent this effect in UIs.
        Specified by:
        getIcon in interface IElevatorEffect
        Returns:
        the non-null icon

      • playEffect

        public abstract void playEffect​(@NotNull
                                @NotNull IElevatorEventData teleportResult,
                                @NotNull
                                @NotNull IElevator elevator)
        Plays this effect for the given event and elevator.

        Implementations may spawn particles, play sounds, or otherwise interact with the world.

        Specified by:
        playEffect in interface IElevatorEffect
        Parameters:
        teleportResult - non-null event context describing the elevator interaction/teleport
        elevator - non-null elevator instance