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 -- des scripts complets fonctionnels que vous pouvez é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 partage le même moteur Lua (Magmacore) qu'EliteMobs. Si vous écrivez déjà des pouvoirs Lua pour EliteMobs, les concepts fondamentaux -- hooks, context, api_version, scheduler, zones et le bac à sable -- sont identiques. La différence est :

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 FMM s'exécutent sur les props et ont des hooks comme on_right_click, on_left_click, on_projectile_hit, etc.

Les API context.world, context.zones, context.scheduler, context.state et context.log sont les mêmes dans les deux plugins. Cette page ne couvre que ce qui est spécifique aux 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.

Ce pour quoi les scripts de props excellent

Les scripts de props brillent lorsque vous avez besoin de :

Props interactifs qui réagissent aux clics des joueurs (portes, leviers, boutons)
Props décoratifs invulnérables qui ne peuvent pas être cassés par les joueurs
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.

À 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

Si vous êtes complètement nouveau en Lua, voici la syntaxe minimale dont vous avez besoin.

Variables

Utilisez local pour stocker une valeur :

local animation_name = "open"
local sound_volume = 1.0

Fonctions

Les fonctions sont des blocs de logique réutilisables :

local function log_click(context)
  context.log:info("Le prop a été cliqué !")
end

Vérifications `if`

Utilisez if quand quelque chose ne doit se produire que parfois :

if context.event == nil then
  return
end

`nil`

nil signifie « aucune valeur ». Vous le vérifierez souvent :

if context.event ~= nil then
  context.event.cancel()
end

Tables

Lua utilise les tables pour les objets avec des clés nommées et pour la définition du script retournée :

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Commentaires

Utilisez -- pour les notes :

-- Annuler l'événement de dégâts pour que le prop ne puisse pas être cassé
context.event.cancel()

astuce

Pour une introduction plus complète à Lua, consultez la page Pour commencer d'EliteMobs. Les bases de syntaxe sont identiques.

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 tous les fichiers .lua dans plugins/FreeMinecraftModels/scripts/ au démarrage.

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          <-- configuration de script pour torch_01
    scripts/
      invulnerable.lua      <-- référencé par 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 a deux champs :

isEnabled: true
scripts:
  - invulnerable.lua

Champ	Type	Défaut	Notes
`isEnabled`	boolean	`true`	Si les scripts sont actifs pour ce prop
`scripts`	liste de chaînes	`[]`	Noms de fichiers de scripts `.lua` dans le dossier `scripts/`

Vous pouvez attacher plusieurs scripts au même prop. Chaque script est sa propre instance indépendante.

Génération paresseuse de la configuration

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
Refaites apparaître le prop ou rechargez (les scripts sont maintenant actifs)

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	S'exécute une fois lorsque le script est lié
`on_game_tick`	Une fois par tick serveur (50 ms)	Actif uniquement si le script définit ce hook
`on_destroy`	Le prop est supprimé du monde	Hook de nettoyage
`on_left_click`	Un joueur fait un clic gauche (frappe) sur le prop	`context.event` est l'événement de dégâts
`on_right_click`	Un joueur fait un clic droit sur le prop	`context.event` est l'événement d'interaction
`on_projectile_hit`	Un projectile touche le prop	`context.event` est l'événement d'impact de projectile
`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

Contrat minimal du fichier

Chaque script Lua de prop doit return une table.

Champs de premier niveau requis et optionnels

Champ	Requis	Type	Notes
`api_version`	Oui	Number	Doit actuellement être `1`
`priority`	Non	Number	Priorité d'exécution. Les valeurs plus basses s'exécutent en premier. Par défaut `0`
clés de hook supportées	Non	Function	Doit utiliser l'un des noms de hook exacts listés dans 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.

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 fonctionnel, construit progressivement

Avant l'étape 1 : Configurer le fichier de 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

Refaites apparaître le prop ou rechargez le serveur

Étape 1 : Faire charger le fichier

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Si cela se charge sans erreurs dans la console, vous avez prouvé :

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 : Faire faire quelque chose de visible au prop

return {
  api_version = 1,

  on_spawn = function(context)
    context.log:info("Script de prop chargé pour : " .. (context.prop.model_id or "inconnu"))
  end
}

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

Étape 3 : Réagir à un clic de joueur

return {
  api_version = 1,

  on_right_click = function(context)
    context.log:info("Le prop a reçu un clic droit !")
  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 pour rendre le prop invulnérable

return {
  api_version = 1,

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

C'est le pattern utilisé par le script pré-configuré invulnerable.lua. Il annule l'événement de dégâts pour que le support d'armure du prop ne puisse pas être détruit.

É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 joue l'animation "open" sur le modèle du prop, avec mélange et sans boucle.

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.

on_right_click = function(context)
  -- context.prop      = le prop qui a été cliqué
  -- context.event     = l'événement de clic (peut être annulé)
  -- context.world     = outils pour les particules, sons, requêtes de blocs
  -- context.state     = votre propre stockage persistant
  -- context.log       = journalisation console
  -- context.scheduler = tâches différées et répétitives
  -- context.zones     = création et surveillance de zones spatiales
end

Vous ne créez pas context vous-même -- FMM le crée et le passe à votre hook.

info

context est créé à neuf pour chaque appel de hook, sauf pour context.state qui persiste pendant toute la durée de vie du prop. Cela signifie que vous pouvez stocker des données dans context.state et les relire plus tard dans un hook différent.

API `context` clés

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

context.prop -- L'entité prop. Fournit model_id, current_location, play_animation() et stop_animation().
context.event -- L'événement Bukkit qui a déclenché ce hook. Disponible dans on_left_click, on_right_click et on_projectile_hit. Fournit cancel(), uncancel() et is_cancelled. Est nil dans les hooks sans événement (comme on_spawn et on_game_tick).
context.state -- Une table Lua simple qui persiste pendant la durée de vie du prop. Utilisez-la pour stocker des drapeaux, des états de basculement, des identifiants de tâches et tout ce dont vous avez besoin de retenir entre les hooks.
context.log -- Journalisation console avec log:info(msg), log:warn(msg) et log:error(msg).
context.scheduler -- Tâches différées et répétitives avec scheduler:run_later(ticks, callback) et scheduler:run_repeating(delay, interval, callback). Les callbacks reçoivent un context frais. Annulez les tâches avec scheduler:cancel(taskId).
context.world -- Interaction avec le monde : particules, sons, requêtes de blocs, foudre, entités à proximité. Consultez API Prop pour la liste complète des méthodes.
context.zones -- Créer et surveiller des zones spatiales (sphères, cylindres, cuboïdes). Consultez API Prop pour la liste complète des méthodes.

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

En Lua, object:method(arg) est un raccourci pour object.method(object, arg). L'API FMM accepte les deux formes :

context.log:info("bonjour")
context.log.info("bonjour")  -- même chose

Toute la documentation utilise : de manière cohérente.

Modèles de démarrage à copier-coller

Plus petit script de prop valide

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Modèle de prop invulnérable

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 de fichier plus grande

local ANIMATION_NAME = "idle"

local function do_something(context)
  context.log:info("En train de faire quelque chose !")
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
}

Premier flux de travail réel

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.

Cet ordre rend le débogage considérablement plus facile car une seule chose change à la fois.

Scripts pré-configurés

FMM est livré avec deux scripts Lua pré-configurés :

invulnerable.lua -- Annule les événements de dégâts de clic gauche, rendant le prop indestructible. C'est le script de prop utile le plus simple.
pickupable.lua -- Permet aux joueurs de ramasser un prop en le frappant trois fois. Chaque coup joue une animation de dégâts sur le prop, et au troisième coup, le prop est supprimé et lâche son objet de placement pour que le joueur le récupère.

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 sandboxé qu'EliteMobs. Les restrictions du bac à sable sont identiques. Pour la liste complète des globales supprimées et des fonctions de bibliothèque standard disponibles, consultez la page Hooks et cycle de vie d'EliteMobs.

En résumé :

Supprimés : debug, dofile, io, load, loadfile, luajava, module, os, package, require
Disponibles : Toutes les fonctions math.*, string.*, table.*, pairs, ipairs, type, tostring, tonumber, pcall, print et plus

astuce

print écrit dans la console du serveur, mais préférez context.log:info(msg) pour la sortie. Les messages de log sont préfixés avec le nom du fichier de script, ce qui facilite l'identification du script qui a produit le message.

Prochaines étapes

API Prop -- référence complète de context.prop, context.event, context.world, context.zones et context.scheduler
Exemples et patterns -- scripts complets fonctionnels avec explications détaillées
Dépannage -- problèmes courants, astuces de débogage et liste de vérification QC

Si vous écrivez également des pouvoirs Lua pour EliteMobs, les API partagées (context.world, context.zones, context.scheduler, context.state, context.log) fonctionnent de manière identique. Consultez la documentation Lua d'EliteMobs pour les API spécifiques aux boss.

Ce que sont les scripts de props​

Ce pour quoi les scripts de props excellent​

À qui s'adresse cette page​

Mini-introduction à Lua​

Variables​

Fonctions​

Vérifications if​

nil​

Tables​

Commentaires​

Où placer les fichiers​

Fichiers de script​

Fichiers de modèle et fichiers de configuration​

Format du fichier de configuration​

Génération paresseuse de la configuration​

Référence des hooks​

Contrat minimal du fichier​

Champs de premier niveau requis et optionnels​

Règles de validation​

Votre premier script de prop fonctionnel, construit progressivement​

Avant l'étape 1 : Configurer le fichier de configuration​

Étape 1 : Faire charger le fichier​

Étape 2 : Faire faire quelque chose de visible au prop​

Étape 3 : Réagir à un clic de joueur​

Étape 4 : Annuler les dégâts pour rendre le prop invulnérable​

Étape 5 : Jouer une animation au clic​

Qu'est-ce que context ?​

API context clés​

Syntaxe des méthodes : : vs .​

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

Plus petit script de prop valide​

Modèle de prop invulnérable​

Modèle de prop interactif​

Structure de fichier plus grande​

Premier flux de travail réel​

Scripts pré-configurés​

Bac à sable Lua​

Prochaines étapes​