API et guide du développeur FreeMinecraftModels

FreeMinecraftModels est à la fois un plugin autonome et une surface API pour d'autres plugins.

Dépôt 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>

Dépendance

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

Utilisez-le en compileOnly/provided. Ne shadez pas le plugin dans votre propre jar.

Points d'entrée principaux

• ModeledEntityManager.modelExists(String)
• ModeledEntityManager.reload()
• ModeledEntityManager.getAllEntities()
• ModeledEntityManager.getDynamicEntities()
• ModeledEntityManager.propEntities()

Types d'exécution principaux

• ModeledEntity
• StaticEntity
• DynamicEntity
• PropEntity

Création d'entités

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);

Tous les chemins de création renvoient null si l'identifiant de modèle demandé n'est pas chargé.

createWithInvisibility est une variante qui applique une potion d'invisibilité au lieu de masquer l'entité des clients. Cela maintient l'entité suivie côté client, ce qui est nécessaire pour la direction des véhicules (utilisé en interne par /fmm mount).

Méthodes d'exécution utiles

• ModeledEntity#setDisplayName(String)
• ModeledEntity#setDisplayNameVisible(boolean)
• ModeledEntity#setLeftClickCallback(...)
• ModeledEntity#setRightClickCallback(...)
• ModeledEntity#setHitboxContactCallback(...)
• ModeledEntity#setModeledEntityHitByProjectileCallback(...)
• ModeledEntity#playAnimation(String, boolean, boolean)
• ModeledEntity#stopCurrentAnimations()
• ModeledEntity#hasAnimation(String)
• DynamicEntity#setSyncMovement(boolean)
• Bone#getBoneLocation()

Surface d'événements

Événements d'interaction génériques :

• ModeledEntityLeftClickEvent
• ModeledEntityRightClickEvent
• ModeledEntityHitboxContactEvent
• ModeledEntityHitByProjectileEvent

Des variantes typées existent également pour StaticEntity, DynamicEntity et PropEntity.

ModeledEntityHitByProjectileEvent et détection de projectiles OBB

FMM utilise la détection de collision OBB (boîte englobante orientée) pour les projectiles contre les entités modelées. Lorsqu'un projectile intersecte la hitbox OBB d'une entité modelée, FMM déclenche un ModeledEntityHitByProjectileEvent. C'est un événement Bukkit annulable standard.

Détails clés :

• Les dégâts de flèche sont calculés avec prise en charge du bonus de l'enchantement POWER
• L'enchantement PIERCING est respecté -- les flèches peuvent traverser vers des cibles supplémentaires
• Annulez l'événement pour empêcher les dégâts et bloquer l'impact entièrement

@EventHandler
public void onProjectileHitModel(ModeledEntityHitByProjectileEvent event) {
    ModeledEntity target = event.getModeledEntity();
    Projectile projectile = event.getProjectile();
    // Annuler pour empêcher les dégâts
    event.setCancelled(true);
}

Utilitaires d'objets et de modèles

ModelItemFactory

Classe factory pour créer des ItemStacks liés aux modèles de manière programmatique.

// Créer un objet de placement de prop (utilise la clé PDC "model_id")
ItemStack placementItem = ModelItemFactory.createModelItem("lamp_post", Material.STICK);

// Créer un objet personnalisé depuis la configuration (utilise la clé PDC "fmm_item_id")
PropScriptConfigFields config = ItemScriptManager.getItemDefinitions().get("magic_sword");
ItemStack customItem = ModelItemFactory.createCustomItem("magic_sword", config);

• createModelItem(String modelId, Material material) -- crée un objet de placement pour les props. Sur 1.21.4+, applique automatiquement le rendu du display model si un JSON de display existe.
• createCustomItem(String itemId, PropScriptConfigFields config) -- crée un objet personnalisé avec nom, lore, enchantements et display model depuis la configuration unifiée.
• formatModelName(String modelId) -- utilitaire qui convertit un ID de modèle comme 01_em_flame_sword en Flame Sword.

DisplayModelRegistry

Registre simple qui suit quels modèles ont un JSON de display disponible.

// Vérifier si un modèle a un JSON de display model enregistré
boolean has3D = DisplayModelRegistry.hasDisplayModel("magic_sword");

• register(String modelId) -- enregistre un ID de modèle (appelé en interne lors du rechargement)
• hasDisplayModel(String modelId) -- renvoie true si un .json de display model existe pour ce modèle
• shutdown() -- efface tous les enregistrements

ItemScriptManager

Gère le cycle de vie des scripts Lua par joueur pour les objets personnalisés (modèles avec material: défini dans leur configuration YML).

// Obtenir toutes les définitions d'objets personnalisés enregistrées
Map<String, PropScriptConfigFields> items = ItemScriptManager.getItemDefinitions();

// Obtenir l'instance de script Lua active pour un joueur + objet
ScriptInstance instance = ItemScriptManager.getActiveScript(playerUUID, "magic_sword");

// Obtenir tous les scripts actifs pour un joueur
Map<String, ScriptInstance> scripts = ItemScriptManager.getActiveScripts(playerUUID);

• scanForCustomItems(File modelsFolder) -- scanne les configurations YML de modèles à la recherche d'objets personnalisés
• updateEquippedScripts(Player player) -- compare les objets équipés avec les scripts en cours d'exécution, déclenchant les hooks équiper/déséquiper
• removePlayer(Player player) -- arrête tous les scripts pour un joueur (appeler à la déconnexion)
• getItemDefinitions() -- renvoie la carte d'ID d'objet vers PropScriptConfigFields

ScriptedItemAPI

API publique permettant aux plugins externes de s'intégrer avec le système d'objets scriptés de FMM. Cela permet à d'autres plugins de marquer leurs propres ItemStacks avec les données d'objets scriptés de FMM (tag PDC + modèle d'objet) pour que les hooks de script Lua de FMM se déclenchent pour ces objets, sans que FMM ne modifie le nom, le lore ou les enchantements de l'objet.

// Vérifier si une définition d'objet scripté existe
boolean exists = ScriptedItemAPI.isValidItemId("flame_blade");

// Appliquer les données d'objet scripté FMM à un ItemStack existant
// Cela définit :
// - Le tag PDC fmm_item_id (pour que le système de script de FMM reconnaisse l'objet)
// - Le modèle d'objet (1.21.4+) du registre de display model de FMM
// NE modifie PAS le nom, le lore, les enchantements ou toute autre propriété de l'objet.
boolean success = ScriptedItemAPI.applyScriptedItemData(itemStack, "flame_blade");

// Obtenir la configuration d'un objet scripté
PropScriptConfigFields config = ScriptedItemAPI.getItemConfig("flame_blade");

• isValidItemId(String itemId) -- renvoie true si l'ID d'objet est enregistré dans les définitions d'objets de FMM
• applyScriptedItemData(ItemStack itemStack, String itemId) -- applique le tag PDC et le modèle d'objet sur un ItemStack existant. Renvoie true en cas de succès, false si l'ID d'objet est invalide ou l'ItemStack n'a pas de meta. Note arc/arbalète : si l'itemId donné n'a pas de display model mais que itemId + "_idle" en a un (c.-à-d. l'objet a des modèles d'état arc/arbalète), la méthode utilise automatiquement le modèle _idle comme display model
• getItemConfig(String itemId) -- renvoie le PropScriptConfigFields pour l'ID d'objet donné, ou null s'il n'est pas trouvé

Intégration EliteMobs

EliteMobs utilise cette API en interne via le champ de configuration scriptedItem. Lorsqu'un objet personnalisé EliteMobs définit scriptedItem: flame_blade, EliteMobs construit son objet normalement (nom, lore, enchantements, niveau) puis appelle ScriptedItemAPI.applyScriptedItemData() pour ajouter le modèle et le comportement de script de FMM par-dessus.

PropScriptConfigFields

Classe de configuration unifiée pour les fichiers de configuration YML de modèles. Utilisée à la fois par les scripts de props et les objets personnalisés.

# Exemple : torch_01.yml
isEnabled: true
scripts:
  - torch_glow.lua
material: STICK          # Si défini, le modèle devient un objet personnalisé
name: "&eMagic Torch"    # Nom d'affichage personnalisé (optionnel)
lore:                     # Lignes de lore personnalisées (optionnel)
  - "&7Glows in the dark"
enchantments:             # Enchantements (optionnel, format : NAME,LEVEL)
  - "FIRE_ASPECT,1"

Méthodes clés : isCustomItem(), getParsedMaterial(), getParsedEnchantments(), getScripts().

Scripts Lua

FreeMinecraftModels prend en charge les scripts Lua à la fois pour les props et les objets personnalisés via le moteur de scripting MagmaCore 2.0. Les fichiers de script sont placés dans plugins/FreeMinecraftModels/scripts/ et sont liés aux modèles via un fichier de configuration YML situé à côté du fichier de modèle.

Hooks de scripts de props

Hook	Déclencheur
on_spawn	Le prop est apparu dans le monde
on_game_tick	Chaque tick tant que le prop est actif
on_zone_enter	Un joueur entre dans la zone du prop
on_zone_leave	Un joueur quitte la zone du prop
on_destroy	Le prop est supprimé
on_left_click	Un joueur fait un clic gauche sur le prop
on_right_click	Un joueur fait un clic droit sur le prop
on_projectile_hit	Un projectile touche le prop

Hooks de scripts d'objets

Les objets personnalisés (modèles avec material: défini) prennent en charge 22 hooks Lua :

Hook	Déclencheur
on_equip	L'objet entre dans un slot d'équipement suivi
on_unequip	L'objet quitte un slot d'équipement suivi
on_game_tick	Chaque tick tant que l'objet est équipé
on_attack_entity	Le joueur attaque une entité en tenant l'objet
on_kill_entity	Le joueur tue une entité en tenant l'objet
on_take_damage	Le joueur prend des dégâts avec l'objet équipé
on_shield_block	Le joueur bloque avec un bouclier
on_shoot_bow	Le joueur tire avec un arc
on_projectile_hit	Un projectile tiré par le joueur touche quelque chose
on_projectile_launch	Le joueur lance un projectile
on_right_click	Le joueur fait un clic droit avec l'objet
on_left_click	Le joueur fait un clic gauche avec l'objet
on_shift_right_click	Le joueur fait shift+clic droit avec l'objet
on_shift_left_click	Le joueur fait shift+clic gauche avec l'objet
on_interact_entity	Le joueur fait un clic droit sur une entité avec l'objet
on_swap_hands	Le joueur échange l'objet entre les mains
on_drop	Le joueur lâche l'objet
on_break_block	Le joueur casse un bloc en tenant l'objet
on_consume	Le joueur consomme l'objet
on_item_damage	L'objet subit des dégâts de durabilité
on_fish	Le joueur utilise une canne à pêche
on_death	Le joueur meurt avec l'objet équipé

Les scripts d'objets reçoivent context.item (avec l'ID de l'objet et les informations du joueur) au lieu de context.prop.

Table de contexte des scripts de props

Les scripts reçoivent une table context. Voici un résumé des API clés -- consultez API Lua Prop et Objet pour les détails complets.

context.prop :

• model_id -- le nom du modèle de base
• current_location -- la position actuelle du prop
• play_animation(name, blend, loop) -- joue l'animation nommée (blend et loop par défaut à true)
• stop_animation() -- arrête toutes les animations en cours
• hurt_visual() -- joue l'animation visuelle de dégâts (flash rouge) sur le prop
• pickup() -- supprime le prop et lâche son objet de placement
• mount(player) -- fait monter un joueur sur le prop
• dismount(player) -- retire un joueur du prop
• get_passengers() -- renvoie la liste des joueurs actuellement montés sur le prop
• spawn_elitemobs_boss(filename, x, y, z) -- fait apparaître un boss EliteMobs relatif au prop

context.event :

• Disponible dans on_left_click, on_right_click et on_projectile_hit
• cancel(), uncancel(), is_cancelled
• player -- le joueur qui a déclenché l'événement

context.world :

• spawn_entity(entity_type, location) -- fait apparaître une entité vanilla
• set_block_at(location, material) -- place un bloc dans le monde
• Plus les particules, sons, requêtes de blocs, foudre et recherche d'entités à proximité

Objets joueur (depuis context.event.player) :

• get_held_item() -- renvoie l'objet que le joueur tient en main
• consume_held_item() -- retire un exemplaire de l'objet tenu
• has_item(material) -- vérifie si le joueur possède un objet
• send_message(text) -- envoie un message de chat au joueur
• game_mode -- le mode de jeu actuel du joueur

Exemple 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

Exemple de script d'objet

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

function on_attack_entity(context)
    -- Fire effect on hit
    context.event.player.send_message("&cBurn!")
end

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

Notes

• FreeMinecraftModels est une dépendance de plugin installé, pas une bibliothèque intégrable.
• Si votre plugin a besoin de modèles fraîchement importés, appelez ModeledEntityManager.reload() au lieu d'essayer de reconstruire l'état de FreeMinecraftModels vous-même.
• Tous les plugins de l'écosystème Nightbreak dépendent désormais de MagmaCore 2.0.0-SNAPSHOT, qui inclut le moteur de scripting Lua partagé utilisé par les scripts de props FreeMinecraftModels et les pouvoirs Lua d'EliteMobs.