SparkWord

SparkWord works by automatically monitoring chat, commands, books, signs, and player input to detect spam, abuse, or banned content in real time. It offers advanced word filtering, anti-spam protection, moderation tools, logs, and player mutes.

🔵 REQUERIMENTS

• Java-21
• Paper/Purpur-1.21.x

---

🔵 FEATURES

• Configurable word blocking and filtering via external text-based dictionaries with hot-reload support.
• Built-in persistence layer using SQLite by default, with optional MySQL or MariaDB backends for scalable environments.
• Advanced anti-spam system covering IP-based checks, domain detection, message flooding, excessive capitalization, numeric abuse, character repetition, and repeated word patterns.
• Injection prevention layer designed to mitigate malformed or malicious input affecting vulnerable plugins.
• Detection and sanitization of dangerous Unicode sequences, including Zalgo and invisible character abuse.
• Content limitations and validation applied to writable books to prevent exploits and abuse.
• Command input writing limits to reduce spam, injection vectors, and abuse through command execution.
• Automated mute mechanisms triggered by configurable violation thresholds across multiple detection systems.
• Comprehensive moderation logs tracking mutes, warnings, and staff command usage for auditing purposes.
• Suggestion and correction system to guide players toward acceptable message formats.
• Preventive staff notifications with contextual information before escalation actions occur.
• Unified filtering and anti-spam enforcement across chat, signs, anvils, books, and other player-input sources.

---

🔵 USAGE

• Word Filtering: The plugin does not rely on traditional regex-based filtering, which was intentionally avoided due to performance issues and server lag. Instead, it uses an Aho–Corasick pattern-matching engine optimized for high-throughput text analysis. Filtering is driven by plain-text wordlists categorized by purpose (Normal, Strong, WriteCommand), each providing a distinct level of enforcement.
  • Normal: Performs partial word blocking, matching standalone or contextual terms (e.g., blocking "cat" without affecting "category" or "education").
  • Strong: Applies aggressive matching, blocking terms regardless of whether they appear as substrings within larger words.
  • WriteCommand: Designed to prevent the use of administrator or staff names within writable commands such as /rename, /tag, /nickname, and similar features.
• Anti-Spam: This module is fully configurable via moderation.yml, allowing fine-grained control over thresholds, cooldowns, and enforcement behavior.
• Suggestions: The suggestion command sw-sg allows players to submit word suggestions, feedback, or staff reports. All entries are stored persistently and can be reviewed using sw list sg. By default, suggestion logs are automatically purged every 3 days; this interval is configurable via config.yml under suggestion.purge-hours.
• commands.yml: Provides centralized control for redefining or aliasing moderation commands exposed to helpers or regular users, enabling permission-based command abstraction.
• Notifications: Staff notifications are delivered using hover-based messages to minimize chat clutter and maintain readability on high-population servers.

---

Commands

Arguments:
- ID: Each suggestion or entry is identified by a unique ID.
- Preset: Predefined warning or moderation presets for quick application.
- Word: The word to be added, removed, or suggested.
- List:
  - n: Normal list
  - s: Strong list
  - wc: WriteCommand list
  - sg: Suggestions list
- Logs:
  - all: All available logs
  - b: Blocked words (only available when filter mode is disabled)
  - m: Applied mutes
  - w: Applied warnings

Command        | Arguments              | Permission            | Usage
/sw info       | none                   | sparkword.info        | Display available commands and their usage based on assigned permissions.
/sw list       | List                   | sparkword.list        | View word lists or pending suggestions.
/sw accept     | ID/List                | sparkword.accept      | Accept suggested words into a target list.
/sw deny       | ID/List                | sparkword.deny        | Deny or reject suggested words.
/sw add        | List/Word              | sparkword.add         | Add words to a specific filtering list.
/sw remove     | List/Word              | sparkword.remove      | Remove words from a specific filtering list.
/sw logs       | Logs                   | sparkword.logs        | Display moderation logs captured by staff or console.
/sw audit      | Staff-Name             | sparkword.audit       | Show command execution logs for a specific staff member or all.
/sw purge      | Logs/Suggest           | sparkword.purge.*     | Manually purge logs or the suggestions list.
/sw reload     | none                   | sparkword.reload      | Hot-reload the plugin configuration.
/sw-debug      | none                   | sparkword.debug       | Enable debugging mode to trace issues in the console.
/sw-mute       | player/preset          | sparkword.mute        | Apply a permanent chat mute to a player.
/sw-permute    | player/preset          | sparkword.permute     | Apply a permanent global mute blocking all writable inputs (chat, signs, anvils, books, and write-related commands).
/sw-tempmute   | player/time/preset     | sparkword.tempmute    | Apply a temporary mute to a player.
/sw-unmute     | player                 | sparkword.unmute      | Remove an active mute from a player.
/sw-warn       | player/preset          | sparkword.warn        | Issue a warning to a player.
/sw-scan       | player                 | sparkword.scan        | Inspect all mutes and warnings accumulated by a player.
/sw-checkmute  | player                 | sparkword.checkmute   | Verify a players mute status and remaining duration.
/sw-sg         | Word/Reason            | sparkword.suggest     | Submit a word suggestion, report, or staff-related issue.

Permissions

# Player permissions
sparkword.suggest # Allows the use of the 'sw-sg' command or any of its aliases to submit suggestions, reports, or staff requests; enabled by default for all players.

# Administrative permissions
sparkword.reload # Grants access to the 'sw reload' command to hot-reload configurations and internal modules.
sparkword.add # Allows execution of 'sw add <list> <word>' to regist	er terms into filtering lists.
sparkword.remove # Allows execution of 'sw remove <list> <word>' to remove previously registered terms.
sparkword.notify.icon # Enables visualization of censored messages using hover components attached to the original message.
sparkword.debug # Grants access to the 'sw debug' command or alias to enable debugging mode and trace events in the console.

# Moderation permissions
sparkword.info # Allows access to the 'sw info <page>' command to view internal documentation and command usage.
sparkword.list # Enables the 'sw list <list>' command to inspect word lists, suggestions, or active configurations.
sparkword.accept # Allows accepting suggestions using 'sw accept <ID/Suggest> <list>' and merging them into the target list.
sparkword.deny # Allows rejecting suggestions via 'sw deny <ID/Suggest>'.
sparkword.mute # Authorizes the use of the 'sw-mute <player> <reason>' command or alias to apply a permanent chat mute.
sparkword.permute # Authorizes the use of the 'sw-permute <player> <reason>' command or alias to apply a permanent global mute across all writable inputs.
sparkword.unmute # Allows removing an active mute using 'sw-unmute <player> <reason>'.
sparkword.tempmute # Allows applying temporary mutes via 'sw-tempmute <player> <time> <reason>'.
sparkword.checkmute # Allows checking a player's current mute status using 'sw-checkmute <player>'.
sparkword.scan # Allows inspecting a player's accumulated mutes and warnings using 'sw-scan <player> <page>'.
sparkword.warn # Authorizes the use of the 'sw-warn <player> <reason>' command or alias to issue formal warnings.
sparkword.notify # Allows staff to receive real-time notifications of player violations via chat.
sparkword.audit # Allows querying staff action audits using 'sw audit <staff-name/page> <page>'.
sparkword.logs # Enables access to 'sw logs <logs/page> <page>' to review moderation and enforcement records.

# Purge permissions
sparkword.purge.logs # Allows full deletion of moderation logs.
sparkword.purge.suggest # Allows full deletion of stored suggestions.
sparkword.purge.warning # Allows deletion of all recorded warnings.
sparkword.purge.mute # Allows deletion of all applied mutes.
sparkword.purge.audit # Allows deletion of all staff audit records.

# Bypass permissions
sparkword.bypass.chat # Allows bypassing content filters applied to chat.
sparkword.bypass.sign # Allows bypassing content filters applied to signs.
sparkword.bypass.books # Allows bypassing content filters applied to writable books.
sparkword.bypass.anvils # Allows bypassing content filters applied to anvils.
sparkword.bypass.spam # Allows bypassing anti-flood, anti-repeat, anti-caps, digit limits, and character spam checks.
sparkword.bypass.writecommands # Allows bypassing filters associated with the WriteCommand list.
sparkword.bypass.injection # Allows bypassing the injection prevention system.
sparkword.bypass.symbol.all # Allows unrestricted usage of dangerous Unicode symbols, including Zalgo and invisible characters.
sparkword.bypass.ip # Allows bypassing IP and domain filtering.
sparkword.bypass.ip.split # Allows bypassing IP-split detection.
sparkword.bypass.cooldown # Allows bypassing the suggestion system cooldown.