> 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/configuration-files/core.md).

# Core

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

The Core configuration file (`core.json`) contains essential bot settings that affect the overall behavior of Athena Bot, including bot status, command cooldowns, global placeholders, and various system-wide features.

***

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

### <mark style="color:yellow;">status</mark>

**Type:** String

Sets the bot's online status indicator.

**Available Options:**

* `"online"` - Green status (online)
* `"dnd"` - Red status (Do Not Disturb)
* `"idle"` - Yellow status (idle/away)
* `"offline"` - Gray status (invisible)

```json
status: "online"
```

***

### <mark style="color:yellow;">activity\_type</mark>

**Type:** String

Defines the type of activity displayed in the bot's status.

**Available Options:**

* `"playing"` - Displays as "Playing ..."
* `"watching"` - Displays as "Watching ..."
* `"listening"` - Displays as "Listening to ..."
* `"competing"` - Displays as "Competing in ..."
* `"streaming"` - Displays as "Streaming ..."

```json
activity_type: "playing"
```

***

### <mark style="color:yellow;">activity</mark>

**Type:** Array of Strings

The text displayed in the bot's status. If multiple activities are provided, the bot will randomly cycle through them every 30 seconds.

**Available Placeholders:**

* `%members%` - Total server member count
* `%tickets_open%` - Number of currently open tickets
* `%tickets_closed%` - Number of closed tickets
* `%mc_online%` - Online players on Minecraft server (requires Minecraft addon)
* `%mc_max%` - Maximum players on Minecraft server (requires Minecraft addon)

**Examples:**

```json
// Single activity
activity: ["/help"]

// Multiple activities (rotates every 30 seconds)
activity: ["with %members% members", "/help", "Watching %tickets_open% tickets"]

// Minecraft server status
activity: ["MC: %mc_online%/%mc_max% players"]
```

***

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

### <mark style="color:yellow;">enabled</mark>

**Type:** Boolean

Enables or disables the command cooldown system globally.

```json
cooldown: {
    enabled: true,  // Cooldowns are active
}
```

**When `true`:** Users must wait between command uses\
**When `false`:** All cooldowns are disabled (not recommended)

***

### <mark style="color:yellow;">cooldown\_length</mark>

**Type:** Number (seconds)

The default cooldown duration in seconds that applies to all commands unless a custom cooldown is set.

```json
cooldown_length: 4
```

This means users must wait 4 seconds between using commands (by default).

***

### <mark style="color:yellow;">role\_bypass</mark>

**Type:** Object

Allows specific roles to bypass all command cooldowns.

```json
role_bypass: {
    enabled: true,
    role_id: "804354015638716443",
}
```

**enabled** - Whether role bypass is active\
**role\_id** - Discord role ID that can bypass cooldowns

**How it works:**

* Users with this role (or any role higher in the Discord role hierarchy) can use commands without waiting
* Useful for staff/moderator roles

{% hint style="info" %}
**Tip:** To get a role ID, enable Developer Mode in Discord, right-click the role in Server Settings → Roles, and click "Copy ID".
{% endhint %}

***

### <mark style="color:yellow;">custom\_command\_cooldowns</mark>

**Type:** Object

Allows you to set specific cooldown durations for individual commands, overriding the default cooldown.

```json
custom_command_cooldowns: {
    enabled: true,
    commands: {
        "restart": 60,
        "backup": 300,
        "giveaway": 30,
    },
}
```

**enabled** - Whether custom cooldowns are active\
**commands** - Object mapping command names to cooldown lengths (in seconds)

**Example:**

* `"restart": 60` means the restart command has a 60-second cooldown
* Commands not listed use the default `cooldown_length`

***

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

**Type:** Array of Objects

Create custom placeholders that can be used throughout all message configurations in any plugin.

```json
global_placeholders: [
    {
        placeholder: '%website%',
        value: 'https://example.com',
    },
    {
        placeholder: '%discord%',
        value: 'https://discord.gg/your-invite',
    },
]
```

**How it works:**

* Define a placeholder name (e.g., `%website%`)
* Set its value (what it should be replaced with)
* Use the placeholder anywhere in embed messages, descriptions, etc.

**Usage Example:**

If you define `%website%` as shown above, you can use it in any message configuration:

```json
description: "Visit our website at %website%"
// Will display as: "Visit our website at https://example.com"
```

{% hint style="success" %}
**Use Case:** Global placeholders are perfect for server-specific information like website URLs, Discord invites, social media links, or server rules that you reference frequently across different messages.
{% endhint %}

***

## <mark style="color:blue;">Permission-Based Help Page</mark>

**Type:** Boolean

When enabled, the `/help` command shows only commands that the user has permission to execute.

```json
permission_based_help_page: false
```

**When `true`:**

* Users see only commands they can use
* Cleaner help menu for regular members
* Staff see all commands they have access to

**When `false`:**

* All users see all commands
* Users may see commands they cannot execute
* More comprehensive overview

{% hint style="info" %}
**Recommendation:** Set to `true` if you want to avoid confusing users with commands they can't access. Set to `false` if you want all users to see the full command list for transparency.
{% endhint %}

***

## <mark style="color:blue;">Commands Blacklisted Channels</mark>

**Type:** Array of Strings

List of channel IDs where **no commands** can be executed

```json
commands_blacklisted_channels: [
    "123456789012345678",
    "234567890123456789",
]
```

**How it works:**

* Commands used in these channels will be ignored
* Useful for keeping certain channels clean

***

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

**Type:** Object

Configures requirements for voice channel time to count toward calltime statistics (used in leveling, economy, etc.).

```json
calltime_requirement_users: {
    enabled: true,
    minimum_users: 2,
    bots_included: false,
}
```

### <mark style="color:yellow;">enabled</mark>

Whether calltime requirements are enforced.

**When `true`:** Calltime only counts if requirements are met\
**When `false`:** Calltime always counts regardless of who's in the channel

***

### <mark style="color:yellow;">minimum\_users</mark>

**Type:** Number

Minimum number of users required in a voice channel for calltime to count.

```json
minimum_users: 2
```

**Example:** With `minimum_users: 2`, a user sitting alone in a voice channel won't earn calltime rewards. Once a second person joins, both start earning calltime.

**Purpose:** Prevents users from AFK farming calltime rewards in empty voice channels.

***

### <mark style="color:yellow;">bots\_included</mark>

**Type:** Boolean

Whether bots count toward the minimum user requirement.

```json
bots_included: false
```

**When `false`:** Bots don't count - only real users\
**When `true`:** Bots count toward the minimum

**Example:** If `minimum_users: 2` and `bots_included: false`:

* 1 user + 1 bot = calltime does NOT count
* 2 users + 0 bots = calltime counts
* 2 users + 1 bot = calltime counts

{% hint style="warning" %}
**Recommended:** Keep `bots_included: false` to prevent users from sitting in voice channels with music bots to farm rewards.
{% endhint %}

***

## <mark style="color:blue;">Pastebin API Key</mark>

**Type:** String

API key for Pastebin integration, used by the `/pastebin` command to upload text content.

```json
pastebin_api_key: ""
```

**How to get an API key:**

1. Go to <https://pastebin.com/doc\\_api>
2. Create a Pastebin account (if you don't have one)
3. Generate your API key
4. Paste the key in this configuration

**When configured:**

* The `/pastebin` command can upload content to Pastebin
* Useful for sharing logs, error messages, or large text content

**When left empty:**

* The `/pastebin` command may not function or will have limited functionality

***

## <mark style="color:blue;">Complete Configuration Example</mark>

Here's a complete, production-ready core configuration:

```json
{
    config: {
        activity: {
            status: "online",
            activity_type: "playing",
            activity: ["with %members% members", "/help", "%tickets_open% tickets open"]
        },

        cooldown: {
            enabled: true,
            cooldown_length: 4,

            role_bypass: {
                enabled: true,
                role_id: "804354015638716443",
            },

            custom_command_cooldowns: {
                enabled: true,
                commands: {
                    "restart": 60,
                    "backup": 300,
                    "giveaway": 30,
                },
            },
        },

        global_placeholders: [
            {
                placeholder: '%website%',
                value: 'https://yourserver.com',
            },
            {
                placeholder: '%discord%',
                value: 'https://discord.gg/yourinvite',
            },
            {
                placeholder: '%rules%',
                value: 'https://yourserver.com/rules',
            },
        ],

        permission_based_help_page: true,

        commands_blacklisted_channels: [
            "123456789012345678",  // #announcements
            "234567890123456789",  // #rules
        ],

        calltime_requirement_users: {
            enabled: true,
            minimum_users: 2,
            bots_included: false,
        },

        pastebin_api_key: "your_api_key_here",
    },
}
```