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
});