Scripts Lua : Pour commencer

Cette page vous apprend à écrire votre premier script Lua pour un prop FreeMinecraftModels, d'un fichier vide jusqu'à un prop interactif fonctionnel. À la fin, vous comprendrez les hooks, le contexte, l'API prop et la structure générale de chaque fichier de script de prop.

Une fois à l'aise avec les bases, poursuivez avec les pages complémentaires :

API Prop -- les API context.prop, context.event, context.world et autres API de contexte
Exemples et patterns : scripts de props avec notes de configuration à étudier et adapter
Dépannage -- erreurs courantes, astuces de débogage et la liste de vérification QC

Fonctionnalité expérimentale

Les scripts Lua pour les props sont actuellement expérimentaux. Les noms de hooks, les méthodes utilitaires et le comportement peuvent encore changer à mesure que FreeMinecraftModels évolue, alors testez soigneusement avant de les utiliser sur un serveur de production.

Relation avec le Lua d'EliteMobs

FreeMinecraftModels utilise le moteur Lua MagmaCore. Si vous écrivez déjà des pouvoirs Lua pour EliteMobs, les concepts fondamentaux vous seront familiers : fichiers retournant une table, api_version, hooks, context, état, temps de recharge, planification et bac à sable. Les noms exacts des hooks et des méthodes du contexte dépendent néanmoins du plugin :

Les scripts EliteMobs s'exécutent sur les boss et ont des hooks comme on_boss_damaged_by_player, on_enter_combat, etc.
Les scripts de props FMM s'exécutent sur les props avec des hooks comme on_right_click, on_left_click, on_zone_enter, etc.
Les enchantements d'objets utilisent le contexte distinct des enchantements définis par les créateurs.

Les API context.world, context.zones, context.scheduler, context.state et context.log présentées ici sont celles de FreeMinecraftModels/MagmaCore. Les scripts de PNJ EliteMobs utilisent les mêmes tables génériques MagmaCore, avec context.npc en plus ; les pouvoirs de boss EliteMobs utilisent des variantes propres aux boss pour plusieurs tables. Cette page couvre les particularités des props FMM.

Ce que sont les scripts de props

Les scripts de props sont des fichiers .lua autonomes qui se trouvent dans le dossier plugins/FreeMinecraftModels/scripts/. Ils sont référencés depuis un fichier de configuration YAML qui se trouve à côté du fichier de modèle, et ils s'exécutent chaque fois que le prop est généré dans le monde.

Utilité des scripts de props

Les scripts de props conviennent aux besoins suivants :

Props interactifs qui réagissent aux clics des joueurs (portes, leviers, boutons)
Props décoratifs qui ignorent les dégâts par défaut du clic gauche
Déclencheurs de proximité qui détectent quand les joueurs entrent ou quittent une zone
Props animés qui jouent des animations lors d'interactions ou sur un minuteur
Props émetteurs de sons qui jouent des sons lorsqu'on clique dessus ou qu'on s'en approche
Tout comportement de prop nécessitant une logique au-delà de la décoration statique

Si votre prop est purement décoratif et n'a pas besoin d'interaction, vous n'avez pas besoin de script.

Objets personnalisés et enchantements

Les objets personnalisés utilisent toujours un YAML voisin du modèle avec un material, mais leurs effets reposent désormais sur des enchantements avec espace de noms. L'ancien moteur de scripts d'objets équipés a été retiré. Un objet personnalisé avec une liste scripts: non vide est ignoré avec un message informatif dans la console ; sa définition reste inchangée.

Les fichiers Lua reconnus comme anciens scripts d'objets équipés dans scripts/ sont conservés dans plugins/MagmaCore/outdated files/FreeMinecraftModels/<archive batch>/scripts/ avant la découverte et après les importations. La règle exige une ancienne définition valide contenant un hook d'objet retiré, comme on_equip ou on_attack_entity. Elle ne classe pas comme anciens scripts d'objets les scripts de props, les fichiers utilisant uniquement des hooks partagés, les scripts mal formés ni les effets actuels d'enchantments/. Consultez les fichiers de configuration retirés pour les consignes de récupération.

Consultez les objets personnalisés et armes magiques pour les définitions actuelles, et les enchantements définis par les créateurs pour les effets. Les listes scripts: des props continuent de fonctionner.

À qui s'adresse cette page

Cette page est écrite pour trois types de lecteurs :

Quelqu'un qui connaît déjà les scripts Lua d'EliteMobs et veut apprendre les hooks et API spécifiques à FMM
Quelqu'un qui est nouveau dans les scripts Lua et a besoin d'une référence complète avec les noms exacts pour les props
Quelqu'un qui utilise l'IA pour rédiger des scripts de props et a besoin de suffisamment de détails pour détecter quand l'IA invente quelque chose de faux

Vous n'avez pas besoin de devenir un développeur Lua complet avant d'écrire des scripts de props utiles. Pour la plupart des scripts pratiques de props, les seules choses dont vous avez vraiment besoin sont :

Comment placer un hook valide dans la table retournée
Comment lire les valeurs depuis context
Comment arrêter l'exécution avec if ... then return end
Comment appeler quelques méthodes utilitaires exactement

Mini-introduction à Lua

Vous n'avez pas besoin d'être un expert Lua pour écrire des scripts FMM. La plupart des scripts n'utilisent qu'une poignée de concepts : les variables (local x = 5), les fonctions (function foo() end), les vérifications if (if x then ... end), les tables ({key = value}) et nil (la valeur « rien » de Lua). La syntaxe est légère — pas de point-virgule, pas d'accolades, juste end pour fermer les blocs.

Pour un parcours complet avec exemples, voir le Moteur de scripts Lua MagmaCore — Mini-introduction à Lua. Cette introduction est partagée par tous les plugins Nightbreak : l'apprendre une fois vaut partout.

Où placer les fichiers

Fichiers de script

Placez les fichiers .lua dans le dossier central de scripts :

plugins/
  FreeMinecraftModels/
    scripts/
      invulnerable.lua
      interactive_door.lua
      proximity_sound.lua

FMM découvre récursivement les fichiers .lua de plugins/FreeMinecraftModels/scripts/ lors de l'initialisation du fournisseur de scripts, puis garde leur source en cache. Utilisez des noms uniques entre sous-dossiers : les liaisons utilisent le nom du fichier, pas son chemin relatif. Après un ajout ou une modification Lua, terminez un /fmm reload réussi avant de créer de nouvelles liaisons. Faire réapparaître le prop ne relit pas la source Lua.

Dans la liste scripts: d'un modèle, incluez l'extension .lua par souci de clarté. FMM accepte aussi les entrées sans extension et ajoute .lua en interne. Le fichier sur le disque doit malgré tout se terminer par .lua, et les noms restent sensibles à la casse.

Fichiers de modèle et fichiers de configuration

Chaque fichier de modèle peut avoir un fichier de configuration .yml adjacent dans le même répertoire :

plugins/
  FreeMinecraftModels/
    models/
      torch_01.fmmodel
      torch_01.yml          <-- script config for torch_01
    scripts/
      invulnerable.lua      <-- referenced by torch_01.yml

Le fichier de configuration .yml est ce qui connecte un modèle à ses scripts.

Format du fichier de configuration

Le fichier de configuration YAML qui se trouve à côté d'un fichier de modèle comporte ces champs :

isEnabled: true
voxelize: false
solidify: false
scripts:
  - invulnerable.lua

Les champs des props sont :

Champ	Type	Défaut	Notes
`isEnabled`	booléen	`true`	Active ou désactive la définition
`scripts`	liste de chaînes	`[]`	Noms des fichiers Lua de props dans `scripts/`
`voxelize`	booléen	`false`	Aligne le placement sur la grille de blocs et la rotation par pas de 90 degrés
`solidify`	booléen	`false`	Ajoute des blocs barrière par paquets à un prop voxelisé

Chaque script de prop listé reçoit sa propre instance. Pour les objets tenus, définissez plutôt material, name, lore et des enchantments avec espace de noms. Consultez les objets personnalisés.

Génération de configuration à la demande

Lorsqu'un prop apparaît et qu'aucun fichier .yml adjacent n'existe, FMM crée automatiquement un fichier de configuration par défaut avec isEnabled: true et une liste scripts: vide. Cela se fait de manière asynchrone, donc le prop n'aura pas de scripts lors de sa première apparition -- seulement après que la configuration soit créée et que vous l'éditiez pour ajouter les noms de fichiers de scripts.

Cela signifie :

Placez votre fichier de modèle dans models/
Faites apparaître le prop une fois (FMM crée le .yml automatiquement)
Éditez le .yml généré pour ajouter vos noms de fichiers de scripts
Réussissez /fmm reload après toute modification YAML ou Lua, puis placez un nouveau prop et vérifiez son journal ou son interaction. Les réglages des props, les vérifications de placement et les listes de scripts du menu partagent le catalogue préparé. Faire réapparaître le prop ne relit pas le YAML.

Référence des hooks

Chaque fichier de script Lua pour prop retourne une table. Chaque clé de cette table (en dehors de api_version et priority) doit être l'un des hooks listés ci-dessous. Le moteur d'exécution appelle la fonction correspondante chaque fois que l'événement de jeu associé se déclenche.

Hook	Se déclenche quand	Notes
`on_spawn`	Le prop apparaît dans le monde, ou se charge de nouveau avec son chunk	S'exécute une fois à chaque liaison du script
`on_game_tick`	Une fois par tick serveur (50 ms à 20 TPS)	Actif uniquement si le script définit ce hook
`on_destroy`	Le prop est supprimé définitivement	Hook de nettoyage. Non appelé lorsque le chunk du prop se décharge ou que FMM recharge
`on_left_click`	Un joueur fait un clic gauche sur le prop	`context.event` porte le drapeau d'annulation des dégâts par défaut de FMM
`on_right_click`	Un joueur fait un clic droit sur le prop	`context.event` porte le drapeau d'annulation de l'interaction par défaut de FMM
`on_zone_enter`	Un joueur entre dans une zone surveillée	Nécessite qu'une surveillance de zone soit configurée
`on_zone_leave`	Un joueur quitte une zone surveillée	Nécessite qu'une surveillance de zone soit configurée
`on_projectile_hit`	Un projectile touche le prop	`context.projectile` est le projectile ; `context.event.player` est le tireur. Voir API des props

Effets des objets

Les anciens hooks d'objets équipés ne sont plus déclenchés. Les effets appartiennent aux enchantements définis par les créateurs, avec leurs propres hooks et leur propre contexte. N'attachez pas le Lua d'un enchantement à la liste scripts: d'un prop et ne recopiez pas un ancien script d'objet sans l'adapter.

Contrat minimal du fichier

Chaque script Lua de prop doit return une table.

Champs de premier niveau obligatoires et facultatifs

Champ	Requis	Type	Notes
`api_version`	Oui	Nombre	Doit actuellement valoir `1`
`priority`	Non	Nombre	Validé si présent, mais FMM ne trie actuellement pas les scripts de props selon ce champ. Les scripts s'exécutent dans l'ordre de la liste `scripts:`
clés de hooks prises en charge	Non	Fonction	Doivent utiliser les noms exacts de la référence des hooks

Règles de validation

Le fichier doit retourner une table.
api_version est requis et doit actuellement être 1.
priority doit être numérique s'il est présent.
Chaque clé de premier niveau supplémentaire doit être un nom de hook supporté.
Chaque clé de hook doit pointer vers une fonction.
Les clés de premier niveau inconnues sont rejetées.

remarque

priority est utile pour garder les scripts portables entre les runtimes basés sur MagmaCore, mais l'ordre d'exécution actuel de FreeMinecraftModels est piloté par la configuration. Placez les scripts de prop dans la liste scripts: du modèle dans l'ordre où vous voulez qu'ils s'exécutent.

Les fonctions utilitaires et les constantes locales doivent être déclarées au-dessus du return final, pas à l'intérieur de la table retournée.

Votre premier script de prop, étape par étape

Avant l'étape 1 : préparer la configuration

Placez votre fichier de modèle (ex : my_prop.fmmodel) dans plugins/FreeMinecraftModels/models/
Faites apparaître le prop une fois pour générer la configuration .yml
Créez votre fichier de script dans plugins/FreeMinecraftModels/scripts/first_test.lua
Éditez plugins/FreeMinecraftModels/models/my_prop.yml :

isEnabled: true
scripts:
  - first_test.lua

Enregistrez le contenu Lua de l'étape 1 ci-dessous, lancez /fmm reload et vérifiez sa réussite. Refaites apparaître le prop si nécessaire. Répétez ce rechargement réussi après chaque modification Lua des étapes suivantes.

Étape 1 : charger le fichier

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

L'absence d'erreur dans la console est une première vérification utile. Utilisez le message explicite de l'étape 2 pour confirmer que :

Le fichier est du Lua valide
FMM l'a trouvé dans le dossier scripts/
La configuration le référence correctement
La forme de la table retournée est correcte

Étape 2 : obtenir un résultat visible

return {
  api_version = 1,

  on_spawn = function(context)
    context.log:info("Prop script loaded for: " .. (context.prop.model_id or "unknown"))
  end
}

Vérifiez la console du serveur. Si vous voyez le message de log, votre hook fonctionne.

Étape 3 : réagir au clic d'un joueur

return {
  api_version = 1,

  on_right_click = function(context)
    context.log:info("Prop was right-clicked!")
  end
}

Faites un clic droit sur le prop en jeu. Si la console affiche le message, le hook de clic fonctionne.

Étape 4 : annuler les dégâts du clic gauche

return {
  api_version = 1,

  on_left_click = function(context)
    if context.event then
      context.event.cancel()
    end
  end
}

C'est le principe utilisé par le script fourni invulnerable.lua. Il annule les dégâts par défaut de FMM pour ce clic, mais ne rend pas l'entité sous-jacente invulnérable à toutes les sources de dégâts.

Étape 5 : jouer une animation au clic

return {
  api_version = 1,

  on_right_click = function(context)
    context.prop:play_animation("open", true, false)
  end
}

Cela demande l'animation "open", sans boucle, après le tick de l'état actuel. Le modèle doit la contenir. blend ne produit pas de fondu ; la file n'a qu'une place et une demande ultérieure peut remplacer la précédente. La mort terminale peut refuser la demande. Vérifiez le résultat visible en jeu : l'acceptation ne prouve pas la lecture.

Qu'est-ce que `context` ?

Chaque fonction de hook reçoit un argument appelé context. Considérez-le comme une boîte à outils que FMM vous donne chaque fois que quelque chose se produit -- elle contient tout ce dont vous avez besoin pour interagir avec le prop, le monde, les zones et plus encore.

Vous ne créez pas context vous-même -- FMM le crée et le passe à votre hook. Pour tous les détails sur les API de contexte partagées (context.state, context.log, context.cooldowns, context.scheduler, context.world, context.zones), voir la page Moteur de scripts Lua MagmaCore.

Principales API de `context`

Voici un résumé de ce qui est disponible. Pour les détails complets, consultez API Prop.

context.prop -- (Scripts de prop uniquement) L'entité prop. Fournit model_id, current_location, play_animation() et stop_animation().
context.player : le joueur déclencheur dans les hooks de clic sur prop et les hooks de zones génériques, ainsi que le tireur dans on_projectile_hit lorsqu'un joueur a tiré le projectile. Vaut nil dans les hooks de cycle de vie du prop, les fonctions planifiées et les hooks sans joueur.
context.event : le drapeau d'annulation de FMM et le joueur acteur pour les hooks de clic, l'événement d'impact de projectile et son tireur dans on_projectile_hit, ou une table contenant uniquement l'acteur pour les hooks de zones génériques. Fournit event.player, is_cancelled et, pour les clics et les impacts de projectiles, cancel() / uncancel(). N'expose pas les champs Bukkit tels que target, block, projectile ou item. Vaut nil dans les hooks sans événement ni joueur acteur, comme on_spawn et on_game_tick.
context.projectile : l'entité projectile dans on_projectile_hit, et nil dans tous les autres hooks. Voir on_projectile_hit.
context.state -- Une table Lua simple qui persiste pendant la durée de vie de l'instance de script. Voir context.state.
context.cooldowns -- Aides pour les temps de recharge locaux et globaux. Utilisez context.cooldowns:check_local("key", ticks) pour les temps de recharge normaux par script. Voir context.cooldowns.
context.log -- Journalisation console. Voir context.log.
context.scheduler -- Tâches différées et répétitives. Voir context.scheduler.
context.world -- Interaction avec le monde : particules, sons, requêtes de blocs, foudre, entités à proximité. Voir context.world.
context.zones -- Créer et surveiller des zones spatiales (sphères, cylindres, cuboïdes). Voir context.zones.

Syntaxe des méthodes : `:` et `.`

Pour une explication de la syntaxe de méthode : vs . en Lua, voir la page Moteur de scripts Lua MagmaCore. Les deux formes sont acceptées par l'API FMM.

Modèles de départ à copier-coller

Plus petit script de prop valide

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Modèle d'annulation des dégâts du clic gauche

return {
  api_version = 1,

  on_left_click = function(context)
    if context.event then
      context.event.cancel()
    end
  end
}

Modèle de prop interactif

return {
  api_version = 1,

  on_spawn = function(context)
    context.state.is_active = false
  end,

  on_right_click = function(context)
    context.state.is_active = not context.state.is_active

    if context.state.is_active then
      context.prop:play_animation("activate", true, true)
    else
      context.prop:stop_animation()
    end
  end
}

Structure d'un fichier plus long

local ANIMATION_NAME = "idle"

local function do_something(context)
  context.log:info("Doing something!")
end

return {
  api_version = 1,
  priority = 0,

  on_spawn = function(context)
    context.state.task_id = nil
  end,

  on_right_click = function(context)
    do_something(context)
  end,

  on_destroy = function(context)
    if context.state.task_id ~= nil then
      context.scheduler:cancel(context.state.task_id)
    end
  end
}

Première procédure complète

Lors de la construction d'un tout nouveau script de prop, suivez cet ordre :

Créez le fichier .lua et faites fonctionner on_spawn.
Ajoutez le nom du fichier de script à la configuration .yml du prop.
Changez pour le hook réel que vous voulez (ex : on_right_click).
Ajoutez un message de log d'abord, avant les animations ou effets.
Ajoutez un seul effet réel (animation, son, particule).
Seulement après cela, ajoutez les utilitaires, l'état, la logique de scheduler ou les zones.

Après chaque modification Lua, enregistrez le fichier et terminez un /fmm reload réussi avant de vérifier le nouveau comportement. Limitez chaque étape à un changement pour que le journal ou l'effet visible indique ce qui fonctionne.

Scripts fournis

FMM écrit quatre scripts Lua lorsqu'ils manquent. Il remplace aussi les anciennes versions par défaut reconnues, mais conserve les autres modifications existantes. Inspectez le fichier installé si son comportement diffère des valeurs actuelles :

invulnerable.lua : annule les dégâts par défaut du clic gauche de FMM. Il ne bloque pas toutes les sources de dégâts possibles.
pickupable.lua : annule les dégâts par défaut du clic gauche et compte trois coups autorisés avant de demander le ramassage. Le compteur appartient à la liaison, donc les joueurs le partagent ; une tâche de 100 ticks serveur le remet à zéro après un coup précédent. Les coups autorisés demandent un flash de dégâts. Le script bloque les emplacements protégés ou de donjons, sauf pour la permission de contournement FMM ou le statut opérateur.
storage_double.lua : demande un inventaire de 54 emplacements, des animations et sons d'ouverture et de fermeture. Il applique le même contrôle de protection et la même exception opérateur, et consulte le suivi des joueurs tous les 5 ticks serveur. L'inventaire du prop est partagé par tous les joueurs qui le consultent et sauvegardé lorsque le dernier d'entre eux le ferme ou que le chunk se décharge. La destruction demande drop_inventory(), qui sauvegarde d'abord l'inventaire ouvert : les objets placés dans un inventaire encore ouvert font donc partie de ce qui tombe. Voir prop:open_inventory pour les détails.
storage_single.lua -- Identique à storage_double, mais avec 3 rangées (27 emplacements) au lieu de 6.

Vous pouvez trouver plus d'exemples sur la page Exemples et patterns.

Bac à sable Lua

Les scripts de props s'exécutent dans le même environnement LuaJ isolé qu'EliteMobs, avec les mêmes restrictions. Pour la liste complète des variables globales retirées et des fonctions de la bibliothèque standard disponibles, consultez le moteur de scripts Lua MagmaCore.

Prochaines étapes

API des props : référence complète de context.prop, context.event, context.world, context.zones et context.scheduler
Exemples et méthodes : scripts de props expliqués pas à pas avec notes de configuration
Dépannage -- problèmes courants, astuces de débogage et checklist de contrôle qualité

Si vous écrivez également des pouvoirs Lua de boss EliteMobs, le bac à sable, api_version, la table d'état, les concepts de temps de recharge et la structure pilotée par les hooks vous seront familiers, mais le contexte de boss utilise des noms de méthodes spécifiques à EliteMobs. Voir la documentation Lua d'EliteMobs pour les API de boss exactes.

Ce que sont les scripts de props​

Utilité des scripts de props​

Objets personnalisés et enchantements​

À qui s'adresse cette page​

Mini-introduction à Lua​

Où placer les fichiers​

Fichiers de script​

Fichiers de modèle et fichiers de configuration​

Format du fichier de configuration​

Génération de configuration à la demande​

Référence des hooks​

Effets des objets​

Contrat minimal du fichier​

Champs de premier niveau obligatoires et facultatifs​

Règles de validation​

Votre premier script de prop, étape par étape​

Avant l'étape 1 : préparer la configuration​

Étape 1 : charger le fichier​

Étape 2 : obtenir un résultat visible​

Étape 3 : réagir au clic d'un joueur​

Étape 4 : annuler les dégâts du clic gauche​

Étape 5 : jouer une animation au clic​

Qu'est-ce que context ?​

Principales API de context​

Syntaxe des méthodes : : et .​

Modèles de départ à copier-coller​

Plus petit script de prop valide​

Modèle d'annulation des dégâts du clic gauche​

Modèle de prop interactif​

Structure d'un fichier plus long​

Première procédure complète​

Scripts fournis​

Bac à sable Lua​

Prochaines étapes​