Hologramas

A biblioteca de hologramas do yPlugins oferece uma interface comum para criar textos e itens flutuantes. O acesso é feito pela HologramFactory, e cada holograma criado é manipulado pela interface Hologram.

As interfaces públicas estão no pacote:

br.com.ystoreplugins.lib.helper.entity.hologram

Preparação

Adicione o yPlugins ao seu projeto conforme o guia de API dos Plugins. Se o seu plugin é carregado pelo loader, consulte também Desenvolva com o yPlugins.

Obtendo a factory

A instância é disponibilizada pelo BukkitBootstrap:

import br.com.ystoreplugins.bootstrap.BukkitBootstrap;
import br.com.ystoreplugins.lib.helper.entity.hologram.HologramFactory;

HologramFactory factory = BukkitBootstrap.get().getHologramFactory();

if (factory == null) {
    // A factory ainda não está disponível. Adie a criação dos hologramas.
    return;
}

Dentro de uma classe que estende BukkitPlugin, o acesso também pode ser feito por getLoader():

HologramFactory factory = getLoader().getHologramFactory();

A inicialização das factories é agendada para 1 tick após o onEnable() do yPlugins. Obtenha a factory após essa etapa e verifique se ela está disponível antes de criar hologramas.

Métodos da HologramFactory

Método	Retorno	Descrição
`getHolograms()`	`List<Hologram>`	Consulta os hologramas registrados na factory.
`spawnHologram(Plugin plugin, Location location)`	`Hologram`	Cria um holograma na localização informada. As linhas são adicionadas ao objeto retornado.
`close(Plugin plugin)`	`void`	Executa a limpeza dos hologramas gerenciados pela factory.

O parâmetro plugin deve ser uma instância de org.bukkit.plugin.Plugin. Para plugins que estendem BukkitPlugin, passe getLoader().

Criando um holograma

O exemplo abaixo recebe a factory já obtida, o plugin Bukkit e a localização de criação:

import br.com.ystoreplugins.lib.helper.entity.hologram.Hologram;
import br.com.ystoreplugins.lib.helper.entity.hologram.HologramFactory;
import org.bukkit.Location;
import org.bukkit.plugin.Plugin;

import java.util.Arrays;
import java.util.HashMap;

public Hologram criarHolograma(HologramFactory factory, Plugin plugin, Location location) {
    Hologram hologram = factory.spawnHologram(plugin, location.clone());

    HashMap<String, String> substituicoes = new HashMap<>();
    substituicoes.put("{servidor}", "Survival");
    substituicoes.put("{online}", "10");

    hologram.setLines(Arrays.asList(
        "§6Bem-vindo ao {servidor}!",
        "§7Jogadores online: §f{online}"
    ), substituicoes);

    return hologram;
}

Em um BukkitPlugin, a chamada fica assim:

Hologram hologram = criarHolograma(factory, getLoader(), location);

Guarde a referência retornada para atualizar ou remover esse holograma posteriormente.

Linhas de texto e itens

Definindo e atualizando linhas

Os métodos recebem uma lista de linhas e um HashMap<String, String> com as substituições de texto. Use um mapa vazio quando não houver substituições.

void setLines(List<String> lines, HashMap<String, String> toReplace);

void updateLines(List<String> lines, HashMap<String, String> toReplace);

void setLines(List<String> lines, HashMap<String, String> toReplace,
              HashMap<String, ItemStack> toReplaceItem);

void updateLines(List<String> lines, HashMap<String, String> toReplace,
                 HashMap<String, ItemStack> toReplaceItem);

Use setLines(...) na montagem inicial e updateLines(...) para atualizar as linhas existentes. Para manter a compatibilidade entre os provedores, atualize preservando a quantidade e o tipo das linhas.

Exemplo de atualização do holograma anterior:

HashMap<String, String> substituicoes = new HashMap<>();
substituicoes.put("{servidor}", "Survival");
substituicoes.put("{online}", "25");

hologram.updateLines(Arrays.asList(
    "§6Bem-vindo ao {servidor}!",
    "§7Jogadores online: §f{online}"
), substituicoes);

As substituições são aplicadas ao chamar o método. Para refletir novos valores, chame updateLines(...) novamente com os dados atualizados.

Linhas especiais

Além do texto comum, as listas de linhas aceitam estes prefixos:

Formato	Descrição
`[item]DIAMOND`	Exibe um item pelo material informado.
`[item]premio`	Usa o `ItemStack` da chave `premio` no mapa `toReplaceItem`.
`[head]textura`	Exibe uma cabeça com a textura informada no lugar de `textura`.

Exemplo de montagem de um novo holograma com um item personalizado:

import org.bukkit.Material;
import org.bukkit.inventory.ItemStack;

Hologram hologramPremio = factory.spawnHologram(plugin, location.clone());

HashMap<String, String> substituicoes = new HashMap<>();
substituicoes.put("{premio}", "Diamante");

HashMap<String, ItemStack> itens = new HashMap<>();
itens.put("premio", new ItemStack(Material.DIAMOND));

hologramPremio.setLines(Arrays.asList(
    "§ePrêmio: §f{premio}",
    "[item]premio"
), substituicoes, itens);

Para adicionar linhas individualmente, use:

hologram.appendTextLine("§aClique no NPC para continuar!");
hologram.appendItemLine(new ItemStack(Material.EMERALD));

Métodos do Hologram

Além das sobrecargas de setLines(...) e updateLines(...), a interface oferece:

Método	Retorno	Descrição
`appendTextLine(String line)`	`void`	Adiciona uma linha de texto.
`appendItemLine(ItemStack line)`	`void`	Adiciona uma linha de item.
`setVisibileByDefault(boolean visible)`	`void`	Define a visibilidade padrão do holograma.
`showTo(Player player)`	`void`	Exibe o holograma para o jogador informado.
`isDeleted()`	`boolean`	Informa se o holograma foi removido.
`delete()`	`void`	Remove o holograma.
`getLocation()`	`Location`	Retorna a localização atual.
`teleport(Location location)`	`void`	Move o holograma para outra localização.
`getInitialSpawn()`	`Location`	Retorna a localização de criação.

Visibilidade

hologram.setVisibileByDefault(false);
hologram.showTo(player);

O nome do método na API é setVisibileByDefault, com essa grafia.

Localização

Location atual = hologram.getLocation();
Location origem = hologram.getInitialSpawn().clone();

hologram.teleport(atual.clone().add(0, 1, 0));

Remoção e ciclo de vida

Remova os hologramas criados pelo seu plugin quando eles deixarem de ser necessários ou durante o onDisable():

if (hologram != null && !hologram.isDeleted()) {
    hologram.delete();
    hologram = null;
}

getHolograms() consulta a factory compartilhada e não representa apenas os hologramas do seu plugin. Para gerenciar seus próprios hologramas, mantenha as referências retornadas por spawnHologram(...) e consulte isDeleted() quando necessário.

O loader chama close(Plugin) no seu encerramento. Essa operação pode remover os hologramas da factory inteira; para a limpeza de um plugin individual, use delete() nas referências que ele criou.

Nesta página