Interface Helper


public interface Helper
  • Method Details

    • getJavaVersion

      int getJavaVersion()
      Returns the current java version.
      Returns:
      The current java version used in this JVM
    • parseInt

      @Nullable @Nullable Integer parseInt(String str)
      Parses the string to an int
      Parameters:
      str - The string we want to parse
      Returns:
      Parsed string. Null if it's not valid
    • parseLong

      @Nullable @Nullable Long parseLong(String str)
      Parses the string to a long
      Parameters:
      str - The string we want to parse
      Returns:
      Parsed string. Null if it's not valid
    • parseDouble

      @Nullable @Nullable Double parseDouble(String str)
      Parses the string to a double
      Parameters:
      str - The string we want to parse
      Returns:
      Parsed string. Null if it's not valid
    • formatNumber

      String formatNumber(long num)
      Tries to format the number in a human-readable way.

      Uses system or user configuration to understand in which language it shall format in.
      Example: When user is running an english system and you're passing the number 1989321, then this method returns "1,989,321"

      Parameters:
      num - The number you want to get formatted
      Returns:
      The formatted number
    • formatNumber

      String formatNumber(double num)
      Tries to format the number in a human-readable way.

      Uses system or user configuration to understand in which language it shall format in.
      Example: When user is running an english system and you're passing the number 1989321.5555, then this method returns "1,989,321.555,5"

      Parameters:
      num - The number you want to get formatted
      Returns:
      The formatted number
    • formatNumber

      String formatNumber(BigDecimal num)
      Tries to format the number in a human-readable way.

      Uses system or user configuration to understand in which language it shall format in.
      Example: When user is running an english system and you're passing the number 1989321.5555, then this method returns "1,989,321.555,5"

      Parameters:
      num - The number you want to get formatted
      Returns:
      The formatted number
    • evaluateString

      @Nullable @Nullable Double evaluateString(String expression)
      Tries to evaluate an equation passed in as a String.

      Uses the javaluator library internally. Example: If you pass in the string (e^3-1)*sin(pi/4)*ln(pi^2), the result would be 30.8974331526.

      Parameters:
      expression - The expression you want to evaluate
      Returns:
      The solution to the expression. May be null if the equation is invalid.
    • parseItemStack

      @Nullable @Nullable ItemStack parseItemStack(String str)
      Tries to form an ItemStack given by a String. The same format as every else in the plugin configurations is being used.

      The opposite of that is composeItemStack(ItemStack).

      Parameters:
      str - The String that shall get parsed
      Returns:
      The resulting ItemStack. May be null if the given String is nonsense
    • composeItemStack

      String composeItemStack(ItemStack is)
      Forms a human-readable String given by an ItemStack. The same format as every else in the plugin configurations is being used.

      The opposite of that is parseItemStack(String).

      Parameters:
      is - The ItemStack that shall be parsed
      Returns:
      The resulting human-readable String
    • dye

      ItemStack dye(ItemStack is, DyeColor color)
      Tries to apply a color to an ItemStack if possible. This includes e.g. dying a leather armor or changing the wool color.

      It's possible that this method doesn't return a new instance and instead applies the effect to the instance given.

      Parameters:
      is - The item that shall be dyed
      color - The color that needs to be applied to the item
      Returns:
      Possibly a new instance depending on the internal method used. Otherwise the same ItemStack instance
    • setUnbreakable

      void setUnbreakable(ItemMeta im, boolean unbreakable)
      Sets the "unbreakable" tag to the given ItemMeta.

      You should use this method instead of ItemMeta.setUnbreakable(boolean) as that method has involved in some spigot versions and by that might not work for any user.

      Parameters:
      im - The ItemMeta of the item whose tag shall be changed
      unbreakable - true causes the item to not lose any damage
    • setUnbreakable

      default void setUnbreakable(ItemStack is, boolean unbreakable)
      Sets the "unbreakable" tag to the given item.

      You should use this method instead of ItemMeta.setUnbreakable(boolean) as that method has involved in some spigot versions and by that might not work for any user.

      Parameters:
      is - The item whose tag shall be changed
      unbreakable - true causes the item to not lose any damage
    • replacePAPIPlaceholders

      String replacePAPIPlaceholders(String str, Player player)
      Will return a new String will all the PAPI (or similar supported plugins) being replaced.

      Example: "Hi, my K/D is %mbedwars_stats-kd%"
      will be become: "Hi, my K/D is 1.5"

      Parameters:
      str - The raw string
      Returns:
      The new formatted string
    • getPlayerNickName

      @Nullable @Nullable String getPlayerNickName(Player player)
      Tries to obtain the nicked name of a plugin which possibly has been changed by a third-party nick plugin.

      The plugin automatically injects itself into quite a few nick plugins automatically and tries to obtain the players nick name using their API. In cases where the player is not nicked the method returns null.

      Parameters:
      player - The player whose nickname we want to find out
      Returns:
      The nickname of the player. null if he doesn't have one
    • getNickedPlayerRealName

      String getNickedPlayerRealName(Player player)
      Nicknaming plugins might replace HumanEntity.getName() in favour for the nicked name. This method returns the player's real name.

      The plugin automatically injects itself into quite a few nick plugins automatically and tries to obtain the players real name using their API.

      Parameters:
      player - The player from who want to find out the real name
      Returns:
      His real username
    • getPlayerDisplayName

      String getPlayerDisplayName(Player player)
      Returns the display name of a player that shall be shown to the public.

      Generally, this method works similar to getPlayerNickName(Player). Only that it returns the player's name if he isn't nicked. Meaning that this method never returns null.

      Parameters:
      player - The player whose public display name we want to find out
      Returns:
      His name that can safely be shown to the public
    • isBedrockPlayer

      boolean isBedrockPlayer(UUID uuid)
      Returns whether the player is playing using Minecraft's Bedrock Edition or not.
      Parameters:
      uuid - The id of the player
      Returns:
      true when we are able to confirm that
    • isBedrockPlayer

      boolean isBedrockPlayer(OfflinePlayer player)
      Returns whether the player is playing using Minecraft's Bedrock Edition or not.
      Parameters:
      player - The player we want to check
      Returns:
      true when we are able to confirm that
    • getEntityTypeByName

      @Nullable @Nullable EntityType getEntityTypeByName(String name)
      Tries to identify the type of an entity given by its name.
      Parameters:
      name - The name of the entity
      Returns:
      The EntityType that might fit. null if none was found
    • copy

      int copy(InputStream is, OutputStream os) throws IOException
      Copies bytes from an InputStream to an OutputStream.
      This method buffers the input internally, so there is no need to use a BufferedInputStream.
      Large streams (over 2GB) will return a bytes copied value of -1 after the copy has completed since the correct number of bytes cannot be returned as an int. For large streams use the copyLarge(InputStream, OutputStream) method.
      Parameters:
      is - The InputStream to read.
      os - The OutputStream to write.
      Returns:
      The number of bytes copied, or -1 if greater than Integer.MAX_VALUE.
      Throws:
      IOException - If an I/O error occurs.
    • parseSNBTAsJson

      com.google.gson.JsonObject parseSNBTAsJson(String nbt) throws IllegalArgumentException
      Converts a SNBT (String format of NBT) to a JsonObject.
      Parameters:
      nbt - The data tag
      Returns:
      The converted JsonObject containing the info of the given SNBT tag.
      Throws:
      IllegalArgumentException - When it failed to parse the NBT
    • composeJsonAsSNBT

      String composeJsonAsSNBT(com.google.gson.JsonObject json)
      Tries to convert a JsonObject to a SNBT data tag.

      The process is not perfect due to the way of how json stores their numbers etc.

      Parameters:
      json - The json object
      Returns:
      The converted NBT string containing the info of the JsonObject.
    • setPlayerArmor

      boolean setPlayerArmor(Player player, ItemStack armor, boolean force)
      Tries to make a player wear armor (ie automatically puts an items in a players armor slot)
      Parameters:
      player - the player we are giving the armor to
      armor - itemstack of armor that the player should wear
      force - weather or not to override an existing piece of armor
      Returns:
      whether or not the armor was given successfully
    • givePlayerItem

      void givePlayerItem(Player player, ItemStack itemStack)
      Properly gives an item to a player.

      If a players Inventory is full, the items will be dropped close to them. No items will be deleted/lost (Unlike when using Inventory#addItem())

      Parameters:
      player - the player we are giving the item to
      itemStack - the item that is being given to the player
    • getMaterialByName

      @Nullable @Nullable Material getMaterialByName(String name)
      Tries to identify a material given by its name.
      Parameters:
      name - The name of the material
      Returns:
      The Material that might fit. null if none was found
    • getEffectByName

      @Nullable @Nullable Effect getEffectByName(String name)
      Tries to identify an effect given by its name.
      Parameters:
      name - The name of the effect
      Returns:
      The Effect that might fit. null if none was found
    • getPotionTypeByName

      @Nullable @Nullable PotionType getPotionTypeByName(String name)
      Tries to identify a potion type given by its name.
      Parameters:
      name - The name of the potion type
      Returns:
      The type that might fit. null if none was found
    • getSoundByName

      @Nullable @Nullable Sound getSoundByName(String name)
      Tries to identify a sound given by its name.
      Parameters:
      name - The name of the sound
      Returns:
      The sound that might fit. null if none was found
    • getBlockVariant

      Material getBlockVariant(Material mat)
      Returns the block variant of a material.

      Sometimes there are multiple entries within Material for basically the same material, but with the only difference being that one is thought to be added to the inventory and the other one to be placed. This is especially common in 1.12 and previous versions.

      Parameters:
      mat - The input material
      Returns:
      The output material, possibly the same one as the input one
    • getInventoryVariant

      Material getInventoryVariant(Material mat)
      Returns the inventory variant of a material.

      Sometimes there are multiple entries within Material for basically the same material, but with the only difference being that one is thought to be added to the inventory and the other one to be placed. This is especially common in 1.12 and previous versions.

      Parameters:
      mat - The input material
      Returns:
      The output material, possibly the same one as the input one
    • synchronize

      void synchronize(Runnable runn)
      Runs a given task on the main thread.

      Due to performance reasons, it's not granted that the task will be executed immediately with the next tick-

      Parameters:
      runn - The task that shall be run on the main thread
    • getMinHeight

      int getMinHeight(World world)
      Returns the minimum height of an arena.

      Basically returns World#getMinHeight() on 1.17+. Always returns 0 on older version. Useful when you're trying to add support for newer versions.

      Parameters:
      world - The world
      Returns:
      The minimum height at which players may place blocks at
    • getPlayerSkinData

      @Nullable @Nullable Pair<String,String> getPlayerSkinData(Player player)
      Gets the texture & signature of the player's skin.

      Note that the method may return null when the skin generally can't be seen, such as when the server is on cracked mode, when the server hasn't fetched the skin yet or when no custom skin has been defined by the player.

      Parameters:
      player - The player from whom we want to fetch it
      Returns:
      A pair, with the key being the texture, and the value being the signature. May be null if he doesn't have one
    • getBukkitChatColorFromBungee

      ChatColor getBukkitChatColorFromBungee(net.md_5.bungee.api.ChatColor color)
      Gets the ChatColor (from the Bukkit package) that fits the most to the Bungee color.

      This method also supports hex colors.

      Parameters:
      color - The color instance from the Bungee package
      Returns:
      The matching Spigot color
    • getBlockAsync

      default void getBlockAsync(Location location, Consumer<Block> callback)
      Allows you to retrieve and modify a block asynchronously on 1.14+

      If run on unsupported versions, the loading of the block, as well as the execution callback will occur synchronously

      Parameters:
      location - the location of the block
      callback - called when the block is ready to be used
    • getBlockAsync

      default void getBlockAsync(World world, XYZ xyz, Consumer<Block> callback)
      Allows you to retrieve and modify a block asynchronously on 1.14+

      If run on unsupported versions, the loading of the block, as well as the execution callback will occur synchronously

      Parameters:
      world - the world of the block
      xyz - the coordinates if the block
      callback - called when the block is ready to be used
    • getBlockAsync

      void getBlockAsync(World world, int x, int y, int z, Consumer<Block> callback)
      Allows you to retrieve and modify a block asynchronously on 1.14+

      If run on unsupported versions, the loading of the block, as well as the execution callback will occur synchronously

      Parameters:
      world - the world of the block
      x - the x coordinate of the block
      y - the y coordinate of the block
      z - the z coordinate of the block
      callback - called when the block is ready to be used
    • getChunkAsync

      void getChunkAsync(World world, int x, int z, Consumer<Chunk> callback)
      Allows you to retrieve and modify a block asynchronously on 1.14+

      If run on unsupported versions, the loading of the chunk, as well as the execution callback will occur synchronously

      Parameters:
      world - the world of the chunk
      x - the x coordinate of the chunk
      z - they y coordinate of the chunk
      callback - called when the chunk is ready to be used
    • teleportAsync

      void teleportAsync(Entity entity, Location loc, @Nullable @Nullable Runnable callback)
      Allows you to teleport entities asynchronously on 1.14+

      If run on unsupported versions, the teleport and callback will be called synchronously. The callback can be null if nothing needs to be done after the entity has teleported.

      Parameters:
      entity - The entity being teleported
      loc - The location the entity should be teleported to
      callback - Called after the entity has been teleported
    • playSound

      void playSound(Player player, Location location, Sound sound, float volume, float pitch)
      Plays a sound - even on a non-main thread.

      It is not possible anymore to play a sound on a non-main thread since 1.19. This method fixes it, but you may surely use this method on the main thread and on older versions as well.

      Parameters:
      player - The player who shall hear the sound
      location - The location where the sound shall be played
      sound - The sound that shall be played
      volume - The volume of the sound
      pitch - The pitch of the sound
    • playSound

      void playSound(Location location, Sound sound, float volume, float pitch)
      Plays a sound - even on a non-main thread.

      It is not possible anymore to play a sound on a non-main thread since 1.19. This method fixes it, but you may surely use this method on the main thread and on older versions as well.

      Parameters:
      location - The location where the sound shall be played
      sound - The sound that shall be played
      volume - The volume of the sound
      pitch - The pitch of the sound
    • playCustomSound

      void playCustomSound(Player player, Location location, String sound, float volume, float pitch)
      Plays a custom sound - even on a non-main thread.

      It is not possible anymore to play a sound on a non-main thread since 1.19. This method fixes it, but you may surely use this method on the main thread and on older versions as well.

      This method does not play vanilla sounds and only works on 1.9+

      Parameters:
      player - The player who shall hear the sound
      location - The location where the sound shall be played
      sound - The sound that shall be played
      volume - The volume of the sound
      pitch - The pitch of the sound
    • playCustomSound

      void playCustomSound(Location location, String sound, float volume, float pitch)
      Plays a custom sound - even on a non-main thread.

      It is not possible anymore to play a sound on a non-main thread since 1.19. This method fixes it, but you may surely use this method on the main thread and on older versions as well.

      This method does not play vanilla sounds and only works on 1.9+

      Parameters:
      location - The location where the sound shall be played
      sound - The sound that shall be played
      volume - The volume of the sound
      pitch - The pitch of the sound
    • get

      static Helper get()
      Contains utility stuff.
      Returns:
      The global Helper instance