Gestisci ShieldPlay con consapevolezza.

Cosa fa ShieldPlay

ShieldPlay unisce un agente Minecraft compatibile con Paper e un dashboard cloud. L’agente osserva eventi di gioco autorevoli lato server, invia telemetria e violazioni limitate; il dashboard offre a owner e staff un unico punto per evidenze, salute server, accessi e notifiche.

Il prodotto segue un principio prudente: un flag è evidenza da rivedere, non un verdetto automatico. Le euristiche combat e i risultati X-Ray restano per revisione staff; una punizione automatica richiede evidenza indipendente, sostenuta e separatamente idonea.

Prima dell’installazione

Per le build moderne supportate usa un server Paper/Purpur compatibile con Minecraft 1.20.6–1.21.x e Java 21.

Requisito	Motivo
Java 21	L’agente corrente è compilato e testato con Java 21.
Server Paper/Purpur 1.20.6–1.21.x	Le build moderne usano eventi Paper/Bukkit e bounding box del server.
Account Owner dashboard	L’Owner crea e ruota la chiave di connessione specifica del server.
HTTPS in uscita	Il game server deve raggiungere https://api.shieldplay.it/api/v1.

Non inserire nel file Minecraft token di sessione dashboard o credenziali Stripe. All’agente serve solo la sua chiave API specifica del server.

Installa e collega l’agente

Scarica dalla pagina Download sia il JAR ShieldPlay sia ProtocolLib 5.4.0.
Arresta Minecraft e copia entrambi i JAR nella cartella plugins.
Avvia una volta per creare la configurazione, quindi arresta il server oppure usa reload dopo la modifica.
Nel dashboard registra il server Minecraft e crea o ruota la sua API key.
Imposta URL cloud e key nel file dell’agente, avvia il server e verifica la connessione nel dashboard.

plugins/AntiCheatSaaS/config.yml

cloud:
  api-base-url: "https://api.shieldplay.it/api/v1"
  api-key: "INCOLLA_LA_CHIAVE_SPECIFICA_DEL_SERVER"
  heartbeat-interval-seconds: 30
  request-timeout-seconds: 12

Tratta api-key come un segreto: non pubblicarla in screenshot, repository Git, Discord o codice client.

Comandi e accesso

Il permesso di amministrazione in-game è anticheat.admin. L’accesso staff del dashboard è sincronizzato separatamente per UUID. Mantieni il roster ristretto e usa esenzioni per-check solo per test controllati o strumenti operativi fidati.

Comando	Scopo
/anticheat gui	Apre la GUI in-game per un amministratore autorizzato.
/anticheat reload	Ricarica la configurazione locale, inclusa lista X-Ray e presentazione Discord X-Ray.
/anticheat status	Mostra connessione locale e stato operativo di base.

Policy di rilevamento e revisione

ShieldPlay distingue deliberatamente raccolta dati, alert e sanzione. Un segnale a bassa confidence può essere registrato senza aumentare il rischio o aprire un incidente. Le correlazioni aiutano lo staff a capire comportamenti ripetuti, ma non sono prova autonoma per una punizione automatica.

Il check Hitbox geometrico traccia il raggio dagli occhi contro una AABB del bersaglio espansa lato server. Salta contesti instabili come ping alto, TPS basso, transizioni recenti e stati di movimento speciali. Paper fornisce geometria server al momento dell’evento, non un rewind completo della visuale client, quindi il risultato è intenzionalmente review-only.

Configura X-Ray con cautela

X-Ray è valutato solo alla rottura di blocchi monitorati. Il pattern deve rispettare insieme volume di blocchi, minerali rari non esposti, densità e durata del burst. I minerali esposti ad aria, acqua o lava sono esclusi per ridurre falsi positivi.

checks.movement.xray in config.yml

checks:
  movement:
    xray:
      rare-ores:
        - DIAMOND_ORE
        - DEEPSLATE_DIAMOND_ORE
        - EMERALD_ORE
        - DEEPSLATE_EMERALD_ORE
        - ANCIENT_DEBRIS

L’Owner può scegliere anche dal dashboard Minecraft Staff i materiali vanilla consentiti. Rimuovendo l’override dashboard torna attiva la lista in config.yml.

Staff, lingua ed esenzioni

L’Owner gestisce il roster staff nel modulo Minecraft Staff. Può scegliere italiano o inglese per GUI e alert in-game e assegnare a uno UUID staff un’esenzione per un singolo check. Le esenzioni sono esatte, controllate prima di profilazione e report e non usano wildcard.

Discord e webhook in uscita

Crea un webhook del canale in Discord, poi aggiungilo in Dashboard → Webhooks e iscrivilo a Flag X-Ray. ShieldPlay trasforma gli endpoint Discord in embed con giocatore, server, minerale e stato review-only. I webhook generici mantengono invece un envelope JSON per sistemi esterni.

Presentazione Discord X-Ray e anti-spam

notifications:
  discord:
    xray:
      enabled: true
      embed:
        title: "ShieldPlay · Flag X-Ray"
        description: "{player} ha minato {hidden_ores} minerali non esposti. Ultimo: {ore}."
        color: "#F59E0B"
      rate-limit:
        cooldown-seconds: 60

Il cooldown Discord X-Ray è limitato a 15–600 secondi per webhook. Durante il cooldown i flag restano salvati; sono soppresse solo le notifiche ripetute.

Checklist operativa

Controlla heartbeat, TPS e versione agente dopo ogni update.
Rivedi nuove violazioni insieme a ping, TPS, esenzioni contestuali ed evidenze precedenti prima di agire.
Usa l’unban dal dashboard per mantenere allineati punizione persistita e pardon profilo Paper.
Ruota una server key esposta e aggiorna solo il config.yml di quel server.
Usa Test in Webhooks prima di affidarti a un canale alert durante un incidente.

Risoluzione problemi

Problema	Controlli da eseguire
Agente offline	Verifica cloud.api-base-url, API key, HTTPS in uscita, registrazione server e selezione server nel dashboard.
Nessun alert X-Ray	Verifica check attivo, materiale monitorato, soglie pattern e assenza di esenzioni staff.
Discord non riceve	Usa Test Webhook, seleziona Flag X-Ray, lascia il webhook attivo e verifica URL e permessi canale.
Flag inatteso	Non bannare da un singolo alert. Valuta metriche, latenza, TPS, contesto e cronologia incidente; modifica configurazione solo dopo revisione.