Execution and Guild Prefixes

Prefix resolution precedence

When the framework receives a message, the PrefixParser checks whether the text starts with a recognized prefix. Resolution follows a strict precedence order: guild-specific prefixes are checked first, then the global prefix, and finally bot mention if enabled. The first match wins and the remaining options are skipped.

This precedence model means that a guild override always takes priority over the global default. If a guild has registered ? as its prefix and the global config uses !, messages starting with ? are matched in that guild while ! is ignored. If no guild override exists, the parser falls back to the global prefix. Mention prefix (e.g., @Bot roll 6) is always checked last as a universal fallback.

The resolution order is important for bots that serve multiple communities with different conventions. A moderation-focused guild might prefer . as a prefix because it is quiet and unobtrusive, while a gaming guild might choose >> for visibility. The guild prefix system lets each community set its own convention without affecting others.

PrefixConfig reference

The PrefixConfig interface controls global behavior for the prefix subsystem. You pass it to definePrefix in your configuration file. Every field except prefix is optional and has a sensible default value.

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

Managing guild prefixes at runtime

The PrefixGuildManager is accessible through the PrefixDispatcher and provides a complete API for reading, writing, and removing guild-specific prefix overrides. Changes take effect immediately for the next incoming message without requiring a restart. This lets you build admin commands or dashboard integrations that update prefixes dynamically.

Each guild entry stores the guild ID, one or more prefixes, and an optional metadata record. The metadata field is not used by the framework itself, but it gives you a place to store context like who changed the prefix and when. This is useful for audit logging in moderation bots.

The loadFromProvider method is called automatically at startup if you define a guildPrefixProvider in the config. You can also call it manually to reload guild prefixes from your database at any time, for example after a bulk import or migration.

Runtime prefix mutation example

A common pattern is building an admin command that lets guild owners change their prefix through a message command. The handler injects the PrefixDispatcher to access the guildPrefixes manager and persists the change to a database. The runtime update takes effect immediately for subsequent messages.

import { PrefixArg, PrefixCommand } from '@spraxium/common';

@PrefixCommand({ name: 'set-prefix' })
export class SetPrefixCommand {
  @PrefixArg.String('newPrefix', { minLength: 1, maxLength: 5 })
  build() {}
}

Cooldown system

The PrefixCooldownManager enforces per-user, per-command cooldowns. When a command defines a cooldown value in its @PrefixCommand decorator (or uses the global defaultCooldown from config), the manager tracks the last execution timestamp for each user-command pair. If a user tries to run a command before the cooldown expires, the framework blocks execution and can optionally reply with the remaining time.

Cooldowns are stored in memory and reset when the bot restarts. The check method returns the remaining seconds (zero if the cooldown has expired), the set method registers a new cooldown entry, and the clear method removes all tracked cooldowns. For most bots, the decorator-level cooldown field and the global defaultCooldown config handle everything automatically without direct API calls.