# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.iynxdev.com/premium-addons/command-maker/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.