NPCs

A biblioteca de NPCs do yPlugins oferece uma interface comum para criar personagens com nome, skin e ações de clique. O acesso é feito pela NpcFactory, e cada NPC criado é manipulado pela interface Npc.

As interfaces públicas estão no pacote:

br.com.ystoreplugins.lib.helper.entity.npc

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.npc.NpcFactory;

NpcFactory factory = BukkitBootstrap.get().getNpcFactory();

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

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

NpcFactory factory = getLoader().getNpcFactory();

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 NPCs.

Métodos da NpcFactory

Criação com textura e assinatura

Npc spawnNpc(Location location, String nametag,
             String skinTextures, String skinSignature);

Npc spawnNpc(Location location, String nametag,
             String skinTextures, String skinSignature, boolean lookClose);

Parâmetro	Descrição
`location`	Localização de criação do NPC.
`nametag`	Nome exibido sobre o NPC.
`skinTextures`	Valor da propriedade `textures` da skin, em Base64.
`skinSignature`	Assinatura correspondente à propriedade `textures`.
`lookClose`	Define se o NPC deve olhar para jogadores próximos. Na sobrecarga sem esse argumento, o valor utilizado é `true`.

Os métodos retornam um Npc. Forneça textura e assinatura da mesma skin; skinTextures é o valor da propriedade, e não uma URL de imagem.

Criando um NPC

O exemplo abaixo recebe a factory já obtida, a localização e os dados da skin:

import br.com.ystoreplugins.lib.helper.entity.npc.Npc;
import br.com.ystoreplugins.lib.helper.entity.npc.NpcFactory;
import org.bukkit.Location;

public Npc criarNpc(NpcFactory factory, Location location,
                    String skinTextures, String skinSignature) {
    Npc npc = factory.spawnNpc(
        location.clone(),
        "§6Loja",
        skinTextures,
        skinSignature,
        true
    );

    npc.setShowNametag(true);
    npc.setClickCallback(player -> player.sendMessage("§aBem-vindo à loja!"));

    return npc;
}

Guarde a referência retornada para alterar o NPC ou removê-lo posteriormente.

Sobrecargas obsoletas

As versões que recebem o nome de um jogador para definir a skin estão marcadas como @Deprecated na interface:

@Deprecated
Npc spawnNpc(Location location, String nametag, String skinPlayer);

@Deprecated
Npc spawnNpc(Location location, String nametag, String skinPlayer, boolean lookClose);

Para novas integrações, utilize as sobrecargas com skinTextures e skinSignature.

Encerramento

void close();

Executa a limpeza dos NPCs gerenciados pela factory compartilhada. O loader chama esse método no seu encerramento. Para remover apenas os NPCs criados pelo seu plugin, guarde as referências e utilize Npc.delete().

Métodos do Npc

Método	Retorno	Descrição
`setClickCallback(Consumer<Player> callback)`	`void`	Define a mesma ação para os cliques esquerdo e direito. Aceita `null` para remover as ações.
`setClickCallback(Consumer<Player> left, Consumer<Player> right)`	`void`	Define ações separadas para os cliques esquerdo e direito. Cada argumento aceita `null`.
`setSkin(String textures, String signature)`	`void`	Altera a skin usando textura e assinatura.
`setSkin(String skinPlayer)`	`void`	Altera a skin pelo nome de um jogador. Método obsoleto (`@Deprecated`).
`setName(String name)`	`void`	Altera o nome do NPC.
`setShowNametag(boolean show)`	`void`	Define se o nome deve ser exibido.
`setGlow(boolean glow)`	`void`	Solicita o efeito de brilho, conforme o suporte do provedor e da versão do servidor.
`traitLookAltern(boolean value)`	`void`	Ativa ou desativa o comportamento de olhar para jogadores próximos.
`getMeta()`	`String`	Retorna a chave de identificação por metadata utilizada pelo provedor.
`setMeta(String meta, FixedMetadataValue value)`	`void`	Define uma metadata quando há uma entidade Bukkit compatível.
`getEntity()`	`Entity`	Retorna a entidade Bukkit associada, quando disponível. Pode retornar `null`.
`getInitialSpawn()`	`Location`	Retorna a localização de criação.
`delete()`	`void`	Remove o NPC.

Ações de clique

O callback recebe o Player que clicou no NPC. Com dois argumentos, o primeiro corresponde ao clique esquerdo e o segundo ao direito:

npc.setClickCallback(
    player -> player.sendMessage("§eVocê clicou com o botão esquerdo."),
    player -> player.sendMessage("§aVocê clicou com o botão direito.")
);

Para responder somente ao clique direito:

npc.setClickCallback(null, player -> {
    player.sendMessage("§aAbrindo a loja...");
    // Abra seu menu aqui.
});

Para remover ambas as ações:

npc.setClickCallback(null, null);

Aparência e comportamento

npc.setName("§bVendedor");
npc.setShowNametag(true);
npc.setSkin(skinTextures, skinSignature);
npc.setGlow(true);
npc.traitLookAltern(false);

setGlow(boolean) possui uma implementação padrão vazia na interface. O efeito depende do suporte oferecido pelo provedor ativo.

Entidade e metadata

A interface permite consultar a entidade Bukkit associada. Como ela pode não existir, verifique o retorno antes de utilizá-la:

import org.bukkit.entity.Entity;

Entity entity = npc.getEntity();

if (entity != null) {
    Location atual = entity.getLocation();
}

Quando há suporte a metadata na entidade, é possível associar dados usando um Plugin Bukkit como proprietário:

import org.bukkit.metadata.FixedMetadataValue;

if (npc.getEntity() != null) {
    npc.setMeta("minha-loja", new FixedMetadataValue(plugin, "principal"));
}

Em um BukkitPlugin, substitua plugin por getLoader(). Para consultar a posição de criação pela interface comum, use npc.getInitialSpawn().clone().

Remoção e ciclo de vida

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

if (npc != null) {
    npc.delete();
    npc = null;
}

A NpcFactory não expõe um método de listagem de NPCs. Mantenha as referências retornadas por spawnNpc(...) em um campo ou coleção para controlar o ciclo de vida dos seus personagens.

Nesta página