Перейти к основному содержимому

Руководство по API рассылки сообщений (broadcast)

Класс Server предоставляет вспомогательные методы рассылки для сообщений чата, заголовков, подсказок (tip) и панелей действий. Каждый метод возвращает int — количество получателей, которым содержимое было фактически доставлено (для заголовков, подсказок и панелей действий учитываются только находящиеся в сети получатели типа Player).

Соответствие исходному коду

Эта страница написана по актуальному исходному коду Nukkit-MOT, в частности по методам Server#broadcastMessage(...), Server#broadcastTitle(...), Server#broadcastTip(...), Server#broadcastActionBar(...) и Server#broadcast(...).

Как определяются получатели​

Каждый метод рассылки существует вплоть до трёх вариантов указания получателей:

  • По умолчанию — без аргумента получателя: отправка во встроенный пользовательский канал Server.BROADCAST_CHANNEL_USERS (nukkit.broadcast.user).
  • С привязкой к правам — аргумент String permissions: отправка подписанным CommandSender, обладающим хотя бы одним из указанных каналов прав. Несколько каналов разделяются знаком ; (например, "myplugin.alerts;nukkit.broadcast.admin"). Встроенный канал администраторов — Server.BROADCAST_CHANNEL_ADMINISTRATIVE (nukkit.broadcast.admin), на который подписана консоль.
  • Коллекция получателей — аргумент Collection<? extends CommandSender>: отправка ровно указанным получателям.

Для заголовков, подсказок и панелей действий получатели, не являющиеся Player, в итоговом наборе молча пропускаются, поэтому возвращаемое значение может быть меньше размера коллекции.

broadcastMessage​

Отправляет сообщение в чат. Вариант с привязкой к правам находится в методе более низкого уровня broadcast(...).

public int broadcastMessage(String message)
public int broadcastMessage(TextContainer message)
public int broadcastMessage(String message, CommandSender[] recipients)
public int broadcastMessage(String message, Collection<? extends CommandSender> recipients)
public int broadcastMessage(TextContainer message, Collection<? extends CommandSender> recipients)

public int broadcast(String message, String permissions)
public int broadcast(TextContainer message, String permissions)

В отличие от рассмотренных ниже визуальных рассылок, сообщения чата доставляются также отправителям, не являющимся игроками, например консоли.

broadcastTitle​

Показывает заголовок с подзаголовком. Тайминги задаются параметрами fadeIn / stay / fadeOut в тиках (20 тиков = 1 секунда); в перегрузках без таймингов используются значения по умолчанию 20/20/5.

public int broadcastTitle(String title, String subtitle)
public int broadcastTitle(String title, String subtitle, String permissions)
public int broadcastTitle(String title, String subtitle, Collection<? extends CommandSender> recipients)
public int broadcastTitle(String title, String subtitle, int fadeIn, int stay, int fadeOut)
public int broadcastTitle(String title, String subtitle, int fadeIn, int stay, int fadeOut, String permissions)
public int broadcastTitle(String title, String subtitle, int fadeIn, int stay, int fadeOut, Collection<? extends CommandSender> recipients)

broadcastTip​

Показывает всплывающую подсказку над панелью быстрого доступа.

public int broadcastTip(String message)
public int broadcastTip(String message, String permissions)
public int broadcastTip(String message, Collection<? extends CommandSender> recipients)

broadcastActionBar​

Показывает сообщение в панели действий. Тайминги задаются параметрами fadeIn / duration / fadeOut в тиках; в перегрузках без таймингов используются значения по умолчанию 1/0/1.

public int broadcastActionBar(String message)
public int broadcastActionBar(String message, String permissions)
public int broadcastActionBar(String message, Collection<? extends CommandSender> recipients)
public int broadcastActionBar(String message, int fadeIn, int duration, int fadeOut)
public int broadcastActionBar(String message, int fadeIn, int duration, int fadeOut, String permissions)
public int broadcastActionBar(String message, int fadeIn, int duration, int fadeOut, Collection<? extends CommandSender> recipients)

Примеры​

Рассылка заголовка всем игрокам в сети через пользовательский канал по умолчанию:

import cn.nukkit.Server;

Server server = this.getServer();

int shown = server.broadcastTitle("§6Event Starting", "§eHead to spawn!", 10, 60, 10);
this.getLogger().info("Title shown to " + shown + " players");

Отправка панели действий с привязкой к правам только для администраторов, а также подсказки специально отобранному набору получателей:

import cn.nukkit.Player;
import cn.nukkit.Server;
import cn.nukkit.command.CommandSender;

import java.util.Collection;

Server server = this.getServer();

// Only senders subscribed to and holding the permission see this
server.broadcastActionBar("§cRestart in 60 seconds", Server.BROADCAST_CHANNEL_ADMINISTRATIVE);

// Explicit recipient list, e.g. everyone in one world
Collection<? extends CommandSender> lobbyPlayers = server.getOnlinePlayers().values().stream()
        .filter(player -> player.getLevel().getName().equals("lobby"))
        .toList();
server.broadcastTip("§aWelcome to the lobby!", lobbyPlayers);

Примечания​

  • Все параметры таймингов задаются в тиках.
  • Каналы прав разделяются знаком ;; получатель, подходящий сразу под несколько каналов, всё равно получает рассылку только один раз (получатели дедуплицируются).
  • Возвращаемое значение учитывает только игроков, у которых фактически отобразился заголовок, подсказка или панель действий; для broadcastMessage/broadcast оно учитывает всех получателей, которым было отправлено сообщение.