MANUAL DEL ADMINISTRADOR & WIKI TÉCNICA

WarriorClasses — Sistema de Clases & Combate Táctico

WarriorClasses es un motor de combate RPG nativo y liviano para servidores Minecraft Purpur/Paper. Integra 5 clases especializadas, 35 habilidades, pericia de armas con reducción dinámica de cooldowns, mitigación de daño vanilla (Swing Softening), estados alterados (Sangrado, Herida Profunda) y un Motor de Amenaza Universal (Threat Engine) autónomo basado en la API nativa de Paper 1.21.1.

Plataforma Purpur 1.21.11 / Paper 1.21.1

Entorno Runtime Java 21 (JDK 21)

Package Base com.castlehill.classes

Threat Engine Universal / Agnóstico

1. Arquitectura & Rendimiento

Diseño thread-safe, 100% dirigido por eventos y sin bucles globales pesados.

Sistema de Pasivas Zero-Lag

Sin bucles globales por tick verificando jugadores. Todas las pasivas y estados alterados son dirigidos por eventos (EntityDamageEvent, EntityDeathEvent) y un único task por segundo para el gestor de estados.

✓ Event-Driven Architecture

✓ 0% carga de CPU en reposo

I/O Asíncrono de Perfiles

Perfiles, historial de maestría y configuraciones se gestionan de forma asíncrona mediante ConcurrentHashMap y guardado I/O no bloqueante, protegiendo el TPS del hilo principal (Main Thread).

✓ Thread-Safe Profile Caching

✓ I/O Async sin caídas de TPS

Experiencia Móvil / Bedrock

Elimina la necesidad de escribir comandos en consolas y celulares. El Selector de Habilidades (Brújula) rota con un clic y dispara con otro, complementado con el Compendio Rápido /fl (GUI de 27 slots).

✓ Ítem persistente al morir

✓ Compatible con Java y Geyser/Bedrock

2. Instalación y Despliegue

Pasos para desplegar en tu servidor Purpur o Paper.

1
Requisitos del Entorno Servidor Purpur 1.21.11 o Paper 1.21.1 ejecutando sobre Java 21.
2
Colocar el Plugin Copia WarriorClasses.jar dentro de la carpeta /plugins/ del servidor.
3
Dependencias Opcionales Instala PlaceholderAPI si deseas proyectar variables de clase en scoreboards, TAB o chat (el plugin opera de forma autónoma sin dependencias externas obligatorias).
4
Iniciar el Servidor Se generará automáticamente la carpeta plugins/WarriorClasses/ con messages.yml y perfiles en userdata/.

3. Matriz de Clases & Habilidades

Parámetros exactos, fórmulas, cooldowns y efectos según messages.yml.

4. Mecánicas Avanzadas de Combate

Fórmulas implementadas en WeaponMechanicsManager.java y CombatListener.java.

1. Pericia de Arma (0 a 400 pts)

Escala el daño físico base de un 80% a un 160% y reduce los tiempos de recarga de habilidades activas hasta un 40%.

ratio = Math.min(1.0, (double) expertise / cap);

minCooldown = (int) Math.max(1, Math.round(baseCooldown * 0.60)); // Hasta 40% más rápido

return (int) Math.max(1, Math.round(baseCooldown - ratio * (baseCooldown - minCooldown)));

• Cap por Tier: Tier 1 = 100 pts, Tier 2 = 200 pts, Tier 3 = 400 pts.
• Reducción de Cooldowns: calculateDynamicCooldown() aplica hasta -40% al CD base (a 400 de pericia, 10s baja a 6s exactos).

2. Swing Softening (Mitigación Vanilla)

El spam-click en Vanilla castiga severamente el daño (hasta -80%). WarriorClasses suaviza esta penalización en proporción a la pericia acumulada por el guerrero.

vanillaFactor = 0.2 + (cd * cd) * 0.8

softened = vanillaFactor + (1.0 - vanillaFactor) * (ratio * 0.5)

3. Golpe Rozado (Glancing Blow)

Atacar a un mob o jugador de mayor nivel activa un Golpe Rozado (10% a 55% según diferencia de nivel), reduciendo el daño saliente en un 22% plano.

4. Estados Alterados Personalizados

🩸 Sangrado: Daño verdadero continuo que ignora armadura y escudos (0.8 daño/stack cada segundo).

🩹 Herida Profunda: Reduce en un -50% toda curación entrante (pociones, rezos, vendajes).

5. Threat Engine & Sistema de Progresión

Evaluación de amenaza en tiempo real, calibración del motor y avance por Tiers.

Fórmula de Amenaza (Dificultad Dinámica):

Threat = HealthWeight + DamageWeight + ArmorWeight + EffectWeight

Escanea atributos nativos de Paper API (vida máxima, daño base, armadura y efectos poción activos) al iniciar el combate, categorizando el objetivo automáticamente y asignando los Puntos de Amenaza ganados.

Threat < 15.0 pts Dificultad Básica

Threat 15.0 a 39.9 pts ★ Moderado (Apto Tier 1)

Threat ≥ 40.0 pts ★ Monstruos de Alto Riesgo / Jefes

Evolución de Clase, Ritmo y Topes Diarios (Modo Calibración)

La evolución entre Tiers (Tier 1 → Tier 2 → Tier 3) no depende de compras de monedas ni de matar enemigos comunes: está gobernada directamente por el Motor de Amenaza mediante el combate contra enemigos de élite y monstruos de alto riesgo.

Tope Diario (3.500 pts) Para premiar la constancia y evitar maratones abusivas, existe un límite estricto de 3.500 puntos de amenaza diarios acumulables (medianoche servidor).

Bono Primera Sangre (x4) Los primeros 250 puntos base del día rinden con un multiplicador x4, otorgando hasta 1.000 pts rápidos para jugadores casuales.

Metas & 10 Grados por Tier Cada Tier se divide en 10 Grados de maestría (1 grado cada 10% de amenaza requerida: 2.500 pts por grado en Tier 1).

Requisitos de Ascenso (/class evolve):

Tier 1 → Tier 2: 25.000 Puntos de Amenaza + 500 XP de Rol + 1 Desafío Vencido (calabozo/mob ≥150 amenaza).
Tier 2 → Tier 3: 62.500 Puntos de Amenaza + 2.000 XP de Rol + 5 Desafíos Vencidos (o Trofeo de Jefe ≥400 amenaza).

Reglas del Motor: Techo máximo de 50 pts por kill, fatiga de ráfaga (-50% si mueren mobs a menos de 5s entre sí), y exclusión de mobs pacíficos y granjas abusivas.

6. Comandos & Permisos

Comandos oficiales y matriz completa de nodos de permisos declarados en plugin.yml.

Comandos de Jugador

Default: Todos

/class [nombre] Abre el menú interactivo de clases (54 slots) o selecciona una clase directamente.

/class status Consulta Tier actual, pericia de arma, puntos en el Motor de Amenaza (diario/acumulado), Desafíos y XP de Rol.

/class evolve Asciende al siguiente Tier al cumplir los requisitos de Amenaza, XP de Rol y Desafíos/Trofeo.

/class reset Cambia de clase consumiendo un Cristal de Reasignación en mano (conserva el historial si ya alcanzaste Tier 3).

/skill preparar|quitar <habilidad> Equipa o retira habilidades activas en las ranuras de combate permitidas según tu Tier.

/fl Abre el Compendio Rápido de Habilidades (Fast Loadout GUI de 27 slots).

/warrior help Muestra la guía interactiva en el chat con los atajos de clase y el uso de la Brújula como selector oficial.

Comandos de Administración

Default: OP

/warrior reload .admin.reload

Recarga config.yml y messages.yml en memoria sin reiniciar el servidor.

/warrior reset <jugador> .admin.reset

Resetea por completo la clase, el Tier y la pericia de un jugador.

/warrior settier <jugador> <1-3> .admin.settier

Fuerza el Tier de combate del jugador de forma instantánea.

/warrior addkills|adddungeons <jugador> <n> .admin.addkills

Suma puntos de amenaza o desafíos completados al registro del jugador.

/warrior givetrophy <jugador> .admin.givetrophy

Otorga el Trofeo de Jefe indispensable para el ascenso a Tier 3.

/warrior givecrystal <jugador> .admin.givecrystal

Entrega Cristales de Reasignación de Clase (cambio con confirmación 10s).

Matriz de Permisos (plugin.yml)

Nodo de Permiso	Descripción / Propósito	Default
warriorclasses.admin.*	Comodín maestro: Otorga acceso a todos los comandos y funciones administrativas del plugin.	OP
warriorclasses.admin.reload	Permite recargar `config.yml` y `messages.yml` con `/warrior reload`.	OP
warriorclasses.admin.reset	Permite resetear totalmente la clase, Tier y maestría de un jugador con `/warrior reset`.	OP
warriorclasses.admin.settier	Permite modificar el Tier de clase directamente con `/warrior settier`.	OP
warriorclasses.admin.addkills	Permite sumar bajas élite o calabozos manualmente a un jugador con `/warrior addkills\|adddungeons`.	OP
warriorclasses.admin.givetrophy	Permite entregar el Trofeo de Jefe de Calabozo personalizado con `/warrior givetrophy`.	OP
warriorclasses.admin.givecrystal	Permite entregar Cristales de Reasignación de Clase con `/warrior givecrystal`.	OP
Comandos de Jugador (/class, /warrior, /skill, /fl)	Acceso libre y automático a selección de clase, preparación de habilidades, compendio y rotación sin necesidad de configurar nodos restrictivos.	Todos

Soporte Multilingüe Dinámico en Comandos

Los comandos /class y /skill reconocen automáticamente dos formas de entrada en el juego:

Nombre Canónico en Inglés Siempre activo por defecto, independiente de la localización del servidor (ej. /class Bastion, /skill Shield Wall o el ID técnico /skill shield-wall).

Nombre Localizado (messages.yml) Si traduces los parámetros display_name (en clases) o alias (en habilidades) a cualquier idioma (español, portugués, etc.), el motor procesará el comando en ese idioma de forma automática al guardar o ejecutar /warrior reload.

7. Expansión PlaceholderAPI

Variables registradas en WarriorClassesExpansion.java para Tablist, Chat y Scoreboard.

Placeholder	Descripción	Ejemplo
%warriorclasses_class%	Nombre de la clase actual	Bastión / Bárbaro
%warriorclasses_tier%	Nivel de Tier numérico (1, 2 o 3)	2
%warriorclasses_rank%	Título del rango según el Tier	Baluarte / Berserker
%warriorclasses_expertise%	Puntos de pericia de arma actuales	145 / 200
%warriorclasses_role_xp%	Experiencia de rol acumulada	620
%warriorclasses_slots_prepared%	Ranuras de habilidades ocupadas vs máx	3/3

Recordatorio Técnico de Registro La expansión WarriorClassesExpansion se autoregistra automáticamente en el motor de PlaceholderAPI al arrancar el servidor. Si PlaceholderAPI se instala, actualiza o recarga con el servidor ya iniciado, simplemente ejecuta /papi reload para sincronizar los placeholders.

8. Archivos de Configuración

Ajustes de persistencia, multiplicadores de XP, conmutadores de combate y localización.

config.yml Motor Principal del Plugin

plugins/WarriorClasses/config.yml

# =========================================================
# WARRIORCLASSES — CONFIGURACIÓN PRINCIPAL (config.yml)
# =========================================================

# --- [ CONFIGURACIÓN GENERAL Y PERSISTENCIA ] ---
storage:
  # Intervalo de guardado automático de perfiles en disco (en minutos).
  auto-save-interval-minutes: 10
  # Ejecutar operaciones de lectura/escritura de forma asíncrona para proteger los TPS.
  async-io: true
  # Muestra información extendida en la consola del servidor para depuración.
  debug-mode: false

# --- [ PROGRESIÓN Y MULTIPLICADORES DE XP ] ---
progression:
  # Multiplicador global de experiencia de rol ganada en combate.
  role-xp-multiplier: 1.0
  # Ganancia base de puntos de pericia de arma por cada golpe efectivo.
  expertise-per-hit: 0.5
  # Puntos máximos de pericia permitidos según el Tier del jugador.
  expertise-caps:
    tier-1: 100.0
    tier-2: 200.0
    tier-3: 400.0

# --- [ CONMUTADORES Y MÓDULOS DE COMBATE ] ---
combat-mechanics:
  # Swing Softening: Atenúa la penalización vanilla del spam-click según la pericia.
  swing-softening:
    enabled: true
    # Porcentaje de mitigación máxima concedido al alcanzar el cap de pericia (0.50 = 50%).
    max-mitigation-bonus: 0.50

  # Glancing Blow: Activa la probabilidad de propinar un "Golpe Rozado" (-22% de daño)
  # si la diferencia de nivel o amenaza entre atacante y objetivo es elevada.
  glancing-blow:
    enabled: true
    min-chance: 0.10
    max-chance: 0.55
    damage-reduction: 0.22

  # Estados alterados personalizados.
  status-effects:
    bleeding:
      enabled: true
      damage-per-stack: 0.8
      interval-seconds: 1.0
    deep-wound:
      enabled: true
      healing-reduction-percentage: 0.50

# --- [ THREAT ENGINE UNIVERSAL ] ---
threat-engine:
  # Habilita la evaluación automática de amenaza al iniciar combate con cualquier entidad.
  enabled: true
  # Umbrales para clasificar el nivel de amenaza de un objetivo.
  thresholds:
    moderate: 15.0 # Requiere >= 15.0 pts para contar como baja valiosa en Tier 1
    epic: 40.0     # Requiere >= 40.0 pts para contar como baja de jefe en Tiers 2 y 3

Persistencia y Rendimiento

storage.auto-save-interval-minutes: Controla la frecuencia (en minutos) con la que los perfiles almacenados en userdata/ se sincronizan en el disco.
storage.async-io: Mantiene el guardado en un hilo secundario (asíncrono) para evitar micro-tirones (stuttering) y proteger los 20 TPS del hilo principal (Main Thread).
storage.debug-mode: Activa trazas detalladas de combate y eventos en la consola para administradores.

Progresión y Pericia de Arma

progression.role-xp-multiplier: Factor multiplicador para la XP de rol recibida por bajas de monstruos.
progression.expertise-per-hit: Puntos sumados a la pericia por golpe acertado (sujeto a cooldown interno anti-spam).
progression.expertise-caps: Topes máximos de pericia por Tier (Tier 1: 100, Tier 2: 200, Tier 3: 400 pts).

Conmutadores y Módulos de Combate

combat-mechanics.swing-softening: Mitiga dinámicamente hasta un 50% de la penalización vanilla por golpear antes de recargar el arma según tu pericia.
combat-mechanics.glancing-blow: Calcula si un golpe roza (-22% de daño) frente a mobs de amenaza muy superior (probabilidad entre 10% y 55%).
combat-mechanics.status-effects: Configura el tick de Sangrado (0.8 HP/s) y la reducción de curación por Herida Profunda (-50%).

Threat Engine Universal

threat-engine.enabled: Habilita el cálculo algorítmico de amenaza sobre cualquier entidad sin depender de plugins externos.
thresholds.moderate (15.0): Puntos requeridos para contar como baja meritoria en la evolución de Tier 1 a Tier 2.
thresholds.epic (40.0): Puntos de amenaza para categorizar jefes de élite y calabozos requeridos en la ascensión a Tier 3.

messages.yml Localización y Mensajes al Jugador (Español Oficial)

plugins/WarriorClasses/messages.yml

# ==============================================================================
# IMPORTANTE: /class y /skill siempre aceptan el nombre en inglés (Bastion,
# Shield Wall, etc.) además de lo que esté escrito acá abajo. Si traducís
# estos nombres a otro idioma, la traducción también funciona en el comando
# automáticamente — no hace falta tocar código para eso.
# ==============================================================================

prefix: "&8[&6WarriorClasses&8] &r"

class:
  current: "&cYa tienes seleccionada esta clase."
  already-has-class: "&c¡Ya has elegido una clase! Usa un &dCristal de Reasignación &cpara cambiarla."
  not-chosen: "&cNo has seleccionado ninguna clase guerrera. Usa &e/class&c."
  chosen-success: "&a¡Has elegido la clase &e%class%&a exitosamente!"
  status:
    header: "&8=== &6Estado del Guerrero &8==="
    class: "&eClase: &a%class%"
    rank: "&eRango: &b%rank% &7(Tier %tier%)"
    slots: "&eHabilidades equipadas: &f%current%/%max%"
    expertise: "&ePericia de Arma: &6%current%/%max%"

classes:
  bastion:
    display_name: "Bastión"
    tier_1: "Bastión"
    tier_2: "Baluarte"
    tier_3: "Fortaleza"
  barbarian:
    display_name: "Bárbaro"
    tier_1: "Bárbaro"
    tier_2: "Berserker"
    tier_3: "Devastador"
  assassin:
    display_name: "Asesino"
    tier_1: "Asesino"
    tier_2: "Cazador"
    tier_3: "Verdugo"
  sorcerer:
    display_name: "Hechicero"
    tier_1: "Hechicero"
    tier_2: "Conjurador"
    tier_3: "Archimago"
  cleric:
    display_name: "Clérigo"
    tier_1: "Clérigo"
    tier_2: "Adepto"
    tier_3: "Hierofante"

9. Calculadora Interactiva de Cooldowns

Simula cómo la pericia reduce el tiempo de recarga de tus habilidades.

Cooldown Base (segundos): 15s

Puntos de Pericia (0 a 400): 200

Cooldown Final Dinámico: 13.5s -1.5s (-10%) más rápido

10. API para Desarrolladores & Integración

Librería pública independiente distribuida vía JitPack para desarrolladores de plugins.

Artefacto Oficial de API Pública

WarriorClasses cuenta con una API pública liviana y desacoplada (warriorclasses-api) alojada en GitHub y distribuida mediante JitPack. Esta librería permite a desarrolladores de plugins de terceros consultar perfiles de jugadores, escuchar eventos clave de progresión e integrarse con las mecánicas de combate sin requerir acceso al motor interno ni generar dependencias rígidas.

Repositorio GitHub

Versión: v1.0.0

Licencia: MIT

1. Añadir la Dependencia

Agrega el repositorio de JitPack y las coordenadas de la API en tu gestor de proyectos (Maven o Gradle):

Maven pom.xml

<scope>provided</scope>

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.mercadanteus</groupId>
        <artifactId>warriorclasses-api</artifactId>
        <version>v1.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle (Groovy) build.gradle

compileOnly

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.mercadanteus:warriorclasses-api:v1.0.0'
}

2. Descriptor del Plugin (plugin.yml)

Para garantizar que tu plugin cargue después de WarriorClasses, agrégalo a tu lista de softdepend o depend:

src/main/resources/plugin.yml YAML Manifest

name: MyCustomPlugin
version: 1.0.0
main: com.example.myplugin.MyPlugin
softdepend: [WarriorClasses]

3. Ejemplos de Uso: Consultar Perfiles de Jugador

Puedes consultar el perfil de un jugador usando WarriorClassesAPI.getProfile(Player). Siempre realiza una comprobación de nulidad (null check) por si el jugador aún no ha seleccionado clase o sus datos están cargando:

Ejemplo en Java WarriorClassesAPI • IWarriorProfile

import com.castlehill.classes.api.WarriorClassesAPI;
import com.castlehill.classes.api.IWarriorProfile;
import org.bukkit.entity.Player;

public void checkPlayerClass(Player player) {
    IWarriorProfile profile = WarriorClassesAPI.getProfile(player);

    if (profile != null) {
        String className = profile.getCurrentClass().getDefaultName();
        int tier = profile.getTier();
        int grade = profile.getGrade();
        int eliteKills = profile.getEliteMobKills();

        player.sendMessage("You are a Tier " + tier + " " + className + " (Grade " + grade + ")!");
    } else {
        player.sendMessage("You do not have an active Warrior profile.");
    }
}

4. Escuchar Eventos Personalizados de Bukkit

La API expone eventos de Bukkit que se disparan en momentos clave de la progresión:

WarriorClassChangeEvent

Disparado cuando un jugador selecciona, cambia o resetea su clase. Brinda acceso a la clase anterior y a la nueva vocación.

WarriorTierEvolveEvent

Disparado cuando un jugador asciende/evoluciona al siguiente Tier de clase (Tier 1 → 2 o Tier 2 → 3).

WarriorThreatGainEvent

Disparado en combate cuando un jugador genera puntos de amenaza contra entidades compatibles, exponiendo la ganancia y el nuevo total.

Implementación de Listener Bukkit org.bukkit.event.Listener

import com.castlehill.classes.api.events.WarriorClassChangeEvent;
import com.castlehill.classes.api.events.WarriorTierEvolveEvent;
import com.castlehill.classes.api.events.WarriorThreatGainEvent;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class ClassEventListener implements Listener {

    @EventHandler
    public void onClassChange(WarriorClassChangeEvent event) {
        Player player = event.getPlayer();
        String newClassName = event.getNewClass().getDefaultName();

        player.sendMessage("Congratulations on becoming a " + newClassName + "!");
    }

    @EventHandler
    public void onTierEvolve(WarriorTierEvolveEvent event) {
        Player player = event.getPlayer();
        int newTier = event.getNewTier();

        // Custom logic (e.g., granting a special item or broadcast)
    }

    @EventHandler
    public void onThreatGain(WarriorThreatGainEvent event) {
        Player player = event.getPlayer();
        int gainedAmount = event.getAmountGained();
        int newTotal = event.getNewTotal();

        // Track combat engagement
    }
}

Código Fuente & Repositorio Oficial

Consulta la documentación completa de interfaces, Javadocs y releases en GitHub bajo licencia de código abierto.

mercadanteus/warriorclasses-api

SERVER ADMINISTRATOR MANUAL & TECHNICAL WIKI

WarriorClasses — RPG Class & Tactical Combat Engine

WarriorClasses is a lightweight, native RPG combat engine designed for Minecraft Purpur/Paper servers. It features 5 specialized classes, 35 skills, weapon expertise scaling with dynamic cooldown reductions, vanilla Swing Softening mitigation, custom status effects (Bleeding, Deep Wound), and a standalone Universal Threat Engine built on the native Paper 1.21.1 API.

Platform Purpur 1.21.11 / Paper 1.21.1

Runtime Env Java 21 (JDK 21)

Base Package com.castlehill.classes

Threat Engine Universal / Agnostic

1. Core Architecture & Performance

Thread-safe, event-driven design with zero per-tick performance overhead.

Zero-Lag Passive System

No global per-tick loops checking player states. All class passives and status effects are 100% event-driven (EntityDamageEvent, EntityDeathEvent) with a single 1-second task for active status effects.

✓ Event-Driven Architecture

✓ 0% idle CPU overhead

Async I/O Profile Management

Player profiles, mastery history, and configurations are handled asynchronously via ConcurrentHashMap and non-blocking I/O to protect server Main Thread TPS.

✓ Thread-Safe Profile Caching

✓ Async I/O prevents TPS drops

Geyser / Bedrock Native UX

Eliminates the command barrier for console and mobile players. The Skill Selector Compass rotates with one click and triggers with another, complemented by the Fast Loadout /fl 27-slot GUI.

✓ Persistent on death

✓ Full Java & Bedrock support

2. Installation & Deployment Guide

Step-by-step instructions for deploying to your server.

1
Check Server Environment Ensure your server runs Purpur 1.21.11 or Paper 1.21.1 using Java 21 (JDK 21).
2
Copy Plugin JAR Place WarriorClasses.jar into your server's /plugins/ directory.
3
Optional Soft-Dependencies Install PlaceholderAPI if you wish to expose class variables in scoreboards, TAB, or chat (the plugin runs autonomously with zero hard dependencies).
4
Start the Server The plugins/WarriorClasses/ folder will automatically generate with messages.yml and userdata/.

3. Class & Skill Technical Matrix

Exact damage formulas, multipliers, base cooldowns, and status effects from messages.yml.

4. Advanced Combat Engine

Mathematical logic implemented inside WeaponMechanicsManager.java and CombatListener.java.

1. Weapon Expertise Scaling (0 to 400 pts)

Directly scales base physical damage from 80% up to 160% and reduces active skill cooldowns by up to 40%.

ratio = Math.min(1.0, (double) expertise / cap);

minCooldown = (int) Math.max(1, Math.round(baseCooldown * 0.60)); // Up to 40% faster

return (int) Math.max(1, Math.round(baseCooldown - ratio * (baseCooldown - minCooldown)));

• Cap per Tier: Tier 1 = 100 pts, Tier 2 = 200 pts, Tier 3 = 400 pts.
• Cooldown Reduction: calculateDynamicCooldown() shaves up to -40% off base CD (at 400 expertise, 10s drops to 6s exact).

2. Swing Softening (Vanilla Mitigation)

Spam-clicking in vanilla heavily penalizes outgoing damage (up to -80%). WarriorClasses softens this penalty based on the warrior's expertise.

vanillaFactor = 0.2 + (cd * cd) * 0.8

softened = vanillaFactor + (1.0 - vanillaFactor) * (ratio * 0.5)

3. Glancing Blow

Striking a higher-level mob or player triggers a Glancing Blow (10% to 55% chance), reducing outgoing damage by a flat 22%.

4. Custom Status Effects

🩸 Bleeding: Continuous True Damage that bypasses all armor and shields (0.8 damage/stack every second).

🩹 Deep Wound: Reduces all incoming heals by -50% (potions, cleric prayers, barbarian bandages).

5. Threat Engine & Progression System

Real-time threat evaluation, engine calibration, and Tier progression.

Threat Evaluation Formula (Dynamic Difficulty):

Threat = HealthWeight + DamageWeight + ArmorWeight + EffectWeight

Scans Paper API native attributes (maximum health, base attack damage, armor rating, and active potion effects) upon engaging in combat, automatically categorizing the target and awarding Threat Points earned.

Threat < 15.0 pts Basic Difficulty

Threat 15.0 to 39.9 pts ★ Moderate (Tier 1 Eligible)

Threat ≥ 40.0 pts ★ High-Risk Mobs / Bosses

Class Evolution, Progression Pace & Daily Caps (Calibration Mode)

Evolution across Tiers (Tier 1 → Tier 2 → Tier 3) is strictly governed by the Threat Engine through real combat against elite enemies and high-risk monsters, rewarding persistence and tactical skill.

Daily Cap (3,500 pts) To reward consistent daily play and prevent burnout marathons, a strict cap of 3,500 daily threat points is enforced (server midnight reset).

First Blood Bonus (x4) The first 250 base threat points each day yield a 4x multiplier, providing up to 1,000 fast daily points for casual players.

Metas & 10 Grades Each Tier is structured into 10 Mastery Grades (1 grade per 10% of required threat: 2,500 pts per grade in Tier 1).

Ascension Requirements (/class evolve):

Tier 1 → Tier 2: 25,000 Threat Points + 500 Role XP + 1 Defeated Challenge (dungeon/mob ≥150 threat).
Tier 2 → Tier 3: 62,500 Threat Points + 2,000 Role XP + 5 Defeated Challenges (or Boss Trophy ≥400 threat).

Engine Rules: Hard cap of 50 pts per kill, burst fatigue (-50% if kills occur <5s apart), and strict exclusion of passive mobs and spawner farms.

6. Commands & Permissions

Official command list and complete permission node matrix declared in plugin.yml.

Player Commands

Default: Everyone

/class [name] Open class selection GUI (54 slots) or pick a class directly.

/class status Display current Tier, weapon expertise, Threat Engine points (daily/lifetime), Defeated Challenges, and Role XP.

/class evolve Ascend to the next Tier when meeting required Threat Points, Role XP, and Defeated Challenges/Boss Trophy.

/class reset Reset active class consuming a Reassignment Crystal in hand (preserves historical mastery if you reached Tier 3).

/skill prepare|unprepare <skill> Equip or remove active skills in allowable combat slots according to your Tier.

/fl Open the Fast Loadout Skill Compendium (27-slot GUI).

/warrior help Display in-game chat help guide and usage of the Compass as the official skill selector.

Administrator Commands

Default: OP

/warrior reload .admin.reload

Reload config.yml and messages.yml into memory without restarting the server.

/warrior reset <player> .admin.reset

Fully reset a player's class, Tier, and weapon expertise.

/warrior settier <player> <1-3> .admin.settier

Force a player's combat Tier immediately.

/warrior addkills|adddungeons <player> <n> .admin.addkills

Add threat points or completed challenges to player records.

/warrior givetrophy <player> .admin.givetrophy

Grant the custom Dungeon Boss Trophy required for Tier 3.

/warrior givecrystal <player> .admin.givecrystal

Grant Reassignment Crystals (class change with 10s confirmation).

Permission Matrix (plugin.yml)

Permission Node	Description / Purpose	Default
warriorclasses.admin.*	Master wildcard: Grants access to all administrative commands and management capabilities.	OP
warriorclasses.admin.reload	Allows reloading `config.yml` and `messages.yml` via `/warrior reload`.	OP
warriorclasses.admin.reset	Allows fully resetting a player's class, Tier, and mastery history via `/warrior reset`.	OP
warriorclasses.admin.settier	Allows directly overriding a player's combat Tier via `/warrior settier`.	OP
warriorclasses.admin.addkills	Allows manually adding elite mob kills or dungeons to player records via `/warrior addkills\|adddungeons`.	OP
warriorclasses.admin.givetrophy	Allows granting the custom Dungeon Boss Trophy via `/warrior givetrophy`.	OP
warriorclasses.admin.givecrystal	Allows granting Class Reassignment Crystals via `/warrior givecrystal`.	OP
Player Commands (/class, /warrior, /skill, /fl)	Free, unrestricted access to class selection, skill preparation, fast loadout, and rotation without needing explicit permission nodes.	Everyone

Dynamic Multilingual Command Support

The /class and /skill commands natively accept two forms of input in-game:

Canonical English Identifier Always active by default regardless of server locale (e.g. /class Bastion, /skill Shield Wall, or technical ID /skill shield-wall).

Localized Name (messages.yml) If you translate display_name (classes) or alias (skills) into any language (Spanish, Portuguese, etc.), the engine dynamically maps and accepts localized commands upon saving or running /warrior reload.

7. PlaceholderAPI Expansion

Variables registered in WarriorClassesExpansion.java for Tablist, Chat, and Scoreboards.

Placeholder	Description	Sample Value
%warriorclasses_class%	Current class display name	Bastion / Barbarian
%warriorclasses_tier%	Numeric Tier level (1, 2, or 3)	2
%warriorclasses_rank%	Rank title based on Tier	Bulwark / Berserker
%warriorclasses_expertise%	Current weapon expertise points	145 / 200
%warriorclasses_role_xp%	Accumulated role experience	620
%warriorclasses_slots_prepared%	Prepared skill slots vs maximum	3/3

Technical Registration Note The WarriorClassesExpansion automatically hooks into PlaceholderAPI upon server startup. If PlaceholderAPI is installed, updated, or reloaded after WarriorClasses is already active, simply run /papi reload to synchronize the placeholders.

8. Configuration Files

Persistence settings, XP multipliers, combat toggles, and localization templates.

config.yml Main Engine Configuration

plugins/WarriorClasses/config.yml

# =========================================================
# WARRIORCLASSES — MAIN CONFIGURATION (config.yml)
# =========================================================

# --- [ GENERAL & PERSISTENCE CONFIGURATION ] ---
storage:
  # Interval for automatic disk profile saves (in minutes).
  auto-save-interval-minutes: 10
  # Execute read/write operations asynchronously to safeguard server TPS.
  async-io: true
  # Display verbose debugging logs in the server console.
  debug-mode: false

# --- [ PROGRESSION & XP MULTIPLIERS ] ---
progression:
  # Global multiplier for role experience earned in combat.
  role-xp-multiplier: 1.0
  # Base weapon expertise points awarded per effective hit.
  expertise-per-hit: 0.5
  # Maximum weapon expertise caps per player Tier.
  expertise-caps:
    tier-1: 100.0
    tier-2: 200.0
    tier-3: 400.0

# --- [ COMBAT MECHANICS & TOGGLES ] ---
combat-mechanics:
  # Swing Softening: Mitigates vanilla spam-click attack penalty based on expertise.
  swing-softening:
    enabled: true
    # Maximum mitigation percentage awarded at maximum expertise (0.50 = 50%).
    max-mitigation-bonus: 0.50

  # Glancing Blow: Enables a chance to land a "Glancing Blow" (-22% damage)
  # when the level or threat delta between attacker and target is significant.
  glancing-blow:
    enabled: true
    min-chance: 0.10
    max-chance: 0.55
    damage-reduction: 0.22

  # Custom combat status effects.
  status-effects:
    bleeding:
      enabled: true
      damage-per-stack: 0.8
      interval-seconds: 1.0
    deep-wound:
      enabled: true
      healing-reduction-percentage: 0.50

# --- [ UNIVERSAL THREAT ENGINE ] ---
threat-engine:
  # Enables automatic algorithmic threat evaluation when engaging any entity.
  enabled: true
  # Score thresholds to categorize entity threat levels.
  thresholds:
    moderate: 15.0 # Requires >= 15.0 pts to qualify as a valid Tier 1 kill
    epic: 40.0     # Requires >= 40.0 pts to qualify as a boss kill for Tiers 2 & 3

Persistence & Performance

storage.auto-save-interval-minutes: Configures the interval (in minutes) at which memory profiles sync to userdata/ on disk.
storage.async-io: Dispatches file I/O to background worker threads to eliminate stuttering and maintain a solid 20 TPS on the Main Thread.
storage.debug-mode: Toggles verbose logging for combat calculations and event tracking in the server console.

Progression & Weapon Expertise

progression.role-xp-multiplier: Scaling multiplier applied to role combat XP upon slaying hostile mobs.
progression.expertise-per-hit: Expertise points gained per valid swing hit (governed by internal anti-spam rate limits).
progression.expertise-caps: Maximum expertise ceiling allowed per player Tier (Tier 1: 100, Tier 2: 200, Tier 3: 400 pts).

Combat Toggles & Modules

combat-mechanics.swing-softening: Dynamically softens vanilla spam-click damage reduction up to 50% based on player weapon expertise.
combat-mechanics.glancing-blow: Determines whether a strike glances (-22% damage) when engaging high-threat monsters (10% to 55% chance).
combat-mechanics.status-effects: Adjusts Bleeding tick damage (0.8 HP/s) and Deep Wound healing reduction (-50%).

Universal Threat Engine

threat-engine.enabled: Enables algorithmic target assessment without relying on external plugins.
thresholds.moderate (15.0): Threat points required to count as a qualifying kill for Tier 1 → Tier 2 progression.
thresholds.epic (40.0): Threat score threshold to classify elite/dungeon boss kills for Tier 3 ascension.

messages.yml Localization and Player Messages (Official English)

plugins/WarriorClasses/messages.yml

# ==============================================================================
# IMPORTANT: /class and /skill always accept the canonical English name (Bastion,
# Shield Wall, etc.) in addition to whatever is written below. If you translate
# these names into another language, the translation also works in the command
# automatically — no code modifications required.
# ==============================================================================

prefix: "&6[WarriorClasses]&r "

class:
  not-chosen: "&eYou have not chosen a class yet. Use /class <name> to pick one."
  current: "&aYour current class: %class%"
  chosen-success: "&aYou are now a %class%!"
  status:
    header: "&6=== Warrior Status ==="
    class: "&eClass: &a%class%"
    rank: "&eRank: &b%rank% &7(Tier %tier%)"
    slots: "&ePrepared Slots: &f%current%/%max%"
    expertise: "&eWeapon Expertise: &6%current%/%max%"

classes:
  bastion:
    display_name: "Bastion"
    tier_1: "Bastion"
    tier_2: "Bulwark"
    tier_3: "Fortress"
  barbarian:
    display_name: "Barbarian"
    tier_1: "Barbarian"
    tier_2: "Berserker"
    tier_3: "Ravager"
  assassin:
    display_name: "Assassin"
    tier_1: "Assassin"
    tier_2: "Slayer"
    tier_3: "Executioner"
  sorcerer:
    display_name: "Sorcerer"
    tier_1: "Sorcerer"
    tier_2: "Conjurer"
    tier_3: "Archmage"
  cleric:
    display_name: "Cleric"
    tier_1: "Cleric"
    tier_2: "Adept"
    tier_3: "Hierophant"

9. Interactive Cooldown Calculator

Simulate how weapon expertise reduces active skill cooldowns.

Base Cooldown (seconds): 15s

Expertise Points (0 to 400): 200

Dynamic Final Cooldown: 13.5s -1.5s (-10%) faster

10. Developer API & Integration

Lightweight public API library hosted on GitHub and distributed via JitPack.

Official Public API Artifact

WarriorClasses features a lightweight, standalone public API (warriorclasses-api) hosted on GitHub and distributed via JitPack. This library allows third-party developers to query player profile data, listen to progression milestones, and hook into class mechanics without requiring access to the core engine or creating hard dependencies.

GitHub Repo

Version: v1.0.0

License: MIT

1. Adding the Dependency

Add the JitPack repository and API coordinate to your project build file (Maven or Gradle):

Maven pom.xml

<scope>provided</scope>

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.mercadanteus</groupId>
        <artifactId>warriorclasses-api</artifactId>
        <version>v1.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle (Groovy) build.gradle

compileOnly

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.mercadanteus:warriorclasses-api:v1.0.0'
}

2. Plugin Descriptor (plugin.yml)

To ensure your plugin loads after WarriorClasses, declare it in your softdepend or depend list:

src/main/resources/plugin.yml YAML Manifest

name: MyCustomPlugin
version: 1.0.0
main: com.example.myplugin.MyPlugin
softdepend: [WarriorClasses]

3. Usage Examples: Querying Player Profiles

You can query a player's active class, Tier, Grade, and combat milestones via WarriorClassesAPI. Always perform a null check in case the player data hasn't loaded or the player hasn't selected a class yet:

Java Sample Code WarriorClassesAPI • IWarriorProfile

import com.castlehill.classes.api.WarriorClassesAPI;
import com.castlehill.classes.api.IWarriorProfile;
import org.bukkit.entity.Player;

public void checkPlayerClass(Player player) {
    IWarriorProfile profile = WarriorClassesAPI.getProfile(player);

    if (profile != null) {
        String className = profile.getCurrentClass().getDefaultName();
        int tier = profile.getTier();
        int grade = profile.getGrade();
        int eliteKills = profile.getEliteMobKills();

        player.sendMessage("You are a Tier " + tier + " " + className + " (Grade " + grade + ")!");
    } else {
        player.sendMessage("You do not have an active Warrior profile.");
    }
}

4. Listening to Custom Events

The API fires custom Bukkit events allowing your plugin to react to class progression without polling or repeating checks:

WarriorClassChangeEvent

Fired when a player selects, changes, or resets their class. Provides access to old and new class records.

WarriorTierEvolveEvent

Fired when a player ascends to a higher Tier (Tier 1 → 2 or Tier 2 → 3).

WarriorThreatGainEvent

Fired when a player generates threat points against supported mobs in combat, exposing gained amount and new total.

Event Listener Implementation org.bukkit.event.Listener

import com.castlehill.classes.api.events.WarriorClassChangeEvent;
import com.castlehill.classes.api.events.WarriorTierEvolveEvent;
import com.castlehill.classes.api.events.WarriorThreatGainEvent;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class ClassEventListener implements Listener {

    @EventHandler
    public void onClassChange(WarriorClassChangeEvent event) {
        Player player = event.getPlayer();
        String newClassName = event.getNewClass().getDefaultName();

        player.sendMessage("Congratulations on becoming a " + newClassName + "!");
    }

    @EventHandler
    public void onTierEvolve(WarriorTierEvolveEvent event) {
        Player player = event.getPlayer();
        int newTier = event.getNewTier();

        // Custom logic (e.g., granting a special item or broadcast)
    }

    @EventHandler
    public void onThreatGain(WarriorThreatGainEvent event) {
        Player player = event.getPlayer();
        int gainedAmount = event.getAmountGained();
        int newTotal = event.getNewTotal();

        // Track combat engagement
    }
}

Source Code & Repository

Review the complete interface definitions, Javadocs, and release tags on GitHub under open-source licensing.

mercadanteus/warriorclasses-api