STYGION Documentation Search the docs

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.

Keystone 0.5.0 Updated 5 min read
On this page 7 parts
  1. What players see
  2. Points, a warning, mutes
  3. The lists
  4. Chat formats and other mods
  5. For your own tools
  6. Mutes and Discord timeouts
  7. Privacy

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.

Did this page help?

Opens the feedback panel with this page attached. It lands in the same queue as everything else.