Pular para o conteúdo principal

API do FreeMinecraftModels e Guia do Desenvolvedor

O FreeMinecraftModels é tanto um plugin independente quanto uma superfície de API para outros plugins.

Repositório Maven​

<repository>
    <id>magmaguy-repo-releases</id>
    <name>MagmaGuy's Repository</name>
    <url>https://repo.magmaguy.com/releases</url>
</repository>
<repository>
    <id>magmaguy-repo-snapshots</id>
    <name>MagmaGuy's Snapshot Repository</name>
    <url>https://repo.magmaguy.com/snapshots</url>
</repository>

Dependência​

<dependency>
    <groupId>com.magmaguy</groupId>
    <artifactId>FreeMinecraftModels</artifactId>
    <version>LATEST.VERSION.HERE</version>
    <scope>provided</scope>
</dependency>

Use como compileOnly/provided. Não faça shade do plugin dentro do seu próprio jar.

Pontos de Entrada Principais​

  • ModeledEntityManager.modelExists(String)
  • ModeledEntityManager.reload()
  • ModeledEntityManager.getAllEntities()
  • ModeledEntityManager.getDynamicEntities()
  • ModeledEntityManager.propEntities()
  • DisguiseAPI — disfarça / retira disfarce de jogadores como modelos carregados
  • LocationAPI — registra detectores de dungeon e provedores de proteção (alimenta os predicados Lua em.location.*)
  • ScriptedItemAPI — marca ItemStacks de terceiros com metadados de item programável do FMM

Tipos Principais de Runtime​

  • ModeledEntity
  • StaticEntity
  • DynamicEntity
  • PropEntity

Criando Entidades​

StaticEntity preview = StaticEntity.create("example_model", location);
DynamicEntity mobModel = DynamicEntity.create("example_model", livingEntity);
DynamicEntity mount = DynamicEntity.createWithInvisibility("example_model", livingEntity);
PropEntity prop = PropEntity.spawnPropEntity("example_model", location);

Todos os caminhos de criação retornam null se o ID do modelo solicitado não estiver carregado.

createWithInvisibility é uma variante que aplica uma poção de invisibilidade em vez de esconder a entidade dos clientes. Isso mantém a entidade rastreada no lado do cliente, necessário para direção de veículos (usado internamente por /fmm mount).

Métodos Úteis de Runtime​

  • ModeledEntity#setDisplayName(String)
  • ModeledEntity#setDisplayNameVisible(boolean)
  • ModeledEntity#setLeftClickCallback(...)
  • ModeledEntity#setRightClickCallback(...)
  • ModeledEntity#setHitboxContactCallback(...)
  • ModeledEntity#setModeledEntityHitByProjectileCallback(...)
  • ModeledEntity#playAnimation(String, boolean, boolean)
  • ModeledEntity#stopCurrentAnimations()
  • ModeledEntity#hasAnimation(String)
  • ModeledEntity#getEntityID() -- retorna a string do ID do modelo
  • ModeledEntity#getLocation() -- retorna o Location atual
  • ModeledEntity#getWorld() -- retorna o World
  • ModeledEntity#getViewers() -- retorna o HashSet<UUID> de jogadores que podem ver a entidade
  • ModeledEntity#getNametagBones() -- retorna List<Bone> de bones de nametag (útil para colocar texto adicional)
  • ModeledEntity#getScaleModifier() / setScaleModifier(double)
  • ModeledEntity#removeWithDeathAnimation() -- remove com a animação de morte (se existir uma)
  • ModeledEntity#removeWithMinimizedAnimation() -- remove com uma animação de redução de escala
  • ModeledEntity#remove() -- remove imediatamente a entidade e todos os bones
  • ModeledEntity#setTintColor(Color) / getTintColor() -- aplica um tint persistente via o canal de tinta de armadura de couro. Flashes de dano sobrescrevem brevemente o tint e então retornam a ele. Passe null para limpar.
  • ModeledEntity#setViewDistanceOverride(int) / getEffectiveViewDistance() -- sobrescreve DefaultConfig.maxModelViewDistance para uma única entidade. Passe -1 para reverter ao padrão geral do plugin.
  • DynamicEntity#setSyncMovement(boolean)
  • DynamicEntity#isDamagesOnContact() / setDamagesOnContact(boolean) -- controla se a entidade causa dano em jogadores via contato com hitbox
  • Bone#getBoneLocation()

Superfície de Eventos​

Eventos de interação genéricos:

  • ModeledEntityLeftClickEvent
  • ModeledEntityRightClickEvent
  • ModeledEntityHitboxContactEvent
  • ModeledEntityHitByProjectileEvent

Variantes tipadas também existem para StaticEntity, DynamicEntity e PropEntity.

Eventos de ciclo de vida:

  • ResourcePackGenerationEvent -- dispara quando o FMM termina de gerar ou regenerar o resource pack (na inicialização e em /fmm reload). Escute para acionar pós-processamento no pack gerado.

  • FmmReloadedEvent -- dispara após o FMM terminar sua sequência de inicialização na inicialização e após cada /fmm reload. Sempre dispara na thread principal do servidor.

    Plugins consumidores que mantêm referências de longa duração a DynamicEntity ou PropEntity (EliteMobs, BetterStructures, etc.) devem lidar com este evento recriando seus anexos de modelo nas entidades subjacentes sobreviventes. Sem isso, essas entidades ficam invisíveis após um reload porque o FMM derrubou as display entities durante onDisable enquanto a referência do consumidor agora está obsoleta.

    @EventHandler
    public void onFmmReloaded(FmmReloadedEvent event) {
        for (MyTrackedEntity tracked : myEntities) {
            if (tracked.bukkitEntity != null && tracked.bukkitEntity.isValid()) {
                tracked.fmmModel = DynamicEntity.create("my_model", tracked.bukkitEntity);
            }
        }
    }

ModeledEntityHitByProjectileEvent e Detecção de Projéteis OBB​

O FMM usa detecção de hit OBB (oriented bounding box) para projéteis contra entidades modeladas. Quando um projétil intersecta o hitbox OBB de uma entidade modelada, o FMM dispara um ModeledEntityHitByProjectileEvent. Este é um evento Bukkit cancelável padrão.

Detalhes principais:

  • O dano de flecha é calculado com suporte ao bônus do encantamento POWER
  • O encantamento PIERCING é respeitado -- flechas podem atravessar para alvos adicionais
  • Cancele o evento para prevenir dano e bloquear o hit por completo
@EventHandler
public void onProjectileHitModel(ModeledEntityHitByProjectileEvent event) {
    ModeledEntity target = event.getModeledEntity();
    Projectile projectile = event.getProjectile();
    // Cancela para prevenir dano
    event.setCancelled(true);
}

Utilitários de Item e Modelo​

ModelItemFactory​

Classe factory para criar ItemStacks relacionados a modelos programaticamente.

// Cria um item de colocação de prop (usa a chave PDC "model_id")
ItemStack placementItem = ModelItemFactory.createModelItem("lamp_post", Material.STICK);

// Cria um item customizado a partir de config (usa a chave PDC "fmm_item_id")
PropScriptConfigFields config = ItemScriptManager.getItemDefinitions().get("magic_sword");
ItemStack customItem = ModelItemFactory.createCustomItem("magic_sword", config);
  • createModelItem(String modelId, Material material) -- cria um item de colocação para props. Em 1.21.4+, aplica automaticamente renderização de display model se um JSON de display existir.
  • createCustomItem(String itemId, PropScriptConfigFields config) -- cria um item customizado com nome, lore, encantamentos e display model a partir da config unificada.
  • formatModelName(String modelId) -- utilitário que converte um ID de modelo como 01_em_flame_sword em Flame Sword.

DisplayModelRegistry​

Registro simples que rastreia quais modelos têm um JSON de display disponível.

// Verifica se um modelo tem um JSON de display model registrado
boolean has3D = DisplayModelRegistry.hasDisplayModel("magic_sword");
  • register(String modelId) -- registra um ID de modelo (chamado internamente durante o reload)
  • hasDisplayModel(String modelId) -- retorna true se um .json de display model existir para este modelo
  • getRegisteredModels() -- retorna um Set<String> imutável de todos os IDs de modelo que têm display models registrados
  • shutdown() -- limpa todos os registros

ItemScriptManager​

Gerencia o ciclo de vida de scripts Lua por jogador para itens customizados (modelos com material: definido em sua configuração YML).

// Obtém todas as definições de itens customizados registradas
Map<String, PropScriptConfigFields> items = ItemScriptManager.getItemDefinitions();

// Obtém a instância de script Lua ativa para um jogador + item
ScriptInstance instance = ItemScriptManager.getActiveScript(playerUUID, "magic_sword");

// Obtém todos os scripts ativos para um jogador
Map<String, ScriptInstance> scripts = ItemScriptManager.getActiveScripts(playerUUID);
  • scanForCustomItems(File modelsFolder) -- escaneia configurações YML de modelos para itens customizados
  • updateEquippedScripts(Player player) -- faz diff de itens equipados contra scripts em execução, disparando hooks de equip/unequip
  • removePlayer(Player player) -- encerra todos os scripts para um jogador (chame ao sair)
  • getItemDefinitions() -- retorna o mapa de ID de item para PropScriptConfigFields

ScriptedItemAPI​

API pública para plugins externos integrarem com o sistema de itens programáveis do FMM. Isso permite que outros plugins marquem seus próprios ItemStacks com dados de item programável do FMM (tag PDC + item model) para que os hooks de script Lua do FMM disparem para esses itens, sem o FMM sobrescrever o nome, lore ou encantamentos do item.

// Verifica se uma definição de item programável existe
boolean exists = ScriptedItemAPI.isValidItemId("flame_blade");

// Aplica dados de item programável do FMM a um ItemStack existente
// Isto define:
// - A tag PDC fmm_item_id (para que o sistema de scripts do FMM reconheça o item)
// - O item model (1.21.4+) a partir do registro de display models do FMM
// NÃO modifica nome, lore, encantamentos ou quaisquer outras propriedades do item.
boolean success = ScriptedItemAPI.applyScriptedItemData(itemStack, "flame_blade");

// Obtém a config para um item programável
PropScriptConfigFields config = ScriptedItemAPI.getItemConfig("flame_blade");
  • isValidItemId(String itemId) -- retorna true se o ID do item está registrado nas definições de item do FMM
  • applyScriptedItemData(ItemStack itemStack, String itemId) -- carimba tag PDC e item model em um ItemStack existente. Retorna true em sucesso, false se o ID do item é inválido ou o ItemStack não tem meta. Nota para arco/besta: se o itemId dado não tem um display model mas itemId + "_idle" tem (ou seja, o item tem modelos de estado de arco/besta), o método usa automaticamente o modelo _idle como display model
  • getItemConfig(String itemId) -- retorna o PropScriptConfigFields para o ID de item dado, ou null se não encontrado
Integração com EliteMobs

O EliteMobs usa esta API internamente via o campo de config scriptedItem. Quando um item customizado do EliteMobs define scriptedItem: flame_blade, o EliteMobs constrói seu item normalmente (nome, lore, encantamentos, nível) e então chama ScriptedItemAPI.applyScriptedItemData() para adicionar o modelo e comportamento de script do FMM por cima.

DisguiseAPI​

Ponto de entrada público para o recurso de disfarce de jogadores. Plugins de terceiros devem chamar esta classe em vez do DisguiseManager interno para que refatorações internas permaneçam seguras.

import com.magmaguy.freeminecraftmodels.api.DisguiseAPI;

// Disfarça um jogador como um modelo carregado. Substitui qualquer disfarce existente de forma limpa.
boolean ok = DisguiseAPI.disguise(player, "dragon");

// Retira o disfarce (retorna true se um disfarce foi removido).
DisguiseAPI.undisguise(player);

// Consulta de estado.
boolean disguised = DisguiseAPI.isDisguised(player);
String modelID = DisguiseAPI.getDisguiseModelID(player); // null se não estiver disfarçado

// Snapshot de todos os jogadores atualmente disfarçados.
Collection<Player> all = DisguiseAPI.getDisguisedPlayers();
  • disguise(Player, String modelID) -- retorna false se o ID do modelo não estiver carregado
  • undisguise(Player) -- retorna true se um disfarce foi removido
  • isDisguised(Player) -- verificação booleana rápida
  • getDisguiseModelID(Player) -- retorna o ID do modelo ativo ou null
  • getDisguisedPlayers() -- snapshot imutável de jogadores disfarçados

Jogadores disfarçados ficam invisíveis para os outros e assim permanecem até serem deszdisfarçados — baldes de leite, limpezas de efeito por beacon e interações similares não quebram a invisibilidade.

LocationAPI​

API pública para plugins contribuírem com detecção de dungeon e verificações de proteção de região. Os predicados registrados alimentam as verificações Lua em.location.is_in_dungeon e em.location.is_protected do FMM (usadas por scripts pré-feitos como pickupable.lua e storage_double.lua).

Plugins passam um Predicate<Location> puro para que nenhum tipo FMM com shade atravesse classloaders de plugins.

import com.magmaguy.freeminecraftmodels.api.LocationAPI;

// No enable do seu plugin, após WorldGuard/EliteMobs/etc. estarem disponíveis.
LocationAPI.registerDungeonLocator("EliteMobs",
        location -> EliteMobs.isInsideDungeon(location));

LocationAPI.registerProtectionProvider("WorldGuard",
        location -> WorldGuardBridge.isProtected(location));
  • registerDungeonLocator(String providerName, Predicate<Location> predicate) — qualquer predicado registrado retornando true marca a localização como "em dungeon"
  • registerProtectionProvider(String providerName, Predicate<Location> predicate) — qualquer predicado registrado retornando true marca a localização como protegida

Operadores podem verificar o registro com /fmm location, que reporta a contagem ao vivo de provedores e testa ambos os predicados contra a localização atual.

PropScriptConfigFields​

Classe de configuração unificada para arquivos YML de config de modelo. Usada tanto por scripts de prop quanto por itens customizados.

# Exemplo: torch_01.yml
isEnabled: true
scripts:
  - torch_glow.lua
material: STICK          # Se definido, o modelo se torna um item customizado
name: "&eMagic Torch"    # Nome de exibição customizado (opcional)
lore:                     # Linhas de lore customizadas (opcional)
  - "&7Glows in the dark"
enchantments:             # Encantamentos (opcional, formato: NOME,NÍVEL)
  - "FIRE_ASPECT,1"

Métodos principais: isCustomItem(), getParsedMaterial(), getParsedEnchantments(), getScripts().

Scripting Lua​

O FreeMinecraftModels suporta scripts Lua tanto para props quanto para itens customizados através do motor de scripting MagmaCore 2.0. Arquivos de script são colocados em plugins/FreeMinecraftModels/scripts/ e são vinculados a modelos via uma config YML irmã ao lado do arquivo do modelo.

Hooks de Script de Prop​

HookGatilho
on_spawnO prop é spawnado no mundo
on_game_tickA cada tick enquanto o prop estiver vivo
on_zone_enterUm jogador entra na zona do prop
on_zone_leaveUm jogador sai da zona do prop
on_destroyO prop é removido
on_left_clickO jogador clica com botão esquerdo no prop
on_right_clickO jogador clica com botão direito no prop
on_projectile_hitUm projétil atinge o prop

Hooks de Script de Item​

Itens customizados (modelos com material: definido) suportam 22 hooks Lua:

HookGatilho
on_equipO item entra em um slot de equipamento rastreado
on_unequipO item sai de um slot de equipamento rastreado
on_game_tickA cada tick enquanto o item estiver equipado
on_attack_entityO jogador ataca uma entidade segurando o item
on_kill_entityO jogador mata uma entidade segurando o item
on_take_damageO jogador sofre dano enquanto o item está equipado
on_shield_blockO jogador bloqueia com um escudo
on_shoot_bowO jogador atira com um arco
on_projectile_hitUm projétil disparado pelo jogador atinge algo
on_projectile_launchO jogador lança um projétil
on_right_clickO jogador clica com botão direito com o item
on_left_clickO jogador clica com botão esquerdo com o item
on_shift_right_clickO jogador shift-clica com botão direito com o item
on_shift_left_clickO jogador shift-clica com botão esquerdo com o item
on_interact_entityO jogador clica com botão direito em uma entidade com o item
on_swap_handsO jogador troca o item entre as mãos
on_dropO jogador derruba o item
on_break_blockO jogador quebra um bloco segurando o item
on_consumeO jogador consome o item
on_item_damageO item sofre dano de durabilidade
on_fishO jogador usa uma vara de pesca
on_deathO jogador morre com o item equipado

Scripts de item recebem context.item (com o ID do item e info do jogador) em vez de context.prop.

Tabela de Contexto do Script de Prop​

Scripts de prop recebem uma tabela context. Aqui está um resumo das APIs principais -- veja API Lua de Prop para detalhes completos.

context.prop:

  • model_id -- o nome do modelo blueprint
  • current_location -- a localização atual do prop
  • play_animation(name, blend, loop) -- toca a animação nomeada (blend e loop padrão para true)
  • stop_animation() -- para todas as animações atuais
  • hurt_visual() -- toca o visual de dano (flash vermelho) no prop
  • pickup() -- remove o prop e dropa seu item de colocação
  • mount(player) -- faz um jogador montar o prop
  • dismount(player) -- remove um jogador do prop
  • get_passengers() -- retorna uma lista de jogadores atualmente montados no prop
  • spawn_elitemobs_boss(filename, x, y, z) -- spawna um chefe EliteMobs relativo ao prop

context.event:

  • Disponível em on_left_click, on_right_click e on_projectile_hit
  • cancel(), uncancel(), is_cancelled
  • player -- o jogador que disparou o evento

context.world:

  • spawn_entity(entity_type, location) -- spawna uma entidade vanilla
  • set_block_at(location, material) -- define um bloco no mundo
  • Além de partículas, sons, consultas de blocos, raios e buscas de entidades próximas

Objetos de jogador (de context.event.player):

  • get_held_item() -- retorna o item que o jogador está segurando
  • consume_held_item() -- remove um do item segurado
  • has_item(material) -- verifica se o jogador tem um item
  • send_message(text) -- envia uma mensagem de chat ao jogador
  • game_mode -- o modo de jogo atual do jogador

Exemplo de Script de Prop​

function on_spawn(context)
    context.prop.play_animation("idle", true, true)
end

function on_right_click(context)
    context.prop.play_animation("activate", false, false)
end

Exemplo de Script de Item​

function on_equip(context)
    context.event.player.send_message("&6You equipped the Flame Blade!")
end

function on_attack_entity(context)
    -- Efeito de fogo no hit
    context.event.player.send_message("&cBurn!")
end

function on_unequip(context)
    context.event.player.send_message("&7Flame Blade sheathed.")
end

Notas​

  • O FreeMinecraftModels é uma dependência de plugin instalado, não uma biblioteca embarcável.
  • Se seu plugin precisa de modelos recém-importados, chame ModeledEntityManager.reload() em vez de tentar reconstruir o estado do FreeMinecraftModels sozinho.
  • Todos os plugins no ecossistema Nightbreak agora dependem do MagmaCore 2.2.0-SNAPSHOT, que inclui o motor de scripting Lua compartilhado usado por scripts de prop do FreeMinecraftModels e poderes Lua do EliteMobs, mais o LocationQueryRegistry e WorldFolderResolver compartilhados.
  • O FreeMinecraftModels declara WorldGuard, WorldEdit, GriefPrevention e Vault como softdepend. Nenhum é obrigatório para iniciar o plugin, mas eles desbloqueiam recursos específicos: WorldGuard/WorldEdit/GriefPrevention alimentam a LocationAPI, e Vault habilita a loja de mobília.