Documentation Guide

Developer API (Java)

Integration guide and documentation for the AxLore public Developer API.

💻 AxLore Developer API

AxLore provides a robust and highly integrated Java API that allows other plugin developers to trigger immersive narratives, hook into playback events, and utilize our advanced visual engine (TextDisplay).

🚀 Getting Started

To use the AxLore API, you simply need to make sure AxLore is loaded before your plugin. Add it as a depend or softdepend in your plugin.yml:

yaml

name: MyQuestPlugin
version: 1.0
main: com.myplugin.Main
depend: [AxLore]

All interactions are handled statically through the AxLoreAPI class located at com.axxtrial.license.api.AxLoreAPI. You do not need to instantiate any classes to use the core features.

🎬 Narrative Control

You can manually trigger or stop configured scenes for any player.

Play a Scene

Triggers a scene configured in AxLore's config.yml. It automatically handles the player's language preference and synchronization.

java

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

public void startIntroduction(Player player) {
    if (!AxLoreAPI.isPlaying(player)) {
        // "intro_scene" must exist in AxLore's config.yml
        AxLoreAPI.playScene(player, "intro_scene");
    } else {
        player.sendMessage("You are already listening to a story!");
    }
}

Stop a Scene

Instantly stops the narration (cutting off the audio) and removes any active holograms or BossBars.

java

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

⚡ Listening to Events (Hooks)

AxLore provides custom Bukkit events that allow your plugin to react to the narrative lifecycle. This is particularly useful for granting rewards only after a story finishes.

Important Notice Make sure your class implements `org.bukkit.event.Listener` and is registered in your plugin's `onEnable()`.

1. AxLoreSceneEndEvent

The most useful event. It fires when a scene completes its duration naturally, or if it is forcefully stopped.

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 QuestListener implements Listener {

    @EventHandler
    public void onSceneComplete(AxLoreSceneEndEvent event) {
        if (event.getSceneName().equalsIgnoreCase("tutorial_quest")) {
            event.getPlayer().sendMessage("§aYou finished the tutorial! Here is your reward.");
            event.getPlayer().getInventory().addItem(new ItemStack(Material.DIAMOND, 1));
        }
    }
}

2. AxLoreSceneTriggerEvent (Cancellable)

Fires before a scene starts. You can use this to prevent a scene from playing if the player is in a certain state (e.g., in combat or dead).

java

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

public class CombatListener implements Listener {

    @EventHandler
    public void onSceneTrigger(AxLoreSceneTriggerEvent event) {
        // Assuming you have a method to check combat state
        if (CombatPlugin.isInCombat(event.getPlayer())) {
            event.setCancelled(true);
            event.getPlayer().sendMessage("§cYou cannot listen to stories while in combat!");
        }
    }
}

3. AxLoreSceneStartEvent

Fires exactly when the audio begins playing and the hologram appears.

🛠 Player Preferences

AxLore stores preferences persistently per player. You can read or modify these values.

java

// Get the player's selected language (e.g. "es", "en")
String lang = AxLoreAPI.getLanguage(player);

// Force change the language
AxLoreAPI.setLanguage(player, "fr");

// Check if the player has muted narrations in their AxLore menu
boolean isMuted = AxLoreAPI.isMuted(player);

// Force mute or unmute a player programmatically
AxLoreAPI.setMuted(player, true);

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

// Subtitles visibility (Holograms/BossBars)
boolean subs = AxLoreAPI.hasSubtitles(player);
AxLoreAPI.setSubtitles(player, false);

🏆 Scene & Global Progress

You can check if players have completed specific stories or manage global server sessions.

java

// Check if a player finished a one-time scene
if (AxLoreAPI.isCompleted(player, "tutorial_quest")) {
    player.sendMessage("Welcome back, hero!");
}

// Manually mark a scene as completed
AxLoreAPI.markCompleted(player, "easter_egg_found");

// --- Global Management ---

// Get total active narrations on the server
int active = AxLoreAPI.getActiveSessionsCount();

// Force stop every single narration on the server
AxLoreAPI.stopAllSessions();

Note All player preferences and completion statuses persist across sessions using the player's `PersistentDataContainer`.

🔮 Using the Visual Engine (Holograms)

You don't need to create a full audio scene to use AxLore's advanced TextDisplay engine. You can spawn high-performance, relative holograms that follow the player for your own plugin's notifications.

java

public void showLevelUp(Player player) {
    // Shows a hologram that follows the player's vision for 5 seconds
    AxLoreAPI.showHologram(
        player, 
        "§e§lLEVEL UP!",               // Title
        "§fYou have reached level 10", // Subtitle/Text
        5.0                            // Duration in seconds
    );
}

Pro Tip Holograms spawned via `AxLoreAPI.showHologram` automatically clean themselves up after the specified duration. They use the offsets defined in AxLore's `config.yml` for perfect positioning.

Was this helpful?

Help us improve our documentation.(Anonymous & any language)