Antispam & moderation

Three layers run server-side on every outbound message, in this order:

Rate limit (per-player rolling window).
Duplicate detection (same message twice within a short window).
Blocked-word filter (normalised substring match, leet-aware).

A fourth layer - the profanity escalation ladder - sits on top of the blocked-word filter and tracks repeat offenders. All four are configured in config.lua under the antispam and profanityEscalation blocks. The defaults are reasonable for a roleplay server; the rest of this page covers the tuning knobs.

Rate limit + duplicate detection

config.lua

antispam = {
    enabled           = true,
    maxMessages       = 6,       -- per windowMs
    windowMs          = 5000,    -- rolling 5-second window
    duplicateWindowMs = 4000,    -- "same text twice in 4s" guard
    minLength         = 1,       -- empty messages dropped
    maxLength         = 220,     -- hard cap (also enforced client-side)
    bypassPermission  = 'awoken_chat.bypass',
},

Key	Default	What it does
`enabled`	`true`	Master switch. `false` disables the rate-limit and duplicate checks (NOT the blocked-word filter - that has its own gate).
`maxMessages`	`6`	Max messages a player can send within `windowMs` before the next message is dropped with a `ratelimited` notify.
`windowMs`	`5000`	Rolling window for the rate limit, in milliseconds.
`duplicateWindowMs`	`4000`	If a player sends the exact same text twice within this window, the second send is dropped. Set to `0` to disable.
`minLength`	`1`	Minimum message length. Empty / whitespace-only sends are dropped silently.
`maxLength`	`220`	Hard cap. Messages longer than this are dropped. The client-side counter shows this limit.
`bypassPermission`	`'awoken_chat.bypass'`	ACE permission that exempts a player from antispam (and the blocked-word filter).

Per-channel exemption

Some channels - typically /me - benefit from repeated text. Players legitimately type “*sighs*”, “*nods*”, “*looks around*” in quick succession, and the duplicate detection would flag them as flood. Tick Bypass antispam in the Category Manager for that channel. The flag stores as bypassAntispam = true on the category row. When set:

Rate limit + duplicate checks are skipped for messages in that channel.
Length cap still applies (structural safety, not behavioural).
Blocked-word filter still applies (slurs are slurs regardless of channel).
Profanity escalation still applies on blocked-word hits.

See Categories for the full per-channel flag reference.

Blocked-word filter

Substring-matched against a normalised version of the message, so common evasion tricks (leet, spacing, padding) collapse to the same canonical form as the bare word.

config.lua

antispam = {
    -- ...
    blockedWords = {
        -- ...80+ entries...
    },
},

Normalisation pipeline

Both the message body and each blocked-word entry are normalised the same way before comparison:

Lowercased - "SLUR" → "slur"
Leet substitutions - 1→i, 3→e, 4→a, 5→s, 7→t, 8→b, 9→g, @→a, $→s, !→i, |→i, +→t, 0→o, 2→z, 6→g. "61ur" → "slur".
Strip non-letters - punctuation, spaces, digits not in the leet map. "s l u r" → "slur". "s.l.u.r" → "slur".
Collapse runs - (.)\1+ → \1. Any run of 2+ identical letters collapses to one. "slurrrr" → "slu". The blocked-word list is normalised the same way, so 'slur' becomes 'slu' too and the haystack "slu..." contains the needle "slu". Match.

The collapse-to-one rule has one known false positive: the country / place name “Niger” (single g) normalises to the same canonical form as the slur. If your server can’t accept that collision, remove the slur from blockedWords and live with the evasion gap.

Customising the list

Add or remove entries freely. The shipped list is intentionally conservative - a handful of very short / ambiguous terms (e.g. 'gay', 'fag' outside 'faggot', 'fat', 'ass', 'rape') are deliberately omitted because they collide with legitimate English words at substring level. Add them yourself if you want stricter matching and accept the false positives.

blockedWords = {
    -- shipped list…
    'yournewword',
    'anotherone',
},

Profanity escalation

Counts blocked-word hits per-license and runs an action when the count crosses a rung.

config.lua

profanityEscalation = {
    enabled       = true,
    resetAfterMs  = 3600000,   -- 1 hour of clean behaviour resets the counter
    rungs = {
        { hits = 1, action = 'warn' },
        { hits = 3, action = 'mute', durationMs = 60000 },
        { hits = 6, action = 'kick' },
    },
},

How the ladder works

A player trips the blocked-word filter → counter increments → highest matching rung fires.
Counter is per-license, persists across reconnects within the session.
Counter resets to zero after resetAfterMs of clean behaviour (no blocked-word hits). Default: 1 hour.
Players with awoken_chat.bypass ACE never increment the counter.

Rung actions

Action	What happens
`warn`	Yellow system toast: `"Warning: this is offense #N. Continued offenses will be muted or kicked."`
`mute`	Player can’t send chat for `durationMs`. Tries to send → red toast: `"You've been muted for N seconds for repeated offenses."`
`kick`	`DropPlayer(source, 'Removed from chat for repeated offenses.')`

The shipped ladder (warn → mute(60s) → kick at 6 hits) is intentionally gentle for first-offence cases. Tune the hits thresholds, durationMs, and resetAfterMs to match your server’s culture.

Customising the ladder

Rungs are evaluated bottom-to-top - the highest rung whose hits threshold is matched fires. So you can add intermediate steps:

rungs = {
    { hits = 1,  action = 'warn' },
    { hits = 3,  action = 'mute', durationMs = 60000 },     -- 1 minute
    { hits = 5,  action = 'mute', durationMs = 300000 },    -- 5 minutes
    { hits = 8,  action = 'kick' },
    -- Combine with a Discord webhook + your ban resource for permaban at hit 12
},

Bypass permission

add_ace group.admin awoken_chat.bypass allow

awoken_chat.bypass is the only ACE that’s NOT implied by awoken_chat.admin. Granting “admin” alone gives Category Manager access + admin-delete + clear, but does NOT skip the blocked-word filter. Bypass is intentional, opt-in only.

A player with bypass:

Never trips the rate limit / duplicate / blocked-word filter.
Doesn’t increment the profanity escalation counter.
Can send the exact same message back-to-back without throttling.

Reserve for trusted staff who need to discuss moderation cases (“the player said X, here’s what they typed verbatim”) without their own messages getting filtered.

Audit trail

Every blocked-word hit, rate-limit hit, and duplicate flood posts a Discord embed to webhooks.violations if configured. See Webhooks for the embed shape and what’s included.

Get Started

Awoken Scripts

Antispam & moderation

Rate limit + duplicate detection

Per-channel exemption

Blocked-word filter

Normalisation pipeline

Customising the list

Profanity escalation

How the ladder works

Rung actions

Customising the ladder

Bypass permission

Audit trail

​Rate limit + duplicate detection

​Per-channel exemption

​Blocked-word filter

​Normalisation pipeline

​Customising the list

​Profanity escalation

​How the ladder works

​Rung actions

​Customising the ladder

​Bypass permission

​Audit trail

Rate limit + duplicate detection

Per-channel exemption

Blocked-word filter

Normalisation pipeline

Customising the list

Profanity escalation

How the ladder works

Rung actions

Customising the ladder

Bypass permission

Audit trail