Package devs.beer.nativepackets.api

Interface FastPacketSender

public interface FastPacketSender
Specialized allocation-minimal packet sends addressed to one platform player.

Every method bypasses native-object listeners and the vanilla packet encoder while retaining compression, encryption, and socket processing. Exact documented client-native paths may also bypass protocol translation; all other connections retain it.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    batch(Object platformPlayer, Consumer<FastPacketBatch> batch)
    Runs connection-scoped primitive writes on one Netty event-loop task and flushes once.
    void
    sendArmorStandPose(Object platformPlayer, int entityId, EntityMetadataField<MetadataRotation> pose, float x, float y, float z)
    Sends one ArmorStand body-part pose directly as entity metadata and flushes immediately.
    default void
    sendDisplayRotation(Object platformPlayer, int entityId, EntityMetadataField<NativeValue> rotation, float xDegrees, float yDegrees, float zDegrees)
    Converts XYZ Euler angles in degrees directly to a quaternion and sends it.
    void
    sendDisplayRotation(Object platformPlayer, int entityId, EntityMetadataField<NativeValue> rotation, float x, float y, float z, float w)
    Sends one Display quaternion rotation directly as entity metadata and flushes immediately.
    void
    sendDisplayScale(Object platformPlayer, int entityId, float x, float y, float z)
    Sends one Display scale vector directly as entity metadata and flushes immediately.
    void
    sendDisplayScaleAndRotation(Object platformPlayer, int entityId, float scaleX, float scaleY, float scaleZ, EntityMetadataField<NativeValue> rotation, float rotationX, float rotationY, float rotationZ, float rotationW)
    Sends Display scale and one quaternion rotation together in one entity-metadata packet and flushes immediately.
    void
    sendDisplayTranslation(Object platformPlayer, int entityId, float x, float y, float z)
    Sends one Display translation vector directly as entity metadata and flushes immediately.
    void
    sendDisplayTranslationAndRotation(Object platformPlayer, int entityId, float translationX, float translationY, float translationZ, EntityMetadataField<NativeValue> rotation, float rotationX, float rotationY, float rotationZ, float rotationW)
    Sends Display translation and one quaternion rotation together in one entity-metadata packet and flushes immediately.
    void
    sendDisplayTranslationAndScale(Object platformPlayer, int entityId, float translationX, float translationY, float translationZ, float scaleX, float scaleY, float scaleZ)
    Sends Display translation and scale together in one entity-metadata packet and flushes immediately.
    void
    sendDisplayTranslationAndScaleAndRotation(Object platformPlayer, int entityId, float translationX, float translationY, float translationZ, float scaleX, float scaleY, float scaleZ, EntityMetadataField<NativeValue> rotation, float rotationX, float rotationY, float rotationZ, float rotationW)
    Sends Display translation, scale, and one quaternion rotation together in one entity-metadata packet and flushes immediately.
    void
    sendEntityHeadRotation(Object platformPlayer, int entityId, float yaw)
    Sends one clientbound entity head rotation and flushes immediately.
    void
    sendEntityRotation(Object platformPlayer, int entityId, float yaw, float pitch, boolean onGround)
    Sends one clientbound entity body rotation and flushes immediately.
    void
    sendEntityTeleport(Object platformPlayer, int entityId, double x, double y, double z, float yaw, float pitch, boolean onGround)
    Encodes and sends one absolute clientbound entity teleport directly from primitives.
    void
    writeArmorStandPose(Object platformPlayer, int entityId, EntityMetadataField<MetadataRotation> pose, float x, float y, float z)
    Writes an ArmorStand pose without requesting an immediate flush.
    default void
    writeDisplayRotation(Object platformPlayer, int entityId, EntityMetadataField<NativeValue> rotation, float xDegrees, float yDegrees, float zDegrees)
    Converts XYZ Euler angles in degrees and writes without requesting an immediate flush.
    void
    writeDisplayRotation(Object platformPlayer, int entityId, EntityMetadataField<NativeValue> rotation, float x, float y, float z, float w)
    Writes a Display rotation without requesting an immediate flush.
    void
    writeDisplayScale(Object platformPlayer, int entityId, float x, float y, float z)
    Writes one Display scale vector without requesting an immediate flush.
    void
    writeDisplayScaleAndRotation(Object platformPlayer, int entityId, float scaleX, float scaleY, float scaleZ, EntityMetadataField<NativeValue> rotation, float rotationX, float rotationY, float rotationZ, float rotationW)
    Writes Display scale and one quaternion rotation together in one entity-metadata packet without requesting an immediate flush.
    void
    writeDisplayTranslation(Object platformPlayer, int entityId, float x, float y, float z)
    Writes one Display translation vector without requesting an immediate flush.
    void
    writeDisplayTranslationAndRotation(Object platformPlayer, int entityId, float translationX, float translationY, float translationZ, EntityMetadataField<NativeValue> rotation, float rotationX, float rotationY, float rotationZ, float rotationW)
    Writes Display translation and one quaternion rotation together in one entity-metadata packet without requesting an immediate flush.
    void
    writeDisplayTranslationAndScale(Object platformPlayer, int entityId, float translationX, float translationY, float translationZ, float scaleX, float scaleY, float scaleZ)
    Writes Display translation and scale together in one entity-metadata packet without requesting an immediate flush.
    void
    writeDisplayTranslationAndScaleAndRotation(Object platformPlayer, int entityId, float translationX, float translationY, float translationZ, float scaleX, float scaleY, float scaleZ, EntityMetadataField<NativeValue> rotation, float rotationX, float rotationY, float rotationZ, float rotationW)
    Writes Display translation, scale, and one quaternion rotation together in one entity-metadata packet without requesting an immediate flush.
    void
    writeEntityHeadRotation(Object platformPlayer, int entityId, float yaw)
    Writes one clientbound entity head rotation without requesting an immediate flush.
    void
    writeEntityRotation(Object platformPlayer, int entityId, float yaw, float pitch, boolean onGround)
    Writes one clientbound entity body rotation without requesting an immediate flush.
    void
    writeEntityTeleport(Object platformPlayer, int entityId, double x, double y, double z, float yaw, float pitch, boolean onGround)
    Writes one absolute clientbound entity teleport without requesting an immediate flush.

  • Method Details

    • batch

      void batch(Object platformPlayer, Consumer<FastPacketBatch> batch)
      Runs connection-scoped primitive writes on one Netty event-loop task and flushes once.

      The player connection is resolved once before scheduling. The callback runs inline when already on that connection's event loop, or asynchronously through exactly one event-loop submission otherwise. It must use only captured thread-safe snapshots and must not access Bukkit entity, world, chunk, or inventory state.

      The supplied writer is valid only during the callback and must not be retained. Pending writes are flushed when the callback finishes, including when it throws.

      Parameters:
      platformPlayer - platform player that should receive the batch
      batch - batch callback executed on the player's Netty event loop

    • sendEntityTeleport

      void sendEntityTeleport(Object platformPlayer, int entityId, double x, double y, double z, float yaw, float pitch, boolean onGround)
      Encodes and sends one absolute clientbound entity teleport directly from primitives.

      This path bypasses native-object listeners and the vanilla packet encoder. Exact client-native paths also bypass protocol translation; other connections retain it. It requests a flush immediately after the write; use writeEntityTeleport(Object, int, double, double, double, float, float, boolean) to batch multiple outbound writes before one flush.

      Parameters:
      platformPlayer - platform player owned by this server
      entityId - client-visible entity ID
      x - absolute X position
      y - absolute Y position
      z - absolute Z position
      yaw - entity yaw in degrees
      pitch - entity pitch in degrees
      onGround - whether the entity is on the ground

    • writeEntityTeleport

      void writeEntityTeleport(Object platformPlayer, int entityId, double x, double y, double z, float yaw, float pitch, boolean onGround)
      Writes one absolute clientbound entity teleport without requesting an immediate flush.

      The packet is still encoded and submitted to the player's Netty event loop, but pending outbound data is not explicitly pushed toward the socket by this call. This allows several packets to be written and then released together with ConnectionHandle.flush(), reducing flush/syscall pressure at the cost of waiting until that flush occurs. Any other operation that flushes the same connection may also release the pending packet, so this method does not guarantee a transmission delay.

      For example, batch calls to this method and finish with api.connection(platformPlayer).flush(). Use sendEntityTeleport(Object, int, double, double, double, float, float, boolean) when this packet should request an immediate flush.

      Parameters:
      platformPlayer - platform player owned by this server
      entityId - client-visible entity ID
      x - absolute X position
      y - absolute Y position
      z - absolute Z position
      yaw - entity yaw in degrees
      pitch - entity pitch in degrees
      onGround - whether the entity is on the ground

    • sendEntityRotation

      void sendEntityRotation(Object platformPlayer, int entityId, float yaw, float pitch, boolean onGround)
      Sends one clientbound entity body rotation and flushes immediately.

    • writeEntityRotation

      void writeEntityRotation(Object platformPlayer, int entityId, float yaw, float pitch, boolean onGround)
      Writes one clientbound entity body rotation without requesting an immediate flush.

    • sendEntityHeadRotation

      void sendEntityHeadRotation(Object platformPlayer, int entityId, float yaw)
      Sends one clientbound entity head rotation and flushes immediately.

    • writeEntityHeadRotation

      void writeEntityHeadRotation(Object platformPlayer, int entityId, float yaw)
      Writes one clientbound entity head rotation without requesting an immediate flush.

    • sendArmorStandPose

      void sendArmorStandPose(Object platformPlayer, int entityId, EntityMetadataField<MetadataRotation> pose, float x, float y, float z)
      Sends one ArmorStand body-part pose directly as entity metadata and flushes immediately.

      Accepted fields are EntityMetadataFields.ArmorStand.HEAD_POSE, EntityMetadataFields.ArmorStand.BODY_POSE, EntityMetadataFields.ArmorStand.LEFT_ARM_POSE, EntityMetadataFields.ArmorStand.RIGHT_ARM_POSE, EntityMetadataFields.ArmorStand.LEFT_LEG_POSE, and EntityMetadataFields.ArmorStand.RIGHT_LEG_POSE.

      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible ArmorStand entity ID
      pose - one of the six pose fields in EntityMetadataFields.ArmorStand
      x - X rotation in degrees
      y - Y rotation in degrees
      z - Z rotation in degrees

    • writeArmorStandPose

      void writeArmorStandPose(Object platformPlayer, int entityId, EntityMetadataField<MetadataRotation> pose, float x, float y, float z)
      Writes an ArmorStand pose without requesting an immediate flush. Batching semantics are the same as writeEntityTeleport(Object, int, double, double, double, float, float, boolean).
      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible ArmorStand entity ID
      pose - one of the six pose fields documented by the flushing overload
      x - X rotation in degrees
      y - Y rotation in degrees
      z - Z rotation in degrees

    • sendDisplayTranslation

      void sendDisplayTranslation(Object platformPlayer, int entityId, float x, float y, float z)
      Sends one Display translation vector directly as entity metadata and flushes immediately.

      This field belongs to the base Display entity and therefore works with item, block, and text displays.

      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      x - translation X component
      y - translation Y component
      z - translation Z component

    • writeDisplayTranslation

      void writeDisplayTranslation(Object platformPlayer, int entityId, float x, float y, float z)
      Writes one Display translation vector without requesting an immediate flush. Batching semantics are the same as writeEntityTeleport(Object, int, double, double, double, float, float, boolean).
      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      x - translation X component
      y - translation Y component
      z - translation Z component

    • sendDisplayScale

      void sendDisplayScale(Object platformPlayer, int entityId, float x, float y, float z)
      Sends one Display scale vector directly as entity metadata and flushes immediately.

      This field belongs to the base Display entity and therefore works with item, block, and text displays.

      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      x - scale X component
      y - scale Y component
      z - scale Z component

    • writeDisplayScale

      void writeDisplayScale(Object platformPlayer, int entityId, float x, float y, float z)
      Writes one Display scale vector without requesting an immediate flush. Batching semantics are the same as writeEntityTeleport(Object, int, double, double, double, float, float, boolean).
      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      x - scale X component
      y - scale Y component
      z - scale Z component

    • sendDisplayRotation

      void sendDisplayRotation(Object platformPlayer, int entityId, EntityMetadataField<NativeValue> rotation, float x, float y, float z, float w)
      Sends one Display quaternion rotation directly as entity metadata and flushes immediately.

      The field may be EntityMetadataFields.Display.LEFT_ROTATION or EntityMetadataFields.Display.RIGHT_ROTATION. Both fields belong to the base Display entity and therefore work with item, block, and text displays.

      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      rotation - left or right Display quaternion field
      x - quaternion X component
      y - quaternion Y component
      z - quaternion Z component
      w - quaternion W component

    • sendDisplayRotation

      default void sendDisplayRotation(Object platformPlayer, int entityId, EntityMetadataField<NativeValue> rotation, float xDegrees, float yDegrees, float zDegrees)
      Converts XYZ Euler angles in degrees directly to a quaternion and sends it.

      The conversion uses only scalar primitives and allocates no quaternion, vector, array, or wrapper. The four-component overload remains cheaper when a quaternion is already available because Euler conversion requires six trigonometric operations.

      Gimbal-lock warning: XYZ Euler angles have singularities and can lose one rotational degree of freedom. Converting them to a quaternion does not undo that loss. For gimbal-lock-free animation, calculate or accumulate a quaternion directly and call the four-component overload.

      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      rotation - left or right Display quaternion field
      xDegrees - rotation around X in degrees
      yDegrees - rotation around Y in degrees
      zDegrees - rotation around Z in degrees

    • writeDisplayRotation

      void writeDisplayRotation(Object platformPlayer, int entityId, EntityMetadataField<NativeValue> rotation, float x, float y, float z, float w)
      Writes a Display rotation without requesting an immediate flush. Batching semantics are the same as writeEntityTeleport(Object, int, double, double, double, float, float, boolean).
      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      rotation - EntityMetadataFields.Display.LEFT_ROTATION or EntityMetadataFields.Display.RIGHT_ROTATION
      x - quaternion X component
      y - quaternion Y component
      z - quaternion Z component
      w - quaternion W component

    • sendDisplayTranslationAndScale

      void sendDisplayTranslationAndScale(Object platformPlayer, int entityId, float translationX, float translationY, float translationZ, float scaleX, float scaleY, float scaleZ)
      Sends Display translation and scale together in one entity-metadata packet and flushes immediately.

      Both fields belong to the base Display entity and therefore work with item, block, and text displays. Combining them avoids a second packet, buffer, and metadata terminator.

      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      translationX - translation X component
      translationY - translation Y component
      translationZ - translation Z component
      scaleX - scale X component
      scaleY - scale Y component
      scaleZ - scale Z component

    • writeDisplayTranslationAndScale

      void writeDisplayTranslationAndScale(Object platformPlayer, int entityId, float translationX, float translationY, float translationZ, float scaleX, float scaleY, float scaleZ)
      Writes Display translation and scale together in one entity-metadata packet without requesting an immediate flush. Batching semantics are the same as writeEntityTeleport(Object, int, double, double, double, float, float, boolean).
      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      translationX - translation X component
      translationY - translation Y component
      translationZ - translation Z component
      scaleX - scale X component
      scaleY - scale Y component
      scaleZ - scale Z component

    • sendDisplayTranslationAndRotation

      void sendDisplayTranslationAndRotation(Object platformPlayer, int entityId, float translationX, float translationY, float translationZ, EntityMetadataField<NativeValue> rotation, float rotationX, float rotationY, float rotationZ, float rotationW)
      Sends Display translation and one quaternion rotation together in one entity-metadata packet and flushes immediately.

      The rotation field may be EntityMetadataFields.Display.LEFT_ROTATION or EntityMetadataFields.Display.RIGHT_ROTATION. Both fields belong to the base Display entity and therefore work with item, block, and text displays.

      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      translationX - translation X component
      translationY - translation Y component
      translationZ - translation Z component
      rotation - left or right Display quaternion field
      rotationX - quaternion X component
      rotationY - quaternion Y component
      rotationZ - quaternion Z component
      rotationW - quaternion W component

    • writeDisplayTranslationAndRotation

      void writeDisplayTranslationAndRotation(Object platformPlayer, int entityId, float translationX, float translationY, float translationZ, EntityMetadataField<NativeValue> rotation, float rotationX, float rotationY, float rotationZ, float rotationW)
      Writes Display translation and one quaternion rotation together in one entity-metadata packet without requesting an immediate flush. Batching semantics are the same as writeEntityTeleport(Object, int, double, double, double, float, float, boolean).
      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      translationX - translation X component
      translationY - translation Y component
      translationZ - translation Z component
      rotation - EntityMetadataFields.Display.LEFT_ROTATION or EntityMetadataFields.Display.RIGHT_ROTATION
      rotationX - quaternion X component
      rotationY - quaternion Y component
      rotationZ - quaternion Z component
      rotationW - quaternion W component

    • sendDisplayScaleAndRotation

      void sendDisplayScaleAndRotation(Object platformPlayer, int entityId, float scaleX, float scaleY, float scaleZ, EntityMetadataField<NativeValue> rotation, float rotationX, float rotationY, float rotationZ, float rotationW)
      Sends Display scale and one quaternion rotation together in one entity-metadata packet and flushes immediately.

      The rotation field may be EntityMetadataFields.Display.LEFT_ROTATION or EntityMetadataFields.Display.RIGHT_ROTATION. Both fields belong to the base Display entity and therefore work with item, block, and text displays.

      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      scaleX - scale X component
      scaleY - scale Y component
      scaleZ - scale Z component
      rotation - left or right Display quaternion field
      rotationX - quaternion X component
      rotationY - quaternion Y component
      rotationZ - quaternion Z component
      rotationW - quaternion W component

    • writeDisplayScaleAndRotation

      void writeDisplayScaleAndRotation(Object platformPlayer, int entityId, float scaleX, float scaleY, float scaleZ, EntityMetadataField<NativeValue> rotation, float rotationX, float rotationY, float rotationZ, float rotationW)
      Writes Display scale and one quaternion rotation together in one entity-metadata packet without requesting an immediate flush. Batching semantics are the same as writeEntityTeleport(Object, int, double, double, double, float, float, boolean).
      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      scaleX - scale X component
      scaleY - scale Y component
      scaleZ - scale Z component
      rotation - EntityMetadataFields.Display.LEFT_ROTATION or EntityMetadataFields.Display.RIGHT_ROTATION
      rotationX - quaternion X component
      rotationY - quaternion Y component
      rotationZ - quaternion Z component
      rotationW - quaternion W component

    • sendDisplayTranslationAndScaleAndRotation

      void sendDisplayTranslationAndScaleAndRotation(Object platformPlayer, int entityId, float translationX, float translationY, float translationZ, float scaleX, float scaleY, float scaleZ, EntityMetadataField<NativeValue> rotation, float rotationX, float rotationY, float rotationZ, float rotationW)
      Sends Display translation, scale, and one quaternion rotation together in one entity-metadata packet and flushes immediately.

      The rotation field may be EntityMetadataFields.Display.LEFT_ROTATION or EntityMetadataFields.Display.RIGHT_ROTATION. All three fields belong to the base Display entity and therefore work with item, block, and text displays. Combining them avoids two additional packets, buffers, and metadata terminators.

      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      translationX - translation X component
      translationY - translation Y component
      translationZ - translation Z component
      scaleX - scale X component
      scaleY - scale Y component
      scaleZ - scale Z component
      rotation - left or right Display quaternion field
      rotationX - quaternion X component
      rotationY - quaternion Y component
      rotationZ - quaternion Z component
      rotationW - quaternion W component

    • writeDisplayTranslationAndScaleAndRotation

      void writeDisplayTranslationAndScaleAndRotation(Object platformPlayer, int entityId, float translationX, float translationY, float translationZ, float scaleX, float scaleY, float scaleZ, EntityMetadataField<NativeValue> rotation, float rotationX, float rotationY, float rotationZ, float rotationW)
      Writes Display translation, scale, and one quaternion rotation together in one entity-metadata packet without requesting an immediate flush. Batching semantics are the same as writeEntityTeleport(Object, int, double, double, double, float, float, boolean).
      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      translationX - translation X component
      translationY - translation Y component
      translationZ - translation Z component
      scaleX - scale X component
      scaleY - scale Y component
      scaleZ - scale Z component
      rotation - EntityMetadataFields.Display.LEFT_ROTATION or EntityMetadataFields.Display.RIGHT_ROTATION
      rotationX - quaternion X component
      rotationY - quaternion Y component
      rotationZ - quaternion Z component
      rotationW - quaternion W component

    • writeDisplayRotation

      default void writeDisplayRotation(Object platformPlayer, int entityId, EntityMetadataField<NativeValue> rotation, float xDegrees, float yDegrees, float zDegrees)
      Converts XYZ Euler angles in degrees and writes without requesting an immediate flush. This overload has the same gimbal-lock limitation documented by the flushing overload.
      Parameters:
      platformPlayer - platform player that should receive the update
      entityId - client-visible Display entity ID
      rotation - EntityMetadataFields.Display.LEFT_ROTATION or EntityMetadataFields.Display.RIGHT_ROTATION
      xDegrees - rotation around X in degrees
      yDegrees - rotation around Y in degrees
      zDegrees - rotation around Z in degrees