Complex sample players placeholders for server list ping

api/src/main/java/com/velocityctd/api/cluster/ClusterPlayer.java

@@ -66,6 +66,14 @@ public interface ClusterPlayer {
    */
   boolean isClientListingAllowed();
 
+  /**
+   * Gets the timestamp, in milliseconds since the epoch, at which the player connected
+   * to the proxy they are currently on.
+   *
+   * @return the join timestamp in milliseconds since the epoch
+   */
+  long getJoinedAt();
+
   /**
    * Kicks the player from the proxy with the given reason.
    *

proxy/src/main/java/com/velocityctd/proxy/cluster/local/LocalClusterPlayer.java

@@ -77,6 +77,11 @@ public boolean isClientListingAllowed() {
     return player.getPlayerSettings().isClientListingAllowed();
   }
 
+  @Override
+  public long getJoinedAt() {
+    return player.getJoinedAt();
+  }
+
   @Override
   public void kick(Component reason) {
     player.disconnect0(reason, true);

proxy/src/main/java/com/velocityctd/proxy/cluster/redis/RedisClusterPlayer.java

@@ -80,6 +80,11 @@ public boolean isClientListingAllowed() {
     return redisEntry.isClientListingAllowed();
   }
 
+  @Override
+  public long getJoinedAt() {
+    return redisEntry.getJoinedAt();
+  }
+
   @Override
   public void kick(Component reason) {
     redis.publish(new VelocityKick(redisEntry.getUniqueId(), reason));

proxy/src/main/java/com/velocityctd/proxy/config/migration/CtdConfigMigrations.java

@@ -26,7 +26,33 @@ public class CtdConfigMigrations {
 
   public static List<ConfigurationMigration> createCtdMigrations() {
     return List.of(
+        new CtdMotdHoverMigration(),
+
         // root
+        migration(
+            "Shown when hovering over the player count in the server list. Accepts a list of lines, and\n"
+                + " supports the same placeholders as \"fallback-version-ping\" plus the \"{players}\" placeholder.\n"
+                + "\n"
+                + " \"{players}\" lists online players. By default it shows a random selection, which is the Notchian\n"
+                + " (vanilla) behavior. Setting motd-hover = [\"{players}\"] reproduces the vanilla player tooltip.\n"
+                + " It accepts optional arguments written as \"{players:arg=value:arg2=value}\":\n"
+                + " - max:        maximum number of players to list.\n"
+                + " - maxPerLine: maximum number of players listed per line.\n"
+                + " - ordering:   how players are picked and ordered. One of:\n"
+                + "   - RANDOM:                a random selection (Notchian behavior).\n"
+                + "   - ALPHABETICAL:          sorted A-Z by name.\n"
+                + "   - ALPHABETICAL_REVERSED: sorted Z-A by name.\n"
+                + "   - LAST_JOINED:           most recently joined players first.\n"
+                + "   - FIRST_JOINED:          longest-connected players first.\n"
+                + " - empty:      text shown when no players are online.\n"
+                + " - prefix:     text inserted before each player name.\n"
+                + " - separator:  text inserted between player names (trimmed at the end of each line).\n"
+                + " Example: \"{players:max=10:maxPerLine=2:ordering=ALPHABETICAL:separator=<gray>, }\"",
+            "motd-hover",
+            List.of(
+                "<gray>Players online: <white>{player-count}</white>/<white>{max-players}</white></gray>",
+                "{players}")
+        ),
         migration(
             "Whether chat signing should be enforced. If disabled, backend servers MUST disable chat signing.",
             "enforce-chat-signing",
@@ -147,10 +173,22 @@ public static List<ConfigurationMigration> createCtdMigrations() {
             "advanced.server-brand",
             "{backend-brand} ({proxy-brand})"
         ),
+        migration(
+            "Replaces what is returned for both the server brand and fallback version pinger.",
+            "advanced.custom-brand-proxy",
+            "Velocity-CTD"
+        ),
+        migration(
+            "Replaces what is returned as the server brand for the user's client.",
+            "advanced.custom-brand-backend",
+            "Paper"
+        ),
         migration(
             "Modifies the brand and server version that displays in the multiplayer menu and status pingers.\n"
                 + " Supports placeholders: {protocol-min}, {protocol-max}, {protocol}, {proxy-brand},\n"
-                + " {proxy-brand-custom}, {proxy-version}, {proxy-vendor}, {player-count}, {max-players}.",
+                + " {proxy-brand-custom}, {proxy-version}, {proxy-vendor}, {player-count}, {max-players}.\n"
+                + " These placeholders are also available in \"motd\" and \"motd-hover\", and the\n"
+                + " \"{players}\" placeholder (documented under \"motd-hover\") may be used here as well.",
             "advanced.fallback-version-ping",
             "{proxy-brand} {protocol-min}-{protocol-max}"
         ),
@@ -162,14 +200,19 @@ public static List<ConfigurationMigration> createCtdMigrations() {
             false
         ),
         migration(
-            "Replaces what is returned for both the server brand and fallback version pinger.",
-            "advanced.custom-brand-proxy",
-            "Velocity-CTD"
+            "When a player disables \"Allow Server Listings\" in their client options, they are shown as\n"
+                + " \"Anonymous Player\" in the {players} sample of the server list ping. Set this to true to ignore\n"
+                + " that request and always show their real username.",
+            "advanced.ignore-anonymous-player-request",
+            false
         ),
         migration(
-            "Replaces what is returned as the server brand for the user's client.",
-            "advanced.custom-brand-backend",
-            "Paper"
+            "Whether the {players} sample of the motd, motd-hover and fallback-version-ping should draw from a\n"
+                + " single shared pool. When true, a player never appears more than once across those three sections.\n"
+                + " When false (default), each section samples players independently and the same player may appear in\n"
+                + " more than one section.",
+            "advanced.pool-players-across-sections",
+            false
         ),
 
         // [redis]

proxy/src/main/java/com/velocityctd/proxy/config/migration/CtdMotdHoverMigration.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright (C) 2026 Velocity-CTD Contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.velocityctd.proxy.config.migration;
+
+import com.electronwill.nightconfig.core.file.CommentedFileConfig;
+import com.velocitypowered.proxy.config.migration.ConfigurationMigration;
+import java.util.ArrayList;
+import java.util.List;
+import org.apache.logging.log4j.Logger;
+
+/**
+ * Migrates the removed {@code sample-players-in-ping} option into the {@code motd-hover}
+ * {@code {players}} placeholder. When the option was enabled, the server list ping used to display
+ * a sample of online players, so a {@code {players}} line is inserted at the top of
+ * {@code motd-hover} to preserve that behavior. The legacy option is then removed.
+ */
+public final class CtdMotdHoverMigration implements ConfigurationMigration {
+
+  private static final String LEGACY_KEY = "sample-players-in-ping";
+  private static final String MOTD_HOVER_KEY = "motd-hover";
+  private static final String PLAYERS_LINE = "{players}";
+
+  @Override
+  public boolean shouldMigrate(CommentedFileConfig config) {
+    return config.contains(LEGACY_KEY);
+  }
+
+  @Override
+  public void migrate(CommentedFileConfig config, Logger logger) {
+    if (config.getOrElse(LEGACY_KEY, false)) {
+      List<String> motdHover = new ArrayList<>();
+      if (config.get(MOTD_HOVER_KEY) instanceof List<?> existing) {
+        for (Object line : existing) {
+          motdHover.add(String.valueOf(line));
+        }
+      }
+      motdHover.addFirst(PLAYERS_LINE);
+      config.set(MOTD_HOVER_KEY, motdHover);
+    }
+
+    config.remove(LEGACY_KEY);
+  }
+}

proxy/src/main/java/com/velocityctd/proxy/redis/depot/player/PlayerEntry.java

@@ -70,6 +70,11 @@ public final class PlayerEntry extends DepotEntry<UUID, PlayerEntry> {
    */
   private final String ipAddress;
 
+  /**
+   * The timestamp, in milliseconds since the epoch, at which the player joined the proxy.
+   */
+  private final long joinedAt;
+
   /**
    * Whether this player entry may be listed in the server list ping MOTD hover, generated in
    * {@link com.velocitypowered.proxy.connection.util.ServerListPingHandler}.
@@ -97,6 +102,7 @@ public final class PlayerEntry extends DepotEntry<UUID, PlayerEntry> {
         .orElse(null);
     this.ipAddress = player.getRemoteAddress().getAddress().getHostAddress();
     this.clientListingAllowed = player.getPlayerSettings().isClientListingAllowed();
+    this.joinedAt = player.getJoinedAt();
   }
 
   /**
@@ -171,6 +177,15 @@ public void setServerName(String serverName) {
     return ipAddress;
   }
 
+  /**
+   * Gets the timestamp, in milliseconds since the epoch, at which the player joined the proxy.
+   *
+   * @return the join timestamp
+   */
+  public long getJoinedAt() {
+    return joinedAt;
+  }
+
   /**
    * Whether this player entry may be listed in the server list ping MOTD hover, generated in
    * {@link com.velocitypowered.proxy.connection.util.ServerListPingHandler}.