Class PlayerVoiceFrame

java.lang.Object
com.hypixel.hytale.server.core.modules.voice.PlayerVoiceFrame
public final class PlayerVoiceFrame extends Object
Mutable view of one inbound player voice frame, passed to a PlayerVoiceInterceptor. Valid only for the duration of PlayerVoiceInterceptor.intercept(PlayerVoiceFrame). Do not retain it past that call.

By default a living speaker's frame is delivered to nearby same-world listeners and a dead speaker's frame is delivered to no one. An interceptor changes that with one of the audience methods. When several interceptors act on the same frame the last audience call wins, so a frame drop() left for no one can still be re-routed by a later interceptor with deliverByProximity() or deliverTo(Collection).

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    deliverByProximity()
    Delivers this frame to all nearby same-world listeners, clearing any proximity filters a prior interceptor set.
    void
    deliverTo(Collection<UUID> listeners)
    Delivers this frame to exactly listeners (any world, no distance falloff), playing at each listener rather than spatialized.
    void
    drop()
    Delivers this frame to no one.
    int
    entityNetworkId()
    The speaker's entity network id, which drives the client's overhead speaking indicator.
    void
    excludeListener(UUID listener)
    Excludes a listener from proximity delivery, accumulating across calls.
    byte[]
    opus()
    The Opus frame bytes.
    org.joml.Vector3dc
    position()
    The speaker's current ear position, or null when not yet cached (see worldId).
    void
    restrictProximityTo(Set<UUID> allowed)
    Restricts proximity delivery to the intersection of nearby listeners and allowed, switching delivery to proximity and keeping any prior excludeListener(UUID).
    short
    sequenceNumber()
    The client-stamped sequence number for this frame.
    void
    setOpus(byte[] frame)
    Replaces the Opus frame bytes (for example a censor beep or a baked clip).
    void
    setPosition(org.joml.Vector3dc position)
    Overrides the position used for proximity distance and the relayed (quantized) position.
    void
    setUnderwater(boolean underwater)
    Overrides whether the speaker is treated as underwater for proximity delivery.
    PlayerRef
    speaker()
    The speaking player.
    boolean
    speakerDead()
    Whether the speaker is dead.
    int
    timestamp()
    The client-stamped capture timestamp (48kHz sample units) for this frame.
    boolean
    underwater()
    Whether the speaker's ears are submerged, applied as the underwater muffle for proximity delivery.
    UUID
    worldId()
    The speaker's world, or null when the position cache is not yet populated (just connected, or mid world transfer).

    Methods inherited from class Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • speaker

      @Nonnull public PlayerRef speaker()
      The speaking player. Use it for identity and thread-safe lookups only. Do not read ECS, component, or block state from here (this runs off the world thread).

    • worldId

      @Nullable public UUID worldId()
      The speaker's world, or null when the position cache is not yet populated (just connected, or mid world transfer).

    • entityNetworkId

      public int entityNetworkId()
      The speaker's entity network id, which drives the client's overhead speaking indicator.

    • sequenceNumber

      public short sequenceNumber()
      The client-stamped sequence number for this frame.

    • timestamp

      public int timestamp()
      The client-stamped capture timestamp (48kHz sample units) for this frame.

    • speakerDead

      public boolean speakerDead()
      Whether the speaker is dead. A dead speaker's frame defaults to no delivery. Opt it back in with deliverByProximity() or deliverTo(Collection).

    • position

      @Nullable public org.joml.Vector3dc position()
      The speaker's current ear position, or null when not yet cached (see worldId). Used for proximity distance and quantized into the relayed position. The returned vector is a read-only view of internal state, so do not cast and mutate it. Override the position with setPosition(Vector3dc).

    • underwater

      public boolean underwater()
      Whether the speaker's ears are submerged, applied as the underwater muffle for proximity delivery.

    • opus

      @Nonnull public byte[] opus()
      The Opus frame bytes. Read-only access for taps. Replace them with setOpus(byte[]) and do not mutate the array.

    • setPosition

      public void setPosition(@Nonnull org.joml.Vector3dc position)
      Overrides the position used for proximity distance and the relayed (quantized) position.
      Parameters:
      position - the replacement position, whose coordinates must be finite
      Throws:
      IllegalArgumentException - if any coordinate is not finite

    • setUnderwater

      public void setUnderwater(boolean underwater)
      Overrides whether the speaker is treated as underwater for proximity delivery.

    • setOpus

      public void setOpus(@Nonnull byte[] frame)
      Replaces the Opus frame bytes (for example a censor beep or a baked clip). The server does not encode audio, so the bytes must already be a valid Opus frame: 48kHz mono, 1 to 512 bytes.

      The array is fanned out to every recipient without copying, so hand off a fresh array and never mutate it afterward, or a recipient's encode could read a half-overwritten frame.

      Parameters:
      frame - the replacement Opus frame, 1 to 512 bytes
      Throws:
      IllegalArgumentException - if the frame is empty or larger than the limit

    • drop

      public void drop()
      Delivers this frame to no one. A later interceptor in the chain can still re-route it with deliverByProximity() or deliverTo(Collection). This is the same state a dead speaker's frame starts in.

    • deliverByProximity

      public void deliverByProximity()
      Delivers this frame to all nearby same-world listeners, clearing any proximity filters a prior interceptor set. Use it to route a dead speaker's voice that would otherwise be dropped. Narrow it afterward with restrictProximityTo(Set) or excludeListener(UUID).

    • restrictProximityTo

      public void restrictProximityTo(@Nonnull Set<UUID> allowed)
      Restricts proximity delivery to the intersection of nearby listeners and allowed, switching delivery to proximity and keeping any prior excludeListener(UUID). Membership is tested per nearby listener, so a Set is taken for O(1) lookups. The set is referenced, not copied, so do not mutate it after this call. The server reads it during routing, once the interceptor chain has run. An empty set delivers to no one. Distance falloff and the per-speaker listener cap still apply, after this filter.

    • excludeListener

      public void excludeListener(@Nonnull UUID listener)
      Excludes a listener from proximity delivery, accumulating across calls. This only refines proximity delivery and does not enable it, so on a dropped or dead-speaker frame call deliverByProximity() first or the exclusion has nothing to act on.

    • deliverTo

      public void deliverTo(@Nonnull Collection<UUID> listeners)
      Delivers this frame to exactly listeners (any world, no distance falloff), playing at each listener rather than spatialized. The collection is referenced, not copied, so do not mutate it after this call. The server reads it during routing, once the interceptor chain has run. Null elements are skipped. An empty collection delivers to no one.