Adding a Command

​

1. Write the command

const {ApplicationCommandOptionType} = require('discord.js');
const {isAdmin} = require('../../utils/adminRoles');
const {resolveTarget} = require('../../utils/commandGuild');
const {GUILD_OPTION, guildOptionAutocomplete} = require('../../utils/guildAutocomplete');

module.exports = {
    name: 'example',
    description: 'One sentence, sentence case, ending in a period.',
    options: [
        {
            name: 'username',
            description: 'The Minecraft username.',
            type: ApplicationCommandOptionType.String,
            required: true,
        },
        GUILD_OPTION,
    ],

    callback: async (client, interaction) => {
        if (!isAdmin(interaction.member)) {
            return interaction.reply({content: '❌ You are not allowed to use this.', ephemeral: true});
        }

        await interaction.deferReply();

        const target = await resolveTarget(interaction);
        if (!target.ok) return;   // resolveTarget has already replied

        // ... work ...
    },

    autocomplete: guildOptionAutocomplete(),
};

​

2. Get the guild right

​

3. Get the permissions right

​

4. Talk to Hypixel through the helpers

• Reading something back: queryGuild(record, '/guild list'). Never hand-roll a message listener — Hypixel gives no request/response correlation, and queryGuild is what stops two concurrent commands eating each other’s output.
• Saying something: sendChat(record, text). Calling bot.chat directly for relayed traffic gets accounts muted.
• Building a chat line from user input: buildGuildChatCommand(name, body). If you build one by hand, validate the username with isValidMinecraftName() and run free text through sanitizeForChat() — an unflattened multi-line message sends its second line at command position.

​

5. Reply in the house style

​

6. The after-every-change checklist

1. CHANGELOG.md — an entry under ## Unreleased, written for the people running the bot. Format in Releasing.
2. DISCORD_CHANGELOG.md — one line, second person, only if a guild member would notice.
3. README.md — a row in the command table, and anything else it mentions that you changed.
4. The public docs — docs/FEATURES.md is the canonical in-repo description; the Mintlify page restates it for its reader. A new command always touches Commands, which is meant to be exhaustive. New config file? Config files. New permission? Permissions.

​

7. Do not run the bot to check

​

Registration

• Global propagation takes up to an hour, so a new command will not appear immediately.
• choices and autocomplete are mutually exclusive in the Discord API. Never set both.

​

Next

• Architecture
• Contributing
• Releasing