Scripting Lua : Dépannage

Cette page couvre les problèmes courants que vous pouvez rencontrer lors de l'écriture ou du débogage de scripts de props FreeMinecraftModels, ainsi que des conseils pour travailler avec le système de génération différée de la configuration. Si vous cherchez des exemples fonctionnels, consultez Exemples et modèles. Si vous débutez, consultez Premiers pas.

Problèmes courants

1. Le fichier de configuration ne se charge pas / Le script n'est pas assigné

Symptôme : Le prop apparaît mais ne réagit pas aux clics ni à aucun hook.

Causes et solutions :

Aucun fichier de configuration .yml n'existe encore. FMM génère la configuration de manière différée lors du premier spawn du prop. La première fois qu'un modèle est généré, FMM crée la configuration .yml de manière asynchrone avec des valeurs par défaut (activé, aucun script). Vous devez modifier la configuration générée pour ajouter les noms de vos fichiers de script, puis régénérer le prop.
La configuration a isEnabled: false. Ouvrez le fichier .yml situé à côté du fichier du modèle et définissez isEnabled: true.
La liste scripts: est vide. Ajoutez les noms de vos fichiers de script :
```
isEnabled: true
scripts:
  - my_script.lua
```
Le nom du fichier .yml ne correspond pas au nom du fichier du modèle. La configuration doit avoir le même nom de base que le fichier du modèle. Par exemple, torch_01.fmmodel nécessite torch_01.yml dans le même répertoire.

2. Fichier de script introuvable

Symptôme : La console affiche : [FMM Scripts] Script 'my_script.lua' not found in scripts/ folder

Causes et solutions :

Mauvais répertoire. Les fichiers de script doivent se trouver dans plugins/FreeMinecraftModels/scripts/, pas à côté du fichier du modèle.
Nom de fichier différent. Le nom dans la configuration .yml doit correspondre exactement au nom du fichier dans le dossier scripts/, y compris la casse et l'extension .lua.
Fichier absent. Vérifiez que le fichier .lua existe réellement dans le dossier scripts/.

3. Le script ne se charge pas du tout

Symptôme : Aucune erreur dans la console, mais aucun hook ne se déclenche.

Vérifiez la console du serveur pour détecter les erreurs de syntaxe Lua au démarrage. Les causes les plus courantes sont :

end manquant pour fermer une fonction ou un bloc if
Parenthèses non appariées
Virgule manquante entre les définitions de hooks dans la table retournée
Le fichier ne se termine pas par .lua

S'il y a une erreur Lua, la console affichera un bloc d'erreur [Lua] avec le nom du fichier, le numéro de ligne et une description.

4. Le hook ne se déclenche jamais

Symptôme : Le script se charge (vous voyez le message [FMM Scripts] Bound script), mais un hook spécifique ne se déclenche jamais.

Vérifiez que le nom du hook est écrit exactement comme indiqué dans la référence des hooks. Erreurs courantes :

Nom incorrect	Nom correct
`on_click`	`on_right_click` ou `on_left_click`
`on_interact`	`on_right_click`
`on_hit`	`on_left_click`
`on_tick`	`on_game_tick`
`on_remove`	`on_destroy`
`on_arrow_hit`	`on_projectile_hit`

Vérifiez également que le prop possède bien une entité armor stand associée. Certaines configurations de props peuvent ne pas produire d'entité cliquable.

5. Délai dépassé / Budget d'exécution dépassé

Symptôme : La console affiche un message comme :

[Lua] my_script.lua took 73ms in 'on_game_tick' (limit: 50ms) -- script disabled to prevent lag.

Le script effectuait trop de travail en un seul appel de hook. Causes courantes :

Itération sur trop d'entités dans on_game_tick
Création de trop de particules par tick
Exécution de boucles coûteuses sans répartir le travail sur plusieurs ticks

Solution : Déplacez le travail lourd derrière un cooldown basé sur l'état ou utilisez scheduler:run_repeating() avec un intervalle raisonnable au lieu de on_game_tick.

6. `context.event` est nil dans un hook de clic

Cela ne devrait normalement pas se produire pour on_left_click et on_right_click, mais protégez-vous toujours avec :

if context.event then
  context.event.cancel()
end

Dans les callbacks du scheduler, context.event est toujours nil -- c'est le comportement attendu. La modification d'événement ne peut avoir lieu qu'à l'intérieur du hook d'événement lui-même.

7. L'animation ne se joue pas

Symptôme : play_animation() retourne false, ou rien de visible ne se passe.

Causes et solutions :

Nom d'animation incorrect. Le nom doit correspondre exactement à ce qui est défini dans le fichier du modèle. Vérifiez votre fichier .bbmodel ou .fmmodel pour le nom d'animation correct.
Le modèle n'a pas d'animations. Tous les modèles n'ont pas d'animations. Vérifiez que le fichier du modèle contient bien des données d'animation.
Les joueurs ne sont pas à portée du pack de ressources. L'animation est côté serveur, mais les joueurs doivent avoir le pack de ressources FMM chargé pour voir le modèle.

8. Les particules n'apparaissent pas

Vérifiez que le nom de la particule est une valeur valide de l'enum Particle de Bukkit en MAJUSCULES : "FLAME", pas "flame".
Vérifiez que l'emplacement se trouve dans un chunk chargé. Si aucun joueur n'est à proximité, le chunk peut être déchargé.
Vérifiez que count est d'au moins 1.
Certaines particules (comme DUST) nécessitent des données supplémentaires spécifiques que le spawn_particle() de base peut ne pas supporter. Utilisez des particules standard comme FLAME, HEART, HAPPY_VILLAGER, NOTE, ENCHANT, etc.

9. Le son ne se joue pas

Vérifiez que le nom du son est une constante valide de l'enum Sound de Bukkit en MAJUSCULES. Exemple : "BLOCK_NOTE_BLOCK_HARP", pas "block.note_block.harp".
Vérifiez que les coordonnées de l'emplacement sont correctes (pas toutes à zéro ou NaN).
Vérifiez que le volume est supérieur à 0.

10. L'état se réinitialise de manière inattendue

context.state est par instance de prop et persiste pendant la durée de vie du prop. Si l'état semble se réinitialiser :

Le prop a peut-être été supprimé et régénéré (chaque spawn crée une nouvelle instance).
Vous lisez peut-être l'état dans un callback du scheduler en utilisant la mauvaise variable de contexte. Utilisez toujours le paramètre de contexte propre au callback.

Fonctionnement de la génération différée de configuration

Comprendre le système de configuration différée aide à éviter la confusion lors de la mise en place de nouveaux props :

Premier spawn : Lorsqu'un prop apparaît et qu'aucun fichier .yml associé n'existe, FMM crée la configuration de manière asynchrone. Cela signifie que le fichier est écrit dans un thread d'arrière-plan et n'est pas immédiatement disponible.
Valeurs par défaut : La configuration générée a isEnabled: true et une liste vide scripts: [].
Aucun script au premier spawn : Comme la configuration est créée après que le prop a déjà été généré (et n'a aucun script listé), le prop n'aura aucun script assigné lors de son premier spawn.
Modifier et régénérer : Après que FMM a créé la configuration, vous la modifiez pour ajouter les noms de vos fichiers de script. La prochaine fois que le prop apparaîtra, les scripts seront chargés.
Emplacement de la configuration : Le fichier .yml est créé dans le même répertoire que le fichier du modèle, avec le même nom de base. Par exemple :
- Modèle : plugins/FreeMinecraftModels/models/fountain.fmmodel
- Configuration : plugins/FreeMinecraftModels/models/fountain.yml

Flux de travail de configuration rapide

Placez le modèle dans models/
Placez le script dans scripts/
Générez le prop une fois (crée le .yml)
Modifiez le .yml pour ajouter scripts: [my_script.lua]
Régénérez le prop -- le script est maintenant actif

Lecture des messages d'erreur

Quand quelque chose ne va pas dans un script Lua de prop, la console affiche un bloc d'erreur [Lua]. Ces messages vous indiquent exactement quel fichier, quelle ligne, quel hook et ce qui s'est passé en langage clair.

Une erreur typique ressemble à ceci :

[Lua] Error in 'my_door.lua' at line 12 during 'on_right_click':
[Lua]   -> You tried to call a method or function that doesn't exist.
[Lua]   -> Check the method name for typos, or make sure you're using ':' (colon) for method calls, not '.' (dot).
[Lua]   -> Script has been disabled for this entity to prevent further errors.

Le système traduit les erreurs Lua courantes en langage clair :

Erreur Lua brute	Ce que la console vous indique
`attempt to call nil`	Vous avez essayé d'appeler une méthode ou une fonction qui n'existe pas. Vérifiez les fautes de frappe et l'utilisation de `:` vs. `.`.
`index expected, got nil`	Vous avez essayé d'accéder à un champ sur quelque chose qui est nil. Vérifiez que le code précédent l'a initialisé.
`attempt to index`	Vous avez essayé d'accéder à une propriété sur une valeur nil ou invalide.
`bad argument`	Une fonction a reçu le mauvais type d'argument. Le message montre le type attendu vs. le type réel.
Timeout	Votre script a pris Xms dans 'hook_name' (limite : 50ms) -- script désactivé pour éviter le lag.

astuce

Lisez toujours le message d'erreur [Lua] complet avant de plonger dans le code. Il vous oriente généralement directement vers la solution.

Ne supposez pas que des méthodes non documentées existent

L'API Lua de FMM expose un ensemble spécifique de méthodes. Ne supposez pas que des noms abrégés ou alternatifs existent. Erreurs courantes :

context.prop:get_location() -- n'existe pas. Utilisez context.prop.current_location (un champ, pas une méthode).
context.prop:set_animation("open") -- n'existe pas. Utilisez context.prop:play_animation("open", true, true).
context.event:setCancelled(true) -- n'existe pas. Utilisez context.event.cancel().
context.cooldowns:check_local(...) -- n'existe pas dans FMM. Utilisez context.state avec scheduler:run_later() pour les cooldowns.
context.player -- n'existe pas dans les scripts de props FMM. Utilisez context.world:get_nearby_players() pour trouver les joueurs proches du prop.
context.boss -- n'existe pas. C'est pour EliteMobs. Utilisez context.prop dans FMM.

En cas de doute, consultez la page API des Props. Si ce n'est pas documenté là, ça n'existe pas.

Conseils de débogage

1. Utilisez `context.log:info()` généreusement

Ajoutez des messages de log à chaque étape lors du débogage :

on_right_click = function(context)
  context.log:info("Right click received!")
  context.log:info("Event present: " .. tostring(context.event ~= nil))
  context.log:info("State is_open: " .. tostring(context.state.is_open))
end

2. Vérifiez la console au démarrage

FMM journalise [FMM Scripts] Bound script 'X' to prop 'Y' pour chaque liaison réussie. Si vous ne voyez pas ce message, la configuration ou le script n'a pas été chargé.

3. Vérifiez le chemin du fichier modèle

La configuration .yml doit être un fichier voisin du fichier du modèle (même répertoire, même nom de base). Vérifiez cela en contrôlant :

Chemin du fichier modèle : plugins/FreeMinecraftModels/models/my_model.fmmodel
Chemin du fichier de configuration : plugins/FreeMinecraftModels/models/my_model.yml

4. Testez les hooks individuellement

Lorsque vous construisez un script complexe, commencez par tester chaque hook individuellement. Ajoutez un hook à la fois et vérifiez qu'il se déclenche avant de passer au suivant.

5. Vérifiez les fautes de frappe dans les noms de hooks

La raison la plus courante pour laquelle un hook ne se déclenche pas est un nom de hook mal orthographié. Le script se chargera sans erreur, mais la fonction de hook mal orthographiée sera rejetée lors de la validation.

Parcours de progression pour débutants

Si vous souhaitez apprendre ce système à partir de zéro, cette progression fonctionne bien :

Écrivez un fichier avec uniquement api_version = 1 et on_spawn qui journalise un message.
Ajoutez le script à une configuration de prop et vérifiez que le message de log apparaît.
Ajoutez on_right_click et journalisez quand le prop est cliqué.
Ajoutez on_left_click avec context.event.cancel() pour l'invulnérabilité.
Jouez une animation sur le clic droit.
Ajoutez un son sur le clic droit.
Ajoutez l'état et le comportement de basculement.
Ajoutez une surveillance de zone pour la détection de proximité.
Ce n'est qu'alors que vous passerez à des scripts complexes multi-hooks avec des schedulers.

Chaque étape s'appuie sur la précédente, et vous pouvez tester à chaque étape.

Prochaines étapes

Premiers pas -- structure des fichiers, hooks, guide du premier script, modèles à copier-coller
API des Props -- référence complète de l'API
Exemples et modèles -- scripts complets fonctionnels que vous pouvez étudier et adapter

Problèmes courants​

1. Le fichier de configuration ne se charge pas / Le script n'est pas assigné​

2. Fichier de script introuvable​

3. Le script ne se charge pas du tout​

4. Le hook ne se déclenche jamais​

5. Délai dépassé / Budget d'exécution dépassé​

6. context.event est nil dans un hook de clic​

7. L'animation ne se joue pas​

8. Les particules n'apparaissent pas​

9. Le son ne se joue pas​

10. L'état se réinitialise de manière inattendue​

Fonctionnement de la génération différée de configuration​

Lecture des messages d'erreur​

Ne supposez pas que des méthodes non documentées existent​

Conseils de débogage​

1. Utilisez context.log:info() généreusement​

2. Vérifiez la console au démarrage​

3. Vérifiez le chemin du fichier modèle​

4. Testez les hooks individuellement​

5. Vérifiez les fautes de frappe dans les noms de hooks​

Parcours de progression pour débutants​

Prochaines étapes​

Problèmes courants

1. Le fichier de configuration ne se charge pas / Le script n'est pas assigné

2. Fichier de script introuvable

3. Le script ne se charge pas du tout

4. Le hook ne se déclenche jamais

5. Délai dépassé / Budget d'exécution dépassé

6. `context.event` est nil dans un hook de clic

7. L'animation ne se joue pas

8. Les particules n'apparaissent pas

9. Le son ne se joue pas

10. L'état se réinitialise de manière inattendue

Fonctionnement de la génération différée de configuration

Lecture des messages d'erreur

Ne supposez pas que des méthodes non documentées existent

Conseils de débogage

1. Utilisez `context.log:info()` généreusement

2. Vérifiez la console au démarrage

3. Vérifiez le chemin du fichier modèle

4. Testez les hooks individuellement

5. Vérifiez les fautes de frappe dans les noms de hooks

Parcours de progression pour débutants

Prochaines étapes