# 💻| Plugin

El plugin Minecraft es la parte que se instala dentro del servidor y se encarga de convertir los diálogos publicados en conversaciones reales con NPCs.

Cuando un jugador interactúa con un NPC de Citizens, el plugin revisa si ese NPC tiene un diálogo publicado y sincronizado. Si existe, inicia la conversación dentro del juego.

### Qué hace el plugin

NPC-RealTalking permite:

* Detectar interacciones con NPCs.
* Buscar diálogos asociados al ID del NPC.
* Iniciar conversaciones en el chat.
* Mostrar opciones de respuesta.
* Permitir selección con mouse, números o selector.
* Aplicar efectos visuales.
* Controlar la cámara del jugador.
* Finalizar conversaciones por distancia, sneak o acciones del diálogo.
* Sincronizar diálogos desde el backend.
* Usar cache local si el backend no responde.

### Requisitos

El plugin necesita:

* Servidor Bukkit, Spigot o Paper.
* Citizens instalado.
* Acceso al backend.
* Una `PLUGIN_API_KEY` válida.
* Diálogos publicados desde el panel web.

### Interacción con NPCs

El jugador inicia una conversación interactuando con un NPC.

El plugin toma el ID interno del NPC de Citizens y busca un diálogo publicado para ese ID.

Si encuentra un diálogo, inicia la conversación.

Si no encuentra un diálogo, el comportamiento depende de esta opción:

```yaml
conversation:
  notify-missing-dialogue: true
```

Si está en true, el jugador verá un mensaje en el chat.

Si está en false, el plugin ignorará la interacción silenciosamente.

***

### Controles de conversación

El plugin puede usar distintos métodos para elegir opciones durante una conversación.

La configuración está en:

```yml
interaction: 
  use-mouse: true 
  use-numbers: true 
  use-selector: true 
  select-method: SWAP
```

### Selección con mouse

Si use-mouse está activado, el jugador puede hacer click sobre las opciones del chat.

```yml
interaction: 
  use-mouse: true
```

Este es el método más simple para la mayoría de jugadores.

### Selección con números

Si use-numbers está activado, el jugador puede elegir opciones usando teclas numéricas.

```yml
interaction: 
  use-numbers: true
```

Por ejemplo:

`1. ¿Quién eres?` \
`2. ¿Tienes una misión?` \
`3. Adiós.`

### Selector visual

Si use-selector está activado, el plugin muestra una flecha o indicador sobre la opción seleccionada.

```yml
interaction: 
  use-selector: true
```

La opción seleccionada puede confirmarse con el método configurado en **select-method**.

***

### Método de confirmación

El valor select-method define cómo se confirma una opción seleccionada.

Opciones disponibles:

```yml
select-method: CLICK
select-method: SWAP
select-method: DROP
```

Significado:

* CLICK: confirmar golpeando/clickeando.
* SWAP: confirmar con la tecla de intercambio de mano, normalmente F.
* DROP: confirmar con la tecla de tirar item, normalmente Q.

Configuración recomendada:

```yml
interaction: 
  use-selector: true 
  select-method: SWAP
```

***

### Cámara

Durante una conversación, el plugin puede ayudar a mantener la cámara del jugador enfocada hacia el NPC.

Configuración:

```yml
camera: 
  return-speed: 0.25 
  delay-to-return-seconds: 0.8
```

### Velocidad de retorno

return-speed controla qué tan rápido vuelve la cámara hacia el NPC.

```yml
camera: 
  return-speed: 0.25
```

Valores recomendados:

* 0.05: muy suave.
* 0.10: suave.
* 0.25: moderado.
* 1.0: casi instantáneo.

### Delay de retorno

delay-to-return-seconds define cuánto tiempo puede mover la cámara el jugador antes de que el plugin vuelva a enfocar al NPC.

```yml
camera: 
  delay-to-return-seconds: 0.8
```

Si usás:

`delay-to-return-seconds: 0.0`

la cámara intentará enfocar siempre al NPC.

### Efectos visuales

El plugin puede aplicar efectos al iniciar una conversación.

```yml
visuals:
  zoom:
    enabled: true
    level: 3

  darkness:
    enabled: true
```

### Zoom

El zoom usa un efecto visual para reducir el FOV del jugador.

```yml
visuals:
  zoom:
    enabled: true
    level: 3
```

Valores sugeridos:

* 1: leve.
* 3: moderado.
* 5: fuerte.

### Oscurecimiento

El oscurecimiento usa un efecto visual para dar más foco a la conversación.

```yml
visuals:
  darkness:
    enabled: true
```

Si querés conversaciones más limpias o menos invasivas, podés desactivarlo:

```yml
visuals:
  darkness:
    enabled: false
```

***

### Sonidos

El plugin puede reproducir sonidos al iniciar, terminar o seleccionar opciones.

```yml
sounds:
  start:
    enabled: false
    sound: "entity.experience_orb.pickup"
    volume: 1.0
    pitch: 1.0

  end:
    enabled: false
    sound: "ui.button.click"
    volume: 1.0
    pitch: 0.8

  select:
    enabled: true
    sound: "block.note_block.hat"
    volume: 0.5
    pitch: 1.5
```

Podés usar sonidos vanilla o sonidos custom de un resource pack.

### Distancia máxima

Si el jugador se aleja demasiado del NPC, la conversación termina automáticamente.

```yml
conversation:
  max-distance-blocks: 6.0
```

*Esto evita que una conversación quede activa cuando el jugador ya se fue.*

### Mensajes

Los mensajes principales se pueden modificar desde config.yml.

```yml
messages:
  no-dialogue: "&e[NPC-RealTalking] Este NPC no tiene un dialogo publicado sincronizado."
  conversation-start: "&aConversación iniciada con {npc}."
  conversation-hint: "&7Agáchate (Sneak) o aléjate para terminar la conversación."
  conversation-ended-sneak: "&cHas cortado la conversación."
  conversation-ended-far: "&cTe alejaste demasiado, la conversación ha terminado."
  conversation-ended-error: "&cLa conversación terminó inesperadamente."
  reload-success: "&a[NPC-RealTalking] Configuración recargada exitosamente."
  no-permission: "&cNo tienes permiso para usar este comando."
  command-usage: "&e[NPC-RealTalking] Uso: /{command} reload|sync"
```

Los colores usan el formato clásico de Minecraft con &.

Ejemplo:

```
&aVerde
&cRojo
&eAmarillo
&7Gris
```

### Sincronización

El plugin obtiene los diálogos publicados desde el backend.

Configuración:

```yml
backend:
  base-url: "https://nrt.mstudiosmc.online"
  api-key: "TU_PLUGIN_API_KEY"
  allow-insecure-http: false

  sync:
    auto-refresh-enabled: true
    auto-refresh-minutes: 5
    cache-file: "cache/dialogues.json"
```

### Sync manual

Para forzar una sincronización:

`/nrt sync`

### Recargar configuración

Después de editar config.yml, usá:

`/nrt reload`

Esto recarga la configuración sin reiniciar todo el servidor.

### Cache local

El plugin guarda una copia local de los diálogos sincronizados.

Por defecto:

`plugins/NPC-RealTalking/cache/dialogues.json`

Si el backend no responde, el plugin puede usar la última versión sincronizada.

### Flujo dentro del juego

```mermaid
flowchart TD
    A[Jugador interactúa con NPC] --> B[Plugin obtiene ID del NPC]
    B --> C{¿Hay diálogo sincronizado?}
    C -->|Sí| D[Inicia conversación]
    C -->|No| E[Mostrar mensaje o ignorar]
    D --> F[Jugador elige opción]
    F --> G[Ejecutar acción]
    G --> H{¿Continúa?}
    H -->|Sí| D
    H -->|No| I[Termina conversación]

```

### Buenas prácticas

* Usá SWAP como método de selección si querés evitar conflictos con clicks.
* Mantené allow-insecure-http: false en producción.
* Usá HTTPS en base-url.
* Ejecutá /nrt sync después de publicar diálogos.
* Probá cada NPC después de asignarle un diálogo.
* Desactivá notify-missing-dialogue si tenés muchos NPCs decorativos.
* Ajustá max-distance-blocks según el tipo de interacción.<br>

***

{% hint style="info" %}

### Problemas comunes

{% endhint %}

#### El NPC no abre conversación

Revisá que:

* El NPC tenga un diálogo publicado.
* El ID de Citizens coincida con el ID configurado en el panel.
* El plugin haya sincronizado con /nrt sync.
* El NPC esté spawneado.
* El backend esté disponible.

#### El plugin dice que el NPC no tiene diálogo

El plugin no encontró ningún diálogo publicado para ese ID de NPC.

Revisá:

* ID del NPC.
* Estado publicado del diálogo.
* Última sincronización.
* Archivo de cache.

#### No funcionan las opciones

Revisá la sección:

`interaction: use-mouse: true use-numbers: true use-selector: true select-method: SWAP`

Si usás selector, verificá que el método elegido no tenga conflicto con otros plugins.

#### No se conecta al backend

Revisá:

`backend: base-url: "https://nrt.mstudiosmc.online" api-key: "TU_PLUGIN_API_KEY" allow-insecure-http: false`

Si la API key es incorrecta, el backend responderá con error de autorización.

#### Los cambios no aparecen en Minecraft

Ejecutá:

`/nrt sync`

También verificá que el diálogo haya sido publicado desde el panel web.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wikinrt.mstudiosmc.online/inicio/or-plugin.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.