Rotación y shards

Rotación de actividades

Cuando tu bot tiene varias cosas que comunicar, puedes rotar actividades en un intervalo fijo. El método startRotation acepta un arreglo de actividades y un intervalo en milisegundos. Establece la primera actividad de inmediato y luego avanza a la siguiente cada vez que se dispara el intervalo. La rotación vuelve al inicio cuando llega al final del arreglo.

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,
    );
  }
}

Llamar a startRotation detiene cualquier rotación existente antes de iniciar la nueva. El temporizador está unref'd, lo que significa que no impide que el proceso de Node.js termine limpiamente durante el apagado. Los placeholders en nombres de actividad se vuelven a resolver en cada tick, por lo que valores como {{totalServers}} se mantienen actualizados.

También puedes configurar la rotación al iniciar definiendo rotateInterval en tu configuración de presencia y proporcionando más de una actividad. Define la configuración en la carpeta config/ y pásala a initPresence en main.ts. El framework inicia la rotación automáticamente después de que el cliente se conecta, sin código adicional en listeners.

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,
};

Detener la rotación

El método stopRotation limpia el temporizador de intervalo. La última actividad activa permanece visible hasta que definas una nueva o llames a reset. Esto es útil para congelar temporalmente la presencia durante una ventana de mantenimiento o cuando el bot entra en un estado especial.

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

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

Presencia por shard al iniciar

Cuando tu bot se ejecuta en múltiples shards, cada proceso de shard resuelve los placeholders integrados de forma independiente. Un único placeholder {{totalServers}} muestra números distintos en diferentes shards porque cada shard solo conoce sus propias guilds. Esto ocurre automáticamente sin configuración especial.

Para una personalización más profunda, el objeto PresenceOptions admite un registro perShard. Cada clave es un ID de shard, y el valor sobrescribe la presencia global para ese shard específico. Las sobrescrituras se combinan con la configuración global, así que solo necesitas especificar los campos que quieres cambiar.

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' },
      ],
    },
  },
};

Sobrescrituras de shard en tiempo de ejecución

Los métodos estáticos setShardPresence, setShardActivity, clearShardPresence y clearShardActivity te permiten cambiar la presencia por shard en tiempo de ejecución. Estas sobrescrituras tienen prioridad sobre la presencia global para el shard correspondiente en cada llamada posterior a applyPresence.

setShardPresence acepta un ID de shard y un objeto de presencia parcial con status y activities opcionales. Se combina con cualquier sobrescritura existente para ese shard. setShardActivity es un atajo que solo cambia la actividad de un shard, con opción de inyectar variables de placeholder personalizadas.

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);
  }
}

El tercer argumento de setShardActivity es un registro de variables de placeholder personalizadas. Se combinan por encima de las integradas, así que {{version}} en el ejemplo anterior se resuelve al string que pases. Placeholders integrados como {{totalServers}} y {{shardNumber}} siempre están disponibles y no hace falta pasarlos manualmente.

Referencia de API

Página siguiente

Continúa con Referencia de CLI.