Class PlayerRef

java.lang.Object
com.hypixel.hytale.server.core.universe.PlayerRef
All Implemented Interfaces:
Component<EntityStore>, MetricProvider, CommandSender, PermissionHolder, IMessageReceiver, Cloneable
public class PlayerRef extends Object implements Component<EntityStore>, MetricProvider, CommandSender, PermissionHolder
A component class that represents a player within the server.

This class is used to reference a player in a way that is independent of any single entity component store. This is needed because players, unlike other entities, can be moved between stores or even exist without a store.

(e.g. when joining, teleporting between worlds). This is designed to be a single instance that will be updated to point to the player's current Ref if in a store, or Holder if moving/joining one.

This stores some state that may be used outside a store e.g. the packet handler.

  • Field Details

    • METRICS_REGISTRY

      @Nonnull public static final MetricsRegistry<PlayerRef> METRICS_REGISTRY
      The metrics registry for thread-safe player reference data. Component-dependent metrics are in COMPONENT_METRICS_REGISTRY and collected separately on world threads.

    • COMPONENT_METRICS_REGISTRY

      @Nonnull public static final MetricsRegistry<PlayerRef> COMPONENT_METRICS_REGISTRY
      Metrics registry for component-dependent player data. Must be called on the world thread where the player's entity resides.

  • Constructor Details

    • PlayerRef

      public PlayerRef(@Nonnull Holder<EntityStore> holder, @Nonnull UUID uuid, @Nonnull String username, @Nonnull String language, @Nonnull PacketHandler packetHandler, @Nonnull ChunkTracker chunkTracker)
      Default Constructor for a PlayerRef instance.
      Parameters:
      holder - The holder containing the player's components.
      uuid - The UUID of the player.
      username - The username of the player.
      language - The language of the player.
      packetHandler - The packet handler for the player.
      chunkTracker - The chunk tracker for the player.

  • Method Details

    • getComponentType

      @Nonnull public static ComponentType<EntityStore, PlayerRef> getComponentType()
      Returns:
      the component type for the PlayerRef component.

    • addToStore

      @Nullable public Ref<EntityStore> addToStore(@Nonnull Store<EntityStore> store)
      Not thread safe. Must be run on the store thread that the player is being added to.
      Parameters:
      store - The store to add the player to.
      Returns:
      The reference to the player in the store.

    • addedToStore

      public void addedToStore(Ref<EntityStore> ref)
      Called when the player has been added to the store, after HolderSystems have run, but before RefSystems.

      Ensures that the PlayerRef has a reference to its entity Ref and nulls the Holder.

      Parameters:
      ref - this player's ref.

    • removeFromStore

      @Nonnull public Holder<EntityStore> removeFromStore()
      Note: Not thread safe. Must be run on the store thread that the player is being added to.
      Returns:
      The holder containing the components of the player

    • isValid

      public boolean isValid()
      If invalid, neither a reference nor a holder is present.
      Returns:
      true if valid in some form, false otherwise.

    • getReference

      @Nullable public Ref<EntityStore> getReference()
      Returns:
      the entity reference of this player, or null if not in a store.

    • getHolder

      @Nullable public Holder<EntityStore> getHolder()
      Returns:
      the holder of this player's components, or null if in a store.

    • getComponent

      @Nullable @Deprecated public <T extends Component<EntityStore>> T getComponent(@Nonnull ComponentType<EntityStore, T> componentType)
      Deprecated.
      Blocks in some cases. Ideally you should know if it's a ref or holder at any given point if then manually inspect this and handle as needed.
      Gets the component from the entity whether its in the world or not.

      If the entity is in a world but this isn't called on the world thread then it may be blocking as it fetches from the world thread.

      Type Parameters:
      T - The component type.
      Parameters:
      componentType - The component to look up.
      Returns:
      The component or null.

    • getComponentConcurrent

      @Nullable public <T extends Component<EntityStore>> T getComponentConcurrent(@Nonnull ComponentType<EntityStore, T> componentType)
      Reads a component from any thread, whether the player is held out of world or live in a store, without blocking the caller. The holder read takes its own lock; the store read is seqlock-safe against slot reuse but not field mutation, so only presence checks and immutable-component reads are safe off the world thread.
      Type Parameters:
      T - The component type.
      Parameters:
      componentType - The component to look up.
      Returns:
      the component, or null if the entity does not have it, the store reference is invalidated mid-read, or the player currently has neither a holder nor a store reference.

    • getUuid

      @Nonnull public UUID getUuid()
      Specified by:
      getUuid in interface CommandSender
      Returns:
      the UUID of the player.

    • getUsername

      @Nonnull public String getUsername()
      Specified by:
      getUsername in interface CommandSender
      Returns:
      the username of the player.

    • hasPermission

      public boolean hasPermission(@Nonnull String id)
      Checks if the player has the specified permission.
      Specified by:
      hasPermission in interface PermissionHolder
      Parameters:
      id - the identifier of the permission to check; must not be null
      Returns:
      true if the player has the specified permission, false otherwise

    • hasPermission

      public boolean hasPermission(@Nonnull String id, boolean def)
      Determines if the player has a specific permission.
      Specified by:
      hasPermission in interface PermissionHolder
      Parameters:
      id - The identifier of the permission to check.
      def - The default value to return if the permission is not explicitly set.
      Returns:
      true if the player has the specified permission, false otherwise.

    • hasPermission

      public boolean hasPermission(@Nonnull PermissionQuery query)
      Description copied from interface: PermissionHolder
      Determines whether the associated instance has the given permission.

      A holder that resolves permissions itself should override this, because a lookup built once and reused costs an order of magnitude less than one built for each check.

      Specified by:
      hasPermission in interface PermissionHolder
      Parameters:
      query - The lookup for the permission.
      Returns:
      true if they have the permission, false otherwise.

    • hasPermission

      public boolean hasPermission(@Nonnull PermissionQuery query, boolean def)
      Specified by:
      hasPermission in interface PermissionHolder
      Parameters:
      query - The lookup for the permission.
      def - The default value to return if nothing decides.
      Returns:
      true if they have the permission, false otherwise.
      See Also:

    • getPacketHandler

      @Nonnull public PacketHandler getPacketHandler()
      Returns:
      the packet handler for the player.

    • getChunkTracker

      @Nonnull public ChunkTracker getChunkTracker()
      Returns:
      the chunk tracker for the player.

    • getHiddenPlayersManager

      @Nonnull public HiddenPlayersManager getHiddenPlayersManager()
      Returns:
      the affiliated HiddenPlayersManager instance

    • getTeleportAckTracker

      @Nonnull public TeleportAckTracker getTeleportAckTracker()
      Returns:
      the teleport acknowledgement tracker for this player's connection.

    • getLanguage

      @Nonnull public String getLanguage()
      Returns:
      the language of the player.

    • setLanguage

      public void setLanguage(@Nonnull String language)
      Called to set the language of the player.
      Parameters:
      language - The new language of the player.

    • getTransform

      @Nonnull public Transform getTransform()
      Returns:
      the Transform of the player the last time they ticked

    • getWorldUuid

      @Nullable public UUID getWorldUuid()
      Returns:
      the UUID of the world the player is in, or null before they join one

    • setWorldUuid

      public void setWorldUuid(@Nonnull UUID worldUuid)
      Records the world the player is joining, so getWorldUuid() is correct from the moment they are added to a world rather than only after their first position update.
      Parameters:
      worldUuid - The UUID of the world the player is joining.

    • getHeadRotation

      @Nonnull public Rotation3f getHeadRotation()
      Returns:
      the head rotation of the player when they last ticked

    • updatePosition

      public void updatePosition(@Nonnull World world, @Nonnull Transform transform, @Nonnull Rotation3f headRotation)
      Called to update the current position information of the player ref.
      Parameters:
      world - The current world the player is in.
      transform - The current transform of the player.
      headRotation - The current head rotation of the player.

    • replaceHolder

      @Deprecated public void replaceHolder(@Nonnull Holder<EntityStore> holder)
      Deprecated.
      Exists for resetPlayer
      Called to replace the holder of the player with another instance.
      Parameters:
      holder - The new holder for the player.

    • clone

      @Nonnull public Component<EntityStore> clone()
      Specified by:
      clone in interface Component<EntityStore>
      Returns:
      a clone instance of the original component instance.

    • toMetricResults

      @Nonnull public MetricResults toMetricResults()
      Specified by:
      toMetricResults in interface MetricProvider

    • referToServer

      public void referToServer(@Nonnull String host, int port)
      Refers this player to another server, allowing server-to-server transfers with optional data.
      Parameters:
      host - the hostname/IP of the destination server
      port - the port of the destination server

    • referToServer

      public void referToServer(@Nonnull String host, int port, @Nullable byte[] data)
      Refers this player to another server, allowing server-to-server transfers with optional data.
      Parameters:
      host - the hostname/IP of the destination server
      port - the port of the destination server
      data - optional byte array data to send along with the referral (can be null, max 4KB)
      Throws:
      IllegalArgumentException - if data exceeds maximum size

    • sendMessage

      public void sendMessage(@Nonnull Message message)
      Description copied from interface: IMessageReceiver
      Called to send a message to this receiver.
      Specified by:
      sendMessage in interface IMessageReceiver
      Parameters:
      message - The message to be sent.