> For the complete documentation index, see [llms.txt](https://docs.iynxdev.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iynxdev.com/premium-addons/command-maker/configuration.md).

# Configuration

## <mark style="color:blue;">Getting Started</mark>

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.

***

## <mark style="color:blue;">Part 1: Creating Custom Commands</mark>

### <mark style="color:yellow;">Step 1: Understanding Command Structure</mark>

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

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

***

### <mark style="color:yellow;">Step 2: Basic Command Configuration</mark>

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

#### <mark style="color:orange;">1. Set the Command ID</mark>

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

```json
"minecraft_ip": {
    enabled: true,
```

#### <mark style="color:orange;">2. Set Command Name & Description</mark>

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

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

#### <mark style="color:orange;">3. Set Permissions</mark>

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

```json
    command_permission: "everyone",
```

Common permission levels:

* `everyone` - All server members
* `staff` - Staff members and above
* `admin` - Administrators only
* `management` - Server management only

***

### <mark style="color:yellow;">Step 3: Creating Predefined Messages</mark>

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

{% hint style="info" %}
**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
   {% endhint %}

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

***

### <mark style="color:yellow;">Step 4: Configure Command Response</mark>

Now configure what happens when the command is executed:

```json
    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

***

### <mark style="color:yellow;">Step 5: Adding Command Parameters</mark>

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

#### <mark style="color:orange;">Example: Command with User Parameter</mark>

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

```json
"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"
        }
    ],
```

#### <mark style="color:orange;">Example: Command with String Options</mark>

Create a command where users select from predefined options:

```json
    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

***

### <mark style="color:yellow;">Step 6: Adding Actions</mark>

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

#### <mark style="color:orange;">Available Action Types</mark>

**ROLE\_APPLY** - Give the user a role:

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

**ROLE\_REMOVE** - Remove a role from the user:

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

**CHANNEL\_SEND** - Send a message to a specific channel:

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

**USER\_SEND** - Send a DM to a user:

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

{% hint style="warning" %}
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
  {% endhint %}

***

### <mark style="color:yellow;">Step 7: Using Placeholders</mark>

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:

```json
"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")

***

### <mark style="color:yellow;">Complete Command Example</mark>

Here's a fully configured custom command:

```json
"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

***

## <mark style="color:blue;">Part 2: Creating Custom Buttons</mark>

### <mark style="color:yellow;">Step 1: Understanding Button Structure</mark>

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

```json
{
    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: []
            }
        }
    }
}
```

***

### <mark style="color:yellow;">Step 2: Basic Button Configuration</mark>

#### <mark style="color:orange;">1. Set Button ID & Type</mark>

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

#### <mark style="color:orange;">2. Set Button Text & Emoji</mark>

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

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

#### <mark style="color:orange;">3. Choose Button Style</mark>

```json
    button_type: "Primary",
```

**Available Styles:**

* `Primary` - Blue button
* `Secondary` - Gray button
* `Success` - Green button
* `Danger` - Red button
* `Link` - URL button (requires `button_url`)

#### <mark style="color:orange;">4. Configure Link Buttons (Optional)</mark>

For `Link` type buttons:

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

***

### <mark style="color:yellow;">Step 3: Button Response & Actions</mark>

Button responses work the same as command responses:

```json
    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

***

### <mark style="color:yellow;">Complete Button Example</mark>

```json
"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

***

## <mark style="color:blue;">Part 3: Practical Examples</mark>

### <mark style="color:yellow;">Example 1: Server Rules Command</mark>

```json
"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: []
}
```

***

### <mark style="color:yellow;">Example 2: Support Ticket Button</mark>

```json
"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"
        }
    ]
}
```

***

### <mark style="color:yellow;">Example 3: Role Selection Menu</mark>

```json
"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"
        }
    ]
}
```

***

## <mark style="color:blue;">Tips & Best Practices</mark>

{% hint style="success" %}
**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
  {% endhint %}

{% hint style="warning" %}
**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
  {% endhint %}

***

## <mark style="color:blue;">Troubleshooting</mark>

### <mark style="color:yellow;">Command not appearing in Discord</mark>

* 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

### <mark style="color:yellow;">Predefined message not found</mark>

* Double-check the `predefined_message_id` spelling
* Ensure you've saved the message using `/sendmsg` or `/editmsg`
* Predefined message IDs are case-sensitive

### <mark style="color:yellow;">Actions not executing</mark>

* 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

### <mark style="color:yellow;">Buttons not working</mark>

* 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