Visión general de presencia

Qué resuelve el sistema de presencia

Los bots de Discord muestran un indicador de estado (online, idle, do not disturb, invisible) y una línea de actividad bajo su nombre (Playing, Watching, Listening, Streaming, Competing). Estos campos de presencia son lo primero que las personas ven al revisar el bot en la lista de miembros. PresenceManager ofrece una API estática para definir y actualizar estos campos desde cualquier parte de tu aplicación, incluyendo soporte para sobrescrituras por shard e interpolación dinámica de placeholders.

Sin un gestor de presencia, tendrías que llamar a client.user.setPresence() directamente, lo que implica necesitar una referencia a la instancia del cliente, protegerte contra llamadas antes de que el cliente esté listo y no tener soporte integrado para rotar actividades o mostrar texto específico por shard. PresenceManager maneja todo esto mediante una clase estática centralizada que el framework inicializa automáticamente cuando el bot se conecta.

El sistema de presencia se integra con el sistema de sharding. Cuando tu bot se ejecuta en múltiples shards, cada shard puede mostrar su propio texto de actividad con información específica, como el número de shard o la cantidad de guilds en ese shard. Placeholders integrados como {{totalServers}} y {{shardNumber}} se resuelven automáticamente a partir del estado en vivo del cliente en cada actualización de presencia.

Definir una actividad estática

El caso de uso más simple es definir una actividad fija que se mantenga hasta que la cambies. Llama a PresenceManager.setActivity con un nombre y un tipo. El nombre es el texto que aparece en la lista de miembros, y el tipo determina el prefijo que añade Discord (Playing, Watching, Listening, Streaming o 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',
    });
  }
}

El método setActivity solo cambia la actividad. No toca el indicador de estado. Si quieres cambiar ambos a la vez, usa setPresence, que acepta un status y un arreglo activities. La primera actividad del arreglo pasa a ser la activa.

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

Cambiar solo el estado

El método setStatus actualiza el indicador de color sin tocar el texto de actividad. Hay cuatro valores disponibles: 'online' (verde), 'idle' (amarillo), 'dnd' (rojo) e 'invisible' (gris, aparece desconectado). Esto es útil para señalar ventanas de mantenimiento o estados degradados sin cambiar lo que dice la actividad.

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

PresenceManager.setStatus('idle');

Interpolación de placeholders

Los nombres de actividad admiten placeholders {{key}} que se resuelven desde el estado en vivo del cliente cada vez que se actualiza la presencia. Hay cinco variables integradas disponibles sin configuración adicional. Se refrescan automáticamente, así que un contador como {{totalServers}} se mantiene correcto cuando se agregan o eliminan guilds.

Los placeholders funcionan en todos los lugares donde se usan actividades: en setActivity, setPresence, startRotation, la configuración de inicio y las sobrescrituras por shard. Si una clave de placeholder no se resuelve, permanece tal cual en la salida (por ejemplo, {{unknownKey}}), lo que facilita detectar errores tipográficos.

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

Configuración al iniciar

En lugar de llamar a métodos de PresenceManager en un listener, puedes declarar la presencia inicial como una constante tipada en la carpeta config/ y pasarla a initPresence en el builder de la aplicación en main.ts. El framework la aplica automáticamente después de que el cliente se conecta, antes de que se dispare cualquier listener.

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

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

initPresence acepta un objeto PresenceOptions: un status, un arreglo activities, un rotateInterval para rotación automática y un registro perShard para sobrescrituras específicas por shard en el arranque.

Restablecer al estado de inicio

El método reset restaura exactamente la presencia configurada al inicio. Detiene cualquier rotación activa, restablece el estado y la actividad, y vuelve a iniciar la rotación si la configuración inicial especificaba una. Las sobrescrituras por shard en tiempo de ejecución no se limpian con reset, así que llama primero a clearShardPresence para cada shard si quieres un restablecimiento completo.

PresenceManager.reset();

Página siguiente

Continúa con Rotación y shards.