Участники

Обзор

Когда игрок вступает в гильдию, групповой чат или лобби, он становится участником канала. Игровой процесс может быть построен таким образом, что игроку потребуется самостоятельно инициировать или отменить запрос на вступление в канал. Участника канала можно исключить, замьютить и так далее.

tip

Взаимодействие участника с каналом - это, например, механизм подачи заявки на вступление в клан

Ниже представлен полный список методов, реализованных для управления участниками канала:

• gp.channels.join - запрос на вступление +1 Request
• gp.channels.cancelJoin - отмена запроса на вступление +1 Request
• gp.channels.leave - выход участника из канала +1 Request
• gp.channels.kick - исключение участника из канала +1 Request
• gp.channels.mute - мьют игрока в канале +1 Request
• gp.channels.unmute - отменить мьют игрока +1 Request

Вступление в канал

Чтобы вступить в канал, следует создать запрос на вступление. В этом случае может быть два сценария развития:

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

Запрос на вступление

+1 Request

Для создания запроса на вступление в канал с идентификатором channelId: 123 используется метод gp.channels.join:

gp.channels.join({ channelId: 123 });

Если в канале установлен пароль, то его следует передать вместе с идентификатором:

gp.channels.join({ channelId: 123, password: "qwerty" });

Узнать наличие пароля канала можно с помощью метода gp.channels.fetchChannel({ channelId: 123 }) и посмотреть поле channel.hasPassword.

После вызова метода игрок автоматически вступает в канал, если канал был публичный. Если канал приватный, то отправляется запрос на вступление и его должны принять. Чтобы узнать приватный канал или нет, можно посмотреть поле channel.private.

Чтобы получить результат вызова метода, можно подписаться на события:

gp.channels.on('join', () => {
  // успешно вступил или подал заявку на вступление
});

Выполнение с ошибкой

gp.channels.on('error:join', (err) => {
  // завершен с ошибкой
});

Возможные ошибки приведены в таблице ниже:

базовые ошибки	сценарные ошибки
player_not_found	empty_channel_id
project_not_found	channel_not_found
origin_not_allowed	already_in_channel
player_banned	already_requested 💡
internal_error	channel_capacity_reached
	invalid_password 💡
	already_in_channel

info

already_requested 💡 - уже подал заявку на вступление.

invalid_password 💡 - ошибка возникает если на публичный канал установлен пароль и пароль неверный. Если канал приватный, то пароль игнорируется, так как используется механизм подтверждения заявки владельцем.

Сделав запрос на вступление в публичный канал, игрок автоматически становится его участником и всем игрокам в канале приходит уведомление о вступлении:

gp.channels.on('event:join', (member) => {
    // ID канала
    member.channelId;
    // ID вступившего игрока
    member.id;
    // Поля игрока (аватар, имя, кастомные поля)
    member.state;
    // Информация о мьюте игрока
    member.mute;
});

Запрос на вступление в приватный канал

Всем игрокам в канале (если они могут принимать запросы на вступление) приходит уведомление о том, что новый игрок пытается вступить в канал:

gp.channels.on('event:joinRequest', (joinRequest) => {
    // ID канала
    joinRequest.channelId;
    // ID игрока кто подал запрос на вступление
    joinRequest.playerId;
    // Поля игрока (аватар, имя, кастомные поля)
    joinRequest.player;
    // Дата запроса на вступление в ISO 8601 UTC "2022-12-01T04:52:26+0000"
    joinRequest.date;
});

Игроки могут принять запрос, используя метод acceptJoinRequest или отклонить через rejectJoinRequest (подробнее см. в разделе Запросы).

Отмена запроса на вступление

+1 Request

Для отмены запроса на вступление в канал с идентификатором channelId: 123 используется метод gp.channels.cancelJoin:

gp.channels.cancelJoin({ channelId: 123 });

Чтобы получить результат вызова метода, можно подписаться на события:

gp.channels.on('cancelJoin', () => {
  // успешно отменил заявку на вступление
});

Выполнение с ошибкой:

gp.channels.on('error:cancelJoin', (err) => {
  // завершен с ошибкой
});

Возможные ошибки приведены в таблице ниже:

базовые ошибки	сценарные ошибки
player_not_found	empty_channel_id
project_not_found	channel_not_found
origin_not_allowed	join_request_not_found 💡
player_banned
internal_error

info

join_request_not_found 💡 - игрок не подавал заявку на вступление или отменил ее

Если игрок отменяет запрос на вступление в канал, то всем игрокам в канале (если они могут принимать запросы на вступление) приходит уведомление о том, что запрос на вступление был отменен:

gp.channels.on('event:cancelJoin', (joinRequest) => {
    // ID канала
    joinRequest.channelId;
    // ID игрок, который подал запрос на вступление
    joinRequest.playerId;
});

Выход из канала

+1 Request

Для выхода из канала с идентификатором channelId: 123:

gp.channels.leave({ channelId: 123 });

Чтобы получить результат вызова метода, можно подписаться на события:

gp.channels.on('leave', () => {
  // успешно покинул канал
});

Выполнение с ошибкой:

gp.channels.on('error:leave', (err) => {
  // завершен с ошибкой
});

Возможные ошибки приведены в таблице ниже:

базовые ошибки	сценарные ошибки
player_not_found	empty_channel_id
project_not_found	channel_not_found
origin_not_allowed	player_not_in_channel
player_banned
internal_error

Игрок выходит из канала, и всем игрокам в канале приходит уведомление об этом событии event:leave:

gp.channels.on('event:leave', (memberLeave) => {
    // ID канала
    memberLeave.channelId;
    // ID вышедшего игрока
    memberLeave.playerId;
    // Причина выхода "leave"
    memberLeave.reason;
});

Исключение участника из канала

+1 Request

tip

Владельца канала нельзя исключить из него

Для исключения участника playerId: 123456 из канала channelId: 123:

gp.channels.kick({ channelId: 123, playerId: 123456 });

Чтобы получить результат вызова метода, можно подписаться на события:

gp.channels.on('kick', () => {
  // успешно исключен
});

Выполнение с ошибкой:

gp.channels.on('error:kick', (err) => {
  // завершен с ошибкой
});

Возможные ошибки приведены в таблице ниже:

базовые ошибки	сценарные ошибки
player_not_found	empty_channel_id
project_not_found	channel_not_found
origin_not_allowed	access_denied
player_banned	player_not_in_channel
internal_error

Игрок выходит из канала и всем игрокам в канале приходит уведомление об этом событии event:leave:

gp.channels.on('event:leave', (memberLeave) => {
    // ID канала
    memberLeave.channelId;
    // ID вышедшего игрока
    memberLeave.playerId;
    // Причина выхода "kick"
    memberLeave.reason;
});

Получить участников

+1 Request

Можно посмотреть всех игроков (участников) в нужном канале и получить все их публичные данные. Присоединившись к чату, игрок будет видеть всех его участников:

const response = await gp.channels.fetchMembers({
  channelId: 10,
  // необязательные
  // поиск по ID или имени или ID на площадке
  search: '',
  // искать только тех, кто в сети
  onlyOnline: true,
  // сколько запросить за раз, макс. 100
  limit: 100,
  // сколько записей пропустить, макс. 10000, используется для постраничной навигации или "подгрузить еще"
  offset: 0
});

Чтобы получить результат вызова метода, можно подписаться на события:

gp.channels.on('fetchMembers', (result) => {
  result.items - массив списка участников
  result.canLoadMore - можно ли подгрузить еще участников

  result.items.forEach((member) => {
    // все поля участника
    // id игрока
    member.id
    // сейчас в сети
    member.isOnline

    // публичные поля игрока
    member.state
    // Например имя, аватар и очки
    member.state.name
    member.state.avatar
    member.state.score

    // информация о мьюте игрока
    member.mute
    // замьючен или нет
    member.mute.isMuted
    // время снятия мьюта - дата в ISO 8601, если пустая строка - вечный мьют
    member.mute.unmuteAt
  });
});

Выполнение с ошибкой:

gp.channels.on('error:fetchMembers', (err) => {
  // завершен с ошибкой
});

Возможные ошибки приведены в таблице ниже:

базовые ошибки	сценарные ошибки
player_not_found	empty_channel_id
project_not_found	channel_not_found
origin_not_allowed
player_banned
internal_error

Чтобы дополнительно подгрузить участников по такому же запросу, существует удобный метод:

const response = await gp.channels.fetchMoreMembers({
  channelId: 10,
  // необязательные
  // поиск по ID или имени или ID на площадке
  search: '',
  // искать только тех, кто в сети
  onlyOnline: true,
  // сколько запросить за раз, макс. 100
  limit: 100,
});

Чтобы получить результат вызова метода, можно подписаться на события:

gp.channels.on('fetchMoreMembers', (result) => {
  result.items - массив списка участников
  result.canLoadMore - можно ли подгрузить еще участников
});

Выполнение с ошибкой:

gp.channels.on('error:fetchMoreMembers', (err) => {
  // завершен с ошибкой
});

Возможные ошибки приведены в таблице ниже:

базовые ошибки	сценарные ошибки
player_not_found	empty_channel_id
project_not_found	channel_not_found
origin_not_allowed
player_banned
internal_error

Мьют игрока 🔇

+1 Request

tip

/mute. Владельца канала нельзя замьютить

Чтобы замьютить игрока playerId: 123456 в канале channelId: 123 используется метод gp.channels.mute.

gp.channels.mute({ channelId: 123, playerId: 123456, unmuteAt: '2022-12-01T04:52:26+0000' });

Альтернативный вариант с возможностью задать количество секунд, на которые требуется замьютить игрока:

// замьютить на 5 минут
gp.channels.mute({ channelId: 123, playerId: 123456, seconds: 5 * 60 });

info

Разработчик самостоятельно устанавливает время, на которое следует замьютить игрока, с помощью unmuteAt. Если значение unmuteAt не передано, то игрок глушится на неограниченное время.

Чтобы получить результат вызова метода, можно подписаться на события:

gp.channels.on('mute', () => {
  // успешно замьючен
});

Выполнение с ошибкой:

gp.channels.on('error:mute', (err) => {
  // завершен с ошибкой
});

Возможные ошибки приведены в таблице ниже:

базовые ошибки	сценарные ошибки
player_not_found	empty_channel_id
project_not_found	channel_not_found
origin_not_allowed	access_denied
player_banned	wrong_time_format 💡
internal_error

info

wrong_time_format 💡 - передан неверный формат даты снятия блокировки

При заглушении игрока всем участникам в канале приходит уведомление:

gp.channels.on('event:mute', (mute) => {
    // ID канала
    mute.channelId;
    // ID замьюченного игрока
    mute.playerId;
    // Дата размьюта
    mute.unmuteAt;
});

Размьютить игрока 🔉

+1 Request

tip

/unmute

Вновь разрешить игроку playerId: 123456 писать сообщение в канале channelId: 123 можно с помощью метода gp.channels.unmute:

gp.channels.unmute({ channelId: 123, playerId: 123456 });

Чтобы получить результат вызова метода, можно подписаться на события:

gp.channels.on('unmute', () => {
  // успешно размьючен
});

Выполнение с ошибкой:

gp.channels.on('error:unmute', (err) => {
  // завершен с ошибкой
});

Возможные ошибки приведены в таблице ниже:

базовые ошибки	сценарные ошибки
player_not_found	empty_channel_id
project_not_found	channel_not_found
origin_not_allowed	access_denied
player_banned	not_muted
internal_error

При этом всем участникам в канале приходит уведомление:

gp.channels.on('event:unmute', (mute) => {
    // ID канала
    mute.channelId;
    // ID размьюченного игрока
    mute.playerId;
});

Оставайтесь на связи

С другими разделами документации вы можете ознакомиться здесь. Для начала работы вы можете ознакомиться с нашими туториалами.

Сообщество GamePush в Telegram: @gs_community.

Для ваших обращений e-mail: [email protected]

Желаем вам успехов!