# Polls in chat and on Discord

> Staff ask a question with /poll create in the game or /poll on Discord; everybody answers with a button, in the game or on Discord, and a linked player votes once. New in 0.4, off by default.

Source: https://stygion.eu/docs/keystone/polls
Updated: 2026-11-16

The module `polls`, new in Keystone 0.4. It is off until you set `enabled = true` in `config/keystone/polls.toml` (or in **Settings**) and restart the server - a module's `enabled` is read once, when the server starts.

## Asking

In the game (permission `keystone.polls.create`):

```
/poll create 2h "Asphalt or concrete at spawn?" "Asphalt" "Concrete"
/poll create 1d Asphalt or concrete at spawn? | Asphalt | Concrete
```

Two to six answers; the length is optional (`default-length`, a day; `0` keeps it open until staff close it; never longer than `longest`, 30 days). At most `most-open` (5) polls run at once. `/poll close <id>` ends one early.

On Discord, the bot's `/poll` takes a question, two to six answers and an optional length (`discord-command`, on). It is offered to the Discord roles in `discord-creators` and to anybody whose Discord is linked to a player holding `keystone.polls.create` - nobody else, because an unlinked name proves nothing.

## Answering

- **In the game** everybody online gets the question with a button per answer and its share so far; with Keystone's client half it is a notice card with a POLL plate. `/poll` lists what is open, `/poll vote <id> <n>` votes by typing (permission `keystone.polls`, which the default group has).
- **On Discord** a card with buttons goes to `discord-channel` (`events` by default - the Discord module's events room; `chat`, a channel id, or empty to keep polls in the game).
- **One count for both.** A player whose Discord is linked votes once, in the game or on Discord, and a vote cast before linking is folded in.
- `change-vote` (on): a vote can be changed while the poll is open. `who-votes = linked` lets only people with a linked Discord vote (`everyone` by default).
- `remind-on-join` (on): somebody joining while a poll is open and who has not voted is shown it.

When it ends (its time, or `/poll close`) the result goes to the game and, with `result-post` (on), to Discord as a new card; the old card loses its buttons either way. Discord's own polls are not used: a bot cannot vote in them on a player's behalf.

## Settings

| Setting | Default | What it does |
|---|---|---|
| `enabled` | false | the whole module; needs a restart |
| `discord-channel` | `events` | where the card with buttons goes: a channel id, `chat` or `events`; empty keeps polls in the game |
| `default-length` | `1d` | length when `/poll create` names none; `0` = until closed |
| `longest` | `30d` | the longest a poll may stay open |
| `most-open` | 5 | polls open at once |
| `who-votes` | `everyone` | `everyone` or `linked` |
| `change-vote` | true | votes may be changed while open |
| `remind-on-join` | true | show an open poll to a player who has not voted |
| `result-post` | true | a result card on Discord when a poll closes |
| `discord-command` | true | offer `/poll` on Discord |
| `discord-creators` | empty | Discord role ids that may ask with `/poll` |
| `name`, `discord-colour` | empty, `#5865F2` | the name on the card's plate (empty: the server's name) and the Discord card's colour |

## For your own tools

`GET /v1/polls` (scope `polls.read`); `POST /v1/polls/create`, `/v1/polls/close` and `/v1/polls/vote` (scope `polls.write`) - a vote for a player or a Discord id, from your own site or bot. Every change is the `PollChanged` event.

## What it keeps

Polls and votes live in the server's own `keystone.db`. Nothing leaves the server except the cards on your own Discord, and only when `discord-channel` is set.
