Package com.kamikazejam.kamicommon.nms

Class NmsAPI

java.lang.Object
com.kamikazejam.kamicommon.nms.NmsAPI
public class NmsAPI extends Object
Central API facade for all NMS (Net Minecraft Server) functionality in KamiCommon.

This class serves as the primary entry point for accessing version-independent NMS operations, providing a unified interface that abstracts away the complexity of Minecraft's evolving internal APIs. It integrates all provider systems and wrapper components to deliver consistent functionality across 13+ years of Minecraft evolution.

The API is built on a sophisticated provider system that automatically detects the current Minecraft version and selects appropriate implementations for:

  • High-performance block manipulation and world operations
  • Advanced entity management and spawner mechanics
  • Interactive message systems with hover events and click actions
  • Direct packet manipulation for custom client-server communication
  • Command registration and management systems
  • Item manipulation and metadata editing
  • Cross-version teleportation without event triggers
  • Dual-wielding and main/off-hand item management

Version Support: This API supports Minecraft versions 1.8 through 1.21+, automatically adapting to major API changes including the 1.13 "flattening" update, 1.17 NMS restructuring, and 1.20.5+ Mojang-mapped implementations.

Performance: All NMS operations provided by this API are optimized for performance and bypass normal Bukkit overhead where appropriate, making them suitable for high-frequency operations and bulk world modifications.

Example usage: 


 // High-performance block operations
 AbstractBlockUtil blockUtil = NmsAPI.getBlockUtil();
 blockUtil.setBlockSuperFast(block, XMaterial.STONE, PlaceType.NMS);
 
 // Interactive messaging
 AbstractMessageManager messageManager = NmsAPI.getMessageManager();
 KMessage message = KMessageSingle.ofClickRunCommand("Click me!", "/help");
 messageManager.processAndSend(player, message);
 
 // Direct world access
 NMSWorld nmsWorld = NmsAPI.getNMSWorld(bukkitWorld);
 nmsWorld.refreshBlockAt(player, x, y, z);
 
 // Cross-version item handling
 ItemStack mainHand = NmsAPI.getItemInMainHand(player);
 NmsAPI.setItemInOffHand(player, itemStack);

  • Constructor Details

    • NmsAPI

      public NmsAPI()

  • Method Details

    • getJavaColor

      public static Color getJavaColor(ChatColor chatColor)
      Converts a Bukkit ChatColor to an AWT Color object.

      This method provides cross-version conversion from Minecraft's chat color system to Java's AWT Color representation. On versions 1.16.2+, this uses native color methods for accurate conversion. On earlier versions, it uses approximated RGB values.

      Parameters:
      chatColor - the ChatColor to convert
      Returns:
      the equivalent AWT Color object

    • getBlockUtil

      public static AbstractBlockUtil getBlockUtil()
      Retrieves the version-appropriate block utility implementation.

      Block utilities provide high-performance block manipulation methods that significantly outperform standard Bukkit operations, particularly for bulk modifications like world generation or schematic pasting.

      Returns:
      the AbstractBlockUtil for the current Minecraft version

    • getItemText

      public static AbstractItemTextPre_1_17 getItemText()
      Retrieves the pre-1.17 item text implementation.

      This method provides access to item text and tooltip generation systems for Minecraft versions before 1.17. For 1.17+ versions, use the message manager's integrated text components instead.

      Returns:
      the AbstractItemTextPre_1_17 for pre-1.17 versions

    • getTeleporter

      public static AbstractTeleporter getTeleporter()
      Retrieves the version-appropriate teleporter implementation.

      Teleporters provide direct NMS-based player teleportation that bypasses Bukkit events, offering improved performance for scenarios requiring rapid or silent player movement.

      Returns:
      the AbstractTeleporter for the current Minecraft version

    • getMessageManager

      public static AbstractMessageManager getMessageManager()
      Retrieves the version-appropriate message manager implementation.

      Message managers handle interactive message processing with support for hover events, click actions, and rich text formatting across different text component systems (Bungee/MD5 vs Kyori Adventure).

      Returns:
      the AbstractMessageManager for the current Minecraft version

    • getItemEditor

      public static AbstractItemEditor getItemEditor()
      Retrieves the version-appropriate item editor implementation.

      Item editors provide advanced ItemMeta manipulation capabilities that extend beyond standard Bukkit API functionality, including properties like unbreakable flags and custom attributes.

      Returns:
      the AbstractItemEditor for the current Minecraft version

    • getNmsItemMethods

      public static NmsItemMethods getNmsItemMethods()
      Retrieves the version-appropriate NMS item methods implementation.

      NMS item methods provide access to internal item names, translation keys, and other properties that are essential for plugins requiring deep item inspection or compatibility with external systems.

      Returns:
      the NmsItemMethods for the current Minecraft version

    • getEntityMethods

      public static AbstractEntityMethods getEntityMethods()
      Retrieves the version-appropriate entity methods implementation.

      Entity methods provide advanced entity manipulation capabilities including dimension handling, AI control, persistence settings, and spawner item management across different Minecraft versions.

      Returns:
      the AbstractEntityMethods for the current Minecraft version

    • getPacketHandler

      public static NMSPacketHandler getPacketHandler()
      Retrieves the version-appropriate packet handler implementation.

      Packet handlers provide advanced packet manipulation capabilities for custom client-server communication, entity effects, and network operations that go beyond standard Bukkit capabilities.

      Returns:
      the NMSPacketHandler for the current Minecraft version

    • getCommandMapModifier

      public static CommandMapModifier getCommandMapModifier()
      Retrieves the version-appropriate command map modifier implementation.

      Command map modifiers enable dynamic command registration and unregistration without requiring plugin reloads, supporting features like command aliasing and runtime command modifications.

      Returns:
      the CommandMapModifier for the current Minecraft version

    • getItemInMainHand

      @Nullable public static @Nullable ItemStack getItemInMainHand(@NotNull @NotNull Player player)
      Retrieves the item in the player's main hand.

      This method provides cross-version access to main hand items, properly handling the transition from single-hand (1.8) to dual-wielding (1.9+) systems.

      Parameters:
      player - the Player to query
      Returns:
      the ItemStack in the main hand, or null if empty

    • setItemInMainHand

      public static void setItemInMainHand(@NotNull @NotNull Player player, @Nullable @Nullable ItemStack itemStack)
      Sets the item in the player's main hand.

      This method provides cross-version main hand item setting, ensuring compatibility across both single-hand and dual-wielding versions.

      Parameters:
      player - the Player to modify
      itemStack - the ItemStack to place in the main hand, or null to clear

    • getItemInOffHand

      @Nullable public static @Nullable ItemStack getItemInOffHand(@NotNull @NotNull Player player)
      Retrieves the item in the player's off-hand.

      This method provides cross-version access to off-hand items. On versions before 1.9 (which lack dual-wielding), this always returns null.

      Parameters:
      player - the Player to query
      Returns:
      the ItemStack in the off-hand, or null if empty or unsupported

    • setItemInOffHand

      public static void setItemInOffHand(@NotNull @NotNull Player player, @Nullable @Nullable ItemStack itemStack) throws UnsupportedOperationException
      Sets the item in the player's off-hand.

      This method provides cross-version off-hand item setting. On versions before 1.9 (which lack dual-wielding), this throws an UnsupportedOperationException.

      Parameters:
      player - the Player to modify
      itemStack - the ItemStack to place in the off-hand, or null to clear
      Throws:
      UnsupportedOperationException - if called on versions before 1.9

    • getNamespaced

      public static String getNamespaced(Enchantment enchantment)
      Retrieves the namespaced identifier for an enchantment.

      This method provides cross-version access to enchantment identifiers, handling the transition from numeric IDs (pre-1.13) to namespaced identifiers (1.13+) introduced by the "flattening" update.

      Parameters:
      enchantment - the Enchantment to identify
      Returns:
      the namespaced identifier string (e.g., "minecraft:sharpness")

    • getNMSWorld

      @NotNull public static @NotNull NMSWorld getNMSWorld(@NotNull @NotNull World world)
      Creates an NMS world wrapper for the specified Bukkit world.

      This method creates a version-appropriate NMS world wrapper that provides direct access to Minecraft's internal world representation, enabling high-performance world operations, chunk management, and entity spawning.

      Parameters:
      world - the Bukkit World to wrap
      Returns:
      an NMSWorld wrapper for the specified world