Lua Scripting : Pour commencer

Cette page vous apprend a ecrire votre premier script Lua pour un prop FreeMinecraftModels, depuis un fichier vide jusqu'a un prop interactif fonctionnel. A la fin, vous comprendrez les hooks, le context, la Prop API et la structure generale de chaque fichier de script de prop.

Une fois que vous etes a l'aise avec les bases, poursuivez avec les pages complementaires :

Prop API -- les APIs context.prop, context.event, context.world et autres context
Exemples et modeles -- scripts fonctionnels complets que vous pouvez etudier et adapter
Depannage -- erreurs courantes, conseils de debogage et liste de verification QC

Fonctionnalite experimentale

Les scripts Lua de props sont actuellement experimentaux. Les noms des hooks, les methodes utilitaires et le comportement peuvent encore changer au fur et a mesure que FreeMinecraftModels evolue. Testez donc soigneusement avant de les utiliser sur un serveur de production.

Relation avec EliteMobs Lua

FreeMinecraftModels partage le meme moteur Lua (Magmacore) qu'EliteMobs. Si vous ecrivez deja des pouvoirs Lua pour EliteMobs, les concepts fondamentaux -- hooks, context, api_version, scheduler, zones et la sandbox -- sont identiques. La difference est :

Les scripts EliteMobs s'executent sur les boss et ont des hooks comme on_boss_damaged_by_player, on_enter_combat, etc.
Les scripts FMM s'executent sur les props et ont des hooks comme on_right_click, on_left_click, on_projectile_hit, etc.

Les APIs context.world, context.zones, context.scheduler, context.state et context.log sont les memes pour les deux plugins. Cette page ne couvre que ce qui est specifique 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 references depuis un fichier de config YAML situe a cote du fichier de modele, et ils s'executent chaque fois que le prop est genere dans le monde.

A quoi les scripts de props excellent

Les scripts de props excellent quand vous avez besoin de :

Props interactifs qui reagissent aux clics des joueurs (portes, leviers, boutons)
Props decoratifs invulnerables qui ne peuvent pas etre casses par les joueurs
Declencheurs de proximite qui detectent quand les joueurs entrent ou quittent une zone
Props animes qui jouent des animations lors d'interactions ou sur un minuteur
Props emetteurs de sons qui jouent des sons quand on clique dessus ou qu'on s'en approche
Tout comportement de prop necessitant une logique au-dela de la decoration statique

Si votre prop est purement decoratif et ne necessite aucune interaction, vous n'avez pas besoin d'un script.

A qui s'adresse cette page

Cette page est ecrite pour trois types de lecteurs :

Quelqu'un qui connait deja le scripting Lua d'EliteMobs et veut apprendre les hooks et APIs specifiques a FMM
Quelqu'un qui est nouveau dans le scripting Lua et a besoin d'une reference complete avec les noms exacts pour les props
Quelqu'un qui utilise l'IA pour rediger des scripts de props et a besoin de suffisamment de details pour savoir quand l'IA a invente quelque chose de faux

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

Comment placer un hook valide dans la table retournee
Comment lire des valeurs depuis context
Comment arreter l'execution tot avec if ... then return end
Comment appeler quelques methodes utilitaires exactement

Mini-introduction a Lua

Si vous etes completement 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 reutilisables :

local function log_click(context)
  context.log:info("Prop was clicked!")
end

Verifications `if`

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

if context.event == nil then
  return
end

`nil`

nil signifie "pas de valeur". Vous le verifierez souvent :

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

Tables

Lua utilise des tables pour les objets avec des cles nommees et pour la definition du script retourne :

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Commentaires

Utilisez -- pour les notes :

-- Cancel the damage event so the prop cannot be broken
context.event.cancel()

astuce

Pour une introduction plus complete a Lua, consultez la page Pour commencer avec EliteMobs. Les bases de syntaxe sont identiques.

Ou se trouvent 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 decouvre tous les fichiers .lua dans plugins/FreeMinecraftModels/scripts/ au demarrage.

Fichiers de modele et fichiers de config

Chaque fichier de modele peut avoir un fichier .yml de config associe dans le meme repertoire :

plugins/
  FreeMinecraftModels/
    models/
      torch_01.fmmodel
      torch_01.yml          <-- config de script pour torch_01
    scripts/
      invulnerable.lua      <-- reference par torch_01.yml

Le fichier .yml de config est ce qui relie un modele a ses scripts.

Format du fichier de config

Le fichier de config YAML situe a cote d'un fichier de modele a deux champs :

isEnabled: true
scripts:
  - invulnerable.lua

Champ	Type	Par defaut	Notes
`isEnabled`	boolean	`true`	Si les scripts sont actifs pour ce prop
`scripts`	liste de strings	`[]`	Noms de fichiers `.lua` dans le dossier `scripts/`

Vous pouvez attacher plusieurs scripts au meme prop. Chaque script est sa propre instance independante.

Generation differee de la config

Quand un prop apparait et qu'aucun fichier .yml associe n'existe, FMM cree automatiquement un fichier de config par defaut avec isEnabled: true et une liste scripts: vide. Cela se produit de maniere asynchrone, donc le prop n'aura pas de scripts lors de sa premiere apparition -- seulement apres la creation de la config et votre modification pour ajouter les noms de fichiers de script.

Cela signifie :

Placez votre fichier de modele dans models/
Generez le prop une fois (FMM cree le .yml automatiquement)
Editez le .yml genere pour ajouter vos noms de fichiers de script
Regenerez le prop ou rechargez le serveur (les scripts sont maintenant actifs)

Reference des hooks

Chaque fichier de script Lua de prop retourne une table. Chaque cle de cette table (en dehors de api_version et priority) doit etre l'un des hooks listes ci-dessous. Le runtime appelle la fonction correspondante chaque fois que l'evenement de jeu associe se declenche.

Hook	Se declenche quand	Notes
`on_spawn`	Le prop apparait dans le monde	S'execute une fois quand le script est lie
`on_game_tick`	Une fois par tick du serveur (50 ms)	Actif uniquement si le script definit ce hook
`on_destroy`	Le prop est retire du monde	Hook de nettoyage
`on_left_click`	Un joueur fait un clic gauche (frappe) le prop	`context.event` est l'evenement de degats
`on_right_click`	Un joueur fait un clic droit sur le prop	`context.event` est l'evenement d'interaction
`on_projectile_hit`	Un projectile touche le prop	`context.event` est l'evenement d'impact de projectile
`on_zone_enter`	Un joueur entre dans une zone surveillee	Necessite la mise en place d'une surveillance de zone
`on_zone_leave`	Un joueur quitte une zone surveillee	Necessite la mise en place d'une surveillance de zone

Contrat minimal du fichier

Chaque script Lua de prop doit faire un return d'une table.

Champs de niveau superieur obligatoires et optionnels

Champ	Obligatoire	Type	Notes
`api_version`	Oui	Number	Doit actuellement etre `1`
`priority`	Non	Number	Priorite d'execution. Les valeurs plus basses s'executent en premier. Par defaut `0`
Cles de hook supportees	Non	Function	Doit utiliser l'un des noms exacts de hook listes dans la Reference des hooks

Regles de validation

Le fichier doit retourner une table.
api_version est obligatoire et doit actuellement etre 1.
priority doit etre numerique s'il est present.
Chaque cle de niveau superieur supplementaire doit etre un nom de hook supporte.
Chaque cle de hook doit pointer vers une fonction.
Les cles de niveau superieur inconnues sont rejetees.

Les fonctions utilitaires et les constantes locales doivent se trouver au-dessus du return final, pas a l'interieur de la table retournee.

Votre premier script de prop fonctionnel, construit pas a pas

Avant l'etape 1 : Mettre en place la config

Placez votre fichier de modele (ex. my_prop.fmmodel) dans plugins/FreeMinecraftModels/models/
Generez le prop une fois pour creer la config .yml
Creez votre fichier de script dans plugins/FreeMinecraftModels/scripts/first_test.lua
Editez plugins/FreeMinecraftModels/models/my_prop.yml :

isEnabled: true
scripts:
  - first_test.lua

Regenerez le prop ou rechargez le serveur

Etape 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 prouve :

Le fichier est du Lua valide
FMM l'a trouve dans le dossier scripts/
La config le reference correctement
La forme de la table retournee est correcte

Etape 2 : Faire faire quelque chose de visible au prop

return {
  api_version = 1,

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

Verifiez la console du serveur. Si vous voyez le message de log, votre hook se declenche.

Etape 3 : Reagir 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.

Etape 4 : Annuler les degats pour rendre le prop invulnerable

return {
  api_version = 1,

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

C'est le modele utilise par le script prefait invulnerable.lua. Il annule l'evenement de degats pour que l'armor stand du prop ne puisse pas etre detruit.

Etape 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 modele du prop, avec melange et sans boucle.

Qu'est-ce que `context` ?

Chaque fonction de hook recoit un argument appele context. Considerez-le comme une boite a outils que FMM vous remet chaque fois que quelque chose se produit -- il 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 ete clique
  -- context.event     = l'evenement de clic (peut etre annule)
  -- context.world     = outils pour particules, sons, requetes de blocs
  -- context.state     = votre propre stockage persistant
  -- context.log       = journalisation dans la console
  -- context.scheduler = taches differees et repetitives
  -- context.zones     = creation et surveillance de zones spatiales
end

Vous ne creez pas context vous-meme -- FMM le cree et le passe a votre hook.

info

context est cree a neuf pour chaque appel de hook, sauf context.state qui persiste pendant toute la duree de vie du prop. Cela signifie que vous pouvez stocker des donnees dans context.state et les relire plus tard dans un hook different.

APIs cles de `context`

Voici un resume de ce qui est disponible. Pour les details complets, consultez Prop API.

context.prop -- L'entite du prop. Fournit model_id, current_location, play_animation() et stop_animation().
context.event -- L'evenement Bukkit qui a declenche 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 evenement (comme on_spawn et on_game_tick).
context.state -- Une table Lua simple qui persiste pendant la duree de vie du prop. Utilisez-la pour stocker des flags, des etats d'alternance, des IDs de taches et tout ce que vous devez retenir entre les hooks.
context.log -- Journalisation dans la console avec log:info(msg), log:warn(msg) et log:error(msg).
context.scheduler -- Taches differees et repetitives avec scheduler:run_later(ticks, callback) et scheduler:run_repeating(delay, interval, callback). Les callbacks recoivent un context frais. Annulez les taches avec scheduler:cancel(taskId).
context.world -- Interaction avec le monde : particules, sons, requetes de blocs, eclairs, entites a proximite. Consultez Prop API pour la liste complete des methodes.
context.zones -- Creation et surveillance de zones spatiales (spheres, cylindres, cuboides). Consultez Prop API pour la liste complete des methodes.

Syntaxe des methodes : `:` vs `.`

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

context.log:info("hello")
context.log.info("hello")  -- la meme chose

Toute la documentation utilise : de maniere coherente.

Modeles prets a copier-coller

Plus petit script de prop valide

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Modele de prop invulnerable

return {
  api_version = 1,

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

Modele 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
}

Disposition de fichier plus grande

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
}

Premier flux de travail reel

Lors de la creation d'un tout nouveau script de prop, utilisez cet ordre :

Creez le fichier .lua et faites fonctionner on_spawn.
Ajoutez le nom du fichier de script a la config .yml du prop.
Passez au hook que vous souhaitez reellement (ex. on_right_click).
Ajoutez d'abord un message de log, avant les animations ou les effets.
Ajoutez un vrai effet (animation, son, particule).
Seulement apres cela, ajoutez des fonctions utilitaires, le state, la logique de scheduler ou les zones.

Cet ordre facilite considerablement le debogage car une seule chose change a la fois.

Scripts prefaits

FMM est livre avec un script Lua prefait :

invulnerable.lua -- Annule les evenements de degats par clic gauche, rendant le prop indestructible. C'est le script de prop utile le plus simple.

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

Lua Sandbox

Les scripts de props s'executent dans le meme environnement LuaJ sandboxe qu'EliteMobs. Les restrictions de la sandbox sont identiques. Pour la liste complete des globales supprimees et des fonctions de la bibliotheque standard disponibles, consultez la page EliteMobs Hooks & Lifecycle.

En resume :

Supprimes : 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 ecrit dans la console du serveur, mais preferez context.log:info(msg) pour la sortie. Les messages de log sont prefixes avec le nom du fichier de script, ce qui facilite l'identification du script qui a produit le message.

Prochaines etapes

Prop API -- reference complete de context.prop, context.event, context.world, context.zones et context.scheduler
Exemples et modeles -- scripts fonctionnels complets avec explications
Depannage -- problemes courants, conseils de debogage et une liste de verification QC

Si vous ecrivez aussi des pouvoirs Lua pour EliteMobs, les APIs partagees (context.world, context.zones, context.scheduler, context.state, context.log) fonctionnent de maniere identique. Consultez la documentation Lua d'EliteMobs pour les APIs specifiques aux boss.

Ce que sont les scripts de props​

A quoi les scripts de props excellent​

A qui s'adresse cette page​

Mini-introduction a Lua​

Variables​

Fonctions​

Verifications if​

nil​

Tables​

Commentaires​

Ou se trouvent les fichiers​

Fichiers de script​

Fichiers de modele et fichiers de config​

Format du fichier de config​

Generation differee de la config​

Reference des hooks​

Contrat minimal du fichier​

Champs de niveau superieur obligatoires et optionnels​

Regles de validation​

Votre premier script de prop fonctionnel, construit pas a pas​

Avant l'etape 1 : Mettre en place la config​

Etape 1 : Faire charger le fichier​

Etape 2 : Faire faire quelque chose de visible au prop​

Etape 3 : Reagir au clic d'un joueur​

Etape 4 : Annuler les degats pour rendre le prop invulnerable​

Etape 5 : Jouer une animation au clic​

Qu'est-ce que context ?​

APIs cles de context​

Syntaxe des methodes : : vs .​

Modeles prets a copier-coller​

Plus petit script de prop valide​

Modele de prop invulnerable​

Modele de prop interactif​

Disposition de fichier plus grande​

Premier flux de travail reel​

Scripts prefaits​

Lua Sandbox​

Prochaines etapes​