Aller au contenu principal

Script Lua : Dépannage

webapp_banner.jpg

Cette page couvre les problèmes courants que vous pouvez rencontrer lors de l'écriture ou du débogage de pouvoirs Lua, ainsi que des conseils de migration pour les auteurs venant d'EliteScript. Pour des exemples fonctionnels, consultez Exemples et modèles. Pour débuter, consultez Premiers pas.

Problèmes courants​

1. Le pouvoir ne se charge pas du tout​

Vérifiez la console du serveur pour les erreurs au démarrage. La cause la plus courante est une erreur de syntaxe Lua (manque de end, parenthèses non correspondantes, etc.). Vérifiez aussi que le fichier se termine par .lua et est placé dans le bon répertoire powers.

2. Le hook ne se déclenche jamais​

Vérifiez que le nom du hook est écrit exactement comme dans la liste des hooks. Erreurs courantes : on_boss_hit (incorrect) vs. on_boss_damaged_by_player (correct), ou on_tick (incorrect) vs. on_game_tick (correct).

3. context.player est nil​

Tous les hooks ne fournissent pas un joueur. on_spawn, on_game_tick, on_enter_combat et on_exit_combat n'ont pas de joueur. Ajoutez toujours une garde nil avant d'utiliser context.player.

4. Timeout / budget d'exécution dépassé​

Si un hook ou callback prend trop de temps, le pouvoir est automatiquement désactivé. Le message console ressemble à :

[Lua]   -> Your script took 73ms in 'on_tick' (limit: 50ms) — power disabled to prevent lag.

5. Le callback du planificateur utilise des données obsolètes​

Vous utilisez probablement le context externe au lieu du paramètre du callback. Changez function() ... context.boss ... end en function(tick_context) ... tick_context.boss ... end.

6. La requête de zone ne retourne aucune entité​

Vérifiez la définition de zone. Pour les zones natives, kind doit être en minuscules ("sphere", pas "SPHERE"). Pour les utilitaires de script, shape doit être en majuscules ("CONE", pas "cone").

7. Les particules n'apparaissent pas​

Vérifiez que le nom de particule est un enum Particle Bukkit valide en UPPER_CASE. Erreur courante : "flame" (incorrect) vs. "FLAME" (correct).

8. Le cooldown ne semble pas fonctionner​

Assurez-vous d'utiliser check_local(key, duration) (qui vérifie ET définit en un seul appel), pas local_ready(key) suivi d'un set_local(duration, key) séparé.

9. Le boss continue d'exécuter le pouvoir après sa mort​

Ajoutez une logique de nettoyage dans on_exit_combat et/ou on_death pour annuler les tâches du planificateur.

Lecture des messages d'erreur​

Quand quelque chose ne va pas dans un pouvoir Lua, la console affiche un bloc d'erreur amical préfixé par [Lua]. Ces messages vous disent exactement quel fichier, quelle ligne, quel hook et ce qui a mal tourné -- en langage clair.

[Lua] Error in 'push_zone.lua' at line 35 during 'on_boss_damaged_by_player':
[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]   -> Power has been disabled for this boss to prevent further errors.
Erreur Lua bruteCe que la console vous dit
attempt to call nilVous avez essayé d'appeler une méthode ou fonction qui n'existe pas.
index expected, got nilVous avez essayé d'accéder à un champ sur quelque chose qui est nil.
attempt to indexVous avez essayé d'accéder à une propriété d'une valeur nil ou invalide.
bad argumentAffiche les détails spécifiques de l'incompatibilité d'arguments.
TimeoutVotre script a pris Xms dans 'hook_name' (limite : 50ms) -- pouvoir désactivé.
astuce

Quand vous voyez une erreur [Lua] dans la console, lisez le message complet avant de plonger dans le code -- il vous indique généralement directement la solution.

N'assumez pas que des alias non documentes existent​

L'API Lua expose un ensemble specifique de noms de methodes. Si vous ecrivez des pouvoirs a la main ou avec l'aide d'une IA, n'assumez pas que des raccourcis ou des noms alternatifs existent. Les noms suivants n'existent pas et causeront des erreurs :

  • show_temporary_boss_bar() -- utilisez player:show_boss_bar(title, color, style, duration).
  • run_command_as_player() -- utilisez player:run_command(command).
  • em.location(...) -- il n'y a pas de global em. Utilisez context.boss:get_location(), context.player.current_location, ou les methodes context.world.
  • em.vector(...) -- il n'y a pas de global em. Utilisez context.vectors.get_vector_between_locations(loc1, loc2) ou des tables simples {x=0, y=1, z=0}.
  • em.zone.sphere(...) -- il n'y a pas de global em. Utilisez une table de definition de zone comme {kind = "sphere", radius = 5, origin = location}.
  • entity:teleport_to(...) -- utilisez entity:teleport_to_location(location).
  • entity:set_velocity(...) -- utilisez entity:set_velocity_vector(vector).
  • entity:set_facing(...) -- utilisez entity:face_direction_or_location(direction_or_location).

En cas de doute, consultez les pages de Reference API (Boss et entites, Monde et environnement, Zones et ciblage). Si ce n'est pas documente, ca n'existe pas.

Conseils de migration pour les auteurs EliteScript​

Si vous ecrivez deja de bons EliteScripts, la facon la plus simple d'apprendre les pouvoirs Lua est :

  1. Continuez a penser en termes d'evenements, cibles, zones, vecteurs relatifs et particules. Les concepts sont les memes -- seule la syntaxe change. Les evenements EliteScript deviennent des noms de hooks comme on_spawn ou on_boss_damaged_by_player. Les cibles et zones sont passees en tant que tables a context.script en utilisant les memes noms de champs documentes dans les pages Zones EliteScript et Cibles EliteScript.

  2. Deplacez votre flux de controle vers Lua. Tirages aleatoires, fonctions auxiliaires partagees, boucles, etat persistant (context.state) et planification de taches (context.scheduler) sont les choses que Lua ajoute et qu'EliteScript pur ne peut pas faire facilement. Commencez par convertir un pouvoir conditionnel ou a embranchements en Lua tout en gardant le reste identique.

  3. Utilisez context.script pour le ciblage et la geometrie de zone. Les utilitaires de script acceptent les memes noms de champs qu'EliteScript (targetType, shape, Target, Target2, range, offset, coverage), vous pouvez donc continuer a utiliser la documentation existante d'EliteScript comme reference pour ces specifications. Cela vous permet d'exploiter des patterns familiers tout en gagnant la flexibilite de Lua pour la couche logique.

Chemin de progression pour débutants​

  1. Écrivez un fichier avec seulement api_version = 1 et on_spawn.
  2. Faites envoyer un message ou jouer un son au boss.
  3. Ajoutez un cooldown avec context.cooldowns.
  4. Ajoutez un hook déclenché par le joueur comme on_boss_damaged_by_player.
  5. Ajoutez une action différée avec context.scheduler:run_after(...).
  6. Ajoutez une requête de zone Lua native simple ou un context.script:target(...) simple.
  7. Seulement ensuite passez aux attaques rotatives, machines à états et mécaniques multi-étapes.

Prochaines étapes​

  • Premiers pas -- structure de fichiers, hooks, premier pouvoir, modèles à copier-coller
  • Exemples et modèles -- pouvoirs fonctionnels complets à étudier et adapter