Package io.artificial.enchantments.optional.packetevents

Class PacketEventsAdapter

java.lang.Object
io.artificial.enchantments.optional.packetevents.PacketEventsAdapter
public final class PacketEventsAdapter extends Object
Optional PacketEvents adapter for Artificial Enchantments.

This module provides packet-level inventory item customization when PacketEvents is available. It is completely optional and disabled by default. The core library functions fully without this module or PacketEvents.

Key capabilities:

  • Per-player visual customization of item lore and glint
  • Packet interception for WINDOW_ITEMS and SET_SLOT packets
  • Non-invasive display-only modifications (never alters item state)

Design principles:

  • Soft dependency - no hard requirement on PacketEvents
  • Graceful degradation - silently disabled if PacketEvents absent
  • Display-only - only modifies visual presentation, never enchantment state
  • Opt-in - must be explicitly enabled via configuration
Since:
0.1.0
See Also:

  • Constructor Details

    • PacketEventsAdapter

      public PacketEventsAdapter(@NotNull @NotNull ArtificialEnchantmentsPlugin plugin)
      Creates a new PacketEventsAdapter instance.

      The adapter starts in a disabled state and must be explicitly enabled via enable(). This constructor performs no classloading of PacketEvents classes, making it safe to instantiate regardless of PacketEvents presence.

      Parameters:
      plugin - the ArtificialEnchantments plugin instance
      Throws:
      NullPointerException - if plugin is null

  • Method Details

    • isPacketEventsAvailable

      public boolean isPacketEventsAvailable()
      Checks if PacketEvents is present on the server.

      This performs a safe check that does not trigger classloading of PacketEvents classes. It only checks if the plugin is loaded.

      Returns:
      true if PacketEvents plugin is present

    • isEnabled

      public boolean isEnabled()
      Checks if the adapter is enabled and actively processing packets.
      Returns:
      true if enabled and processing packets

    • enable

      public boolean enable()
      Enables the PacketEvents adapter if PacketEvents is available.

      This method:

      1. Checks if PacketEvents plugin is present
      2. Validates PacketEvents API version compatibility
      3. Registers packet listeners
      4. Initializes the visual processor

      If PacketEvents is not present, this method logs at FINE level and returns without error. The adapter remains in a disabled but non-error state.

      Returns:
      true if successfully enabled, false if PacketEvents unavailable or initialization failed

    • disable

      public void disable()
      Disables the adapter and unregisters all packet listeners.

      This is safe to call even if the adapter was never enabled. All player preferences are cleared.

    • getVisualProcessor

      @Nullable public @Nullable ItemVisualProcessor getVisualProcessor()
      Gets the visual processor for customizing item display.

      Returns null if the adapter is not enabled. Callers should check isEnabled() before using this.

      Returns:
      the visual processor, or null if not enabled

    • setPlayerPreferences

      public void setPlayerPreferences(@NotNull @NotNull UUID playerId, @NotNull @NotNull PacketEventsAdapter.PlayerVisualPreferences preferences)
      Sets visual preferences for a specific player.

      These preferences control how items appear to this specific player without modifying the actual item state.

      Parameters:
      playerId - the player's UUID
      preferences - the visual preferences
      Throws:
      NullPointerException - if either parameter is null

    • getPlayerPreferences

      @Nullable public @Nullable PacketEventsAdapter.PlayerVisualPreferences getPlayerPreferences(@NotNull @NotNull UUID playerId)
      Gets the visual preferences for a player.
      Parameters:
      playerId - the player's UUID
      Returns:
      the preferences, or null if not set
      Throws:
      NullPointerException - if playerId is null

    • removePlayerPreferences

      public void removePlayerPreferences(@NotNull @NotNull UUID playerId)
      Removes visual preferences for a player.
      Parameters:
      playerId - the player's UUID
      Throws:
      NullPointerException - if playerId is null

    • clearAllPlayerPreferences

      public void clearAllPlayerPreferences()
      Clears all player visual preferences.

    • getPlugin

      @NotNull public @NotNull ArtificialEnchantmentsPlugin getPlugin()
      Gets the plugin instance.
      Returns:
      the ArtificialEnchantments plugin

    • getAPI

      @NotNull public @NotNull ArtificialEnchantmentsAPI getAPI()
      Gets the API instance.
      Returns:
      the ArtificialEnchantments API