Core

Introduction

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.

Bot Activity

status

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)

status: "online"

activity_type

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 ..."

activity_type: "playing"

activity

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:

// 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"]

Command Cooldowns

enabled

Type: Boolean

Enables or disables the command cooldown system globally.

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

When true: Users must wait between command uses

When false: All cooldowns are disabled (not recommended)

cooldown_length

Type: Number (seconds)

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

cooldown_length: 4

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

role_bypass

Type: Object

Allows specific roles to bypass all command cooldowns.

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

Tip: To get a role ID, enable Developer Mode in Discord, right-click the role in Server Settings → Roles, and click "Copy ID".

custom_command_cooldowns

Type: Object

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

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

Global Placeholders

Type: Array of Objects

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

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:

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

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.

Permission-Based Help Page

Type: Boolean

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

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

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.

Commands Blacklisted Channels

Type: Array of Strings

List of channel IDs where no commands can be executed

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

How it works:

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

Calltime Requirements

Type: Object

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

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

enabled

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

minimum_users

Type: Number

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

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.

bots_included

Type: Boolean

Whether bots count toward the minimum user requirement.

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

Recommended: Keep bots_included: false to prevent users from sitting in voice channels with music bots to farm rewards.

Pastebin API Key

Type: String

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

pastebin_api_key: ""

How to get an API key:

Go to https://pastebin.com/doc\\_api
Create a Pastebin account (if you don't have one)
Generate your API key
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

Complete Configuration Example

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

{
    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",
    },
}

Core

On this page