In depth Word & Phrase Filter block list setup

Introduction

The intelligent word and phrase filter module blocks swears or other configured words / phrases (and words/phrases similar to those on the blacklist) from being said in chat and commands. It is one of the more complex modules to configure well, but this guide is here to help!

Skip the setup

There are preset word lists available, already configured with necessary modifiers. Click here to view them.

The keys to a good filter

It's important to understand that the filter can only work well if it's configured well. Your configuration can either make or break the filter. Please take careful note of this guide when creating your own configuration so you can make the most of ChatSentry's WAPF abilities.

Block lists should be as concise as possible

The more specific and tuned the block list is, the more accurate it will be. You generally should avoid going over a few hundred entries, but it depends on the context in which you're using the filter in. The more entries, the more potential false positives the filter will be susceptible to.

Blocking words should take precedence over phrases

Though the filter supports blocking entire phrases, the majority of the time you should block singular words when possible instead. When blocking phrases, it's best to keep them as short as possible, preferably 2-4 words. You should only block entire phrases that are very common to be said very similarly to how they're added to the block list.
Use entry modifiers where applicable
One of the core components that lets the filter work well is entry modifiers. Entry modifiers allow you to fine tune the filter on an entry to entry basis. They let you limit how strict or lenient particular entries should be, and are incredibly important to use. Their importance cannot be stressed enough!

Built in checks

The below checks are done automatically, and thus should not be included in your block list. Like mentioned above, it's best to keep your filter as concise as possible.
  • case variants/varying case, like eXaMpLe
  • similar text to entries (with no entry modifier)
  • adding spaces between each letter or other symbols between the letters (with no entry modifier)
  • word exaggerations, like heckkkkkkkkkkkk (with no entry modifier)
  • number and symbol substitutions, like @ for A, 3 for E, etc. (when substitution intelligence is enabled)
  • many additional sub-checks

Entry modifiers

Entry modifiers are the primary way to fine tune your filter. They allow you to fine tune the filter on an entry to entry basis and let you limit how strict or lenient particular entries should be
In some cases, certain words or phrases players type might accidentally conflict with similarity or other checks the filter conducts. This is where entry modifiers come in; they allow you to disable select checks on particular entries to fix and prevent false positive detections.
Ex. if you wish to block "example", but not a similar word like "examples", you can use an entry modifier to tell the filter to strictly block "example" without looking for similarities.
Entry modifiers are incredibly important to the effectiveness of the filter. Entries they should be on lacking proper modifiers severely diminish the filters accuracy

Core modifiers

Modifier
Description
When to use
exactcontains::
Medium detection sensitivity, in between strict and lenient. This is the goldilocks of entry modifiers. You'll find yourself using this one most of the time.
Entry will only detect words/phrases that are exactly equal to the entry (except for case variations).
On entries that are similar to unrelated words/phrases
exact::
Lowest detection sensitivity, most strict
Entry will only detect words/phrases that are exactly equal to the entry (except for case variations) and words/phrases containing the entry
On entries that might be found within other unrelated words or phrases
no modifier
Highest detection sensitivity, most lenient
Entry will be subject to all checks (see above)
On entries that don't have similar unrelated words/phrases or are rarely within other words/phrases shouldn't get any modifiers

Special use modifiers

Modifier
Description
When to use
nocensor::
When using the censor:
If an entry with this modifier is found in a message, the message will be blocked entirely and not be attempted to be censored This modifier is stackable, meaning you can use it along with other m
Good for very vulgar language that you want to keep out of chat entirely. You can use this modifier in conjunction with autowarn-when-censored to apply warnings on select blocked entries, instead of all entries
regex::
Advanced: matches a regex pattern
Entry will be subject to minimal checks, such case variants, word exaggerations, and substitution intelligence. Processed text that matches the pattern will be blocked
When you have an exact regex pattern you would like to block matches of. Remember to escape regex characters you want to use as plain text

Detection examples with and without modifiers

Example input
Detected when using no modifier?
Detected when using exactcontains::?
Detected when using exact::?
badword
yes
yes
yes
b a d w o r d
yes
no
no
badw0rd
yes
no
no
baaaaaaaaworz
yes
no
no
123blaBADWORDbla123
yes
yes
no
Some phrase bob ad word
yes (bo[badword]) (this is a false positive)
no
no

Important points to remember

  • It's not necessary to add variations of words/phrases in the block list as the plugin will do it for you. Only add variations when using entry modifiers.
  • Don't include substituted entries if you're using substitution intelligence; manual substitutions can confuse substitution intelligence and make the filter less effective
  • exact:: is the least sensitive to detections, exactcontains:: is partially sensitive, and no modifier is the most sensitive. You should use these modifiers accordingly to fine tune how entries function