Visão Geral da Presença

O que o sistema de presença resolve

Bots do Discord exibem um indicador de status, como online, idle, não perturbe e invisível, além de uma linha de atividade abaixo do nome, como Playing, Watching, Listening, Streaming ou Competing. Esses campos de presence são uma das primeiras coisas que as pessoas veem quando olham o bot na lista de membros. O PresenceManager oferece uma API estática para definir e atualizar esses campos de qualquer ponto da aplicação, inclusive com suporte a overrides por shard e interpolação dinâmica de placeholders.

Sem um gerenciador de presence, você precisaria chamar client.user.setPresence() diretamente. Isso significa depender de uma referência ao client, se proteger contra chamadas antes do ready e ainda ficar sem suporte embutido para rotação de atividades ou textos específicos por shard. O PresenceManager centraliza tudo isso em uma classe estática que o framework inicializa automaticamente quando o bot conecta.

O sistema de presence também conversa diretamente com o sistema de sharding. Quando o bot roda em vários shards, cada shard pode exibir uma activity própria com informações específicas, como número do shard ou quantidade de guilds atendidas por ele. Placeholders internos como {{totalServers}} e {{shardNumber}} são resolvidos automaticamente a partir do estado vivo do client a cada atualização.

Definindo uma atividade estática

O caso mais simples é definir uma activity fixa e deixá-la ali até você trocar. Chame PresenceManager.setActivity com um nome e um tipo. O nome é o texto exibido na lista de membros, e o tipo determina o prefixo que o Discord mostra, como Playing, Watching, Listening, Streaming ou Competing.

import { Events, Listener, Once } from '@spraxium/common';
import { PresenceManager } from '@spraxium/core';

@Listener(Events.ClientReady)
export class ReadyListener {
  @Once()
  onReady(): void {
    PresenceManager.setActivity({
      name: 'your commands',
      type: 'Listening',
    });
  }
}

O método setActivity altera só a activity. Ele não mexe no indicador de status. Se você quiser atualizar os dois de uma vez, use setPresence, que aceita um status e um array activities. A primeira activity da lista vira a atual.

PresenceManager.setPresence({
  status: 'dnd',
  activities: [{ name: 'maintenance mode', type: 'Playing' }],
});

Alterando só o status

O método setStatus atualiza o indicador colorido sem mexer no texto da activity. Existem quatro valores disponíveis: 'online' (verde), 'idle' (amarelo), 'dnd' (vermelho) e 'invisible' (cinza, aparecendo offline). Isso é útil para sinalizar janela de manutenção ou estado degradado sem trocar o que o bot está exibindo como activity.

import { PresenceManager } from '@spraxium/core';

PresenceManager.setStatus('idle');

Interpolação de placeholders

Os nomes das activities aceitam placeholders no formato {{key}}, resolvidos a partir do estado vivo do client sempre que a presence é atualizada. Cinco variáveis internas ficam disponíveis sem configuração extra. Elas se atualizam sozinhas, então um contador como {{totalServers}} continua correto conforme o bot entra ou sai de guilds.

Placeholders funcionam em todo lugar onde activities aparecem: em setActivity, setPresence, startRotation, configuração de boot e overrides por shard. Se uma chave não for resolvida, ela continua como está no texto final, por exemplo {{unknownKey}}, o que ajuda bastante a perceber erro de digitação.

PresenceManager.setActivity({
  name: '{{totalServers}} servers · {{ping}}ms',
  type: 'Watching',
});

Configuração no boot

Em vez de chamar métodos do PresenceManager dentro de um listener, você pode declarar a presence inicial como uma constante tipada dentro de config/ e passá-la para initPresence no builder da aplicação em main.ts. O framework aplica essa configuração automaticamente depois da conexão do client e antes de qualquer listener rodar.

import type { PresenceOptions } from '@spraxium/core';

export const presenceConfig: PresenceOptions = {
  status: 'online',
  activities: [{ name: '{{totalServers}} servers', type: 'Watching' }],
};

initPresence aceita um objeto PresenceOptions com status, um array de activities, um rotateInterval para rotação automática e um registro perShard para overrides específicos de shard já no boot.

Voltando ao estado inicial

O método reset restaura exatamente a presence configurada no boot. Ele interrompe qualquer rotação ativa, redefine status e activity e reinicia a rotação se a configuração original tiver definido uma. Overrides de shard criados em runtime não são limpos por reset, então, se você quiser um reset completo, chame clearShardPresence para cada shard antes.

PresenceManager.reset();