Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,13 @@
# Changelog

## 0.6.0

- **Adults' words masked for kids** (D233, D235). A new `mask-for-viewers` setting in `filter.yml`, off by default. With it on, a player with `mayor.filter.bypass` writes freely, and anyone without the bypass sees each blocked word as `****` in that player's chat and private messages, while players with the bypass see them as written. A player without the bypass counts as filtered, so one whose permissions aren't known yet is filtered too.
- Filtered players get their own copy of the chat line, rendered the same way. A signed chat message carries its original words even when it's displayed differently, so changing only how it looks wasn't enough.
- Signs, books and item names are stored once for everyone, so with the setting on an adult's blocked words in them are saved as `****`. Showing them per viewer is planned.
- Players without the bypass are still stopped and told kindly when they use a blocked word, as before.
- Tested: 48 unit tests, 6 of them new, and on throwaway Paper 26.3 with bots 75/75 live checks, 8 of them new. Signs and anvil renames weren't tested, and it hasn't been seen in a real game client.

## 0.5.0

- **A new name: Mayor** (D198). The mayor sets how folks in town talk to each other. How it works is unchanged. As the owner asked (D196), no old names are kept: the package, plugin, jar, commands, permissions and data folder all use Mayor.
Expand Down
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Chat rules for family and community Paper servers. Players hear people in the same world, plus anyone who shares a "circle" with them, so groups such as families or age groups keep their own conversations across every world.

**Status:** pre-release. It passes its acceptance tests on throwaway Paper 26.2 and 26.3 servers, using protocol bots with LuckPerms: chat and private messages for every pair of players, replies, blocked commands, the word filter and its bypass, books, `/circles`, reloads, a broken config, and 20 bots chatting at once. BlueMapMini's share was tested with a stand-in plugin here; the real BlueMapMini 0.3.0 and Mayor 0.5.0 haven't been run together yet. Signs and anvil renames weren't tested. It hasn't been seen in a real game client yet, so the wording and colours haven't been checked by a person. See [the live tests](test/live/README.md) and the [test audit](docs/test-audit.md).
**Status:** pre-release. It passes its acceptance tests on throwaway Paper 26.2 and 26.3 servers, using protocol bots with LuckPerms: chat and private messages for every pair of players, replies, blocked commands, the word filter and its bypass, masking adults' words for kids, books, `/circles`, reloads, a broken config, and 20 bots chatting at once. BlueMapMini's share was tested with a stand-in plugin here; the real BlueMapMini 0.3.0 and Mayor 0.5.0 haven't been run together yet. Signs and anvil renames weren't tested. It hasn't been seen in a real game client yet, so the wording and colours haven't been checked by a person. See [the live tests](test/live/README.md) and the [test audit](docs/test-audit.md).

- Requires Paper 26.1 or newer and Java 25. Paper 1.21.11 and older aren't supported.
- With no circles set up it changes nothing about who hears whom, so it's safe to install first and configure after.
Expand All @@ -28,7 +28,9 @@ Otherwise they can't. A world group is a world with its Nether and End (`surviva

**Blocked commands.** Any command can be turned off, each with its own message. `sort` also blocks `anyplugin:sort`, in any letter case.

**Word filter.** `filter.yml` lists words and phrases to keep out of chat, private messages, signs, books and item names. It matches whole words, so "class" and "Scunthorpe" are fine, and it sees through `sh1t`, `$` for s and stretched letters. Spaced-out spellings get through. Blocked text is never logged or stored: the player is told kindly and can try again. Players with `mayor.filter.bypass`, such as an adults-only group, aren't filtered anywhere.
**Word filter.** `filter.yml` lists words and phrases to keep out of chat, private messages, signs, books and item names. It matches whole words, so "class" and "Scunthorpe" are fine, and it sees through `sh1t`, `$` for s and stretched letters. Spaced-out spellings get through. Blocked text is never logged or stored: the player is told kindly and can try again. Players with `mayor.filter.bypass`, such as an adults group, aren't filtered anywhere.

**Masking for kids.** Where adults and kids play together, set `mask-for-viewers: true` in `filter.yml`. Adults (players with `mayor.filter.bypass`) write freely, and everyone else sees each blocked word in their chat and private messages as `****`, while other adults see it as written. A player without the bypass counts as filtered, so a new account is masked until someone adds it to the adults group. Signs, books and item names are stored once for everyone, so an adult's blocked words in them are saved as `****`.

**Nobody heard you.** If you chat and nobody online can hear you, you get a light-hearted note, such as "A squid nods politely. It didn't understand a word." There are 75 in `quips.yml`, and you see them all before any comes round again. At most one every 3 minutes.

Expand Down Expand Up @@ -65,7 +67,7 @@ Every `/mayor` command also takes `--json <id>` at the end, for scripts and the
| `mayor.circles` | everyone | `/circles`. |
| `mayor.circles.names` | everyone | Names in `/circles`. Without it, only a count. |
| `mayor.bypass` | nobody, ops included | Reaching and being reached by everyone, for moderators. It doesn't show anyone else's chat. |
| `mayor.filter.bypass` | nobody, ops included | Skipping the word filter everywhere it applies, for adult groups. It doesn't change who hears whom. |
| `mayor.filter.bypass` | nobody, ops included | Skipping the word filter everywhere it applies, for adult groups. It doesn't change who hears whom. With `mask-for-viewers` on, it's also what lets a player read other adults' words as written. |
| `mayor.admin` | ops | `/mayor`, and config warnings on joining. |

## For other plugins
Expand Down
2 changes: 1 addition & 1 deletion build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ plugins {
}

group = "com.extantape"
version = "0.5.0"
version = "0.6.0"

java {
toolchain.languageVersion.set(JavaLanguageVersion.of(25))
Expand Down
6 changes: 6 additions & 0 deletions docs/test-audit.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,3 +53,9 @@ Each promise in the README, and the test that holds it to it. "Live" is `test/li
**Skipped, with reasons:**
- Sign text and anvil renames: bots can't place and edit signs or use an anvil. They're on the real-client list.
- `ReachService` "safe from any thread": it reads the rules from one snapshot that a reload swaps in whole (a `volatile` field with `final` contents), plus the two players' own permissions and world, the same reads async chat already makes. A dedicated concurrency test would be overkill; the live load test exercises the same path from the async chat thread with 20 bots.


## 2026-11-16: masking for kids (0.6.0, D233, D235)

- **Covered:** `WordFilter.mask` (only blocked words change, phrases masked whole, the allow list, spacing kept, the mask length gives nothing away, nothing blocked gives the same text), the setting off by default and read from `filter.yml`, private messages adult to kid masked and adult to adult as written, kids still stopped. Live on 26.3: chat masked for a player without the bypass and as written for one with it, private messages both ways, clean text unchanged, a kid's own word still stopped, an adult's book saved masked (read back from the server).
- **Skipped:** signs and anvil renames, for the same reason as before (bots can't). Item names and signs share the masking code with books. Live 26.2 wasn't rerun; the change uses no version-specific API.
2 changes: 1 addition & 1 deletion src/main/java/com/extantape/mayor/config/Settings.java
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ public String filterSummary() {
}

/** Which kinds of text the word filter checks. */
public record Filtered(boolean chat, boolean messages, boolean signs, boolean books, boolean itemNames) {
public record Filtered(boolean chat, boolean messages, boolean signs, boolean books, boolean itemNames, boolean maskForViewers) {
}

/** The note players get when nobody could hear their chat. */
Expand Down
5 changes: 3 additions & 2 deletions src/main/java/com/extantape/mayor/config/SettingsLoader.java
Original file line number Diff line number Diff line change
Expand Up @@ -139,14 +139,15 @@ public Result load(String config, String filterText, String quips) {
WordFilter filter = filterOn ? WordFilter.of(strings(FILTER, words, "words"), strings(FILTER, words, "allow")) : WordFilter.NONE;
Settings.Filtered filtered = new Settings.Filtered(
bool(FILTER, words, "check.chat", true), bool(FILTER, words, "check.private-messages", true),
bool(FILTER, words, "check.signs", true), bool(FILTER, words, "check.books", true), bool(FILTER, words, "check.item-names", true));
bool(FILTER, words, "check.signs", true), bool(FILTER, words, "check.books", true), bool(FILTER, words, "check.item-names", true),
bool(FILTER, words, "mask-for-viewers", false));

List<String> quipList = new ArrayList<>();
for (String note : strings(QUIPS, notes, "notes")) if (!note.isBlank()) quipList.add(note);
if (nobodyHeard.enabled() && quipList.isEmpty()) warnings.add(QUIPS + ": there are no notes, so nobody-heard stays quiet.");

Reach reach = new Reach(circles, circleOnly, groupOf, suffixes);
CommandRules commands = new CommandRules(reach, filter, filtered.messages(),
CommandRules commands = new CommandRules(reach, filter, filtered.messages(), filtered.maskForViewers(),
Set.copyOf(strings(CONFIG, base, "private-message-commands")), Set.copyOf(strings(CONFIG, base, "reply-commands")),
Set.copyOf(strings(CONFIG, base, "broadcast-commands")), blocked);
if (!errors.isEmpty()) return new Result(null, List.copyOf(errors), List.copyOf(warnings));
Expand Down
37 changes: 37 additions & 0 deletions src/main/java/com/extantape/mayor/listen/ChatListener.java
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,19 @@
import com.extantape.mayor.rules.Subject;
import com.extantape.mayor.rules.WordFilter;
import com.extantape.mayor.text.Messages;
import io.papermc.paper.chat.ChatRenderer;
import io.papermc.paper.event.player.AsyncChatEvent;
import net.kyori.adventure.audience.Audience;
import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.serializer.plain.PlainTextComponentSerializer;
import org.bukkit.Bukkit;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.Listener;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;

/** Public chat goes only to the players the speaker can reach. Runs on the async chat thread and never blocks it. */
Expand Down Expand Up @@ -56,4 +61,36 @@ public void onChat(AsyncChatEvent event) {
// A tick later, so the note shows under the player's own line.
if (note != null) Bukkit.getScheduler().runTask(plugin, () -> from.sendMessage(Messages.parse(note, Map.of())));
}

/**
* With mask-for-viewers on, an unfiltered speaker's blocked words reach filtered players as ****, and everyone
* with the bypass sees the line as written. A player without the bypass, including one whose permissions aren't
* known, counts as filtered. The console sees it as written.
*
* Runs last, once nothing else will cancel the line or change who hears it. Filtered players are taken off the
* line's viewers and sent their own copy, rendered the same way with the masked text. A signed chat message
* carries the original words even when it's displayed differently, so it isn't enough to change the rendering.
*/
@EventHandler(priority = EventPriority.MONITOR, ignoreCancelled = true)
public void maskForViewers(AsyncChatEvent event) {
MayorPlugin.State state = plugin.state();
if (state == null) return;
Settings settings = state.settings();
Player from = event.getPlayer();
if (!settings.filtered().chat() || !settings.filtered().maskForViewers() || !from.hasPermission(WordFilter.BYPASS)) return;
String plain = PlainTextComponentSerializer.plainText().serialize(event.message());
String masked = settings.filter().mask(plain);
if (masked.equals(plain)) return;
Component hidden = Component.text(masked);
ChatRenderer renderer = event.renderer();
List<Player> filtered = new ArrayList<>();
for (Audience viewer : event.viewers()) if (viewer instanceof Player p && !seesAsWritten(p)) filtered.add(p);
if (filtered.isEmpty()) return;
event.viewers().removeAll(filtered);
for (Player p : filtered) p.sendMessage(renderer.render(from, from.displayName(), hidden, p));
}

static boolean seesAsWritten(Audience viewer) {
return !(viewer instanceof Player p) || p.hasPermission(WordFilter.BYPASS);
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ public void onCommand(PlayerCommandPreprocessEvent event) {
} else plugin.tell(from, decision.key(), decision.vars());
}
case DELIVER -> {
if (decision.rewrite() != null) event.setMessage(decision.rewrite());
UUID to = decision.partner().id();
plugin.partners().put(from.getUniqueId(), to);
plugin.partners().put(to, from.getUniqueId());
Expand Down
54 changes: 53 additions & 1 deletion src/main/java/com/extantape/mayor/listen/TextListener.java
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,13 @@ public void onSign(SignChangeEvent event) {
if (refusal != null) {
event.setCancelled(true);
plugin.tell(event.getPlayer(), refusal);
return;
}
WordFilter mask = masker(event.getPlayer(), Settings.Filtered::signs);
if (mask == null) return;
for (int i = 0; i < lines.size(); i++) {
String masked = mask.mask(lines.get(i));
if (!masked.equals(lines.get(i))) event.line(i, Component.text(masked));
}
}

Expand All @@ -59,7 +66,28 @@ public void onBook(PlayerEditBookEvent event) {
if (refusal != null) {
event.setCancelled(true);
plugin.tell(event.getPlayer(), refusal);
return;
}
WordFilter mask = masker(event.getPlayer(), Settings.Filtered::books);
if (mask == null) return;
boolean changed = false;
List<Component> pages = new ArrayList<>();
List<String> plainPages = new ArrayList<>();
for (Component page : book.pages()) {
String plain = PLAIN.serialize(page), masked = mask.mask(plain);
changed |= !masked.equals(plain);
pages.add(masked.equals(plain) ? page : Component.text(masked));
plainPages.add(masked);
}
if (event.isSigning() && book.hasTitle()) {
String plain = PLAIN.serialize(book.title()), masked = mask.mask(plain);
if (!masked.equals(plain)) { book.title(Component.text(masked)); changed = true; }
}
if (!changed) return;
// An unsigned book keeps plain-text pages; a signed one keeps formatted pages.
if (event.isSigning()) book.pages(pages);
else book.setPages(plainPages);
event.setNewBookMeta(book);
}

@EventHandler(priority = EventPriority.HIGH)
Expand All @@ -68,7 +96,18 @@ public void onAnvil(PrepareAnvilEvent event) {
String name = view.getRenameText();
if (event.getResult() == null || name == null || name.isBlank() || !(view.getPlayer() instanceof Player player)) return;
String refusal = refusal(player, List.of(name), Settings.Filtered::itemNames, "filtered-item-name");
if (refusal == null) return;
if (refusal == null) {
WordFilter mask = masker(player, Settings.Filtered::itemNames);
String masked = mask == null ? name : mask.mask(name);
if (masked.equals(name)) return;
org.bukkit.inventory.ItemStack result = event.getResult().clone();
org.bukkit.inventory.meta.ItemMeta meta = result.getItemMeta();
if (meta == null) return;
meta.customName(Component.text(masked));
result.setItemMeta(meta);
event.setResult(result);
return;
}
event.setResult(null);
long now = System.currentTimeMillis();
Long last = anvilNotes.get(player.getUniqueId());
Expand All @@ -78,6 +117,19 @@ public void onAnvil(PrepareAnvilEvent event) {
}
}

/**
* With mask-for-viewers on, signs, books and item names are stored once for everyone, so an unfiltered writer's
* blocked words are saved as **** and filtered players never see them. Returns the filter to mask with, or null
* when nothing should change.
*/
private WordFilter masker(Player player, java.util.function.Predicate<Settings.Filtered> check) {
MayorPlugin.State state = plugin.state();
if (state == null) return null;
Settings settings = state.settings();
if (!settings.filtered().maskForViewers() || !check.test(settings.filtered()) || !player.hasPermission(WordFilter.BYPASS)) return null;
return settings.filter();
}

/** The message key explaining why this text can't be written, or null if it's fine. */
private String refusal(Player player, List<String> text, java.util.function.Predicate<Settings.Filtered> check, String filteredKey) {
MayorPlugin.State state = plugin.state();
Expand Down
Loading
Loading