WKI_RATTRAP
Server-authoritative player statistics and cheat-detection toolkit with an in-game admin case file. The trap snaps when the rat reaches for the bait.

This is a DETECTION tool, not a punishment tool. It observes, records and alerts - it never kicks or bans anyone automatically. Every indication is a hint for human admin judgement, never a verdict.

=== WHAT IT DOES ===

SERVER-MEASURED TELEMETRY (per individual projectile hit, armor path included):
- Shots fired and hits per weapon class, accuracy per class
- Hit zones on the victim body (head, torso, arms, legs) - helmet hits count as head
- Kill / headshot-kill counters, separately vs. players and vs. AI
- Engagement distances in 7 bands (0-50m up to 1500m+)
- Deaths, teamkills, grenade throws

MAP-USAGE ANALYSIS (client-reported, labelled as such everywhere):
- Continuous full-screen map sessions (classic "UAV overlay" behaviour)
- Cycle detection: repeatedly keeping the map open just under the alert threshold gets flagged itself

RULE ENGINE - 10 configurable rules with sample-size floors and alert hysteresis:
- Headshot share of hits vs. players (default >40% at 30+ hits)
- Headshot-kill share vs. players and vs. AI (default >80% at 5+ kills: 5/5 flags, 4/5 does not)
- Accuracy per precision weapon class vs. players (>50% at 30+ shots) and vs. AI (>70% at 50+)
- Headshot share of hits vs. AI (>60% at 50+ hits)
- Single-body-zone concentration (>80% of all hits in one zone)
- Map session (60s) and map cycle detection (5 sessions with short gaps)
- Re-alert hysteresis: 5 minutes or +10 percentage points
Every threshold is a JSON value in the server profile - tune without touching code.

=== THE ADMIN CASE FILE (F4) ===

A personnel-file styled menu, only for authorized admins:
- Player list with kills, hit%, HS% and indication count (kills and HS share combined across players AND bots - aimbots work on bots too); flagged players are red and sorted on top; live 2s refresh
- Click a player: hit-zone silhouette heatmap (green-yellow-red, share + absolute hits per zone), tabular stats (kills/HS breakdown, per-weapon accuracy, distance bands, map usage), full indication history with rule ids
- Built-in LEGEND: every rule, value and category explained in-game
- Live alerts to every online admin as toast + private chat line (invisible to normal players)
- Key rebindable in Settings > Controls > WKI tab
- Ships in all 13 Reforger languages (EN, DE, FR, IT, ES, CS, PL, RU, UK, JA, KO, PT-BR, ZH)

=== ACCESS CONTROL (FAIL-CLOSED) ===

Only logged-in server ADMINISTRATORs (#login) and identity UUIDs on the allowlist file get anything at all:
- The menu key does nothing for normal players (server-gated open)
- All data requests are checked server-side against the requesting connection - client input is never trusted
- Alerts are sent exclusively to online admins
- Game Master / Session Admin roles have NO access by default (config flags to enable)

=== SERVER FILES ===

All runtime data lives in the server profile under WKI_AC/:
- WKI_AC_config.json - all thresholds and flags (auto-created with defaults)
- WKI_AC_admins.json - UUID allowlist (auto-created template)
- players/<uuid>.json - per-player lifetime stats, merged across restarts
- WKI_AC_suspects.json - persistent indication history; every entry carries a full stat snapshot from the alert moment (flat snake_case JSON: kills, headshot rates, zone distribution, distance bands, map usage, player name) - ready for external admin dashboards and websites
Console log lines are prefixed [WKI-AC]. See the README in the addon for the full admin/developer guide.

=== GOOD TO KNOW ===

- Stage 1 = detection only. Automated responses (warn/kick workflows) may come later as a separate, opt-in stage.
- Map data is client-reported and labelled "client-reported" in every display and alert - treat it as an indication, not proof.
- High headshot rates alone do not flag anyone: every precision rule has a minimum sample size, and thresholds are set so skilled marksmen stay clean while statistical outliers surface.
- Dependency-free, vanilla-only addon. No gamemode changes required; works alongside other mods.
- Roughly 35 self-tests run at startup and report to the server log.

License: custom WKI content license (see LICENSE.txt in the addon). Running the unmodified addon on servers - including cost-recovery monetized servers - is permitted; modification, repacking and redistribution are not.

(c) 2026 WOOKIE [WKI]

WKI_Rattrap

Server-side player stats & cheat detection: hit/headshot telemetry, distance bands, map analysis, rule-based admin alerts, in-game case-file menu and JSON export for web dashboards. No auto-bans.

WKI_Rattrap

1.0.2

1.0.1

1.0.0