AxoHologram API
Esta guia explica como usar la API publica de AxoHologram desde otro plugin de Paper.
La idea es simple: tu plugin no crea entidades Display por su cuenta. Tu plugin le pide a AxoHologram que cree, actualice, muestre, o elimine hologramas usando AxoHologramAPI. AxoHologram se encarga de renderizar las lineas, aplicar formato, refrescar placeholders, guardar YAML cuando corresponde y destruir las entidades cuando el holograma desaparece.
Que ofrece la API
Con ella puedes trabajar con hologramas normales de:
- texto (
TEXT)
- item (
ITEM)
- bloque (
BLOCK)
- lineas mixtas usando
HologramLine
Tambien puedes:
- crear hologramas persistentes, guardados en YAML
- crear hologramas solo de runtime, sin YAML
- crear hologramas temporales que se eliminan solos despues de ciertos ticks
- buscar hologramas por id
- listar hologramas registrados
- reemplazar o agregar lineas
- teletransportar hologramas
- mostrar u ocultar hologramas a los jugadores actuales
- medir altura de hologramas y lineas
La API actual esta enfocada en hologramas de texto, item y bloque. Los hologramas multimedia (IMAGE y VIDEO) existen en el plugin, pero no forman parte de esta interfaz publica.
Como funciona por dentro
Cuando AxoHologram inicia, crea una instancia de AxoHologramProvider y la registra en el ServicesManager de Bukkit/Paper:
getServer().getServicesManager().register(AxoHologramAPI.class, api, this, ServicePriority.Normal);
Tambien expone un acceso directo:
AxoHologram.getAPI();
Eso significa que otro plugin puede obtener la API de dos maneras:
- por
AxoHologram.getAPI(), si ya tienes dependencia directa contra la clase principal
- por
ServicesManager, si prefieres un hook mas desacoplado
En ambos casos, la API real termina llamando al HologramManager interno. Ese manager valida IDs, registra hologramas, guarda archivos YAML si el holograma es persistente, refresca viewers y agenda eliminaciones temporales.
Agregar AxoHologram como dependencia - Maven
Si usas JitPack, agrega el repositorio y compila contra AxoHologram como provided. No empaquetes AxoHologram dentro de tu jar; el servidor debe tener el plugin instalado por separado.
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.github.Axolotle154</groupId>
<artifactId>AxoHologram</artifactId>
<version>3.0.0</version>
<scope>provided</scope>
</dependency>
</dependencies>
Cambia 3.0.0 por el tag o version que publiques en JitPack.
Agregar AxoHologram como dependencia - Gradle Kotlin DSL
repositories {
maven("https://jitpack.io")
}
dependencies {
compileOnly("com.github.Axolotle154:AxoHologram:3.0.0")
}
Declarar la dependencia en tu plugin
Si tu plugin necesita AxoHologram para funcionar, declaralo como dependencia requerida en paper-plugin.yml:
dependencies:
server:
AxoHologram:
load: BEFORE
required: true
join-classpath: true
Si tu plugin puede funcionar sin hologramas, hazlo opcional:
dependencies:
server:
AxoHologram:
load: BEFORE
required: false
join-classpath: true
Para un plugin.yml legacy:
depend: [AxoHologram]
o, si es opcional:
softdepend: [AxoHologram]
Obtener la API - Opcion directa
Esta opcion es comoda cuando AxoHologram es dependencia obligatoria.
import org.axostudio.axohologram.AxoHologram;
import org.axostudio.axohologram.api.AxoHologramAPI;
public final class MyPlugin extends JavaPlugin {
private AxoHologramAPI holograms;
@Override
public void onEnable() {
holograms = AxoHologram.getAPI();
if (holograms == null) {
getLogger().severe("AxoHologram no esta disponible.");
getServer().getPluginManager().disablePlugin(this);
return;
}
}
}
Obtener la API - Opcion con ServicesManager
Esta opcion es buena si quieres que tu integracion sea mas limpia o si AxoHologram es opcional.
import org.axostudio.axohologram.api.AxoHologramAPI;
import org.bukkit.plugin.RegisteredServiceProvider;
import org.bukkit.plugin.java.JavaPlugin;
public final class MyPlugin extends JavaPlugin {
private AxoHologramAPI holograms;
@Override
public void onEnable() {
holograms = hookAxoHologram();
if (holograms == null) {
getLogger().warning("AxoHologram no esta instalado. La integracion de hologramas queda desactivada.");
return;
}
getLogger().info("Hook con AxoHologram listo.");
}
private AxoHologramAPI hookAxoHologram() {
if (!getServer().getPluginManager().isPluginEnabled("AxoHologram")) {
return null;
}
RegisteredServiceProvider provider =
getServer().getServicesManager().getRegistration(AxoHologramAPI.class);
return provider == null ? null : provider.getProvider();
}
}
Crear un holograma persistente
Un holograma persistente se guarda en:
plugins/AxoHologram/holograms/.yml
Ejemplo:
import org.bukkit.Location;
import java.util.List;
Location location = player.getLocation().add(0.0, 2.4, 0.0);
if (!holograms.exists("myplugin_spawn_info")) {
holograms.createHologram(
"myplugin_spawn_info",
location,
List.of(
"&aBienvenido al servidor",
"&7Usa &f/warp &7para viajar"
)
);
}
Este holograma queda guardado. Si el servidor reinicia, AxoHologram lo carga desde su YAML.
Crear un holograma de runtime
Un holograma de runtime existe mientras el plugin esta activo, pero no se guarda en YAML.
holograms.createHologram(
"myplugin_runtime_status",
location,
List.of("&eEvento activo", "&7Termina en 5 minutos"),
false
);
Usa este tipo para datos vivos de tu plugin: eventos, estados temporales, marcadores, avisos de partida, etc.
Crear un holograma temporal
Un holograma temporal se crea como runtime y AxoHologram lo elimina automaticamente despues del tiempo indicado.
holograms.createTemporaryHologram(
player.getLocation().add(0.0, 2.0, 0.0),
List.of("&a+50 XP"),
60L
);
60L son ticks. En Paper normal, 20 ticks equivalen aproximadamente a 1 segundo. Si pasas 0 o un valor negativo, no se agenda eliminacion automatica.
Crear lineas mixtas
Cuando necesitas texto, items y bloques en el mismo holograma, usa las fabricas de lineas:
holograms.createHologram(
"myplugin_reward",
location,
List.of(
holograms.createTextLine("&6Recompensa diaria"),
holograms.createItemLine("DIAMOND"),
holograms.createBlockLine("minecraft:chest[facing=north]"),
holograms.createTextLine("&7Haz click en el NPC")
)
);
Estas lineas implementan HologramLine. Puedes ajustar algunas propiedades por linea antes de crear el holograma:
HologramLine item = holograms.createItemLine("PLAYER_HEAD(%player_name%)");
item.setHeight(0.7D);
item.setPermission("myplugin.rewards.visible");
holograms.createHologram(
"myplugin_player_head",
location,
List.of(
holograms.createTextLine("&bTu perfil"),
item
)
);
Items y cabezas de jugador
Las lineas de item aceptan materiales de Bukkit:
holograms.createItemHologram("myplugin_sword", location, "DIAMOND_SWORD");
Tambien aceptan prefijos como #ITEM::
holograms.createItemHologram("myplugin_icon", location, "#ITEM:EMERALD");
Para cabezas:
holograms.createItemHologram(
"myplugin_head",
location,
"PLAYER_HEAD(%player_name%)"
);
PLAYER_HEAD(...) acepta:
- nombre de jugador
- UUID
base64: o value:texture:, textures: o skin:url: hacia textures.minecraft.net- hash de textura de Minecraft
Si usas PlaceholderAPI o MiniPlaceholders y estan habilitados en AxoHologram, los placeholders se resuelven por jugador cuando se renderiza.
Bloques
Las lineas de bloque aceptan un material o un BlockData completo:
holograms.createBlockHologram("myplugin_block", location, "DIAMOND_BLOCK");
holograms.createBlockHologram(
"myplugin_oriented_stairs",
location,
"minecraft:oak_stairs[facing=east,half=bottom,shape=straight]"
);
Actualizar hologramas
Puedes reemplazar todas las lineas de la primera pagina:
holograms.updateLines(
"myplugin_spawn_info",
List.of("&aServidor online", "&7Jugadores: " + onlineCount)
);
Puedes agregar lineas:
holograms.addTextLine("myplugin_spawn_info", "&eNuevo evento disponible");
holograms.addItemLine("myplugin_spawn_info", "GOLD_INGOT");
holograms.addBlockLine("myplugin_spawn_info", "BEACON");
O reemplazar un holograma de item/bloque:
holograms.updateItemLine("myplugin_icon", "NETHER_STAR");
holograms.updateBlockLine("myplugin_block", "EMERALD_BLOCK");
Buscar, mover, ocultar y eliminar
if (holograms.exists("myplugin_spawn_info")) {
holograms.teleportHologram("myplugin_spawn_info", newLocation);
}
holograms.getHologram("myplugin_spawn_info").ifPresent(hologram -> {
hologram.setViewDistance(48);
hologram.setScale(1.2F);
hologram.refreshViewers();
});
holograms.hideHologram("myplugin_spawn_info");
holograms.showHologram("myplugin_spawn_info");
Cuando ya no quieres conservar un holograma, puedes eliminarlo. Si el holograma era persistente, tambien se borra su archivo YAML.
holograms.deleteHologram("myplugin_spawn_info");
Usar el objeto Hologram
Los metodos de creacion devuelven Hologram. Ese objeto permite tocar ajustes mas concretos:
setLocation(...)setEnabled(...)setViewDistance(...)setScale(...)setBillboard(...)setPermission(...)setVisibilityMode(...)setDefaultPageIndex(...)addPage(...)addLine(...)refreshViewers()
Ejemplo:
import org.axostudio.axohologram.hologram.Hologram;
import org.axostudio.axohologram.hologram.visibility.VisibilityMode;
Hologram hologram = holograms.createHologram(
"myplugin_private",
location,
List.of("&cZona privada")
);
hologram.setVisibilityMode(VisibilityMode.PERMISSION);
hologram.setPermission("myplugin.holograms.private");
hologram.setViewDistance(32);
hologram.refreshViewers();
Reglas importantes
- El id del holograma solo puede usar letras, numeros,
_ y -.
- El id debe ser unico. Usa un prefijo de tu plugin, por ejemplo
myplugin_spawn.
- La
Location debe tener un mundo cargado.
- Los metodos lanzan
IllegalArgumentException si el input es invalido o si intentas editar un holograma que no existe.
- Los metodos de creacion pueden lanzar
IllegalStateException si AxoHologram no puede registrar el holograma.
- Si vienes de una tarea async, vuelve al scheduler del servidor antes de llamar la API.
- La API de
updateLines, addLine y similares trabaja sobre la primera pagina.
- Si creas hologramas de runtime sin duracion, tu plugin deberia eliminarlos cuando ya no los necesite.
Ejemplo de limpieza en onDisable():
@Override
public void onDisable() {
if (holograms != null) {
holograms.deleteHologram("myplugin_runtime_status");
}
}
Ejemplo completo minimo
package com.example.myplugin;
import org.axostudio.axohologram.api.AxoHologramAPI;
import org.bukkit.Location;
import org.bukkit.plugin.RegisteredServiceProvider;
import org.bukkit.plugin.java.JavaPlugin;
import java.util.List;
public final class MyPlugin extends JavaPlugin {
private AxoHologramAPI holograms;
@Override
public void onEnable() {
holograms = hookAxoHologram();
if (holograms == null) {
getLogger().warning("AxoHologram no esta disponible.");
return;
}
Location spawn = getServer().getWorlds().get(0).getSpawnLocation().add(0.5, 2.2, 0.5);
if (!holograms.exists("myplugin_spawn")) {
holograms.createHologram(
"myplugin_spawn",
spawn,
List.of(
"&aBienvenido",
"&7Este holograma fue creado desde otro plugin",
"&eUsa /spawn para volver aqui"
)
);
}
holograms.deleteHologram("myplugin_temp_notice");
holograms.createHologram(
"myplugin_temp_notice",
spawn.clone().add(0.0, 1.0, 0.0),
List.of("&eAviso temporal del plugin"),
false
);
}
@Override
public void onDisable() {
if (holograms != null) {
holograms.deleteHologram("myplugin_temp_notice");
}
}
private AxoHologramAPI hookAxoHologram() {
if (!getServer().getPluginManager().isPluginEnabled("AxoHologram")) {
return null;
}
RegisteredServiceProvider provider =
getServer().getServicesManager().getRegistration(AxoHologramAPI.class);
return provider == null ? null : provider.getProvider();
}
}
Resumen rapido
Para implementar AxoHologram en otro plugin:
- Agrega AxoHologram como
compileOnly/provided.
- Declara
AxoHologram en paper-plugin.yml o plugin.yml.
- Obtiene
AxoHologramAPI con AxoHologram.getAPI() o ServicesManager.
- Usa IDs propios y unicos.
- Crea hologramas persistentes para configuracion estable.
- Crea hologramas temporales o runtime para estados vivos.
- Limpia los hologramas runtime cuando tu plugin ya no los necesite.