Guía de Documentación

Developer API (Java)

Guía de integración y documentación de la API pública de AxLore para desarrolladores.

AxLore Developer API

AxLore proporciona una API de Java robusta y altamente integrada que permite a otros desarrolladores de plugins disparar narrativas inmersivas, engancharse a eventos de reproducción y utilizar nuestro avanzado motor visual (TextDisplay).

Empezando

Para usar la API de AxLore, simplemente necesitas asegurarte de que AxLore se cargue antes que tu plugin. Añádelo como depend o softdepend en tu archivo plugin.yml:

yaml

name: MiPluginDeMisiones
version: 1.0
main: com.miplugin.Main
depend: [AxLore]

Todas las interacciones se manejan estáticamente a través de la clase AxLoreAPI ubicada en com.axxtrial.license.api.AxLoreAPI. No necesitas instanciar ninguna clase para usar las funciones principales.

Control de Narrativa

Puedes activar o detener manualmente las escenas configuradas para cualquier jugador.

Iniciar una Escena

Dispara una escena configurada en el config.yml de AxLore. Maneja automáticamente la preferencia de idioma del jugador y la sincronización.

java

import com.axxtrial.license.api.AxLoreAPI;
import org.bukkit.entity.Player;

public void iniciarIntroduccion(Player player) {
    if (!AxLoreAPI.isPlaying(player)) {
        // "escena_intro" debe existir en el config.yml de AxLore
        AxLoreAPI.playScene(player, "escena_intro");
    } else {
        player.sendMessage("¡Ya estás escuchando una historia!");
    }
}

Detener una Escena

Detiene instantáneamente la narración (cortando el audio) y elimina cualquier holograma o BossBar activo.

java

public void interrumpirNarracion(Player player) {
    if (AxLoreAPI.isPlaying(player)) {
        AxLoreAPI.stopScene(player);
    }
}

Escuchando Eventos (Hooks)

AxLore proporciona eventos personalizados de Bukkit que permiten a tu plugin reaccionar al ciclo de vida narrativo. Esto es particularmente útil para otorgar recompensas solo después de que termine una historia.

Important Notice Asegúrate de que tu clase implemente `org.bukkit.event.Listener` y esté registrada en el `onEnable()` de tu plugin.

1. AxLoreSceneEndEvent

El evento más útil. Se dispara cuando una escena completa su duración de forma natural, o si se detiene a la fuerza.

java

import com.axxtrial.license.event.AxLoreSceneEndEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.inventory.ItemStack;
import org.bukkit.Material;

public class MisionesListener implements Listener {

    @EventHandler
    public void alCompletarEscena(AxLoreSceneEndEvent event) {
        if (event.getSceneName().equalsIgnoreCase("mision_tutorial")) {
            event.getPlayer().sendMessage("§a¡Terminaste el tutorial! Aquí tienes tu recompensa.");
            event.getPlayer().getInventory().addItem(new ItemStack(Material.DIAMOND, 1));
        }
    }
}

2. AxLoreSceneTriggerEvent (Cancelable)

Se dispara antes de que comience una escena. Puedes usar esto para evitar que se reproduzca una escena si el jugador está en un estado específico (ej. en combate o muerto).

java

import com.axxtrial.license.event.AxLoreSceneTriggerEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class CombateListener implements Listener {

    @EventHandler
    public void alDispararEscena(AxLoreSceneTriggerEvent event) {
        // Asumiendo que tienes un método para comprobar el estado de combate
        if (CombatPlugin.isInCombat(event.getPlayer())) {
            event.setCancelled(true);
            event.getPlayer().sendMessage("§c¡No puedes escuchar historias mientras estás en combate!");
        }
    }
}

3. AxLoreSceneStartEvent

Se dispara exactamente cuando el audio comienza a reproducirse y aparece el holograma.

Preferencias del Jugador

AxLore almacena las preferencias de forma persistente por jugador. Puedes leer o modificar estos valores.

java

// Obtener el idioma seleccionado por el jugador (ej. "es", "en")
String lang = AxLoreAPI.getLanguage(player);

// Forzar el cambio de idioma
AxLoreAPI.setLanguage(player, "fr");

// Comprobar si el jugador ha silenciado las narraciones en su menú de AxLore
boolean isMuted = AxLoreAPI.isMuted(player);

// Forzar el silencio o activarlo desde código
AxLoreAPI.setMuted(player, true);

// Gestionar volumen (0.0 to 1.0)
double volume = AxLoreAPI.getVolume(player);
AxLoreAPI.setVolume(player, 0.5);

// Visibilidad de subtítulos (Hologramas/BossBars)
boolean subs = AxLoreAPI.hasSubtitles(player);
AxLoreAPI.setSubtitles(player, false);

🏆 Progreso de Escenas y Global

Puedes consultar si los jugadores han completado historias específicas o gestionar las sesiones globales del servidor.

java

// Verificar si un jugador terminó una escena de un solo uso (one-time)
if (AxLoreAPI.isCompleted(player, "mision_tutorial")) {
    player.sendMessage("¡Bienvenido de nuevo, héroe!");
}

// Marcar manualmente una escena como completada
AxLoreAPI.markCompleted(player, "secreto_encontrado");

// --- Gestión Global ---

// Obtener el total de narraciones activas en el servidor
int activas = AxLoreAPI.getActiveSessionsCount();

// Detener absolutamente todas las narraciones del servidor
AxLoreAPI.stopAllSessions();

Note Todas las preferencias y estados de completado persisten entre sesiones usando el `PersistentDataContainer` del jugador.

Usando el Motor Visual (Hologramas)

No necesitas crear una escena de audio completa para usar el avanzado motor TextDisplay de AxLore. Puedes generar hologramas relativos de alto rendimiento que siguen al jugador para las notificaciones de tu propio plugin.

java

public void mostrarSubidaDeNivel(Player player) {
    // Muestra un holograma que sigue la visión del jugador durante 5 segundos
    AxLoreAPI.showHologram(
        player, 
        "§e§l¡SUBISTE DE NIVEL!",       // Título
        "§fHas alcanzado el nivel 10", // Subtítulo/Texto
        5.0                            // Duración en segundos
    );
}

Pro Tip Los hologramas generados a través de `AxLoreAPI.showHologram` se limpian automáticamente después de la duración especificada. Utilizan los offsets definidos en el `config.yml` de AxLore para un posicionamiento perfecto.

¿Te resultó útil?

Ayúdanos a mejorar nuestra documentación.(Anónimo y en cualquier idioma)