# Bot Settings

## 🔧 Custom Discord Bot Presence

The `bot-settings` section in the `config.yml` allows you to customize the **activity** and **online status** of the Discord bot managed by the plugin.

This feature supports **PlaceholderAPI placeholders**, enabling dynamic values such as total player count across servers (e.g. `%bungee_total%`).

⚠️ Multi-Server Support Notice

If you run this plugin on **multiple Minecraft servers (multi-server setup)** with the same Discord bot token, you **must enable `bot-settings.enabled: true` on only ONE server**.\
Having this enabled on more than one server **may result in duplicate status updates or Discord rate-limiting**.

## 📁 Configuration

Add or edit the following section in your `config.yml`:

```yaml
discord:
  token: "your-discord-bot-token"
  guild-id: "your-guild-id"

  bot-settings:
    # ⚠️ ENABLE WITH CAUTION!
    # Only one server should manage bot presence if you're running multiple servers.
    enabled: true

    # The text to display as the bot's activity.
    # PlaceholderAPI placeholders (e.g. %bungee_total%) are supported.
    activity: "Playing with %bungee_total% players"

    # The type of activity:
    # Options: PLAYING, WATCHING, LISTENING, COMPETING
    activity-type: "PLAYING"

    # The bot's online status:
    # Options: ONLINE, IDLE, DND, INVISIBLE
    status: "ONLINE"

  change-nickname: true
  restrict-to-channel: true
  target-channel-id: "your-channel-id"
```

## 🔁 Live Updating with Placeholders

If `activity` contains **PlaceholderAPI placeholders**, they are parsed automatically using your installed placeholder expansions.

#### 🔄 Refresh Frequency:

* The activity text is refreshed:
  * **60 ticks** after startup (3 seconds)
  * **every 3 minutes** afterwards (asynchronously)
* No update is sent unless the placeholder-resolved text has changed, avoiding unnecessary API calls.

## 🔍 Example Output

If you use the following:

```yaml
activity: "Playing with %bungee_total% players"
activity-type: "PLAYING"
status: "ONLINE"
```

Your bot will display:

> **Playing with 124 players**

And its status will appear as **Online**.


---

# 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.mongenscave.com/premium-products/discordlink/feature-help/bot-settings.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.