> For the complete documentation index, see [llms.txt](https://organized-chaos.gitbook.io/organized-chaos-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://organized-chaos.gitbook.io/organized-chaos-docs/chess/discord-logging.md).

# Discord logging

A staff log of games, stakes and admin actions in a Discord channel.

Chess can post what happens at its tables to a Discord channel of your staff: games starting and ending, stakes and pots, and tables put up or taken away. It is off until you switch it on.

`Config.Discord` is in `config_server.lua`, next to `config.lua`.

```lua
Config.Discord = {
    Enabled = false,
    Webhook = '',        -- better: set the chess_discord_webhook convar
    Username = '',
    AvatarUrl = '',
    Events = {
        Start = true, GameStart = true, GameEnd = true,
        Money = true, Admin = true, Seats = false,
    },
    Identifiers = false,
    FlushMs = 3000,
    MaxQueue = 100,
}
```

## Switching it on

1. In Discord, open the settings of the channel the log should go to, then **Integrations**, **Webhooks** and **New Webhook**, and copy the webhook URL.
2. Put the URL in your `server.cfg`, as shown below.
3. Set `Enabled = true` in `config_server.lua`.
4. Restart the server so the new line in `server.cfg` is read.

```cfg
set chess_discord_webhook "https://discord.com/api/webhooks/..."
```

{% hint style="danger" %}
The webhook URL is a secret. Anyone who has it can post to your channel.
{% endhint %}

`config.lua` is sent to every player. `config_server.lua` is loaded on the server only, so the URL is safe there or in the convar, and must never go into `config.lua`. The resource does not print it either, not even in an error message.

## What is posted

Only events set to `true` in `Events` are posted.

| Event       | What the post says                                                                                                                                                   | Default |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `Start`     | The resource has started: how many tables there are, the stake, and whether ratings are kept                                                                         | `true`  |
| `GameStart` | A game began: the table, both players with their colour, the pot                                                                                                     | `true`  |
| `GameEnd`   | A game ended: who won and how, the number of moves, the pot, and how the ratings moved                                                                               | `true`  |
| `Money`     | Stakes taken when a game starts, the pot paid to the winner, stakes given back after a draw, and winnings kept for a player who was gone and paid when they are back | `true`  |
| `Admin`     | A table put up or taken away with the admin commands, by whom and where                                                                                              | `true`  |
| `Seats`     | Sitting down, standing up, lost connections and returns. This is a lot of messages                                                                                   | `false` |

Every post names the table and where it stands, so you can find it on the map. Players are named with the name they play under and their server id. A computer opponent is marked as such.

## Who the players are

`Identifiers = true` adds every player's licence and their Discord account, as a mention, under the name.

{% hint style="warning" %}
Licences and Discord accounts are personal data. Turn `Identifiers` on only for a channel that just your staff can read, and only if your policy allows it.
{% endhint %}

## Delivery

| Option      | Default | Meaning                                                         |
| ----------- | ------- | --------------------------------------------------------------- |
| `Username`  | `''`    | The name the posts appear under. Empty uses the webhook's own   |
| `AvatarUrl` | `''`    | The picture the posts appear with. Empty uses the webhook's own |
| `FlushMs`   | `3000`  | How often the collected messages are posted, in milliseconds    |
| `MaxQueue`  | `100`   | How many messages wait at most while Discord cannot be reached  |

Messages are not sent one by one. They are collected and posted together, up to ten in one post, so a busy evening stays well inside Discord's rate limit. If Discord cannot be reached, the messages wait and are sent later. When more than `MaxQueue` are waiting, the oldest are dropped, and the next post says how many were lost. A problem with Discord never holds up a game.

## Keeping it through an update

An update replaces `config_server.lua` together with the rest of the folder. Keep a copy of it along with `config.lua`, or keep the URL in the convar, which an update does not touch.