Precedencia de resolución de prefijos
Cuando el framework recibe un mensaje, el PrefixParser comprueba si el texto comienza con un prefijo reconocido. La resolución sigue un orden de precedencia estricto: primero se comprueban los prefijos específicos de guild, luego el prefijo global y, por último, la mención al bot si está habilitada. El primer match gana y las opciones restantes se omiten.
Este modelo de precedencia significa que un override de guild siempre tiene prioridad sobre el valor global por defecto. Si una guild ha registrado ? como prefijo y la configuración global usa !, los mensajes que comienzan con ? hacen match en esa guild mientras que ! se ignora. Si no existe override de guild, el parser vuelve al prefijo global. El prefijo por mención (por ejemplo, @Bot roll 6) siempre se comprueba al final como fallback universal.
El orden de resolución es importante para bots que atienden múltiples comunidades con convenciones diferentes. Una guild enfocada en moderación puede preferir . como prefijo porque es discreto y poco intrusivo, mientras que una guild de gaming puede elegir >> por visibilidad. El sistema de prefijos por guild permite que cada comunidad defina su propia convención sin afectar a las demás.
Comprobar overrides de guild
El parser llama a PrefixGuildManager.getGuildPrefix con el ID de guild del mensaje entrante. Si la guild tiene uno o más prefijos registrados, el parser compara el mensaje contra cada uno en orden. El primer prefijo que coincide se usa y el parser pasa directamente a la tokenización. Los prefijos de guild pueden ser un string único o un arreglo de strings.
Comprobar prefijo global
Si no coincide ningún override de guild (o el mensaje viene de DM), el parser compara el mensaje contra el prefijo global definido en PrefixConfig. El prefijo global también admite arreglos, así que puedes definir varios prefijos globales como ['!', '?']. Si el mensaje comienza con cualquiera de los prefijos globales, se usa el primero que haga match.
Comprobar prefijo por mención
Si mentionPrefix está habilitado (valor por defecto), el parser comprueba si el mensaje comienza con una mención al bot como <@BOT_ID>. Esto actúa como un prefijo universal que siempre funciona sin importar la configuración de guild o global. El prefijo por mención es útil cuando los usuarios olvidan el prefijo configurado y necesitan un fallback confiable.
Referencia de PrefixConfig
La interfaz PrefixConfig controla el comportamiento global del subsistema de prefijos. La pasas a definePrefix en tu archivo de configuración. Todos los campos excepto prefix son opcionales y tienen un valor por defecto razonable.
import { definePrefix } from '@spraxium/core';
import { loadGuildPrefixes } from './prefix/guild-prefix.provider';
export default definePrefix({
prefix: '!',
caseSensitive: false,
mentionPrefix: true,
defaultCooldown: 3,
replyOnNotFound: true,
guildPrefixProvider: loadGuildPrefixes,
});Tu archivo de configuración solo debería definir la política global y la hidratación inicial del subsistema de prefijos. La lógica de lectura y escritura de prefijos, auditoría y sincronización debería vivir en servicios que inyecten PrefixDispatcher. La página Prefixes API via Services muestra esta arquitectura en profundidad para flujos de trabajo de producción.
Gestionar prefijos por guild en runtime
El PrefixGuildManager es accesible a través de PrefixDispatcher y ofrece una API completa para leer, escribir y eliminar overrides de prefijo específicos por guild. Los cambios se aplican de inmediato al siguiente mensaje entrante sin requerir reinicio. Esto te permite construir comandos de administración o integraciones de panel que actualicen prefijos dinámicamente.
Cada entrada de guild almacena el ID de guild, uno o más prefijos y un registro de metadatos opcional. El campo de metadatos no lo usa el framework por sí mismo, pero te da un lugar para guardar contexto como quién cambió el prefijo y cuándo. Esto es útil para auditoría en bots de moderación.
El método loadFromProvider se llama automáticamente al arrancar si defines un guildPrefixProvider en la configuración. También puedes llamarlo manualmente para recargar prefijos por guild desde tu base de datos en cualquier momento, por ejemplo después de una importación masiva o migración.
Ejemplo de mutación de prefijo en runtime
Un patrón común es construir un comando de administración que permita a los owners de guild cambiar su prefijo mediante un comando de mensaje. El handler inyecta PrefixDispatcher para acceder al manager guildPrefixes y persiste el cambio en una base de datos. La actualización en runtime tiene efecto inmediato para mensajes posteriores.
import { PrefixArg, PrefixCommand } from '@spraxium/common';
@PrefixCommand({ name: 'set-prefix' })
export class SetPrefixCommand {
@PrefixArg.String('newPrefix', { minLength: 1, maxLength: 5 })
build() {}
}Sistema de cooldown
El PrefixCooldownManager aplica cooldowns por usuario y por comando. Cuando un comando define un valor cooldown en su decorador @PrefixCommand (o usa el defaultCooldown global de config), el manager rastrea la marca de tiempo de la última ejecución para cada par usuario-comando. Si un usuario intenta ejecutar un comando antes de que expire el cooldown, el framework bloquea la ejecución y puede responder opcionalmente con el tiempo restante.
Los cooldowns se almacenan en memoria y se reinician cuando el bot se reinicia. El método check devuelve los segundos restantes (cero si el cooldown ya expiró), el método set registra una nueva entrada de cooldown y el método clear elimina todos los cooldowns rastreados. Para la mayoría de bots, el campo cooldown a nivel de decorador y el defaultCooldown global en config cubren todo automáticamente sin llamadas directas a la API.
El campo cooldown por comando en @PrefixCommand sobrescribe el defaultCooldown global. Si un comando define cooldown: 5 y el valor global por defecto es 3, ese comando usa un cooldown de 5 segundos.