ServerListPingEvent

Called when a server list ping is coming in. Displayed players can be

checked and removed by {@link #iterator() iterating} over this event.

Note: The players in {@link #iterator()} will not be shown in the

server info if {@link Bukkit#getHideOnlinePlayers()} is true.

当服务端接收到 ServerListPing 数据包时触发本事件。插件在监听器中可以调用 iterator() 方法遍历或删除服务端发回的在线玩家列表。

注意，如果 Bukkit#getHideOnlinePlayers() 方法返回 true ，则 iterator() 方法返回值里的玩家不会在服务器信息中展示。

译注：ServerListPing 是客户端发送给服务端的一种数据包，用于获取服务器的一系列信息，包括服务器现有在线人数、最大在线人数、服务器图标等。这些信息即客户端“多人游戏”页面所展示的服务器列表中各个服务器的信息。服务端在收到 ServerListPing 数据包以后，会给客户端发还 Status Response 数据包，告知客户端相关信息。通过本事件可以修改服务端发给客户端的服务器信息。插件可以将服务器最大在线人数改为 -1 人，亦可修改服务器图标，诸如此类。若操作得当，客户端会显示修改之后的信息。

当鼠标悬停在服务器信息右上方的信号强度图标时，会显示一个列表，列表中展示了全部在线玩家的名称。可以通过 iterator() 方法对这个将要展示的列表进行遍历，也可以通过 Iterator#remove() 方法删除玩家。如果 Bukkit#getHideOnlinePlayers() 返回 true ，那么无论服务器内有多少人在线，都不会有任何玩家的用户名被展示。

有关 ServerListPing 数据包和服务端 Status Response 数据包的具体格式和内容，请参见 https://wiki.vg/Server_List_Ping 页面。

Get the address the ping is coming from.

@return the address

该方法用于获取 ServerListPing 数据包的来源地址。

@return 数据包来源地址。

Get the message of the day message.

@return the message of the day

该方法用于获取将要发送的 MOTD 消息字符串。

@return MOTD 字符串。

译注：所谓“MOTD”，即“Message of the Day”的简称，展示在服务器图标右侧，玩家自定义的服务器名称下方。该字符串的内容一般是服务器简介或宣传标语等。

Change the message of the day message.

@param motd the message of the day

该方法用于设置将要发送的 MOTD 消息字符串。

@param motd MOTD 字符串。

译注：所谓“MOTD”，即“Message of the Day”的简称，展示在服务器图标右侧，玩家自定义的服务器名称下方。该字符串的内容一般是服务器简介或宣传标语等。

Get the number of players sent.

@return the number of players

该方法用于获取将要发送的在线玩家人数。

@return 在线玩家人数。

译注：参见 iterator() 方法。

在 1.16.5 版本 Spigot 服务端中，本事件的 numPlayers 字段是一个以 final 修饰的变量，而且 iterator() 方法的方法体只有一行，是 throw new UnsupportedOperationException(); ，故而无法遍历或修改玩家列表。

Get the maximum number of players sent.

@return the maximum number of players

该方法用于获取将要发送的服务器在线玩家人数上限。

@return 在线玩家人数上限。

Set the maximum number of players sent.

@param maxPlayers the maximum number of player

该方法用于设置将要发送的服务器在线玩家人数上限。

@param maxPlayers 在线玩家人数上限。

Sets the server-icon sent to the client.

@param icon the icon to send to the client

@throws IllegalArgumentException if the {@link CachedServerIcon} is not

created by the caller of this event; null may be accepted for some

implementations

@throws UnsupportedOperationException if the caller of this event does

not support setting the server icon

该方法用于设置将要发送给客户端的服务器图标。

@param icon 将要发送给客户端的服务器图标。

@throws 如果 CachedServerIcon 不是被触发本事件的开发者所创建的，则抛出 IllegalArgumentException 。部分实现类允许传入 null 作为参数。

@throws 如果触发本事件的开发者不允许设置服务器图标，则抛出 UnsupportedOperationException 。

译注：此方法的文档强调了本事件不一定由服务端触发，也可能是由插件触发，实现的方式与 Bukkit 系列服务端可能不同。

在 1.16.5 版本 Spigot 服务端中，本方法的方法体只有一行，是 throw new UnsupportedOperationException(); ，故而无法设置服务端图标。

{@inheritDoc}

Calling the {@link Iterator#remove()} method will force that particular

player to not be displayed on the player list, decrease the size

returned by {@link #getNumPlayers()}, and will not be returned again by

any new iterator.

Note: The players here will not be shown in the server info if

{@link Bukkit#getHideOnlinePlayers()} is true.

@throws UnsupportedOperationException if the caller of this event does

not support removing players

如果调用 Iterator#remove() 方法，会让被删除的那个玩家不再在客户端的玩家列表预览里显示。同时也会让 getNumPlayers() 方法的返回值减小。如果在删除某个玩家以后，再次调用本方法以遍历玩家列表，则该位被删除的玩家不会出现在第二次遍历中。

注意，如果 Bukkit#getHideOnlinePlayers() 返回 true ，则本方法所列的玩家均不会在客户端被显示。

@throws 如果触发本事件的开发者不允许插件删除在线玩家，会抛出 UnsupportedOperationException 。

译注：本方法返回的 Iterator 中的项被删除以后，直接影响将要发送给客户端的在线玩家人数。这样客户端展示的在线玩家列表的长度才能与在线玩家人数相一致。因此没有 setNumPlayers(int) 这样的方法。

此方法的文档强调了本事件不一定由服务端触发，也可能是由插件触发，实现的方式与 Bukkit 系列服务端可能不同。

在 1.16.5 版本 Spigot 服务端中，本方法的方法体只有一行，是 throw new UnsupportedOperationException(); ，因而无法遍历或修改玩家列表。