Interface MagicSender

public interface MagicSender
Platform-agnostic command sender wrapper.

  • Method Summary

    Modifier and Type
    Method
    Description
    default @Nullable String
    address()
    IP address of the sender, if available.
    Audience
    audience()
    Audience for sending messages back to the sender.
    @Nullable Object
    handle()
    Raw platform sender handle.
    static boolean
    hasPermission(Object sender, String permission)
    Checks permission on raw sender using registered adapters.
    static boolean
    hasPermission(Object sender, String permission, int fallbackOpLevel)
    Checks permission on raw sender using registered adapters and a custom op-level fallback.
    boolean
    hasPermission(String permission)
    Permission check for the sender.
    default boolean
    hasPermission(String permission, int fallbackOpLevel)
    Permission check for the sender with a custom op-level fallback.
    default @Nullable UUID
    id()
    Optional sender id (player UUID, if available).
    String
    name()
    Human-readable sender name.
    default CompletableFuture<Boolean>
    teleport(@Nullable String worldName, double x, double y, double z)
    Teleports the sender to a location, if the platform and sender support it.
    default <T> T
    unwrap(Class<T> type)
    Attempt to unwrap the raw handle to the given type.
    static @Nullable MagicSender
    wrap(Object sender)
    Wrap raw sender instance into MagicSender if a platform adapter is available.

  • Method Details

    • wrap

      @Nullable static @Nullable MagicSender wrap(Object sender)
      Wrap raw sender instance into MagicSender if a platform adapter is available.
      Parameters:
      sender - raw sender instance
      Returns:
      wrapped sender or null if unsupported

    • hasPermission

      static boolean hasPermission(Object sender, String permission)
      Checks permission on raw sender using registered adapters.
      Parameters:
      sender - raw sender instance
      permission - permission node
      Returns:
      true if granted

    • hasPermission

      static boolean hasPermission(Object sender, String permission, int fallbackOpLevel)
      Checks permission on raw sender using registered adapters and a custom op-level fallback.
      Parameters:
      sender - raw sender instance
      permission - permission node
      fallbackOpLevel - op level to treat as granted when no permission backend answers
      Returns:
      true if granted

    • audience

      Audience audience()
      Audience for sending messages back to the sender.
      Returns:
      audience wrapper

    • name

      String name()
      Human-readable sender name.
      Returns:
      sender name

    • id

      @Nullable default @Nullable UUID id()
      Optional sender id (player UUID, if available).
      Returns:
      sender id or null

    • hasPermission

      boolean hasPermission(String permission)
      Permission check for the sender.
      Parameters:
      permission - permission node
      Returns:
      true if granted

    • hasPermission

      default boolean hasPermission(String permission, int fallbackOpLevel)
      Permission check for the sender with a custom op-level fallback.

      Platforms that support fallback-aware permission checks should override this method. The default implementation preserves existing behavior.

      Parameters:
      permission - permission node
      fallbackOpLevel - op level to treat as granted when no permission backend answers
      Returns:
      true if granted

    • address

      @Nullable default @Nullable String address()
      IP address of the sender, if available.
      Returns:
      IP address string or null

    • teleport

      default CompletableFuture<Boolean> teleport(@Nullable @Nullable String worldName, double x, double y, double z)
      Teleports the sender to a location, if the platform and sender support it.

      Coordinates are used rather than a platform Location so this stays on the platform-agnostic interface. A worldName of null means "the sender's current world"; platforms that cannot resolve a world by name may ignore it. The move is asynchronous by contract: on Folia/Canvas a synchronous teleport throws on any thread, so implementations must route through the platform's async teleport and complete the returned future when the move resolves.

      The default implementation is a no-op for senders that cannot be teleported (console, non-player) and completes with false. Platforms whose senders can move (e.g. Bukkit players) override this.

      Parameters:
      worldName - target world name, or null for the sender's current world
      x - target x
      y - target y
      z - target z
      Returns:
      a future completed with true once the sender arrives, false if the sender cannot be teleported

    • handle

      @Nullable @Nullable Object handle()
      Raw platform sender handle.
      Returns:
      underlying sender object

    • unwrap

      @Nullable default <T> T unwrap(Class<T> type)
      Attempt to unwrap the raw handle to the given type.
      Type Parameters:
      T - type parameter
      Parameters:
      type - target class
      Returns:
      unwrapped handle or null if not compatible