📂Configuration

Complete guide to configuring custom commands and buttons

Getting Started

The Command Maker addon is configured through the command_maker.json file located in your bot's configuration/ folder. This guide will walk you through creating custom commands and buttons step-by-step.

---

Part 1: Creating Custom Commands

Step 1: Understanding Command Structure

Each custom command is defined within the commands object. You can create up to 5 custom commands. Here's the basic structure:

{
    config: {
        commands: {
            "command_id": {
                enabled: true,
                command_name: "commandname",
                command_description: "Description shown in Discord",
                command_permission: "everyone",
                command_parameters: [],
                command_message_response: { ... },
                actions: []
            }
        }
    }
}

---

Step 2: Basic Command Configuration

Let's create a simple command that displays your Minecraft server IP:

1. Set the Command ID

The command ID is the unique identifier for your command in the config file. This is not visible to users.

"minecraft_ip": {
    enabled: true,

2. Set Command Name & Description

The command name is what users will type in Discord (e.g., /ip). The description appears when users view the command.

    command_name: "ip",
    command_description: "Displays the IP address of our Minecraft server",

3. Set Permissions

Control who can use this command. This must match a permission level from your Core plugin's permission configuration.

    command_permission: "everyone",

Common permission levels:

• everyone - All server members

• staff - Staff members and above

• admin - Administrators only

• management - Server management only

---

Step 3: Creating Predefined Messages

Before configuring the command response, you need to create a predefined message template.

Creating Predefined Messages:

1. Use the /sendmsg command in Discord to create a new message template

2. Design your message with embeds, text, colors, images, etc.

3. Press the Save button and assign it a unique predefined message ID

4. Use this ID in your command configuration

For our Minecraft IP command, create a predefined message with ID minecraft_server_ip that contains your server information.

---

Step 4: Configure Command Response

Now configure what happens when the command is executed:

    command_message_response: {
        predefined_message_id: "minecraft_server_ip",
        files: [],
        components: [],
        ephemeral: false
    },

Options explained:

• predefined_message_id - The ID of your saved message template

• files - Array of file paths to attach (e.g., ["./images/banner.png"])

• components - Array of button IDs to add to the message (e.g., ["info_button"])

• ephemeral - If true, only the user who ran the command sees the response

---

Step 5: Adding Command Parameters

Parameters allow users to provide input when using your command. You can add parameters for user mentions or text with predefined options.

Example: Command with User Parameter

Let's create a /tutorial command that sends a tutorial message to a specific user:

"send_tutorial": {
    enabled: true,
    command_name: "tutorial",
    command_description: "Send a tutorial to a user",
    command_permission: "moderator",
    command_parameters: [
        {
            name: "user",
            description: "The user to send the tutorial to",
            required: true,
            type: "USER"
        }
    ],

Example: Command with String Options

Create a command where users select from predefined options:

    command_parameters: [
        {
            name: "topic",
            description: "Select a tutorial topic",
            options: ["getting-started", "commands", "permissions"],
            required: true,
            type: "STRING"
        }
    ],

Parameter Types:

• USER - User mention/selection

• STRING - Text input with optional predefined options

---

Step 6: Adding Actions

Actions execute automatically when the command is run. You can chain multiple actions together.

Available Action Types

ROLE_APPLY - Give the user a role:

    actions: [
        {
            type: "ROLE_APPLY",
            target: "1234567890123456789"
        }
    ]

ROLE_REMOVE - Remove a role from the user:

    actions: [
        {
            type: "ROLE_REMOVE",
            target: "1234567890123456789"
        }
    ]

CHANNEL_SEND - Send a message to a specific channel:

    actions: [
        {
            type: "CHANNEL_SEND",
            target: "1234567890123456789",
            predefinedId: "welcome_message"
        }
    ]

USER_SEND - Send a DM to a user:

    actions: [
        {
            type: "USER_SEND",
            target: "%user_id%",
            predefinedId: "tutorial_message"
        }
    ]

For CHANNEL_SEND and USER_SEND actions:

• If predefinedId is specified, that message template will be sent

• If predefinedId is null or omitted, the command's main response message will be sent

---

Step 7: Using Placeholders

Placeholders allow dynamic values in your actions:

• %user_id% - The user who executed the command

• %string_args_1% - The value of the first STRING parameter

• %string_args_2% - The value of the second STRING parameter (if exists)

Example: Send different tutorials based on user selection:

"tutorial_sender": {
    enabled: true,
    command_name: "sendtutorial",
    command_description: "Send a tutorial to a user",
    command_permission: "moderator",
    command_parameters: [
        {
            name: "user",
            description: "The user to send the tutorial to",
            required: true,
            type: "USER"
        },
        {
            name: "tutorial",
            description: "Which tutorial to send",
            options: ["beginner", "advanced", "expert"],
            required: true,
            type: "STRING"
        }
    ],
    command_message_response: {
        predefined_message_id: "tutorial_sent_confirmation",
        files: [],
        components: [],
        ephemeral: true
    },
    actions: [
        {
            type: "USER_SEND",
            target: "%user_id%",
            predefinedId: "%string_args_1%"
        }
    ]
}

In this example:

• %user_id% will be replaced with the selected user's ID

• %string_args_1% will be replaced with the tutorial name ("beginner", "advanced", or "expert")

---

Complete Command Example

Here's a fully configured custom command:

"server_ip": {
    enabled: true,
    command_name: "ip",
    command_description: "Get our Minecraft server IP",
    command_permission: "everyone",
    command_parameters: [],
    command_message_response: {
        predefined_message_id: "minecraft_ip_embed",
        files: [],
        components: ["join_button", "rules_button"],
        ephemeral: false
    },
    actions: [
        {
            type: "ROLE_APPLY",
            target: "1234567890123456789"
        },
        {
            type: "CHANNEL_SEND",
            target: "9876543210987654321",
            predefinedId: "new_player_alert"
        }
    ]
}

This command:

1. Shows the server IP using the minecraft_ip_embed message

2. Adds two buttons to the message

3. Gives the user a "Player" role

4. Sends an alert to a staff channel

---

Part 2: Creating Custom Buttons

Step 1: Understanding Button Structure

Buttons are defined in the components object. You can create up to 5 custom buttons:

{
    config: {
        components: {
            "button_id": {
                enabled: true,
                type: "BUTTON",
                button_name: "Click Me",
                button_emoji: "👆",
                button_type: "Primary",
                button_url: "",
                button_permission: "everyone",
                button_message_response: { ... },
                actions: []
            }
        }
    }
}

---

Step 2: Basic Button Configuration

1. Set Button ID & Type

"info_button": {
    enabled: true,
    type: "BUTTON",

2. Set Button Text & Emoji

    button_name: "Server Info",
    button_emoji: "📊",

Set button_emoji: false if you don't want an emoji.

3. Choose Button Style

    button_type: "Primary",

Available Styles:

• Primary - Blue button

• Secondary - Gray button

• Success - Green button

• Danger - Red button

• Link - URL button (requires button_url)

4. Configure Link Buttons (Optional)

For Link type buttons:

    button_type: "Link",
    button_url: "https://yourserver.com",

---

Step 3: Button Response & Actions

Button responses work the same as command responses:

    button_permission: "everyone",
    button_message_response: {
        predefined_message_id: "server_stats",
        files: [],
        components: [],
        ephemeral: true,
        message_update: false
    },
    actions: [
        {
            type: "ROLE_APPLY",
            target: "1234567890123456789"
        }
    ]

Special Option:

• message_update - If true, updates the message containing the button instead of sending a new message

---

Complete Button Example

"verify_button": {
    enabled: true,
    type: "BUTTON",
    button_name: "Verify",
    button_emoji: "✅",
    button_type: "Success",
    button_url: "",
    button_permission: "everyone",
    button_message_response: {
        predefined_message_id: "verification_success",
        files: [],
        components: [],
        ephemeral: true,
        message_update: false
    },
    actions: [
        {
            type: "ROLE_APPLY",
            target: "1234567890123456789"
        },
        {
            type: "ROLE_REMOVE",
            target: "9876543210987654321"
        }
    ]
}

This button:

1. Shows a green button with a checkmark

2. Sends an ephemeral success message

3. Gives the user a "Verified" role

4. Removes an "Unverified" role

---

Part 3: Practical Examples

Example 1: Server Rules Command

"rules": {
    enabled: true,
    command_name: "rules",
    command_description: "Display server rules",
    command_permission: "everyone",
    command_parameters: [],
    command_message_response: {
        predefined_message_id: "server_rules",
        files: [],
        components: ["accept_rules"],
        ephemeral: false
    },
    actions: []
}

---

Example 2: Support Ticket Button

"create_ticket": {
    enabled: true,
    type: "BUTTON",
    button_name: "Create Ticket",
    button_emoji: "🎫",
    button_type: "Primary",
    button_url: "",
    button_permission: "everyone",
    button_message_response: {
        predefined_message_id: "ticket_created",
        files: [],
        components: [],
        ephemeral: true,
        message_update: false
    },
    actions: [
        {
            type: "CHANNEL_SEND",
            target: "1234567890123456789",
            predefinedId: "new_ticket_staff_alert"
        }
    ]
}

---

Example 3: Role Selection Menu

"get_gamer_role": {
    enabled: true,
    type: "BUTTON",
    button_name: "Gamer",
    button_emoji: "🎮",
    button_type: "Primary",
    button_url: "",
    button_permission: "everyone",
    button_message_response: {
        predefined_message_id: "role_added",
        files: [],
        components: [],
        ephemeral: true,
        message_update: false
    },
    actions: [
        {
            type: "ROLE_APPLY",
            target: "1234567890123456789"
        }
    ]
},
"get_artist_role": {
    enabled: true,
    type: "BUTTON",
    button_name: "Artist",
    button_emoji: "🎨",
    button_type: "Success",
    button_url: "",
    button_permission: "everyone",
    button_message_response: {
        predefined_message_id: "role_added",
        files: [],
        components: [],
        ephemeral: true,
        message_update: false
    },
    actions: [
        {
            type: "ROLE_APPLY",
            target: "9876543210987654321"
        }
    ]
}

---

Tips & Best Practices

Best Practices:

• Set appropriate permissions to prevent abuse

• Test your commands in a test channel before deploying

• Use ephemeral messages for personal information

• Create predefined messages before configuring commands

Important Notes:

• Command names must be unique and cannot override built-in commands

• You can have maximum 5 custom commands

• Button type must be "BUTTON" (more types coming soon)

• Predefined message IDs are case-sensitive

• File paths are relative to your bot's index.js file

• Discord limits messages to 25 components (buttons) maximum

---

Troubleshooting

Command not appearing in Discord

• Ensure enabled: true is set

• Check that command_name is unique and doesn't conflict with existing commands

• Verify the bot has permission to register slash commands

• Restart the bot after making configuration changes

Predefined message not found

• Double-check the predefined_message_id spelling

• Ensure you've saved the message using /sendmsg or /editmsg

• Predefined message IDs are case-sensitive

Actions not executing

• Verify role/channel IDs are correct (right-click with Developer Mode enabled)

• Check that the bot has permission to assign roles or send messages to channels

• Ensure role hierarchy - bot's role must be higher than the role being assigned

Buttons not working

• Verify button ID matches the ID referenced in components array

• Check enabled: true is set for the button

• Ensure the button type is valid

• For Link buttons, make sure button_url is a valid URL