Package org.skriptlang.skript.bukkit.lang.eventvalue

Interface EventValue<E extends org.bukkit.event.Event,V>

public sealed interface EventValue<E extends org.bukkit.event.Event,V>
Describes a single "event value" available in a specific Event context. An event value provides a typed value (e.g. the player, entity, location) for a given event and can optionally support changing that value via Skript's Changer API.

Each event value is identified by one or more textual identifier patterns that are matched against user input (e.g. "player", "entity"). Resolution and lookup are handled by EventValueRegistry.

Instances should be created using builder(Class, Class) and registered via EventValueRegistry.register(EventValue).

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    EventValue.Builder<E extends org.bukkit.event.Event,V>
    A builder for creating EventValue instances.
    static interface 
    EventValue.Changer<E extends org.bukkit.event.Event,V>
    A changer for applying modifications to the value for a given event instance.
    static interface 
    EventValue.NoValueChanger<E extends org.bukkit.event.Event,V>
    A changer that does not require a value to be passed (e.g.
    static enum 
    EventValue.Time
    Represents the time state an event value is registered for.
    static enum 
    EventValue.Validation
    Represents the validation status of an event value against an event context.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <E extends org.bukkit.event.Event, V>
    EventValue.Builder<E,V>
    builder(Class<E> eventClass, Class<V> valueClass)
    Creates a new builder for an EventValue.
    Optional<EventValue.Changer<E,V>>
    changer(Changer.ChangeMode mode)
    Returns the changer for the specified Changer.ChangeMode, if present.
    Converter<E,V>
    converter()
    The converter used to obtain the value from the event.
    Class<E>
    eventClass()
    The event class this value applies to.
    @Nullable String
    excludedErrorMessage()
    An optional error message shown when this value is excluded for a matching event.
    Class<? extends E> @Nullable []
    excludedEvents()
    Event types explicitly excluded from using this event value.
    V
    get(E event)
    Obtains the value from the given event instance.
    <ConvertedEvent extends org.bukkit.event.Event, ConvertedValue>
    @Nullable EventValue<ConvertedEvent,ConvertedValue>
    getConverted(Class<ConvertedEvent> newEventClass, Class<ConvertedValue> newValueClass)
    Returns a new event value that converts this value to a different value class, or uses a different event class.
    default <NewEvent extends org.bukkit.event.Event, NewValue>
    @Nullable EventValue<NewEvent,NewValue>
    getConverted(Class<NewEvent> newEventClass, Class<NewValue> newValueClass, Converter<V,NewValue> converter)
    Returns a new event value that converts this value to a different value class using the provided converter.
    <NewEvent extends org.bukkit.event.Event, NewValue>
    EventValue<NewEvent,NewValue>
    getConverted(Class<NewEvent> newEventClass, Class<NewValue> newValueClass, Converter<V,NewValue> converter, @Nullable Converter<NewValue,V> reverseConverter)
    Returns a new event value that converts this value to a different value class using the provided converter and reverse converter.
    boolean
    hasChanger(Changer.ChangeMode mode)
    Checks whether a changer is supported for the specified Changer.ChangeMode.
    default boolean
    matches(Class<? extends org.bukkit.event.Event> eventClass, Class<?> valueClass)
    Checks whether this event value matches the provided event class and value class.
    default boolean
    matches(Class<? extends org.bukkit.event.Event> eventClass, Class<?> valueClass, String[] patterns)
    Checks whether this event value matches the provided event class, value class, and identifier patterns.
    default boolean
    matches(EventValue<?,?> eventValue)
    Checks whether this event value matches the provided event value in terms of event class, value class, and identifier patterns.
    boolean
    matchesInput(String input)
    Checks whether the provided input matches one of patterns() and satisfies any additional input validation.
    String @Nullable []
    patterns()
    Patterns used to identify this event value from user input.
    static <E extends org.bukkit.event.Event, V>
    EventValue<E,V>
    simple(Class<E> eventClass, Class<V> valueClass, Converter<E,V> converter)
    Creates a new EventValue using a getter
    EventValue.Time
    time()
    The time state this event value is registered for.
    EventValue.Validation
    validate(Class<?> event)
    Validates that this event value can be used in the provided event context.
    Class<V>
    valueClass()
    The type of the value produced by this event value.

  • Method Details

    • builder

      static <E extends org.bukkit.event.Event, V> EventValue.Builder<E,V> builder(Class<E> eventClass, Class<V> valueClass)
      Creates a new builder for an EventValue.
      Parameters:
      eventClass - the event type this value applies to
      valueClass - the value type to produce
      Returns:
      a builder to configure and build the event value
      See Also:

    • simple

      static <E extends org.bukkit.event.Event, V> EventValue<E,V> simple(Class<E> eventClass, Class<V> valueClass, Converter<E,V> converter)
      Creates a new EventValue using a getter
      Parameters:
      eventClass - the event type this value applied to
      valueClass - the value type to produce
      converter - the getter
      Returns:
      the constructed event value
      See Also:

    • eventClass

      Class<E> eventClass()
      The event class this value applies to.
      Returns:
      the event type this event value is defined for

    • valueClass

      Class<V> valueClass()
      The type of the value produced by this event value.
      Returns:
      the value type

    • patterns

      String @Nullable [] patterns()
      Patterns used to identify this event value from user input.
      Returns:
      the patterns

    • validate

      EventValue.Validation validate(Class<?> event)
      Validates that this event value can be used in the provided event context.
      Parameters:
      event - the concrete event class to validate against
      Returns:
      the validation status

    • matchesInput

      boolean matchesInput(String input)
      Checks whether the provided input matches one of patterns() and satisfies any additional input validation.
      Parameters:
      input - the identifier provided by the user
      Returns:
      true if the validation succeeds

    • get

      V get(E event)
      Obtains the value from the given event instance.
      Parameters:
      event - the event instance
      Returns:
      the value obtained from the event, which may be null

    • converter

      Converter<E,V> converter()
      The converter used to obtain the value from the event.
      Returns:
      the converter

    • hasChanger

      boolean hasChanger(Changer.ChangeMode mode)
      Checks whether a changer is supported for the specified Changer.ChangeMode.
      Parameters:
      mode - the change mode
      Returns:
      true if a changer is supported

    • changer

      Optional<EventValue.Changer<E,V>> changer(Changer.ChangeMode mode)
      Returns the changer for the specified Changer.ChangeMode, if present.
      Parameters:
      mode - the change mode
      Returns:
      an Optional containing the changer if available

    • time

      EventValue.Time time()
      The time state this event value is registered for.
      Returns:
      the time state

    • excludedEvents

      Class<? extends E> @Nullable [] excludedEvents()
      Event types explicitly excluded from using this event value.
      Returns:
      an array of excluded event classes or null if none

    • excludedErrorMessage

      @Nullable @Nullable String excludedErrorMessage()
      An optional error message shown when this value is excluded for a matching event.
      Returns:
      the exclusion error message or null

    • matches

      default boolean matches(EventValue<?,?> eventValue)
      Checks whether this event value matches the provided event value in terms of event class, value class, and identifier patterns.
      Parameters:
      eventValue - the event value to compare against
      Returns:
      true if they match

    • matches

      default boolean matches(Class<? extends org.bukkit.event.Event> eventClass, Class<?> valueClass, String[] patterns)
      Checks whether this event value matches the provided event class, value class, and identifier patterns.
      Parameters:
      eventClass - the event class to compare against
      valueClass - the value class to compare against
      patterns - the patterns to compare against
      Returns:
      true if they match

    • matches

      default boolean matches(Class<? extends org.bukkit.event.Event> eventClass, Class<?> valueClass)
      Checks whether this event value matches the provided event class and value class.
      Parameters:
      eventClass - the event class to compare against
      valueClass - the value class to compare against
      Returns:
      true if they match

    • getConverted

      @Nullable <ConvertedEvent extends org.bukkit.event.Event, ConvertedValue> @Nullable EventValue<ConvertedEvent,ConvertedValue> getConverted(Class<ConvertedEvent> newEventClass, Class<ConvertedValue> newValueClass)
      Returns a new event value that converts this value to a different value class, or uses a different event class.

      This method attempts to find a suitable converter for the value classes automatically.

      Type Parameters:
      ConvertedEvent - the new event type
      ConvertedValue - the new value type
      Parameters:
      newEventClass - the new event class
      newValueClass - the new value class
      Returns:
      a new converted event value, or null if no converter was found

    • getConverted

      @Nullable default <NewEvent extends org.bukkit.event.Event, NewValue> @Nullable EventValue<NewEvent,NewValue> getConverted(Class<NewEvent> newEventClass, Class<NewValue> newValueClass, Converter<V,NewValue> converter)
      Returns a new event value that converts this value to a different value class using the provided converter.
      Type Parameters:
      NewEvent - the new event type
      NewValue - the new value type
      Parameters:
      newEventClass - the new event class
      newValueClass - the new value class
      converter - the converter to use
      Returns:
      a new converted event value
      See Also:

    • getConverted

      <NewEvent extends org.bukkit.event.Event, NewValue> EventValue<NewEvent,NewValue> getConverted(Class<NewEvent> newEventClass, Class<NewValue> newValueClass, Converter<V,NewValue> converter, @Nullable @Nullable Converter<NewValue,V> reverseConverter)
      Returns a new event value that converts this value to a different value class using the provided converter and reverse converter.
      Type Parameters:
      NewEvent - the new event type
      NewValue - the new value type
      Parameters:
      newEventClass - the new event class
      newValueClass - the new value class
      converter - the converter to use to obtain the new value type
      reverseConverter - the reverse converter to use for changing the value, if available
      Returns:
      a new converted event value