Dans la dernière version du Lexicon, se trouve enfin expliqué la manière d'utiliser le Debugger de Script. Voici, ci-dessous, et suite à mes propres expériences, un petit tutorial sur la marche à suivre.


Introduction
Tout d'abord, il faut savoir à quoi ça sert. Le Debugger de Script est un outils qui est apparu dans la version 1.30 de NWN et qui permet de suivre pas à pas l'exécution d'un script tout en examinant les variables utilisées, afin, éventuellement, de découvrir ce qui peut clocher dans un script. Pour les habitués du Visual C, du Delphi, du Visual Basic et même du Java, l'exécution pas à pas d'un programme est un outil incontournable. Très souvente fois, avant de disposer d'un tel outil dans NWN, les seules solutions disponibles pour savoir ce qui cloche dans un programme est d'afficher des valeurs de variables par l'intermédiaire du fichier Log (PrintString ou WriteTimestampedLogEntry), ou en les affichant à l'écran (SpeakString ou SendMessageToPC). Ceci afin de se faire une idée de la valeur d'une variable à un moment donné. Grace au Debugger de Script, fini les prises de tête.


Préparation indispensable
Avant de pouvoir utiliser le Debugger de Script, il est indispensable de s'y préparer. Quand vous êtes en phase de développement ou que vous ayez un cas spécifique de débuggage à effectuer, il est conseillé de faire les réglages suivants :

- Préparer NWN à tourner en mode "fenêtré". Ca sera plus pratique car le débuggeur va se lancer dans une fenêtre indépendante. Vous pouvez ainsi facilement passer de la fenêtre de jeu à la fenêtre de debugger en évitant les ruptures d'images au moment du changement de mode de la carte vidéo (ce qui fatigue un peu l'écran à la longue). Pour passer en mode "fenêtré", il faut ouvrir le fichier NWN.INI figurant dans le dossier du jeu. Trouvez la ligne où il est écris "FullScreen=1". Mettez la en remarque en mettant un ; devant et ajouter les lignes suivante à la suite :
Code :
De plus il est conseillé que baisser la résolution de NWN en mode fenêtré par rapport à votre résolution courante du bureau, afin que NWN n'occupe pas tout l'espace. Pour cela mettez en remarque les lignes des paramètres "Width" et "Height". Si votre bureau est en 1024x768, créer deux nouvelles lignes sous les valeurs initiales :
Code :
Mettez des valeurs qui vous placent dans la résolution immédiatement inférieure à celle de votre bureau (ou moins si votre NWN fait ramer votre carte vidéo).
Le fait de "mettre en remarque" les lignes que j'ai cité est un gain de temps pour rétablir vos paramètres standard. Dans ce cas il vous suffit de mettre en remarque les lignes que vous venez d'ajouter et de rétablir les lignes d'origine en enlevant le point-virgule.

- Faire en sorte que NWN génère les informations de Debug. Les informations de Debug sont des informations complémentaires insérée dans les scripts compilés par NWN. Vous, en tant que scripteur, n'avez aucun contrôle ni aucune visibilité sur les informations de Debug. Il vous suffit juste de savoir qu'elles sont indispensables à faire tourner le Debugger de Script. Pour que NWN compile en générant les informations de Debug, il faut activer l'option. Dans l'éditeur Aurora, ouvrez les options de l'éditeur, rubrique Script et cocher la case correspondante (je crois que le libellé est "Générer les informations de Debuggage à la compilation"). A partir du moment ou cette case est cochée, tous les scripts sont générés avec les informations de Debug. Cela rend la compilation un peu plus lente et le résultat compilé un peu plus gros. Aussi, songez que lorssque vous n'avez plus besoin de cette option, notamment lorsque votre module est "parfait", votre ultime compilation doit se faire sans cette option.

- Lancer le Debugger de Script. C'est la dernière étapes si vous voulez pouvoir débugger un script, il vous faudra, à chaque fois que vous exécuterez votre module, lancer au préalable l'outil qui se situe dans le dossier "utils" de votre répertoire NWN et qui s'appelle "DebugServer.exe". Ce dernier affiche une petite fenêtre sur laquelle il est possible de désactiver le Debuggeur sans l'arrêter (bouton On/Off) et aussi sur lequel il est possible de définir le serveur qui est "scruté" pour le debuggage. Je passe sur cette option pour le moment, ne l'ayant pas essayé. Elle permet de débugger un serveur NWN à distance, depuis une autre machine que celle qui l'exécute. Pour vos premier débuggage, utilisez le avec les options par défaut. Vous avez juste besoin de le démarrer et c'est tout.


Débugger un script
En fait, il reste une chose à faire pour débugger un script en particulier. Le script lui-même doit "appeler" le debugger. Pour cela, une instruction qui a fait son apparition en 1.30 existe. Il s'agit de SpawnScriptDebugger. Dès que NWN rencontrera cette instruction, il se passera une chose particulière sur votre module. Une fenêtre s'affichera dans l'écran de jeu, indiquant que le Debugger a été appelé et une nouvelle fenêtre apparaîtra sur votre bureau avec un contenu des plus intéressants. A ce stade, l'exécution du script est en fait "gelé" sur l'instruction qui suit SpawnScriptDebugger et attend votre bon vouloir.
En jeu, vous ne pouvez plus rien faire. Vous devez poursuivre les opération sur votre fenêtre de Debuggage, dont voici le descriptif :
- Zone supérieure : le code. La zone supérieure de la fenêtre de débuggage contient le code source de votre script. Dans ce code source, une ligne est "surlignée" (en rouge chez moi, je ne sais pas si la couleur dépend des réglage de couleur de Windows ou non). Cette ligne est la ligne sur laquelle le moteur du jeu est "figé". Cette ligne n'a pas encore été exécutée. Vous pouvez bien sur visiter tous le code source, visible dans cette fenêtre, mais vous ne pouvez pas afficher un autre script que celui qui est en cours d'exécution.

- Zone médiane : les variables. Cette zone liste les variables qui possède une valeur au sein de la fonction dans laquelle vous vous trouvez. Vous avez 2 colonnes, le nom de la variable à gauche (parfois précédé d'un symbole + ou - ) et la valeur qu'elle contient, à droite. Le symbole apparaîtra pour tout objet ou variable dîte complexe. Un variable apparaîtra toujours de manière récurente, c'est OBJECT_SELF. Je rappelle, à toute fin utile que tout script possède ce qu'on appelle, un propriétaire. C'est à dire que tout script est toujours exécuté sous l'égide d'un objet du module (le module lui-même est un objet et c'est l'objet par défaut d'un script qui n'aurait pas été affecté lors de son exécution). De ce fait OBJECT_SELF est toujours renseigné et vous indique le nom d'un objet de votre module. Les script d'évènements utilise l'objet de leurs évènements comme OBJECT_SELF. AssignCommand ou ExecuteScript permettent d'affecter un script à un Objet en particulier qui n'est pas forcément l'OBJECT_SELF courant.
Les symboles + ou - indique des variables qui dispose de structures complexe. + permet indique que l'on peut "déplier" la structure pour voir tout ses valeurs (il faut cliquer sur le "+" pour déployer). - indique que l'on peut "replier" la structure pour qu'elle ne prenne plus qu'une seule ligne dans le débuggeur. Les object, les vector, les effect et les location, ainsi que les types définis par le scripteur (ce n'est pas très usité d'ailleurs) sont des types ayant des structures complexes.

- Zone des commandes : plusieurs boutons à votre disposition pour votre debuggage. Les boutons "entrer" et "passer" servent à la même chose, chacun exécute l'instruction pointée (surlignée) dans la zone supérieure. Mais dans le cas d'"entrer", si l'instruction fait appel à une fonction que vous avez faite, le debugger se rendra dans le code source de la fonction en question pour l'exécuter pas à pas dans la continuité. Dans le cas de "passer", il ne rentre pas dans le code des sous-fonctions et se contente d'exécuter la ligne courante. Après chaque appui sur "entrer" ou "passer" les valeurs des variables sont susceptibles de changer et peuvent donc être immédiatement consultée dans la zone médiane. Les variables que l'on voit, sont uniquement celles de la fonction en cours d'exécution dans le debugger. Si jamais vous "entrez" dans une sous-fonctions, la zone des variables refleteras les variables de cette sous-fonctions et non plus celles de la fonction "appelante" (celle où vous avez fait entrer).
Un bouton vous permet d'exécuter jusqu'au "break". Je n'ai pas encore éprouvé cette fonction ignorant comment on peu placer un "break" dans le code. Techniquement, il doit être possible de déclarer, dans le débugger, une sorte de signet que l'on appelle communément un "breakpoint" indiquant que quoi qu'il arrive le débugger s'arrêtera à ce point s'il y passe. Le bouton dont il est question doit donc poursuivre l'exécution non plus pas à pas, mais en direct jusqu'à ce qu'il rencontre l'un de ces breakpoint. Cela reste à tester.
Et enfin le bouton "quitter" désactive le debugger et poursuit l'exécution du script dans le jeux. S'il ne rencontre pas de nouveau un SpawnScriptDebugger, la main est rendue au jeu.

- Zone inférieure : pîle des appels. En l'occurence vous y lirez le nom du script qui est en cours d'exécution et la fonction, sous-fonctions, sous-sous-fonction, etc.. qui ont été successivement appelée. Chaque ligne d'information présente ici permet de "naviguer" dans la "pile des appels" d'un script. Les développeurs professionels (ou amateurs confirmés) n'hésitent pas à réaliser de nombreuses fonctions pour réaliser leurs scripts. L'idée de base d'un tel découpage est de créer des fonctions primitives qui seront utilisée partout. L'idée secondaire est d'avoir moins de travail de maintenance à faire. Si, par exemple, un grand nombre de calcul qui se répète à plusieurs endroit d'un script n'est pas "mis en fonction", le moindre changement du calcul oblige le développeur à le modifier partout où il est utilisé. Le fait de le mettre en fonction lui permet de localiser précisément la formule de calcul (ou l'opération réalisée). Ainsi, un script peut faire appel à plusieurs niveaux de fonctions. Le script appelle la fonction A, laquelle appelle la fonction B, etc... Dans le débugger, on peut très bien décider de "s'arrêter" dans l'exécution de la fonction B (en y plaçant un SpawnScriptDebugger) sans savoir ce qui s'est produit avant. Qu'à cela ne tienne, le Debugger le sait lui. A chaque fois qu'un script en appelle un autre, il réalise ce qu'on appelle un "empilement". Le script de base (appelé manuellement ou par un évènement Aurora) se situe en bas de la pile et la dernière fonction appelée en haut. Ainsi dans mon pseudo exemple je pourrait lire en première ligne "B" en seconde "A" et en troisième "le Script". La fonction A qui est en train d'exécuter la fonction B peut-être visualisée dans le debugger, il suffit de double cliquer dessus dans cette zone. Rappelez-vous qu'en faisant cela, vous perdez de vue le cours de l'exécution de la fonction B, mais que si vous décider de "Passer" ou d'"Entrer", c'est bien dans cette fonction B que se poursuit l'exécution et le Debugger vous y replacera immédiatement. Mais visiter les autres "niveaux" d'exécution à un avantage, il permet de connaître l'état des variables à l'instant T de la fonction concernée. De plus si l'appel de la fonction B est multiple dans la fonction A, on saura à quel appel nous en sommes. Lorsque la fonction B aura fini de s'exécuter et que nous n'avons pas lâcher le Debugger, la fonction "B" sera enlevé de la pile (on dit "dépilé" dans le jargon des informaticiens) et nous nous retrouverons dans la fonction A (laquelle demeure toujours "empilée" sur le script qui l'a appelé).


Pour éviter les plantages
Peut-être certains d'entre vous ont-ils déjà été confronté à des plantage de NWN et du debugger alors que vous étiez en train de l'utiliser. En tout cas j'ai été confronté au problème et je peux l'expliquer. Il se trouve que le debugger est particulièrement sensible au fait que les scripts ne sont pas entièrement recompilé, en dehors du fait qu'ils ne soient pas forcément tous compilés avec les informations de debuggage si vous avez décidé de ne cocher l'option qu'après avoir fait une compilation globale. Il est fréquent, pour les scripteurs de NWN, de ne pas systématiquement faire de "build" de l'ensemble du module (ou au moins de l'ensemble des scripts) lorsque l'on est en phase de débuggage et de test. Seulement, dans ces cas là, on oublie souvent de recompiler les scripts qu'il faut. La sauvegarde et la compilation d'un script n'est pas tout si celui-ci est utilisé, par un include dans d'autre script, il est indispensable de recompiler ces scripts d'appels également. On aura pu remarqué que cela ne l'est pas toujours (indispensable) pour que les scripts fonctionnent normallement. Mais pour le debugger c'est autre chose. Les informations de debuggages doivent visiblement être restaurée correctement pour permettre au debugger de ne pas se planter. Donc, pour éviter ce problème, je conseille une recompilation systématique de tous les scripts (les scripts suffisent. Dans l'outils de "build" vous pouvez passer en mode avancé et décocher ce qui ne concerne pas les scripts) avant une opération de debuggage.


Quelques compléments d'informations et questions restées en suspens
En ce qui concerne l'affichage d'une variable objet, les informations sont plutôt succinctes. Toute au plus dispose-t-on du TAG (lorsque l'on déploie les composants d'un objet). Si par exemple on sauve des variables sur un objet (par SetLocalxxxxx) celles-ci ne peuvent en aucun cas être relu grace au debugger. C'est une limitation sérieuse. Si l'on s'enquérir des valeurs qui peuvent être stockées de cette façon, on a d'autre choix que de les extraire par un GetLocalxxxxx.

Les bibliothèques de scripts fournies par Bioware, ne sont pas recompilées lors de la compilation de nos scripts. Je ne sais pas si ces scripts disposent des informations de débuggage, mais je ne pense pas que cela soit le cas. De ce fait, vous ne pourrez probablement pas "entrer" dans une fonction fournie par Bioware, à moins de recompiler vous-même une version de leur script dans votre module (comme vous êtes susceptibles de le faire avec les scripts de sortilèges pour les personnaliser par exemple).


Encore plus
J'essaierai de reformuler ou compléter certaines explications au fur et à mesure que je découvrirais cet outils dont je suis susceptible de faire un usage immodéré compte tenu de la complexité de mes scripts. En espérant que ce premier jet vous soit déjà très utile.
_________________
Lendraste de Loreval
Qui cherche la Vérité cherche celui qui la détient, car elle n'existe pas à l'état naturel.
La cité des mensonges - 1

Permet moi de te remettre un grand merci pour ce tuto qui va me servir enormement.

Phoelis

Tu as encore fait des merveilles Landrast !!
Merci merci

J'ai testé et ça fonctionne très bien.

Juste une petite remarque, certains d'entre vous auront peut-être comme moi, dans le fichier NWN.INI, AllowWindowMode au lieu de AllowWindowedMode mais c'est bien la premiere orthographe la bonne, comme l'a indiqué Landrast.
Cependant il n'est pas facile de faire la différence au milieu de toutes les lignes du fichier INI (j'ai cherché un bout de temps pour savoir pourquoi je passais pas en mode fenêtré ).

Je viens d'effectuer une petite mise à jour :
- Explications complémentaires sur la zone inférieure du debuggeur.
- Un paragraphe supplémentaire sur les risques de plantage lorsque l'on utilise le debuggeur.
_________________
Lendraste de Loreval
Qui cherche la Vérité cherche celui qui la détient, car elle n'existe pas à l'état naturel.
La cité des mensonges - 1

Je me permets de rajouter une petite précision à ce sujet :
La fonction "aller jusqu'au break" permet en fait de centrer la vue du code sur la ligne courante (surlignée en rouge). Assez pratique lorsqu'on farfouille dans un code très long et qu'on en oublie où la petite ligne reouge se trouvait

Merci pour ce tutorial très intéressant en tout cas

Je me permet juste d'ajouter un petit commentaire.
J'ignore si c'est dû à une version récente du jeu (patch 1.62, NWN+SoU+HotU), mais j'ai remarqué qu'il n'était pas nécessaire de lancer DebugServer avant de tester un module. En effet, à la première exécution de la commande SpawnScriptDebugger(), le debugger est lancer automatiquement.
_________________
It's time to toss the dice.

Le debugmode est totalement inutile en mode serveur : tu fait que le debug gèle le jeu, on se fait automatiquement déconnecter par TimeOut.
Autrement dit si l'on doit tester un mod avec NWNx2 on est mort.
_________________
Atha, Artisan Scripteur.
meet the most beautiful woman in the world