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


---

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