Rotação e Shards

Rotação de atividades

Quando o seu bot tem mais de uma mensagem para mostrar, você pode alternar activities em um intervalo fixo. O método startRotation recebe um array de activities e um intervalo em milissegundos. Ele aplica a primeira activity imediatamente e, a cada disparo do timer, avança para a próxima. Quando chega ao fim da lista, a rotação volta para o começo.

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

@Listener(Events.ClientReady)
export class ReadyListener {
  @Once()
  onReady(): void {
    PresenceManager.startRotation(
      [
        { name: '{{totalServers}} servers', type: 'Watching' },
        { name: '/help for commands', type: 'Playing' },
        { name: 'feedback from users', type: 'Listening' },
      ],
      30_000,
    );
  }
}

Chamar startRotation interrompe qualquer rotação anterior antes de iniciar a nova. O timer é criado com unref, então ele não impede o processo Node.js de encerrar corretamente durante o shutdown. Placeholders usados nos nomes das activities são resolvidos de novo a cada ciclo, então valores como {{totalServers}} continuam sempre atualizados.

Você também pode configurar essa rotação já no boot definindo rotateInterval na configuração de presence e fornecendo mais de uma activity. Basta declarar isso dentro de config/ e passar o objeto para initPresence em main.ts. O framework inicia a rotação automaticamente depois da conexão do client, sem exigir código de listener.

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

export const presenceConfig: PresenceOptions = {
  status: 'online',
  activities: [
    { name: '{{totalServers}} servers', type: 'Watching' },
    { name: '/help', type: 'Playing' },
    { name: '{{ping}}ms latency', type: 'Competing' },
  ],
  rotateInterval: 20_000,
};

Parando a rotação

O método stopRotation limpa o timer do intervalo. A última activity aplicada continua visível até você definir outra ou chamar reset. Isso é útil para congelar a presence durante uma manutenção ou quando o bot entra num estado excepcional.

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

PresenceManager.stopRotation();
PresenceManager.setActivity({
  name: 'maintenance in progress',
  type: 'Playing',
});

Presença por shard no boot

Quando o bot roda em vários shards, cada processo resolve os placeholders internos de forma independente. Um único {{totalServers}} mostra números diferentes em shards diferentes porque cada um só conhece as guilds que atende. Isso acontece automaticamente, sem configuração especial.

Se você quiser personalização mais profunda, o objeto PresenceOptions aceita um registro perShard. Cada chave representa o ID de um shard, e o valor sobrescreve a presence global para aquele shard específico. Os overrides são mesclados com a configuração global, então você só precisa declarar o que deseja alterar.

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

export const presenceConfig: PresenceOptions = {
  status: 'online',
  activities: [
    { name: 'Shard {{shardNumber}}/{{totalShards}}', type: 'Playing' },
  ],
  perShard: {
    0: {
      status: 'dnd',
      activities: [
        { name: 'Primary shard · {{totalServers}} guilds', type: 'Watching' },
      ],
    },
  },
};

Overrides de shard em runtime

Os métodos estáticos setShardPresence, setShardActivity, clearShardPresence e clearShardActivity permitem alterar a presence de shards específicos em runtime. Esses overrides têm prioridade sobre a presence global daquele shard em todas as chamadas seguintes de applyPresence.

setShardPresence recebe o ID do shard e um objeto parcial de presence com status e activities opcionais. Ele se mescla com qualquer override já existente para aquele shard. Já setShardActivity é um atalho que altera apenas a activity do shard, com opção de injetar placeholders customizados.

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

@Injectable()
export class ShardStatusService {
  updateShardActivity(shardId: number, version: string) {
    PresenceManager.setShardActivity(
      shardId,
      {
        name: 'v{{version}} · {{totalServers}} guilds on shard {{shardNumber}}',
        type: 'Playing',
      },
      { version },
    );
  }

  resetShard(shardId: number) {
    PresenceManager.clearShardPresence(shardId);
  }
}

O terceiro argumento de setShardActivity é um registro com placeholders customizados. Eles são mesclados sobre os placeholders internos, então {{version}} no exemplo acima assume o valor da string que você passar. Placeholders nativos como {{totalServers}} e {{shardNumber}} continuam sempre disponíveis e não precisam ser enviados manualmente.

Referência da API