🔍 AltDetector

Intelligent Alternate Account Detection for Paper

Stop ban evasion in its tracks. AltDetector runs a silent, fully async multi-layer detection engine on every login — no lag, no false positives flooding chat, just precise alerts delivered straight to your staff.

---

✨ Features

🧠 Multi-Layer Detection Engine

Every login is analyzed through four independent detection layers, each producing a confidence score that is then weighted and combined into a final risk score (0. 0–1.0):

| Layer | Method | Weight |
|---|---|---|
| **IP Match** | Shared IP address history | 40% |
| **UUID / Username History** | Name-swap & cross-account username collisions | 25% |
| **Login Pattern Analysis** | Session shifts, never-concurrent play, rapid alternation | 25% |
| **Behavior Fingerprint** | Playtime ratios, peak-hour cosine similarity | 10% |

All detection runs **fully asynchronously** — the main thread is never blocked.

⚠️ Smart Risk Thresholds

| Score | Level | Action |
|---|---|---|
| 0.50 – 0.69 | 🟡 LOW | Staff alert only |
| 0.70 – 0.84 | 🟠 MEDIUM | Staff alert + flag player record |
| 0.85 – 1.00 | 🔴 HIGH | Staff alert + flag + optional auto-ban |

All thresholds are fully configurable.

📣 Interactive Staff Alerts

Alerts are silently sent only to players with altdetector.staff.alerts. Each alert includes clickable [Inspect] [Ban] [Dismiss] [Whitelist] buttons — no need to type a single command. Offline staff receive queued alerts the moment they log in.

🔨 Auto-Ban System

When an alt of a banned player is detected above your configured threshold, AltDetector can automatically issue a ban with a customizable reason and appeal URL. Fires a cancellable AltBanEvent so other plugins can hook in.

🗄️ SQLite Storage (Async, WAL Mode)

All data is stored in a local SQLite database using WAL journal mode and prepared statements. Tracked data includes: - IP address history (up to 20 per player, FIFO) - Username history (up to 50, FIFO) - Risk scores & flagged status - Staff notes - Full detection log with evidence tags

🛡️ Privacy & Fairness Tools

• IP Anonymization — store only partial IPs (first 3 octets) for GDPR compliance
• Shared IP Groups — whitelist households/LAN players so they're never flagged
• VPN/Proxy Hints — detects datacenter IP ranges (configurable CIDR list) and adds a vpn_hint evidence tag with a small risk bump
• Bypass Permission — grant altdetector.bypass to trusted accounts

🖥️ Commands

| Command | Description |
|---|---|
| `/alt <player> [page]` | View all known alts of a player with risk scores |
| `/altadmin inspect <player>` | Full profile: IPs, logins, risk, links, evidence |
| `/altadmin history <player>` | Paginated login history with timestamps |
| `/altadmin link <p1> <p2>` | Manually link two accounts |
| `/altadmin unlink <p1> <p2>` | Remove a link |
| `/altadmin confirm <player>` | Confirm a detected alt link |
| `/altadmin whitelist <player>` | Whitelist from detection |
| `/altadmin ban <player>` | Ban player and all confirmed alts simultaneously |
| `/altadmin note <player> <text>` | Attach a staff note |
| `/altadmin purge <player>` | Full GDPR data wipe |
| `/altadmin export <player>` | Export full record as JSON |
| `/altadmin stats` | Detection statistics |
| `/altadmin reload` | Hot-reload config & messages |

All subcommands support **tab-completion**.

🔌 PlaceholderAPI Support

| Placeholder | Value |
|---|---|
| `%altdetector_risk_score%` | Player's current risk score |
| `%altdetector_alt_count%` | Number of known alt accounts |
| `%altdetector_flagged%` | `true` or `false` |

🪝 Custom API Events

Other plugins can hook into AltDetector's pipeline:

• AltDetectedEvent — fired on any detection above LOW threshold
• AltBanEvent (cancellable) — fired before any auto-ban
• AltLinkConfirmedEvent — fired when staff confirms a link
• AltWhitelistEvent — fired on whitelist changes

---

📦 Requirements

• Paper 1.21+
• Java 21
• PlaceholderAPI (optional, soft-depend)

⚙️ Configuration

Fully documented config.yml and MiniMessage-powered messages.yml with named placeholders. Reload at any time with /altadmin reload — no restart needed.

---

AltDetector is designed for survival, SMP, factions, and competitive servers where ban evasion is a serious problem. Zero dependencies beyond Paper itself.