# Integrazione della chat personalizzata

Normalmente Verité filtra automaticamente i messaggi. Tuttavia, alcuni plugin di chat intercettano il normale evento di chat di Minecraft e gestiscono autonomamente l'invio dei messaggi.

Se il tuo plugin funziona in questo modo, Verité potrebbe non ricevere mai il messaggio originale da filtrare. In tal caso, dovresti far passare il messaggio attraverso Verité prima che il tuo plugin lo invii.

> **Questa guida è necessaria solo se il tuo plugin gestisce o sostituisce la normale chat di Minecraft.** I server che utilizzano la chat standard non richiedono alcuna configurazione aggiuntiva.

## Integrazione Java

Verité mette a disposizione una piccola API pubblica pensata appositamente per integrazioni come i sistemi di chat personalizzati.

### 1. Aggiungi Verité come dipendenza opzionale

Aggiungi Verité al tuo `plugin.yml`:

```yaml
softdepend:
  - Verite
```

L'utilizzo di una dipendenza opzionale garantisce che Verité venga caricato prima della tua integrazione quando è installato, senza renderlo obbligatorio per l'avvio del tuo plugin.

### 2. Verifica se l'API è disponibile

Se Verité è opzionale, verifica la disponibilità dell'API prima di utilizzarla:

```java
private static final boolean VERITE_AVAILABLE;

static {
    boolean available;

    try {
        Class.forName("teacommontea.api.VeriteFilter");
        available = true;
    } catch (ClassNotFoundException ignored) {
        available = false;
    }

    VERITE_AVAILABLE = available;
}
```

In questo modo, la tua integrazione può semplicemente non fare nulla quando Verité non è installato.

### 3. Filtra il messaggio

Prima che il tuo sistema di chat personalizzato invii un messaggio, passalo a `VeriteFilter`:

```java
if (VERITE_AVAILABLE) {
    FilterResult result = VeriteFilter.check(
        player.getUniqueId(),
        message
    );

    if (result.blocks()) {
        player.sendMessage(VeriteFilter.blockMessage());
        return;
    }
}
```

Questo è tutto ciò che serve per un'integrazione di base.

`check()` fa passare il messaggio attraverso il filtro di Verité e registra la segnalazione associata al giocatore. Se `.blocks()` restituisce `true`, il tuo sistema di chat dovrebbe impedire l'invio del messaggio.

### Utilizzare la categoria del filtro

A volte potresti voler sapere **perché** Verité ha rilevato un messaggio:

```java
FilterResult result = VeriteFilter.check(
    player.getUniqueId(),
    message
);

switch (result) {
    case CLEAN -> {
        // Invia normalmente
    }

    case SELF_HARM, ABUSE -> {
        // Gestisci in modo appropriato
    }

    default -> {
        // Normale contenuto bloccato
    }
}
```

I possibili risultati sono:

* `CLEAN`
* `BLOCK`
* `PROFANITY`
* `SELF_HARM`
* `ABUSE`

Qualsiasi risultato diverso da `CLEAN` fa sì che `.blocks()` restituisca `true`.

> **Importante:** `SELF_HARM` e `ABUSE` esistono per consentire di gestire questi messaggi in modo diverso dalle normali violazioni delle regole. Sconsigliamo di considerarli automaticamente come infrazioni della chat da punire.

### Rilevare i messaggi ripetuti

Se il tuo sistema di chat deve distinguere tra contenuti filtrati e rilevamento di messaggi ripetuti, utilizza l'overload che tiene conto delle ripetizioni:

```java
FilterOutcome outcome = VeriteFilter.check(
    player.getUniqueId(),
    message,
    true
);

if (outcome.blocks()) {
    if (outcome.repeat()) {
        player.sendMessage(VeriteFilter.repeatMessage());
    } else {
        player.sendMessage(VeriteFilter.blockMessage());
    }

    return;
}
```

`outcome.category()` fornisce la normale categoria del filtro, mentre `outcome.repeat()` indica se il messaggio è stato bloccato perché ripetuto.

## Filtrare altri contenuti degli utenti

L'API non è limitata alla chat.

Se il tuo plugin accetta contenuti scritti dagli utenti, come nickname, prefissi, tag delle squadre o campi simili, puoi farli passare attraverso lo stesso filtro:

```java
if (VeriteFilter.check(player.getUniqueId(), nickname).blocks()) {
    // Rifiuta il nickname
}
```

Per il testo che non appartiene a un giocatore specifico, utilizza `VeriteFilter.ANONYMOUS`:

```java
FilterResult result = VeriteFilter.check(
    VeriteFilter.ANONYMOUS,
    text
);
```

I controlli anonimi restituiscono comunque la categoria di filtro appropriata, ma non aggiungono alcuna segnalazione al registro di un giocatore.

---

# Utilizzare Verité con Skript

Se il tuo sistema di chat personalizzato è scritto in Skript, non è necessario interagire con l'API Java.

Con **Verité e Skript installati**, la sintassi di filtraggio di Verité è disponibile automaticamente.

## Filtrare la chat personalizzata

Se il tuo script gestisce già autonomamente l'invio dei messaggi di chat, controlla il messaggio prima di inviarlo:

```vb
if {_msg} is blocked for player:
    send block message to player
    stop
```

Includere `for player` indica a Verité chi ha inviato il messaggio e registra la segnalazione associata a quel giocatore.

Senza un giocatore:

```vb
if {_text} is blocked:
    # Rifiuta il testo
```

Verité esegue un semplice controllo del filtro senza registrare alcuna segnalazione. Questo è utile per elementi come nomi, tag, cartelli o altri testi che non dovrebbero essere conteggiati a carico di un giocatore specifico.

## Verificare perché un messaggio è stato bloccato

Per un maggiore controllo, recupera il risultato del filtro:

```vb
set {_result} to filter result of {_msg} for player

if {_result} is "self_harm":
    # Gestisci separatamente
    stop

if {_result} is "abuse":
    # Gestisci separatamente
    stop

if {_result} is not "clean":
    send block message to player
    stop
```

Il risultato sarà uno dei seguenti:

`clean`, `block`, `profanity`, `self_harm` o `abuse`

> **Importante:** Valuta la possibilità di gestire `self_harm` e `abuse` separatamente dalle normali violazioni di moderazione, anziché punire automaticamente il giocatore.

## Controllare il numero di segnalazioni di un giocatore

Puoi anche recuperare il numero di messaggi che Verité ha segnalato per un giocatore:

```vb
set {_flags} to message flags of player
```

Il tuo sistema di moderazione può utilizzare questo valore se desideri adottare un comportamento diverso in caso di violazioni ripetute.

## Riferimento della sintassi Skript

```vb
%string% is blocked [for %-player%]
%string% is not blocked [for %-player%]

filter result of %string% [for %-player%]

block message

message flags of %player%
```

Il giocatore opzionale è importante:

**Con un giocatore:** il risultato del filtro viene registrato per quel giocatore.

**Senza un giocatore:** Verité controlla solamente il testo e non registra alcuna segnalazione.

---

## Riferimento API

L'API pubblica si trova nel package:

```text
teacommontea.api
```

La classe principale per le integrazioni della chat è:

```java
VeriteFilter
```

I metodi utili includono:

```java
VeriteFilter.check(UUID player, String message)
VeriteFilter.check(UUID player, String message, boolean repeatAware)

VeriteFilter.count(UUID player)

VeriteFilter.blockMessage()
VeriteFilter.repeatMessage()
VeriteFilter.selfHarmMessage()

VeriteFilter.blockNotice(FilterResult result, String message)
```

`VeriteFilter.ANONYMOUS` può essere utilizzato per filtrare testo che non è associato a un giocatore.

Verité mette inoltre a disposizione le proprie utilità di normalizzazione per le integrazioni che ne hanno bisogno, tra cui normalizzazione degli accenti, rimozione delle entità, riduzione dei caratteri ripetuti, fingerprinting e rimozione dei caratteri alle estremità. Queste funzioni sono thread-safe e generalmente **non devono essere chiamate manualmente** prima di utilizzare `check()`.

Per la maggior parte delle integrazioni di chat personalizzate, tutto ciò che serve è:

```java
if (VeriteFilter.check(player.getUniqueId(), message).blocks()) {
    // Non inviare il messaggio
}
```

Verité si occupa del resto.