Player Kits

PlayerKitsPlugin para Hytale

Un potente plugin de gestión de kits, rico en características, para servidores de Hytale que permite a los administradores crear, gestionar y distribuir conjuntos de objetos predefinidos a los jugadores con amplias opciones de personalización.

Características

Funcionalidad Principal

• Crear Kits: Guarda los inventarios de los jugadores como kits reutilizables con un solo comando
• Soporte Multi-Inventario: Los kits incluyen almacenamiento, armadura, barra de acceso rápido, espacios de utilidad y artículos de mochila
• Acceso Basado en Permisos: Asigna permisos específicos a cada kit
• Sistema de Tiempo de Espera: Configura tiempos de espera personalizados por kit (desde segundos hasta horas)
• Distribución Fácil: Entrega kits a ti mismo o a otros jugadores con comandos intuitivos

Herramientas Administrativas

• Sistema de Importación/Exportación: Comparte kits entre servidores utilizando archivos JSON
• Operaciones por Lotes: Guarda, recarga o elimina múltiples kits a la vez
• Gestión de Tiempos de Espera: Visualiza y restablece los tiempos de espera de los jugadores a través de comandos
• Información del Kit: Vista detallada del contenido y metadatos del kit
• Almacenamiento Basado en Archivos: Cada kit se guarda como un archivo JSON individual para fácil respaldo

Experiencia del Jugador

• Navegador de Kits: Lista todos los kits disponibles con soporte de paginación
• Visualización de Tiempos de Espera: Seguimiento en tiempo real de los tiempos de espera con tiempo restante formateado
• Retroalimentación de Permisos: Mensajes claros cuando los jugadores carecen de los permisos requeridos
• Seguridad del Inventario: Aplicación de kits no destructiva que respeta los artículos existentes

Comandos

Comandos de Jugador

Comando
Permiso
Descripción

/kit list [page]
razorplay.playerkitsplugin.command.kit.list
Lista todos los kits disponibles con paginación

/kit get <kit>
razorplay.playerkitsplugin.command.kit.get
Reclama un kit para el cual tienes permiso

/kit info <kit>
razorplay.playerkitsplugin.command.kit.info
Ve información detallada sobre un kit

Comandos de Administrador

Comando
Permiso
Descripción

/kit create <id> <name> [description]
razorplay.playerkitsplugin.command.kit.create
Crea un kit a partir de tu inventario actual

/kit delete <kit> --confirm
razorplay.playerkitsplugin.command.kit.delete
Elimina permanentemente un kit

/kit give <player> <kit>
razorplay.playerkitsplugin.command.kit.give
Entrega un kit a otro jugador

/kit reload
razorplay.playerkitsplugin.command.kit.reload
Recarga todos los kits desde el disco

/kit save
razorplay.playerkitsplugin.command.kit.save
Guarda todos los kits en el disco

/kit import <file>
razorplay.playerkitsplugin.command.kit.import
Importa un kit desde un archivo JSON

/kit export <kit> [path]
razorplay.playerkitsplugin.command.kit.export
Exporta un kit a un archivo JSON

Gestión de Tiempos de Espera

Comando
Permiso
Descripción

/kit cooldown clear
razorplay.playerkitsplugin.command.kit.cooldown.clear
Elimina todos los tiempos de espera para todos los jugadores

/kit cooldown check <player> <kit>
razorplay.playerkitsplugin.command.kit.cooldown.check
Verifica el tiempo de espera de un jugador para un kit

/kit cooldown reset <player>
razorplay.playerkitsplugin.command.kit.cooldown.reset
Restablece todos los tiempos de espera para un jugador específico

🔧 Configuración

Estructura de Archivos

mods/RazorPlay_PlayerKitsPlugin/
├── kits/                 # Archivos JSON de kits individuales
│   ├── starter.json
│   ├── warrior.json
│   └── ...
├── cooldowns.json        # Datos de tiempos de espera de jugadores

Propiedades del Kit

Cada kit puede ser configurado con:

• ID: Identificador único (sin espacios/diagonales)
• Nombre: Nombre mostrado a los jugadores
• Descripción: Descripción opcional
• Permiso: Nodo de permiso requerido (dejar vacío para público)
• Tiempo de Espera: Tiempo entre usos en segundos (0 para sin tiempo de espera)
• Artículos: Inventario completo incluyendo armadura y mochila

Nodos de Permiso

razorplay.playerkitsplugin.command.kit.*          # Todos los comandos de kits
razorplay.playerkitsplugin.command.kit.create     # Crear kits
razorplay.playerkitsplugin.command.kit.delete     # Eliminar kits
razorplay.playerkitsplugin.command.kit.give       # Dar kits a otros
razorplay.playerkitsplugin.command.kit.reload     # Recargar kits
razorplay.playerkitsplugin.command.kit.import     # Importar kits
razorplay.playerkitsplugin.command.kit.export     # Exportar kits
razorplay.playerkitsplugin.command.kit.cooldown.* # Todos los comandos de tiempos de espera

Permisos de Kit Personalizados

Crea permisos personalizados para kits específicos:
kit.mykit.use # Ejemplo: Permiso personalizado para “mykit”

🔌 Integración de API

PlayerKitsPlugin proporciona una API completa para desarrolladores

Obtén la instancia de KitAPI 
KitAPI kitAPI = PlayerKitsPlugin.getKitAPI();

Crea kits programáticamente 
Kit kit = kitAPI.createKit("id", "name", player, "description");

Entrega kits a los jugadores 
boolean success = kitAPI.giveKit(player, playerRef, "kitId");

Sistema de eventos para comportamiento personalizado 
kitAPI.registerListener(new KitEventListener() {
    @Override
    public void onKitClaimed(KitClaimEvent event) {
        // Lógica personalizada cuando se reclama un kit
    }
});

Verificación de permisos asíncrona 
CompletableFuture<List<Kit>> availableKits = kitAPI.getAvailableKitsAsync(
    playerId, 
    (uuid, permission) -> checkPermissionAsync(uuid, permission)
);

🎮 Ejemplos de Uso

1. Creando un Kit Inicial

/kit create starter Starter “Herramientas y armadura básicas para nuevos jugadores”

2. Configurando una Recompensa Diaria

Crea el kit con un tiempo de espera de 24 horas:
/kit create daily Daily

Edita el archivo JSON para establecer “Cooldown”: 86400 (24 horas en segundos)

Establece el permiso: “Permission”: “kit.daily.use”

3. Importando Kits de la Comunidad

/kit import /path/to/community_kit.json

📋 Instalación

Descarga el último PlayerKitsPlugin.jar

Colócalo en el directorio mods/ de tu servidor Hytale

Inicia o recarga tu servidor

El plugin creará automáticamente los directorios y archivos necesarios

🔍 Detalles Técnicos

Sistema de Almacenamiento

• Kits: Archivos JSON individuales en mods/PlayerKitsPlugin/kits/
• Tiempos de Espera: Archivo JSON centralizado con seguimiento basado en jugadores
• Serialización: Utiliza el sistema de Codec de Hytale para una serialización de objetos confiable

Características de Rendimiento

• Cacheo: Cacheo de disponibilidad de kits específicos de jugadores (TTL de 30 segundos)
• Operaciones Asíncronas: Entrada/salida de archivos no bloqueante y verificación de permisos
• Carga Eficiente: Carga perezosa de archivos de kits bajo demanda

Características de Seguridad

• Validación de Entrada: IDs de kits sanitizados para prevenir problemas en el sistema de archivos
• Manejo de Errores: Manejo de excepciones completo con registro detallado
• Integridad de Datos: Respaldo automático a través de archivos de kits individuales

🐛 Solución de Problemas

Problemas Comunes

“Kit no encontrado”: Asegúrate de que el ID del kit sea correcto y sensible a mayúsculas

Permiso denegado: Verifica los nodos de permisos y la configuración de LuckPerms/grupos

Inventario no guardado: Verifica que el jugador tenga artículos en el inventario al crear el kit

Errores de archivo: Verifica los permisos de archivo en el directorio mods/RazorPlay_PlayerKitsPlugin/

Registros

Revisa los registros del servidor para obtener información detallada sobre errores:

• [PlayerKitsPlugin] los mensajes con prefijo muestran la actividad del plugin
• Las advertencias indican problemas no críticos
• Los errores requieren atención inmediata

🤝 Contribuyendo

¿Encontraste un error o tienes una solicitud de función? ¡Por favor, abre un problema en nuestro repositorio de GitHub!

📄 Licencia

Este plugin se proporciona bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.

🙏 Créditos

Desarrollador: Razorplay
Pruebas: ¡Tus contribuciones son bienvenidas!