Filters

plugins/AstralChat/filters.yml defines a registry of ChatFilter instances. Filters run only on channels where filtered: true, and they are skipped entirely for players holding astralchat.filters.bypass.

Top-level structure

whitelisted-words:
  - astralrealms
  - minecraft
  - server

filters:
  url:
    type: regex
    enabled: true
    regex:
      - "(?i)\\b(?:https?://)?(?:www\\.)?([a-z0-9-]+\\.)+[a-z]{2,}(?:/[^\\s]*)?"
    whitelist:
      - "astralrealms.fr"
    actions:
      log: true
      cancel: true
      notification-channel: "staff"
      custom-message: "<red>URLs are not allowed."

  caps:
    type: caps
    enabled: true
    amount: 7
    decapitalize: true
    actions:
      log: false
      cancel: false

  anti-spam:
    type: similarity
    enabled: true
    ttl: "5s"
    delay: "500ms"
    threshold-percentage: 70
    actions:
      log: true
      cancel: true
      notification-channel: "staff"
      custom-message: "<red>Please don't repeat yourself."

Field	Type	Description
`whitelisted-words`	`List<String>`	Words that are always allowed; they are stripped before each filter runs.
`filters`	`Map<String, ChatFilter>`	Filter registry. The map key is the filter id, used by `notification-channel` and logs.

Common fields

Every filter shares these fields:

Field	Type	Description
`type`	`regex` \\|`caps` \\|`similarity`	Selects the filter implementation.
`enabled`	boolean	When `false` the filter is skipped at runtime.
`actions`	Object	What to do when the filter matches — see below.

`actions`

Field	Type	Description
`log`	boolean	Log the violation to the server console.
`cancel`	boolean	Drop the message entirely. The sender still sees the `custom-message` if set.
`replacement`	String	Replace matched substrings with this text (e.g. `***`). Used by `regex`.
`custom-message`	MiniMessage	Sent to the violating player.
`notification-channel`	String	Channel name to broadcast the violation to (typically `staff`). Uses the `message-blocked-notification-format` and `message-filtered-notification-format` templates.
`actions`	`PaperActionList`	A list of AstralCore actions to execute as the violating player (e.g. mute, warn).

The actions list is a full PaperActionList, so you can chain [console], [message], [sound], and any custom action your network has registered.

Filter types

`regex`

Matches the message against a list of patterns.

type: regex
enabled: true
regex:
  - "(?i)bad[\\s_-]*word"
  - "(?i)b[a@4][d]"
whitelist:
  - "foosball"   # legitimate phrase that would otherwise match

Field	Type	Description
`regex`	`Set<Pattern>`	Patterns to match. Use `(?i)` for case-insensitive.
`whitelist`	`Set<String>`	Substrings that exempt a message from this filter.

Best practice: design patterns with character-evasion in mind (b[\\s._-]*a[\\s._-]*d) and use the whitelist to avoid false positives on legitimate words.

`caps`

Counts uppercase characters and triggers when the total exceeds the threshold.

type: caps
enabled: true
amount: 7
decapitalize: true

Field	Type	Description
`amount`	int	Threshold — the number of uppercase characters that triggers the filter.
`decapitalize`	boolean	When `true`, the message is rewritten to lowercase instead of being cancelled. Combine with `cancel: false`.

`similarity`

Anti-spam by string similarity. Recent messages are kept in a per-player cache and compared to new ones.

type: similarity
enabled: true
ttl: "5s"
delay: "500ms"
threshold-percentage: 70

Field	Type	Description
`ttl`	Duration	How long a message stays in the comparison cache.
`delay`	Duration	Minimum delay between two messages from the same player; faster sends always trigger.
`threshold-percentage`	int (0–100)	Similarity ratio above which the new message is considered spam.

Pipeline

ChannelChatEvent? ──► ChannelListener (cooldown / pause)
                        │
                        ▼
                     FiltersListener (only if channel.filtered)
                        │ skips on `astralchat.filters.bypass`
                        ▼
              FilterService.filter(player, raw, component)
                        │
              ┌─────────┴─────────┐
              ▼                   ▼
       FilterResult.match    FilterResult.noMatch
              │
              ├── if `cancel: true` → event cancelled, sender sees custom-message
              ├── if `replacement` → matched substrings replaced in the component
              ├── log / notify staff channel
              ├── run the `actions` list
              └── record the hit for the moderation dataset

The filter result drives both whether the chat event is cancelled and whether the broadcast component is rewritten — multiple filters can fire on the same message in sequence. A cancel: true filter returns immediately, so the filters after it never run; the others accumulate, and their names are joined into the single %reason% the staff notification carries.

The component filters see is the unrendered message body — the player's own words, without the channel format, prefix or display name — so a filter can never censor a rank prefix by accident.

Moderation dataset

Every filter hit is also handed to auto moderation through AutoModerationService.recordFilterHit, with source = FILTER and action = BLOCKED or FLAGGED. These are cheap, high-precision labels covering exactly what a classifier tends to miss (links, spam, obfuscated slurs), and for a blocked message they are the only trace left — a blocked message never reaches chat_messages.

Recording is skipped entirely when dataset.enabled or dataset.store-filter-hits is off in moderation.yml, and is subject to the same per-player hourly row quota as everything else.

`custom-message` and the fallback

A filter with cancel: true and no custom-message falls back to the message-doesnt-respect-rules message. When custom-message is set, it is sent instead — never both.

Last modified: 03 September 2026

Filters

Top-level structure

Common fields

actions

Filter types

regex

caps

similarity