# Bot Presences

A bot presence allows you to show a more detailed online status. Mix that with a timer, and you have a periodically updating bot status!

## Examples

![Playing / Default](https://2905471890-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MWJ0CGscN1zQsA_eF9d%2F-MWwjaMC_S_IZP1ucYf9%2F-MWxxEhN5wcflSkYoclN%2Fimage.png?alt=media\&token=522c9854-e44f-4e9f-888a-0ceb1f409b74)

![Watching](https://2905471890-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MWJ0CGscN1zQsA_eF9d%2F-MWwjaMC_S_IZP1ucYf9%2F-MWxxAVNPIePJBPKM9Xq%2Fimage.png?alt=media\&token=0f22c4a5-8667-4313-8fb1-4294c0a2a0f0)

![Listening](https://2905471890-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MWJ0CGscN1zQsA_eF9d%2F-MWwjaMC_S_IZP1ucYf9%2F-MWxx6W-X0m7Zr-lQhu_%2Fimage.png?alt=media\&token=37d2823d-955f-44e5-8f29-1742510a4d41)

![Streaming](https://2905471890-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MWJ0CGscN1zQsA_eF9d%2F-MWwjaMC_S_IZP1ucYf9%2F-MWxxK6FbdS1kySTXmkZ%2Fimage.png?alt=media\&token=b5e00c15-2f08-425d-aff5-13f0a6b59ac2)

{% tabs %}
{% tab title="Example #1" %}
{% code title="config/chatter/discord/theme.json5" %}

```javascript
{
	// ...

	// Bot presences relayed periodically
	"presence": {
		// The number of seconds between presence updates (must be >=15)
		"interval": 60,
		// True if the presences should be randomly selected
		"random": false,
		// Presences
		"entries": [
			{
				// The type of presence (see https://git.io/Jqkez)
				"type": "DEFAULT",
				// The text value that is put on display
				"value": "Minecraft",
				// If defined, sets the URL of the underlying media, e.g. Twitch stream
				"url": null
			},
			{
				// The type of presence (see https://git.io/Jqkez)
				"type": "STREAMING",
				// The text value that is put on display
				"value": "Xisumavoid",
				// If defined, sets the URL of the underlying media, e.g. Twitch stream
				"url": "https://www.twitch.tv/xisumavoid"
			},
			{
				// The type of presence (see https://git.io/Jqkez)
				"type": "LISTENING",
				// The text value that is put on display
				"value": "${tps} TPS",
				// If defined, sets the URL of the underlying media, e.g. Twitch stream
				"url": null
			},
			{
				// The type of presence (see https://git.io/Jqkez)
				"type": "WATCHING",
				// The text value that is put on display
				"value": "${player_count} player",
				// If defined, sets the URL of the underlying media, e.g. Twitch stream
				"url": null
			}
		]
	},

	// ...
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Configuration

{% hint style="success" %}
Made changes to the configuration? Type **`/reload`** to apply the changes immediately!
{% endhint %}

### Update Interval

The number of seconds between presence updates.

{% hint style="danger" %}
A presence update interval shorter than **15 seconds** will lead to rate limits!
{% endhint %}

{% code title="config/chatter/discord/theme.json5" %}

```javascript
{
	// ...
	"presence": {
		// The number of seconds between presence updates (must be >=15)
		"interval": 30,
	}
}
```

{% endcode %}

### Choose Randomly

By default, the presence entries are chosen on a round-robin basis, however, this can be changed to a random selection here.

{% tabs %}
{% tab title="Random" %}
{% code title="config/chatter/discord/theme.json5" %}

```javascript
{
	// ...
	"presence": {
		// True if the presences should be randomly selected
		"random": true,
	}
}
```

{% endcode %}
{% endtab %}

{% tab title="In-Order" %}
{% code title="config/chatter/discord/theme.json5" %}

```javascript
{
	// ...
	"presence": {
		// True if the presences should be randomly selected
		"random": false,
	}
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Presence Entries

A list of presences to be conveyed throughout the lifecycle of the bot.

{% code title="config/chatter/discord/theme.json5" %}

```javascript
{
	// ...
	"presence": {
		// Presences
		"entries": [
			// Add presence entries here
		]
	}
	// ...
}
```

{% endcode %}

#### Type

The type of presence status to be shown.

You can choose from the following types: `DEFAULT`, `STREAMING`, `LISTENING`, and `WATCHING`.

```javascript
// The type of presence (see https://git.io/Jqkez)
"type": "DEFAULT",
```

#### Value

The text value that is put on display.

{% hint style="info" %}
Please refer to the [templating guide](https://axieum.gitbook.io/chatter-for-minecraft/misc/templating) for instructions on substituting player names, etc.
{% endhint %}

| Token                  | Type     | Meaning                                     | Example            |
| ---------------------- | -------- | ------------------------------------------- | ------------------ |
| `${version}`           | String   | The Minecraft server version                | 1.16.5             |
| `${ip}`                | String   | The server's IP address (possibly empty)    | 192.168.1.90       |
| `${port}`              | Integer  | The bound server's port                     | 25565              |
| `${motd}`              | String   | The message of the day (MOTD)               | A Minecraft Server |
| `${difficulty}`        | String   | The world difficulty                        | easy               |
| `${max_players}`       | Integer  | The maximum number of players allowed       | 20                 |
| `${player_count}`      | Integer  | The number of currently logged-in players   | 2                  |
| `${tps}`               | Double   | Average ticks per second (TPS)              | 20.00              |
| `${tps_time}`          | Double   | Average ticks per second (TPS) timing in ms | 12.513             |
| `${uptime[:format]}`   | Duration | For how long the server has been online     | 1 day 5 minutes    |
| `${datetime[:format]}` | DateTime | The current date & time                     | 01/01/2004         |

```javascript
/**
 * The text value that is put on display
 * Use ${version}, ${ip}, ${port}, ${motd}, ${difficulty}, ${max_players}, ${player_count}, ${tps}, ${tps_time}, ${uptime} and ${datetime[:format]}
 */
"value": "Minecraft ${version}",
```

#### Media URL

If defined, sets the URL of the underlying media, e.g. Twitch stream. This is used in conjunction with the `STREAMING` [presence type](#type).

```javascript
// If defined, sets the URL of the underlying media, e.g. Twitch stream
"url": "https://www.twitch.tv/xisumavoid",
```