Package nl.pim16aap2.lightkeeper.framework

Class PlayerHandle

java.lang.Object
nl.pim16aap2.lightkeeper.framework.PlayerHandle
public final class PlayerHandle extends Object
Handle for a synthetic player.

This type exposes common player actions used in end-to-end tests and supports fluent method chaining for orchestration-style tests.

  • Method Details

    • uniqueId

      public UUID uniqueId()
      Gets the synthetic player UUID.
      Returns:
      Player UUID.

    • name

      public String name()
      Gets the current player name.
      Returns:
      The player name.

    • executeCommand

      public PlayerHandle executeCommand(String command)
      Executes a command as this player.
      Parameters:
      command - Command text. Leading slash is optional.
      Returns:
      This handle for fluent chaining.

    • tabComplete

      public List<String> tabComplete(String commandLine)
      Computes command tab-completions for this player as if they had typed the given command-line buffer.

      The suggestions come from the live server command map and are permission-filtered for this player, so a bot that lacks a command's permission never sees it completed. A leading slash is accepted and normalized away agent-side, so "/gamemode" and "gamemode" behave identically; the buffer is otherwise passed through unmodified, so a trailing space (which selects argument completion rather than command-name completion) is preserved.

      Parameters:
      commandLine - The command-line buffer to complete; must not be blank.
      Returns:
      The tab-completion suggestions in server order; empty for an unknown command.

    • teleport

      public PlayerHandle teleport(WorldHandle world, double x, double y, double z)
      Teleports this player to target coordinates in a world.
      Parameters:
      world - Target world.
      x - X coordinate.
      y - Y coordinate.
      z - Z coordinate.
      Returns:
      This handle for fluent chaining.
      Throws:
      IllegalStateException - If the server rejected the teleport (e.g. a plugin cancelled the teleport event).

    • teleport

      public PlayerHandle teleport(WorldHandle world, Vec3 position)
      Teleports this player to a target position in a world.
      Parameters:
      world - Target world.
      position - Target position.
      Returns:
      This handle for fluent chaining.
      Throws:
      IllegalStateException - If the server rejected the teleport (e.g. a plugin cancelled the teleport event).

    • placeBlock

      public PlayerHandle placeBlock(String materialKey, int x, int y, int z)
      Places a block from this player perspective.
      Parameters:
      materialKey - Material key, for example minecraft:stone or STONE.
      x - X coordinate.
      y - Y coordinate.
      z - Z coordinate.
      Returns:
      This handle for fluent chaining.

    • leftClickBlock

      public InteractionResult leftClickBlock(int x, int y, int z)
      Fires a left-click block interaction at a position in this player's current world.
      Parameters:
      x - X coordinate.
      y - Y coordinate.
      z - Z coordinate.
      Returns:
      The interaction result; a real PlayerInteractEvent is always fired.

    • leftClickBlock

      public InteractionResult leftClickBlock(BlockPos position)
      Fires a left-click block interaction at a position in this player's current world.
      Parameters:
      position - Block coordinates.
      Returns:
      The interaction result; a real PlayerInteractEvent is always fired.

    • leftClickBlock

      public InteractionResult leftClickBlock(BlockPos position, org.bukkit.block.BlockFace blockFace)
      Fires a left-click block interaction at a position in this player's current world.
      Parameters:
      position - Block coordinates.
      blockFace - Clicked block face.
      Returns:
      The interaction result; a real PlayerInteractEvent is always fired.

    • rightClickBlock

      public InteractionResult rightClickBlock(int x, int y, int z)
      Fires a right-click block interaction at a position in this player's current world.
      Parameters:
      x - X coordinate.
      y - Y coordinate.
      z - Z coordinate.
      Returns:
      The interaction result; a real PlayerInteractEvent is always fired.

    • rightClickBlock

      public InteractionResult rightClickBlock(BlockPos position)
      Fires a right-click block interaction at a position in this player's current world.
      Parameters:
      position - Block coordinates.
      Returns:
      The interaction result; a real PlayerInteractEvent is always fired.

    • rightClickBlock

      public InteractionResult rightClickBlock(BlockPos position, org.bukkit.block.BlockFace blockFace)
      Fires a right-click block interaction at a position in this player's current world.
      Parameters:
      position - Block coordinates.
      blockFace - Clicked block face.
      Returns:
      The interaction result; a real PlayerInteractEvent is always fired.

    • chat

      public PlayerHandle chat(String message)
      Makes this player say a chat message, firing the real chat event (synchronously, as with any plugin-triggered chat).
      Parameters:
      message - The chat message.
      Returns:
      This handle for fluent chaining.

    • permissions

      public PermissionControl permissions()
      Gets the permission control handle for this player.

      Mutations apply to LightKeeper's own permission attachment and bypass permission plugins; see PermissionControl for the full contract.

      Returns:
      A permission control handle bound to this player.

    • inventory

      public InventorySnapshot inventory()
      Gets a snapshot of this player's inventory.
      Returns:
      Inventory snapshot.

    • dropMainHandItem

      public DropResult dropMainHandItem()
      Simulates the player dropping their main hand item.

      An empty main hand (DropResult.EMPTY_HAND) is reported distinctly from a plugin cancelling the drop event (DropResult.CANCELLED); no event is fired at all for an empty hand. On a cancelled drop, the item entity is created and removed again to satisfy the Bukkit event contract, and the inventory is unchanged.

      Returns:
      The drop outcome.

    • andWaitTicks

      public PlayerHandle andWaitTicks(int ticks)
      Waits for at least the requested number of server ticks.
      Parameters:
      ticks - Tick count to wait.
      Returns:
      This handle for fluent chaining.

    • andWaitForMenuOpen

      public MenuHandle andWaitForMenuOpen(int timeoutSeconds)
      Waits for an open menu for this player.
      Parameters:
      timeoutSeconds - Timeout in seconds.
      Returns:
      A menu handle bound to this player.

    • andWaitForMenuOpen

      public MenuHandle andWaitForMenuOpen()
      Waits for an open menu using the default timeout.
      Returns:
      A menu handle bound to this player.

    • getMenu

      public @Nullable MenuHandle getMenu()
      Returns the currently open menu if available.
      Returns:
      The open menu handle, or null when no actionable menu is open.

    • receivedMessages

      public List<String> receivedMessages()
      Gets all recorded messages received by this player.
      Returns:
      Snapshot of received messages, ordered oldest-to-newest.

    • chatComponents

      public List<ChatComponentSnapshot> chatComponents()
      Gets a list of captured chat components for this player.
      Returns:
      Captured chat components.

    • clickChatComponent

      public PlayerHandle clickChatComponent(ChatComponentSnapshot component)
      Clicks the run_command action of a captured chat component by extracting its command and executing it as this player, exactly as a real player clicking the message would.

      Reuses the same execution path as executeCommand(String) (no new protocol command), so the extracted command is dispatched in this player's context with a leading slash normalized away.

      Parameters:
      component - The captured chat component to click; must carry a run_command click event.
      Returns:
      This handle for fluent chaining.
      Throws:
      IllegalArgumentException - When the component carries no run_command click event to execute.

    • receivedMessagesText

      public String receivedMessagesText()
      Gets all recorded messages flattened into a single multi-line string.
      Returns:
      Received messages joined with line separators.

    • remove

      public void remove()
      Removes this synthetic player from the server.