Block Words (blockedwords)

A server-side chat moderation mod for Minecraft 1.21.1 (NeoForge).

English | 中文说明

---

English

The built-in chat report feature in Minecraft is terrible—it's not just useless, it can also be easily exploited by malicious people. If you don't want to use the crappy chat report feature and still want an easy way to maintain a friendly chat environment, our mod is a great choice for you.

Block Words is a lightweight, fully server-side mod that filters and replaces sensitive words in player chat, and lets you "silence" individual players by making their messages visible only to themselves.

• Minecraft: 1.21.1
• Mod loader: NeoForge 21.1.x
• Mod ID: blockedwords
• Language: Java 21
• License: GPL-3.0-or-later

Features

• Sensitive-word filtering with two configurable strategies:
  • word — replace only the matched word(s).
  • sentence — replace the entire message once anything matches.
• Random replacement texts — provide a pool of replacement texts; one is picked at random each time (each hit in word mode is replaced independently).
• False-positive-averse matching:
  • Chinese: matched only when every character appears contiguously (傻逼 never matches 傻大逼).
  • English/Latin: whole-word matching (fuck never matches fucker), case-insensitive.
  • Phrases with spaces (e.g. fuck you): the whole phrase must match exactly; never split apart.
• Player BAN: a banned player's messages are only visible to themselves — everyone else sees nothing (or a configurable placeholder), while the original text is kept in the server log. Perfect for dealing with troublemaker groups without kicking anyone.
• Hot reload: /blockwords reload applies config changes without restarting the server.

Installation

1. Install NeoForge for Minecraft 1.21.1.
2. Drop blockedwords-1.0.0.jar into the mods/ folder (server and/or client).
3. Start the server — all filtering happens server-side.

Configuration

The server config is written to the world folder:

serverconfig/blockedwords-server.toml

replaceMode = "word"                 # "word" or "sentence"
replacementTexts = ["***", "🔞", "已屏蔽"]
blockedWords = ["傻逼", "fuck you", "nigger"]
banList = []                         # maintained by commands; no need to edit manually
bannedMessagePlaceholder = ""        # what others see when a banned player chats; empty = fully hidden

Commands (OP level 2)

Command	Description
/blockwords reload	Reload the config without restarting.
/blockwords ban <player>	Ban a player — their messages become visible only to themselves.
/blockwords unban <player>	Unban a player.
/blockwords list	Show current blocked words and replacement texts (ban list is not shown).

Note: NeoForge 1.21.1 has no built-in permission-node system, so commands default to OP level 2. The permission constants such as blockedwords.reload are kept in the source for future permission-plugin integration.

How matching works

• Entries containing Chinese characters are matched as contiguous substrings (Chinese has no spaces, so no word boundary is needed).
• Other entries (English/Latin) are matched as whole words with (?<![a-z0-9])…(?![a-z0-9]) boundaries, case-insensitively.
• Longer entries are processed first, so a phrase like fuck you is not broken apart by a shorter entry like fuck.

Building from source

./gradlew build

The jar is produced in build/libs/.

License

This project is licensed under the GNU General Public License v3.0 or later — see LICENSE.

---

中文说明

Minecraft自带的聊天举报功能太烂了，不仅没用还容易被有心之人利用。如果你不想用糟糕的聊天举报功能，还想要便捷地维护和谐的聊天氛围，我们的模组就是你很好的选择。

Block Words 是一个轻量、纯服务端的 Minecraft 1.21.1（NeoForge）聊天内容管理模组：自动屏蔽并替换玩家聊天中的敏感词，也可以把某个玩家的消息“只发给自己看”。

• 游戏版本： 1.21.1
• 模组加载器： NeoForge 21.1.x
• Mod ID： blockedwords
• 开发语言： Java 21
• 开源协议： GPL-3.0-or-later

功能特性

• 敏感词屏蔽，两种可配置策略：
  • word —— 仅替换命中的敏感词；
  • sentence —— 一旦命中任意词，整条消息替换。
• 随机替换文本：配置多个替换文本，触发时随机选取；word 模式下每个命中独立随机替换。
• 完全匹配、防误报：
  • 中文按“字”连续出现即命中（傻逼 不会命中 傻大逼）；
  • 英文/拉丁整词匹配（fuck 不会命中 fucker），不区分大小写；
  • 含空格的词组（如 fuck you）必须整个词组完全一致才命中，不拆分匹配。
• 玩家 BAN： 被 BAN 玩家的消息仅其本人可见，其他玩家完全看不到（或看到可配置的占位文本），服务器日志保留原文。适合对付恶意小团体，无需踢人。
• 热加载： /blockwords reload 无需重启服务器即可生效。

安装

1. 安装 NeoForge（Minecraft 1.21.1）。
2. 将 blockedwords-1.0.0.jar 放入 mods/ 文件夹（服务端/客户端均可）。
3. 启动服务器即可，所有屏蔽逻辑都在服务端执行。

配置

服务端配置文件位于世界目录：

serverconfig/blockedwords-server.toml

replaceMode = "word"                 # "word" 或 "sentence"
replacementTexts = ["***", "🔞", "已屏蔽"]
blockedWords = ["傻逼", "fuck you", "nigger"]
banList = []                         # 由指令动态维护，一般无需手动编辑
bannedMessagePlaceholder = ""        # 其他玩家看到被 BAN 玩家消息时的占位文本；留空则完全不可见

指令（需要 OP 等级 2）

指令	功能
/blockwords reload	热加载配置文件
/blockwords ban <玩家>	屏蔽该玩家，其消息仅本人可见
/blockwords unban <玩家>	解除屏蔽
/blockwords list	查看当前屏蔽词与替换文本（不显示 BAN 列表）

说明：NeoForge 1.21.1 未内置权限节点系统，默认按 OP 等级 2 判断权限；源码中保留了 blockedwords.reload 等权限节点常量，便于日后接入权限插件。

匹配原理

• 含汉字的词条按“字”连续匹配（中文无空格，无需边界）。
• 其他（英文/拉丁）词条用 (?<![a-z0-9])…(?![a-z0-9]) 整词匹配，不区分大小写。
• 长词条优先处理，避免 fuck you 被更短的 fuck 先拆分。

从源码构建

./gradlew build

构建产物位于 build/libs/。

开源协议

本项目采用 GNU 通用公共许可证 v3.0 或更高版本 开源，详见 LICENSE。