Init

content/world/player-refs.en.md

@@ -0,0 +1,215 @@
+---
+title: PlayerRef
+type: docs
+weight: 4
+---
+
+PlayerRef provides a thread-safe way to reference players across worlds and threads.
+
+## Why PlayerRef?
+
+{{< callout type="warning" >}}
+Direct Player references should never be stored or used across threads. Always use PlayerRef for:
+- Async operations
+- Storing player references
+- Cross-world player tracking
+{{< /callout >}}
+
+## Getting a PlayerRef
+
+```java
+import com.hypixel.hytale.server.core.entity.entities.Player;
+import com.hypixel.hytale.server.core.universe.PlayerRef;
+import java.util.UUID;
+
+Player player = ...;
+PlayerRef ref = player.getPlayerRef();
+
+// PlayerRef contains essential player data
+UUID uuid = ref.getUuid();
+String name = ref.getUsername();  // Note: getUsername(), NOT getName()
+```
+
+## Using PlayerRef in Async Code
+
+```java
+import com.hypixel.hytale.server.core.event.events.player.PlayerConnectEvent;
+import com.hypixel.hytale.server.core.universe.world.storage.EntityStore;
+import com.hypixel.hytale.server.core.Message;
+import com.hypixel.hytale.component.Ref;
+import java.util.concurrent.CompletableFuture;
+
+getEventRegistry().register(PlayerConnectEvent.class, event -> {
+    PlayerRef ref = event.getPlayerRef();
+    World world = event.getWorld();
+
+    // Use ref in async operations
+    CompletableFuture.runAsync(() -> {
+        // Safe to use ref here
+        PlayerData data = loadPlayerData(ref.getUuid());
+
+        // Return to world thread to interact with player
+        if (world != null) {
+            world.execute(() -> {
+                Ref<EntityStore> entityRef = ref.getReference();
+                if (entityRef != null && entityRef.isValid()) {
+                    applyData(entityRef, data);
+                }
+                // sendMessage is directly on PlayerRef
+                ref.sendMessage(Message.raw("Your data has been loaded!"));
+            });
+        }
+    });
+});
+```
+
+## PlayerRef Methods
+
+```java
+PlayerRef ref = player.getPlayerRef();
+
+// Get player UUID (always available)
+UUID uuid = ref.getUuid();
+
+// Get player username (always available)
+// Note: It's getUsername(), NOT getName()
+String name = ref.getUsername();
+
+// Get entity reference
+Ref<EntityStore> entityRef = ref.getReference();
+
+// Check if reference is valid
+boolean isValid = ref.isValid();
+
+// Send message directly to player
+ref.sendMessage(Message.raw("Hello!"));
+
+// Get transform (position/rotation)
+Transform transform = ref.getTransform();
+```
+
+{{< callout type="warning" >}}
+**Note:** `PlayerRef.getPlayer()` does NOT exist. PlayerRef stores essential data that survives world changes, but doesn't hold a direct Player reference.
+{{< /callout >}}
+
+## World PlayerRefs
+
+Worlds provide access to PlayerRefs:
+
+```java
+import com.hypixel.hytale.server.core.universe.Universe;
+import java.util.Collection;
+import java.util.List;
+
+World world = Universe.get().getWorld("default");
+
+// Get all player refs in this world
+Collection<PlayerRef> playerRefs = world.getPlayerRefs();
+
+// Get all active players (returns List<Player>)
+List<Player> players = world.getPlayers();
+```
+
+## Storing Player References
+
+```java
+import com.hypixel.hytale.server.core.event.events.player.PlayerDisconnectEvent;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+public class MyPlugin extends JavaPlugin {
+    // Store PlayerRefs, NOT Players
+    private final Map<UUID, PlayerData> playerData = new ConcurrentHashMap<>();
+
+    public MyPlugin(JavaPluginInit init) {
+        super(init);
+    }
+
+    @Override
+    public void setup() {
+        getEventRegistry().register(PlayerConnectEvent.class, event -> {
+            PlayerRef ref = event.getPlayerRef();
+            playerData.put(ref.getUuid(), new PlayerData(ref));
+        });
+
+        getEventRegistry().register(PlayerDisconnectEvent.class, event -> {
+            playerData.remove(event.getPlayerRef().getUuid());
+        });
+    }
+}
+
+class PlayerData {
+    private final PlayerRef playerRef;
+    private int score;
+
+    public PlayerData(PlayerRef ref) {
+        this.playerRef = ref;
+    }
+
+    public void addScore(int amount) {
+        this.score += amount;
+        playerRef.sendMessage(Message.raw("Score: " + score));
+    }
+}
+```
+
+## Cross-World Messaging
+
+```java
+// Send message to player regardless of their current world
+public void sendGlobalMessage(PlayerRef ref, String message) {
+    // PlayerRef.sendMessage handles cross-world messaging directly
+    ref.sendMessage(Message.raw(message));
+}
+
+// Broadcast to all players in all worlds
+public void broadcastAll(String message) {
+    Message msg = Message.raw(message);
+    for (World world : Universe.get().getWorlds().values()) {
+        for (PlayerRef ref : world.getPlayerRefs()) {
+            ref.sendMessage(msg);
+        }
+    }
+}
+```
+
+## PlayerRef vs Player
+
+| Feature | Player | PlayerRef |
+|---------|--------|-----------|
+| Thread-safe | No | Yes |
+| Storable | No | Yes |
+| Cross-world | No | Yes |
+| Get UUID | Yes | Yes |
+| Get Username | Yes (`getDisplayName()`) | Yes (`getUsername()`) |
+| Send Message | Yes | Yes (directly) |
+| Get Position | Via TransformComponent | Via `getTransform()` |
+
+## Best Practices
+
+{{< callout type="info" >}}
+**Always use PlayerRef when:**
+- Storing player references beyond the current method
+- Passing to async tasks
+- Tracking players across world changes
+- Building player-related data structures
+{{< /callout >}}
+
+```java
+// Good: Store PlayerRef
+private final Map<UUID, PlayerRef> trackedPlayers = new ConcurrentHashMap<>();
+
+// Bad: Store Player directly
+// private final Map<UUID, Player> players = new HashMap<>(); // DON'T DO THIS
+
+// Good: Use ref in async
+CompletableFuture.runAsync(() -> {
+    PlayerRef ref = ...;
+    // ref is safe here
+});
+
+// Bad: Use Player in async
+// CompletableFuture.runAsync(() -> {
+//     Player player = ...;  // NOT SAFE
+// });
+```