# The swear filter

> Swear words become ducks and potatoes, points for each lead to a friendly warning and then to mutes that grow, slurs and threats are never shown - with your own lists, an API, events and a signed webhook. New in 0.4, off by default.

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

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

## What players see

A swear word in chat turns into something harmless and silly - `duck`, `potato`, `pickle`, `llama` in English, `kachna`, `bramborák`, `okurka`, `knedlík` in Czech. *"this is fucking great"* reads *"this is waffle great"*. Capitals stay: `SHIT` becomes `PANCAKE`. The rest of the line is untouched.

The same happens:

- across the **Discord bridge**, both ways (`where.discord`); a slur typed on Discord is not brought into the game at all;
- on **signs and in books** (`where.signs-and-books`): a sign with a swear word is not written and the player is told why.

What the player typed is never rewritten. The words are swapped where the line is drawn, per reader - so a server can let its staff read the original (`original = staff` and the permission `keystone.filter.original`). The default is `nobody`: everybody reads the replacements. This is the server's choice, never the player's.

## Points, a warning, mutes

| What happens | Default | Setting |
|---|---|---|
| Points for each caught word | 1, at most 3 per line | `points.per-word`, `points.most-per-line` |
| Points run off while calm | 1 every 10 minutes | `points.decay-by`, `points.decay-every` |
| A private, friendly warning | at 3 points (once per climb) | `points.warn-at` |
| A mute | at 5 points, then points start again | `points.mute-at` |
| Each further filter mute within the window is longer | 5, 15, 60 minutes | `mute.lengths`, `mute.window` (24h) |
| The team gets a ticket | at the 3rd filter mute in the window | `ticket-after` |

A muted player sees why and for how long, like any `/mute`, and the mute covers private messages, `/me`, signs, books and their linked Discord account's lines into the game.

**Slurs and threats** (the severe lists) skip the points: the line is **not shown at all**, the writer is muted straight away (`severe.mute`, 60 minutes, or longer if the ladder says so), and the team gets a record: the editor's *Moderation* screen, `GET /v1/moderation/caught`, the webhook and, if you set `alert-channel`, a Discord post. Only for severe lines is the text kept (`keep-text`); ordinary swearing is never stored.

Whoever has `keystone.filter.exempt` collects no points (their words are still replaced).

## The lists

The jar carries lists for English (`en`) and Czech and Slovak (`cs`); `languages` picks which are used, and every list is checked against every line. `built-in = false` uses only yours.

| Setting | What |
|---|---|
| `words.mild` | your own swear words: replaced and counted |
| `words.severe` | your own words that are never shown |
| `words.allowed` | words never caught although an entry matches them |
| `funny.en`, `funny.cs` | what caught words become; empty = the built-in ones |

How an entry is written decides how much it catches - this is what keeps *Scunthorpe*, *assassin*, *kokos* or *sranda* out of trouble:

- `word` - the whole word only (`cunt` never catches *Scunthorpe*);
- `stem*` - a word starting with it (`kurv*` catches *kurvy*, *kurvou*);
- `*part*` - anywhere inside a word, for the few stems nothing innocent contains (`*fuck*` catches *motherfucker*);
- `two words` - in a row (`kill yourself`);
- `word=replacement` - picks what it becomes.

Before matching, the filter undoes the usual tricks: accents (`kůrvá`), look-alike letters from other alphabets (a Cyrillic `к` - the same folding `/nick` uses), fullwidth and styled letters, l33t (`sh1t`, `a$$`), a `*` for a letter (`f*ck`), doubled letters (`fuuuck`), letters spaced or dotted apart (`k u r v a`, `f.u.c.k`) and a word split in two (`kur va`).

`/keystone filter test <line>` (and the box on the *Moderation* screen) tries a line without saying or counting anything. `/keystone filter points <player>` and `/keystone filter clear <player>` show and clear points (permission `keystone.filter`).

## Chat formats and other mods

To change a line per reader, Keystone writes chat lines itself while the filter is on - in your format, or the default one when `chat.format.enabled` is off. If another mod formats chat and `chat.step-aside` is on, Keystone steps aside and the filter cannot replace words (the console says so once); turn `chat.step-aside` off to let Keystone write chat.

## For your own tools

Nothing in the filter knows about any particular server. Everything it decides is told:

- **Events** for mods: `SwearCaught` (who, where, how bad, what it led to), `MuteRequested` / `MuteLiftRequested` (ask for a mute or lift one; the moderation module answers), and `PlayerPunished` with the source `filter` for each filter mute.
- **API** (keys with `moderation.read` / `moderation.write`): `GET /v1/moderation/mutes`, `GET /v1/moderation/history?player=`, `POST /v1/moderation/mute` (`player`, `for`, `reason`), `POST /v1/moderation/unmute`, `GET /v1/moderation/points`, `GET /v1/moderation/caught`, `POST /v1/moderation/points/clear`, `GET /v1/moderation/words`, `POST /v1/moderation/check`.
- **Webhook** (`moderation.toml`): `webhook.url` (https outside your network; `webhook.allow-local` for a bot on the same machine), `webhook.secret`, `webhook.events` (warn, mute, unmute, ban, unban, kick, swear). Each POST is JSON with `X-Keystone-Timestamp` (seconds) and `X-Keystone-Signature: sha256=<hex HMAC-SHA256 of "<timestamp>.<body>" with the secret>`; recompute it and refuse old timestamps. A `swear` event carries the text only for severe lines.

## Mutes and Discord timeouts

In `discord.toml`, like bans: `mute.game-to-discord` times a linked player out on Discord for as long as the game mute (Discord allows 28 days; a longer mute or one with no end also gets the role `mute.role`), `mute.discord-to-game` mutes the linked player when they are timed out on Discord. Lifting either lifts both, and it is one row in the moderation ledger. Both are off by default; the bot needs the **Moderate Members** permission and a role above the people it times out.

## Privacy

The filter reads chat, Discord bridge lines, signs and books on your server only; nothing is sent anywhere unless you set the webhook or the alert channel. The text of severe lines is kept in `keystone.db` while `keep-text` is on.
