Client-side Fabric mod for Minecraft 1.21.10 / 1.21.11 that analyzes Hypixel SkyBlock chat for scam risk.

ScamScreener combines:

• manual blacklist alerts
• rule-based detection (regex + behavior signals)
• Levenshtein similarity matching (rule phrases + training samples)
• local AI scoring (no required cloud AI service) with updateable model and community training-data upload flow
• message muting with custom patterns
• outgoing safety guard for email addresses and Discord invite links

Why this mod?

Scams in trade/party contexts often use pressure tactics, trust manipulation, external platform pushes, or repeated contact attempts. ScamScreener scores these signals in real time and shows explainable warnings with hoverable rule details.

Features

1) Blacklist alerts

• Add players manually to a local blacklist (name/UUID + score + reason).
• Triggers warnings in relevant contexts:
  • incoming trade request
  • outgoing trade request
  • active trade session
  • party confirmation (You'll be partying with: <Name>)
  • party finder dungeon join (Party Finder > <Name> joined the dungeon group...)
  • co-op join request (<Name> ... join your SkyBlock Co-op)
  • co-op invite sent (You invited <Name> to your co-op!)
  • co-op member joined (<Name> joined your SkyBlock Co-op!)
• Optional auto /p leave on blacklist hit.
• Warning output can show player, score, reason, timestamp, and trigger context.

2) Live chat detection pipeline

Every parsed player chat line is processed through:

• MuteStage (early filter)
• RuleSignalStage (pattern/rule scoring)
• LevenshteinSignalStage (similarity signals)
• BehaviorSignalStage (behavior flags)
• AiSignalStage (local model probability-based signal)
• TrendSignalStage (multi-message trend bonus)
• FunnelSignalStage (intent sequence funnel bonus)
• ScoringStage, DecisionStage (threshold + dedupe), OutputStage

When thresholds are reached:

• risk warning in chat
• explainable rule list with hover details (Why triggered)
• 3x short warning tone (configurable)
• optional auto-capture into training data (by minimum alert level)
• quick action tags inside warnings (manage, info)
• optional follow-up education message for external-platform redirect risk (with one-click disable action)

3) Training data capture and upload lifecycle

• Training samples are stored in CSV.
• /scamscreener upload archives the active training CSV and uploads it via webhook (after ToS consent).
• Existing training/model files are archived under old/.
• Supports sample capture by player, by message id (ai flag), bulk legit capture, and alert review (manage screen).
• Includes training data migration (/scamscreener ai migrate) for older CSV headers.

4) AI update workflow (optional online check)

• Automatic update check once per session when connected.
• Manual checks via command or GUI (AI Update screen).
• Supports update download and actions: accept, merge, ignore.
• Uses SHA-256 verification before applying downloaded model payload.

5) Mute filter with custom patterns

• Add/remove mute patterns via command.
• Case-insensitive matching.
• Regex supported.
• If no regex metacharacters are present, matching defaults to whole word/phrase boundaries (not partial substrings).
• Periodic summary for blocked message counts.

6) Outgoing safety guard

• Blocks outgoing chat/commands containing:
  • email addresses
  • Discord invite links (discord.gg, discord.com/invite)
• Blocks /coopadd <player> once and requires [BYPASS] confirmation
• Shows a clickable [BYPASS] action that allows one resend for the blocked content.

7) In-game settings GUI

Open with /scamscreener settings. If ModMenu is installed, the same settings screen is available via the mod menu config button.

Screens available:

• main settings (alert threshold, auto-capture level, auto-leave, mute filter, local AI signal)
• rule settings
• debug settings
• message settings
• blacklist management
• AI update controls

Requirements

• Minecraft 1.21.10 or 1.21.11
• Fabric Loader >= 0.18.4
• Fabric API matching your MC version
• Java 21+
• Optional: ModMenu (>= 16.0.0) for config access from mod list

Installation

Place the mod JAR in your mods/ folder and start the game.

Build (Developer)

.\gradlew.bat build

Artifact output: build/libs/

Commands

General

• /scamscreener (help)
• /scamscreener add <player|uuid> [score] [reason]
• /scamscreener remove <player|uuid>
• /scamscreener list
• /scamscreener upload
• /scamscreener rules <list|disable|enable> [rule]
• /scamscreener alertlevel [low|medium|high|critical]
• /scamscreener autoleave [on|off] (no args = status)
• /scamscreener review <manage|info> <alertId>
• /scamscreener edu disable <messageId>
• /scamscreener settings
• /scamscreener debug
• /scamscreener debug <true|false> [updater|trade|mute|chatcolor]
• /scamscreener version
• /scamscreener preview (dry-run preview output)

AI

• /scamscreener ai (help)
• /scamscreener ai capture <player> <scam|legit> [count]
• /scamscreener ai capturebulk <count>
• /scamscreener ai flag <messageId> <legit|scam>
• /scamscreener ai migrate
• /scamscreener ai update
• /scamscreener ai update force
• /scamscreener ai update notify [on|off] (no args = status)
• /scamscreener ai model <download|accept|merge|ignore> <id>
• /scamscreener ai reset
• /scamscreener ai autocapture [off|low|medium|high|critical]

Short capture aliases:

• /1 <player> <count> (capture as scam label)
• /0 <player> <count> (capture as legit label)

Mute and safety

• /scamscreener mute (enable mute filter)
• /scamscreener mute <pattern>
• /scamscreener unmute (disable mute filter)
• /scamscreener unmute <pattern>
• /scamscreener bypass <id> (send blocked email/Discord//coopadd content once)

Configuration files

All mod files are stored under:

• config/scamscreener/

Important files:

• scam-screener-blacklist.json
• scam-screener-rules.json
• scam-screener-local-ai-model.json
• scam-screener-training-data.csv
• scam-screener-mute.json
• scam-screener-debug.json
• scamscreener-edu.json

Archive folders:

• config/scamscreener/old/training-data/
• config/scamscreener/old/models/

Training quick guide

1. Collect labeled samples with ai capture and/or ai flag.
2. (Optional) Review alert messages in-game via [manage] and save selected scam/legit lines.
3. Run /scamscreener upload.
4. Training CSV is archived and uploaded via webhook after ToS acceptance.
5. Observe warning quality and false positives over time.

Tips:

• Use both scam and legit examples.
• Keep labels clean; avoid system/mod status lines.
• Fewer high-quality samples are better than noisy bulk labels.

Privacy and network behavior

• Core detection and scoring run locally on the client.
• Training and model files stay in config/scamscreener/.
• Optional network calls are used for:
  • Mojang profile lookup (name to UUID resolution)
  • training-data webhook upload (/scamscreener upload)
  • AI model update check/download (GitHub raw URL)

Limitations

• Rule/keyword/similarity systems have limited semantic understanding.
• Sarcasm and ambiguous context can cause false positives.
• Aggressive mute patterns can hide legitimate chat.
• Local AI quality depends strongly on training data quality.

ScamScreener

ScamScreener is a client-side Fabric mod that analyzes incoming chat, highlights scam-like behavior patterns, and gives you a structured review workflow for safer decisions.

At A Glance

• Realtime chat risk analysis with a multi-stage detection pipeline
• In-game review queue with case-level message tagging
• Whitelist and blacklist tools with command + GUI support
• Optional auto /p leave on blacklist alerts
• Canonical training export (training-cases-v2.jsonl) for later tuning
• Public API entrypoint for integrations (scamscreener-api)

Supported Versions And Requirements

• Minecraft: 1.21.10 (EOL), 1.21.11 (EOL), 26.1
• Mod loader: Fabric Loader >= 0.17
• Dependency: Fabric API
• Environment: client-only

Installation

1. Install Fabric Loader for your Minecraft version.
2. Put ScamScreener and Fabric API into your mods folder.
3. Launch the game.
4. Open settings with /scamscreener settings (or /ss settings).

Quick Start

1. Set your risk threshold (LOW, MEDIUM, HIGH, CRITICAL). Note that LOW might warn you way often when on large public islands!
2. Play as usual and let ScamScreener monitor inbound chat.
3. Open review queue (/scamscreener review) for flagged cases.
4. Mark cases as RISK, SAFE, or DISMISSED.
5. Export reviewed data with /scamscreener review export if needed.

How Detection Works

ScamScreener evaluates each inbound message through a staged pipeline:

• Player list stage (whitelist/blacklist hard matches)
• Deterministic rule stage (links, urgency, platform redirects, payment/account signals)
• Similarity stage (fuzzy phrase matching)
• Behavior stage (sender-local repetition/burst patterns)
• Trend stage (cross-sender wave detection)
• Funnel stage (multi-step trust -> redirect -> payment/account patterns)
• Context stage (signal blend across recent same-sender messages)
• Mute stage / bypass logic

Pipeline outcomes can include IGNORE, REVIEW, BLOCK, WHITELISTED, BLACKLISTED, or MUTED.

In-Game Commands

Root commands:

• /scamscreener ...
• /ss ... (alias)

Main command groups:

• settings, rules, runtime, messages, metrics
• whitelist add/remove/clear
• blacklist add/remove/clear
• review, review player, review manage, review info, review export
• alertlevel
• autoleave on/off
• mute, mute <regex>, unmute, unmute <regex>
• debug
• version, help

GUI Overview

Main settings screen includes:

• Alert threshold and auto-capture settings
• Auto-leave and mute filter toggles
• Whitelist / blacklist management
• Review queue and review settings
• Rules, runtime, metrics, and message settings

Case Review And Training Export

Review flow:

1. Open queue and pick a case.
2. Tag each message as Exclude, Context, or Signal.
3. Save verdict as Risk, Safe, or Dismiss.

Export:

• Command: /scamscreener review export
• Output file: config/scamscreener/training-cases-v2.jsonl

Important status:

• Training Hub is currently not live.
• Contribute Training Data buttons are intentionally disabled in GUI for now.
• Local export is still available and stable.

Configuration Files

ScamScreener stores its data in config/scamscreener/:

• runtime.json (runtime and output behavior)
• rules.json (pipeline rule configuration)
• review.json (review queue state)
• whitelist.json (trusted players)
• blacklist.json (blocked players)
• training-cases-v2.jsonl (manual export artifact)

Privacy And Data Handling

• ScamScreener runs client-side.
• No automatic training upload is performed by the mod.
• Review/training payloads are sanitized and do not persist sender UUID identity.
• UUID-based persistence is intentionally limited to whitelist/blacklist management.

v1 To v2 Migration

On first start of v2, ScamScreener performs a one-time migration:

• Migrates legacy whitelist/blacklist files into v2 config files
• Writes migration marker .v1-to-v2-migration.done
• Cleans up legacy v1 config folder artifacts after migration

Existing v2 target files are never overwritten.

API For Other Mods

Get the API through the Fabric entrypoint:

import eu.tango.scamscreener.api.ScamScreenerApi;
import net.fabricmc.loader.api.FabricLoader;

import java.util.List;

List<ScamScreenerApi> apis = FabricLoader.getInstance()
    .getEntrypoints(ScamScreenerApi.ENTRYPOINT_KEY, ScamScreenerApi.class);

if (!apis.isEmpty()) {
    ScamScreenerApi api = apis.get(0);
}

Then use shared list access and events:

import eu.tango.scamscreener.api.BlacklistAccess;
import eu.tango.scamscreener.api.WhitelistAccess;
import eu.tango.scamscreener.api.event.BlacklistEvent;
import eu.tango.scamscreener.api.event.PipelineDecisionEvent;
import eu.tango.scamscreener.api.event.WhitelistEvent;

WhitelistAccess whitelist = api.whitelist();
BlacklistAccess blacklist = api.blacklist();

PipelineDecisionEvent.EVENT.register((chatEvent, decision) -> {
    // react to pipeline decisions
});

WhitelistEvent.EVENT.register((changeType, entry) -> {
    // entry is null when the list is cleared
});

BlacklistEvent.EVENT.register((changeType, entry) -> {
    // entry is null when the list is cleared
});