📖 FFTopPlugin - Wiki Oficial

📚 Tabla de Contenidos

📌 Introducción

FFTopPlugin es un complemento avanzado diseñado para servidores de Minecraft que desean llevar un registro detallado y visualmente atractivo de las estadísticas de sus jugadores. Este plugin permite la recopilación y presentación de datos de asesinatos, muertes y bloques minados, asegurando una competencia sana y emocionante entre los jugadores.

🔹 ¿Qué hace FFTopPlugin?

FFTopPlugin gestiona y muestra estadísticas de los jugadores en tiempo real, utilizando NPCs y hologramas para representar el ranking de los mejores jugadores en cada categoría. Con una interfaz sencilla y comandos intuitivos, los administradores pueden configurar y personalizar la forma en que se presentan estos datos en el servidor.

🔹 Características principales
- Registro automático de estadísticas como **asesinatos, muertes y bloques minados**.
- Creación de **NPCs interactivos** con el soporte de Citizens, mostrando a los mejores jugadores del servidor.
- Integración con **PlaceholderAPI**, permitiendo utilizar los datos del plugin en otras partes del servidor.
- Comandos accesibles para los jugadores y herramientas avanzadas de administración para moderadores.
- Configuración completamente personalizable mediante config.yml, permitiendo modificar mensajes, formato de hologramas y más.
- Compatibilidad con versiones de **Spigot y Paper** desde 1.16 hasta 1.20+.
🔹 ¿Por qué usar FFTopPlugin?

Los servidores de Minecraft competitivos y basados en estadísticas se benefician enormemente de un sistema de ranking automatizado. FFTopPlugin no solo proporciona una manera eficiente de rastrear estadísticas, sino que también mejora la experiencia visual y competitiva del servidor, motivando a los jugadores a mejorar su rendimiento y alcanzar los primeros lugares en las tablas de clasificación.
🔧 Instalación
1. Descarga el archivo FFTopPlugin.jar y colócalo en la carpeta plugins de tu servidor.
2. Asegúrate de tener instalado **Citizens** y **PlaceholderAPI** (opcional para placeholders).
3. Reinicia el servidor para generar los archivos de configuración.
4. Edita el archivo config.yml según tus preferencias.
5. ¡Listo! Usa /fftop para comenzar.

🎮 Comandos

FFTopPlugin proporciona una serie de comandos útiles tanto para jugadores como para administradores del servidor. A continuación, se presentan los comandos disponibles junto con ejemplos detallados de uso:

Comando	Descripción	Permiso
`/create top <tipo> <posición>`	Crea un NPC con un holograma mostrando un jugador en el ranking.	`fftop.create`
`/fftop kills`	Muestra el ranking de asesinatos.	`fftop.use`
`/fftop deaths`	Muestra el ranking de muertes.	`fftop.use`
`/fftop blocks`	Muestra el ranking de bloques minados.	`fftop.use`
`/fftop leaderboard`	Muestra el top general.	`fftop.use`
`/fftop reset <jugador>`	Reinicia las estadísticas de un jugador.	`fftop.admin`
`/fftop select`	Selecciona un NPC cercano para editarlo.	`fftop.admin`
`/fftop remove`	Elimina el NPC seleccionado y su holograma.	`fftop.admin`
`/fftop select`	Selecciona un NPC cercano para editarlo.	`fftop.admin`
`/fftop reload`	Recarga la configuración y datos del plugin.	`fftop.admin`

📌 Ejemplos de Uso

Mostrar el ranking de asesinatos
```
/fftop kills
```
Muestra el top de jugadores con más asesinatos.

Mostrar el ranking de muertes
```
/fftop deaths
```
Muestra el top de jugadores con más muertes.

Mostrar el ranking de bloques minados
```
/fftop blocks
```
Muestra el top de jugadores con más bloques minados.

Restablecer las estadísticas de un jugador
```
/fftop reset Steve
```
Restablece las estadísticas del jugador llamado Steve.
Seleccionar un NPC cercano
```
/fftop select
```
Selecciona un NPC cercano para editarlo o eliminarlo.

Eliminar un NPC seleccionado y su holograma
```
/fftop remove
```
Elimina el NPC seleccionado junto con su holograma.

Recargar la configuración del plugin
```
/fftop reload
```
Recarga los archivos de configuración y datos del plugin.

Crear un NPC con el jugador en el primer lugar del ranking de asesinatos
```
/create top kills 1
```
Genera un NPC en la ubicación actual del jugador que muestra al jugador número 1 en asesinatos.
Crear un NPC con el jugador en la tercera posición del ranking de bloques minados
```
/create top blocks 3
```
Genera un NPC mostrando al jugador que ocupa la tercera posición en el ranking de bloques minados.
Ver la tabla de clasificación general
```
/fftop leaderboard
```
Muestra la clasificación combinada de los mejores jugadores en todas las estadísticas.

🤖 NPCs con Hologramas

FFTopPlugin permite la creación de NPCs que representan a los jugadores más destacados en diferentes categorías (asesinatos, muertes y bloques minados). Estos NPCs se generan con el soporte del plugin Citizens y pueden incluir hologramas personalizados sobre sus cabezas para mostrar información relevante.

📌 ¿Cómo crear un NPC con holograma?

Para crear un NPC con un holograma que muestre el ranking de los jugadores, usa el siguiente comando:
```
/create top <tipo> <posición>
```
Ejemplo:
```
/create top kills 1
```
Este comando generará un NPC en tu ubicación que representa al jugador con más asesinatos en el servidor.

📌 Características de los NPCs generados
- Apariencia: Se pueden personalizar con skins basadas en los jugadores reales del top.
- Actualización Automática: El plugin actualiza la información periódicamente para reflejar cambios en el ranking.
- Compatibilidad con Hologramas: Se pueden agregar líneas de texto personalizadas sobre el NPC para mostrar estadísticas.
📌 Configuración de Hologramas

Los hologramas pueden ser configurados desde el archivo config.yml. Permiten mostrar información en capas flotantes sobre los NPCs. Aquí tienes un ejemplo de cómo modificar las líneas que aparecen sobre los NPCs:
```
hologram:
  initial-height: 1.5
  lines:
    - "&6▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬"
    - "&e&l%player%"
    - "&7➟ &6Position: &f#%position%"
    - "&7➟ &aScore: &f%value%"
    - "&b✧･ﾟ: *✧ Top &c%type% &bPlayer ✧*:･ﾟ✧"
    - "&6▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬"
```
📌 Ejemplos de Configuración de Hologramas

Mostrar un mensaje personalizado en los hologramas:
```
hologram:
lines:
  - "&5✧･ﾟ: *✧ &d%type% &5TOP &dPlayer &5✧*:･ﾟ✧"
  - "&b✦ %player% ✦"
  - "&5| &fRank: &d#%position%"
  - "&5| &fPuntos: &b%value%"
  - "&5♡･ﾟ: *✧ &d#%position% &5en el ranking &dMístico &5✧*:･ﾟ♡"
```
Este formato resalta al mejor jugador con un diseño llamativo.

Añadir bordes decorativos en los hologramas:
```
hologram:
lines:
  - "&8█▓▒░ &cTOP &6%type% &8░▒▓█"
  - "&e⬛ &f%player% &e⬛"
  - "&a◼ &7Posición: &f#%position%"
  - "&c◼ &7Puntaje: &f%value%"
  - "&8█▓▒░ &6#%position% &een el ranking &8░▒▓█"
```
Usar líneas de separación mejora la visibilidad del holograma.

Reducir la cantidad de información mostrada:
```
hologram:
  lines:
    - "&eTop %type%"
    - "&a%player%"
```
Útil para servidores que prefieren menos texto en pantalla.

Ajustar la altura del holograma para mayor visibilidad:
```
hologram:
  initial-height: 2.0  # Aumenta la altura para evitar que se solape con el NPC
```
Si los hologramas aparecen demasiado bajos, puedes ajustar esta configuración.

Desactivar hologramas en NPCs específicos:
```
hologram:
  enabled: false
```
Si prefieres no usar hologramas en ciertos NPCs, esta opción los desactiva.

📌 Ejemplos de Uso

Crear un NPC para el primer puesto de asesinatos:
```
/create top kills 1
```
Crea un NPC con un holograma mostrando el jugador con más asesinatos.

Crear un NPC para el tercer puesto de bloques minados:
```
/create top blocks 3
```
Muestra al jugador en la tercera posición del ranking de bloques minados.

Eliminar un NPC y su holograma correctamente:
```
/fftop remove
```
Este comando borra el NPC y su holograma. No uses comandos normales de Citizens, ya que dejarán hologramas flotando.

Seleccionar un NPC para edición:
```
/fftop select
```
Te permite seleccionar un NPC cercano para administrarlo.

Actualizar manualmente los NPCs del top:
```
/fftop reload
```
Recarga la configuración y actualiza los datos mostrados en los NPCs.

❗ Importante sobre la eliminación de NPCs

Si eliminas los NPCs con los comandos normales de Citizens, los hologramas NO se eliminarán correctamente y quedarán flotando en el aire. Para eliminarlos de forma segura, usa el comando:
```
/fftop remove
```
Este comando se asegura de borrar tanto el NPC como su holograma, evitando errores visuales en el servidor.

Los NPCs y hologramas son una forma efectiva de resaltar a los mejores jugadores del servidor, agregando un aspecto visual atractivo y competitivo.

📂 Configuración (config.yml)

El archivo de configuración config.yml permite personalizar todos los aspectos del plugin, desde los mensajes que aparecen en el chat hasta la apariencia de los hologramas y la funcionalidad de los menús. A continuación, te mostramos algunos ejemplos detallados de configuración y sus efectos en el servidor.

📌 Ejemplos de configuración y ajustes

Modificar los mensajes del plugin


              # ============================================
              # 🎯 FFTopPlugin - Official Configuration
              # 🔹 Developed by: ElAntiguo
              # 🔹 Version: 1.0.0
              # 🔹 Compatible with: Spigot/Paper 1.16 - 1.20+
              # 🔹 Description: 
              #    This plugin allows managing player rankings based on statistics
              #    such as kills, deaths, and mined blocks.
              #    Also enables creating NPCs with holograms displaying top positions.
              #
              # 🚨 IMPORTANT:
              #  - Edit this file carefully.
              #  - Do not delete entire sections, only change values.
              #  - Use "&" for color codes in messages.
              # ============================================
              
              # 📢 Plugin messages that will appear in server chat
              messages:
                # ⛔ Commands and errors
                command-player-only: "&cThis command can only be executed by players."
                invalid-subcommand: "&cInvalid subcommand. Use: /fftop "
              
                # 🎮 NPC Creation
                create-command-usage: "&eUsage: /create top  "
                create-command-example: "&eExample: /create top kills 1"
                invalid-position-number: "&cPosition must be a valid number."
                invalid-top-type: "&cInvalid top type. Use kills, deaths or blocks."
                no-stats-available: "&cNo data available for this top."
                position-unavailable: "&cSpecified position is out of range."
                npc-spawn-failed: "&cFailed to spawn NPC."
                npc-created: "&aNPC created successfully: %s"
              
                # 🏆 Statistics Commands
                fftop-usage: "&eUsage: /fftop "
                reset-usage: "&eUsage: /fftop reset "
                stats-reset: "&aStatistics reset for %s."
                stats-invalid-player: "&cInvalid player name."
                stats-invalid-uuid: "&cCould not get UUID for: %player%"
                stats-increment: "📊 %statType% incremented for: %player% (Total: %value%)"
                # 📊 NPC and Hologram Management
                npc-selected: "&aYou have selected NPC: %s"
                no-npc-nearby: "&cNo nearby NPC found."
                no-npc-selected: "&cNo NPC selected."
                selected-npc-not-found: "&cSelected NPC not found or has been removed."
                npc-and-hologram-removed: "&aNPC and hologram removed successfully."
                no-npc-skin: "&cNo skin available for NPC."
                error-setting-npc: "Error setting up NPC:"
                hologram-updated: "&aHologram updated successfully."
                no-data-available: "&cNo data available to update."
              
                # 🛠️ System Configuration
                config-reloaded: "&aConfiguration reloaded."
                data-reloaded: "&aData reloaded."
                plugin-enabled: "&aFFTop has been enabled successfully."
                plugin-error: "&cError enabling FFTop."
                data-saved-automatically: "&aData saved automatically."
                stats-file-not-found: "&cStatistics file not found."
                stats-loaded: "&aStatistics loaded successfully."
                stats-saved: "&aStatistics saved successfully."
                stats-save-error: "&cError saving statistics: %error%"
              
                # 📌 Leaderboard Messages
                leaderboard-title: "&6=== General Ranking ==="
                leaderboard-entry: "&e%player%: &f%value%"
              
                # 🔄 Location and World Errors
                invalid-serialized-location: "&cInvalid serialized location: null or empty."
                invalid-location-format: "&cInvalid serialized location format: %location%"
                invalid-world: "&cWorld not found: %world%"
              
              # ============================================
              # 🏆 Hologram Configuration
              # ============================================
              hologram:
                initial-height: 0  # Optimal height adjustment for better visibility
                lines:
                  - "&6▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬"
                  - "&e&l%player%"
                  - "&7➟ &6Position: &f#%position%"
                  - "&7➟ &aScore: &f%value%"
                  - "&b✧･ﾟ: *✧ Top &c%type% &bPlayer ✧*:･ﾟ✧"
                  - "&6▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬"
                  
              
              
              # ============================================
              # 📊 Menu Configuration
              # ============================================
              menu:
                titles:
                  kills: "&cTop Killers"
                  deaths: "&4Top Deaths"
                  blocks: "&6Top Miners"
                item-statistic: "&eStatistic "
                next-page: "&aNext Page"
                filler:
                  material: "GRAY_STAINED_GLASS_PANE"  # 🛑 Do not change if you want to keep the gray background
                  name: " "
              
              # ============================================
              # 🔍 Log Configuration
              # ============================================
              logs:
                enabled: true  # 🔄 Enable (true) or disable (false) plugin logs

Cambia los mensajes que el plugin envía al chat para mayor personalización.

Ajustar la altura de los hologramas sobre los NPCs


hologram:
  initial-height: 1.5  # Ajusta la altura del holograma sobre el NPC

Si los hologramas aparecen muy altos o bajos, este ajuste te ayudará.

Modificar el contenido de los hologramas


hologram:
  lines:
    - "&6=== Estadísticas ==="
    - "&eJugador: %player%"
    - "&aRanking: %position%"
    - "&bPuntos: %value%"

Personaliza los textos de los hologramas que aparecen sobre los NPCs.

Configurar los títulos de los menús de clasificación


menu:
  titles:
    kills: "&cTop Asesinos"
    deaths: "&4Top Muertes"
    blocks: "&6Top Mineros"

Define el título que verán los jugadores cuando abran un menú de estadísticas.

Personalizar el relleno de los menús


menu:
  filler:
    material: "GRAY_STAINED_GLASS_PANE"
    name: " "

Cambia el material de los espacios vacíos en los menús.

Ajustar el intervalo de actualización automática de datos


update-interval: 10

Controla cada cuántos segundos se actualizan los datos de los NPCs.

Configurar el formato del leaderboard


messages:
  leaderboard-title: "&6=== Ranking General ==="
  leaderboard-entry: "&e%player%: &f%value%"

Personaliza el formato en que se muestra la tabla de clasificación en el chat.

Eliminar registros innecesarios en consola


logs:
  enabled: false

Si no quieres ver mensajes del plugin en la consola, puedes desactivarlos.

📖 FFTopPlugin - Wiki Oficial

📚 Tabla de Contenidos

📌 Introducción

🔹 ¿Qué hace FFTopPlugin?

🔹 Características principales

🔹 ¿Por qué usar FFTopPlugin?

🔧 Instalación

🎮 Comandos

📌 Ejemplos de Uso

🤖 NPCs con Hologramas

📌 ¿Cómo crear un NPC con holograma?

📌 Características de los NPCs generados

📌 Configuración de Hologramas

📌 Ejemplos de Configuración de Hologramas

📌 Ejemplos de Uso

❗ Importante sobre la eliminación de NPCs

📂 Configuración (config.yml)

📌 Ejemplos de configuración y ajustes

Modificar los mensajes del plugin

Ajustar la altura de los hologramas sobre los NPCs

Modificar el contenido de los hologramas

Configurar los títulos de los menús de clasificación

Personalizar el relleno de los menús

Ajustar el intervalo de actualización automática de datos

Configurar el formato del leaderboard

Eliminar registros innecesarios en consola