TESCS : Scripting

Tutoriels de références

Avant d'aller plus loin, les documents suivants sont l'alpha et l'oméga pour tout scripteur :

en français :

• Morrowind Scripting for Dummies 8ème édition. Manuel essentiel et quasiment exhaustif qui commence par expliquer les bases avant de couvrir toutes les commandes, les difficultés et les demandes les plus courantes des scripteurs, y compris le scripting avancé, avec de nombreux exemples; recommandable du novice au scripteur chevronné.

• Un début de traduction de la liste alphabétique des fonctions de scripting établie par UESP

en anglais :

• Morrowind Scripting for Dummies 9ème édition : édition revue, augmentée et complétée par rapport à la précédente.

• Liste des commandes sur UESP la liste complète des commandes de scripting par ordre alphabétique, avec leur syntaxe, leur description et les subtilités d'utilisation. Le guide de référence.

Concepts de base

Objets, références, variables

Objets et références

Un objet est un élément défini dans le TESCS par un nom précis que l'on nommera id. Une référence est une instance d'un objet, placée dans le jeu. A une seule id peut donc correspondre plusieurs références placées dans le jeu, par exemple les gardes sont des copies d'un même PNJ, ils ont même id et donc mêmes caractéristiques.

Les commandes de script s'appliquent souvent à des éléments du jeu. Ces éléments sont placés dans le jeu, ce sont donc des références. Mais comme les références n'ont pas de nom en propre, la syntaxe du scripting utilise leurs id pour les nommer, ce qui occasionne bien des problèmes et des confusions.

La plupart du temps, ces commandes de script ne fonctionnent que s'il n'y a pas d'ambiguïté entre id et référence, c'est à dire qu'à une id correspond une unique référence placée dans le jeu. Par exemple, player est l'id du joueur, dont il n'existe qu'une référence associée placée dans le jeu. Player est donc valable pour désigner une référence.

Variables

Une variable est un espace de stockage pour un résultat. Dans Morrowind, une variable est toujours un nombre réel (en pratique, un nombre décimal compris dans une certaine fourchette) ou un nombre entier, Morrowind ne supportant que trois types de variables.

Ces types sont :

- short : un entier compris entre -32768 et 32767

- long : un entier compris entre -2147483648 et 2147483647

- float : un flottant avec au maximum 7 décimales, compris entre -3,4.10^38 et +3,4.10^38

Une variable peut être locale (c'est à dire interne à un script, qu'il soit global ou local) ou globale (utilisable et accessible partout).

Toute variable, locale ou globale, doit être déclarée; dans le TESCS (gameplay->globals) pour les globales et au début du script concerné pour les locales.

Certaines fonctions acceptent des variables en paramètres, d'autres non et n'acceptent que des valeurs numériques. L'extension Tribunal puis MWSE ont augmenté le nombre de commandes de script acceptant des variables.

Les différents types de script

Il existe trois types de scripts :

- le script local, attaché à un objet placé dans le jeu, c'est à dire à une référence. De cette façon, il permet de travailler directement avec cette référence en évitant les confusions entre id et référence.

Un script local ne s'exécute que dans la cellule où est placée sa référence, en intérieur, plus les huit cellules adjacentes, en extérieur.

- le script global est en général lancé par une commande startscript. Une seule instance de ce script s'exécute à la fois et il fonctionne en permanence jusqu'à ce qu'il soit arrêté par une commande stopscript.

- le script ciblé (targeted script) est un hybride entre script local et script global. C'est un script que l'on lance sur une référence à l'aide d'une commande startscript. Il est donc lié à une référence, mais il fonctionne en permanence sans restriction de cellule. Il est possible de lancer plusieurs scripts ciblés sur une même référence, y compris simultanément et même si celle-ci possède déjà un script attaché à son id dans le TESCS, mais il semblerait que lancer simultanément un même script sur différentes références puisse causer des problèmes.

Limitations du scripting

- la profondeur maximale de boucles if imbriquées est de 10

- il y a une limite au nombre de caractères du script (environ 32000) et une limite du nombre de lignes (autour de 1000, probablement 1024 lignes une fois le script compilé)

- il y a une limite de 255 commandes compilées dans une boucle if... endif

- il y a une limite au nombre de conditions if elseif dans un script.

- la 34e variable locale de même type déclarée dans un script n'est pas prise en compte.

Liste alphabétique détaillée et commentée des commandes de scripts

Dans toute la suite :

• ref désignera une référence
• objet_id l'id d'un objet
• n un nombre de type short, éventuellement une variable
• x y z un nombre de type float, éventuellement une variable

AddItem

     ref->AddItem objet_id n

Permet d'ajouter n copies d'un objet d'id objet_id à l'inventaire de la référence ref. D'après MSfD, Additem admet des variables en argument, mais seulement dans les résultats de dialogues et si la variable utilisée n'est pas modifiée dans le même résultat de dialogue.

Cette commande est la seule façon d'affecter une référence dans une cellule encore non visitée, au contraire des commandes de type Set<attribute>, Mod<attribute>, qui ne fonctionnent pas dans ce cas.

AiTravel

     ref->AiTravel x y z

Permet à la référence ref de se rendre aux points de coordonnées x y z dans la cell courante. Par conséquent ceci fonctionne aussi bien en extérieur qu'en intérieur puisque l'id de la cellule n'est pas mentionné.

AiTravel n'accepte pas les variables en argument, même avec Tribunal; cet écueil n'est surmontable qu'avec MWSE (voir la commande xAiTravel)

La présence ou non d'un pathgrid a un certain effet sur cette commande. Lorsqu'un pathgrid existe et permet à la référence en question de se rendre au point x y z, alors s'il n'y pas d'obstacle entre le PNJ et le point d'arrivée, le PNJ s'y rend en ligne droite en empruntant le chemin le plus court; sinon le PNJ se rend au point désiré en empruntant les lignes du pathgrid. S'il n'y a pas de pathgrid, la référence essaie toujours de se rendre au point x y z en ligne droite. S'il y a un obstacle entre le point de départ et le point d'arrivée, la référence aura alors tendance à warper, c'est à dire à disparaître lorsqu'elle rencontre l'obstacle pour réapparaître immédiatement au point x y z.

S'il n'y a pas de difficulté majeure en intérieur, en extérieur le franchissement de bordure d'une cellule pose par contre de gros problèmes. Si l'on veut éviter à la référence de warper, il faut conduire par un AiTravel la référence jusqu'au début de la cellule voisine – mais pas plus loin - puis appeler un autre AiTravel. Cette procédure est délicate et nécessite des tests in game soigneux.

CellChanged

Retourne 1 à la frame où le PJ entre dans une nouvelle cell, 0 le reste du temps.

Attention, lors de cette frame, le PNJ compagnon suiveur se trouve toujours dans la cell précédente. Ce n'est qu'ensuite qu'il est téléporté dans la nouvelle cell,d'où les bugs de PNJs qui subissent des dégats de chute lorsque les deux cells sont à des altitudes différentes et la difficulté de les corriger; dans Morrowind, bon nombre de cells intérieures ont été négligemment créées à l'altitude z = 16000, au lieu de respecter la cohérence entre l'intérieur et l'extérieur.

D'après MsfD, CellChanged n'est pas viable à 100% pour détecter un changement de cell (par exemple avec les téléportations scriptées).

CreateMaps

     CreateMaps "Morrowind.esm"

Commande console permettant permet de créer une carte des cells extérieurs du jeu, prenant en compte tous les esm et esp chargés.

Pour pouvoir utiliser cette commande, il convient de changer la ligne Create Maps Enable=0 en : Create Maps Enable=2 dans la section [General] de Morrowind.ini, et de créer un répertoire Maps dans le répertoire Morrowind; puis de l'appeler en cours de jeu à la console par CreateMaps "Morrowind.esm". Le processus charge successivement toutes les cells du jeu et peut s'avérer très long, souvent plus d'une heure. Le résultat est produit sous forme d'images au format bmp (une image par cell, de format 256x256, pesant chacune 193 ko). Morrowind compte environ un millier de cells extérieures.

DisableLevitation

DisableTeleporting désactive la téléportation dans la cell courante (dans toutes les cells extérieures si appelé en extérieur). Cela s'applique aux interventions d'almsivi, intervention divine, marque et rappel, mais pas aux commandes scriptées telles que positioncell, ou aux objets scriptés de cette façon tels que la bague absconse de Barilzar.

DisableLevitation interdit toute lévitation selon les mêmes conditions.

Ces fonctions sont Tribunal requis.

EnableLevitation

Permet d'autoriser à nouveau la lévitation/la téléportation après que celle-ci a été désactivée par un DisableLevitation/Disableteleporting.

Ces fonctions sont Tribunal requis.

Le script TribunalMain, qui est un script global tournant en permanence et qui interdit la lévitation à Longsanglot et la lévitation et la téléportation dans la cité de Sotha Sil, est buggué en ce sens qu'il cause des problèmes collatéraux, par exemple il rétablit la téléportation dans la chambre de l'Akhulakhan. Il cause aussi des problèmes dans les mods qui utilisent ces commandes. Il existe un script corrigé fonctionnel qui a été appliqué par exemple dans Kalendaar et par le PnoGoty.

Equip

ref->Equip objet_id

Permet de faire équiper un objet à la référence ref, le PJ, un PNJ ou une créature. Commande bugguée avec Morrowind seul, provoquant le message d'erreur habituel« compile and run error ». Réparée avec Tribunal et versions ultérieures. Equip est donc Tribunal requis de facto et rend tout mod l'employant Tribunal requis pour fonctionner correctement.

Face

     ref->Face x y

Face x y fait se tourner un PNJ dans la direction de coordonnées x y dans la cell courante. Face semble admettre des variables en argument.

Il semble qu'essayer d'appeler cette commande continûment (par exemple, pour faire suivre du regard un objet se déplaçant), ou même à intervalles réguliers, fonctionne assez mal.

FixMe

Commande console permettant de déplacer un PNJ.

FixMe peut être utilisé dans les scripts.

FixMe est une commande indispensable si l'on fait des teleports par setpos en extérieur. En effet, si l'on enregistre la position initiale du PJ par des getpos x/y/z, qu'on le téléporte dans une autre cell, puis qu'on le ramène au point de départ par setpos, la cell initiale n'est plus chargée en mémoire, ce qui cause un beau trou dans le paysage et un joli bug graphique. Ajouter un FixMe dans le script après le SetPos de retour permet de recharger la cell en question et donc d'éviter cet écueil.

GameHour

Variable globale qui est de type float (c'est à dire que s'il est midi et quart, gamehour ne retournera pas 12 mais 12.25, il faut donc en tenir compte dans les scripts d'emploi du temps; if ( gamehour == 12 ) est par exemple, un type de condition à proscrire absolument car jamais vraie en pratique ).

Un autre piège à éviter est relatif à l'incrémentation de cette variable pour simuler un écoulement de temps. En effet, si Gamehour dépasse 24 d'une quelconque quantité (que ce soit 24.001 ou 1234), Gamehour est réinitialisé à 0 (et la globale Day est incrémentée de 1). Ainsi un set GameHour to ( Gamehour + 5 ) ne produira qu'un écoulement de temps d'une heure s'il est déjà 23 heures.

GetHealthGetRatio

ref->GetHealthGetRatio

GetHeathGetRatio retourne un float compris entre 0 et 1 qui correspond au quotient santé actuelle/santé de départ de la référence ref.

Attention, dans tout Morrowind, il est adopté la convention que 0/0 = 1 (ce qui permet d'ailleurs de beaux cheats basé sur le remplissage de la barre de magie par des réductions/atténuations d'intelligence jusqu'à atteindre 0, puis en revenant à la normale). Si un PNJ voit sa santé actuelle ET sa santé de départ réduites à 0, par exemple par un SetHealth 0, GethealthGetRatio retournera donc par la suite 1. Il est donc extrêmement peu recommandable d'utiliser un GethealthGetRatio pour déterminer si un PNJ est mort ou non, et même, pour cette raison, il est préférable d'éviter cette commande, à moins de prévoir explicitement ce cas, par exemple en écrivant une boucle préalable court-circuitant le test si GetHealth retourne une valeur <= 0.

GetPCCell

GetPCCell cell_id

Retourne 1 si le PJ se trouve dans une cell dont le nom commence par cell_id, et 0 sinon. Par exemple, si le PJ se trouve dans la cell « Vivec, temple », GetPCCell « Vivec » va donc retourner 1.

Pour que le TESCS accepte de compiler la commande, il faut cependant que la cell cell_id existe vraiment. C'est pourquoi on trouve dans les fichiers esm du jeu des cells quasi-vides et inaccessibles dans le jeu nommées « Longsanglot », « Sotha Sil », etc...

GetPCVisionBonus

Commande console fonctionnant également dans les scripts. Elle retourne une variable de type float comprise entre -1 (aveugle complet, écran noir) et 1 (vision nocturne maximale). Le PJ non affecté par aveuglement ou vision nocturne a un GetPCVisionBonus de 0. 100 points de vision nocturne correspond à GetPCVisionBonus = 1. Au-delà, les points ne sont plus décomptés, ce qui peut occasionner des bugs et un aveuglement temporaire du joueur en combinant plusieurs sorts (si vous lancez un sort donnant 50 points de vision nocturne pendant 30 secondes puis tout de suite après un sort donnant 100 points de vision nocturne pendant 60 secondes, vous êtes à GetPCVisionBonus = 1 les trente premières secondes, puis après la dissipation du premier sort qui vous ôte 50 points de vision, vous êtes à GetPCVisionBonus = 0.5 les trente secondes suivantes, en dépit du fait que vous soyez sous l'effet d'un sort de 100 points de vision nocturne)

GetScale/SetScale

  ref->GetScale
  ref->SetScale x

GetScale permet de retourner l'échelle actuelle de la référence désignée, et SetScale de modifier l'échelle de l'objet. Ces deux commandes sont Tribunal requis; SetScale admet des variables en argument.

Le tescs via la fenêtre « reference data » permet de fixer une échelle à une référence comprise entre 0.5 et 2, par rapport à la taille initiale (échelle = 1 ).

Curieusement, pour les créatures, l'échelle est liée à la créature même(c'est à dire définie dans son id) et donc a priori non modifiable pour une référence particulière; mais on peut le faire tout de même avec la commande S+clic gauche continu sur la créature + mouvement de souris, ce qui permet d'ailleurs de dépasser les limites 0.5 et 2 en dupliquant la référence ainsi mise à l'echelle, (probablement un bug).

SetScale permet de modifier cette échelle en s'affranchissant de la limite 0.5x – 2x la taille initiale. N'importe quelle valeur est acceptée, y compris très grande ou très petite. On peut même appeler SetScale continûment à chaque frame pour créer des effets d'expansion ou de contraction. Toutefois, il ne faut pas appeler SetScale à chaque frame sur un grand nombre d'objets sous peine d'une perte sensible de performances.

Il semblerait que l'utilisation de cette commande créé des problèmes de boîte de collision avec certains meshes, notamment les meshes animées, il faut donc en général ne pas trop s'écarter de la valeur 1 sous peine de problèmes de ce type.

Perte de la valeur d'échelle courante

Si l'échelle d'un objet est supérieure à 2 ou inférieure à 0.5, elle est réajustée au chargement d'une partie (cela peut être un moyen de détecter le chargement d'une partie, et autrement, il faut que le script s'occupe de remettre l'objet à l'ancienne échelle dans ce cas de figure).

Un objet que l'on peut prendre dans son inventaire est toujours ramené à l'échelle 1 lorsqu'on le droppe, même si son échelle est autre dans le tescs (à moins qu'un script n'appelle à nouveau un setscale). Tout objet que l'on peut équiper et qui est visible est, visuellement, proportionné à l'échelle du NPC, et non à l'échelle de l'objet, même si celui-ci est scripté pour réajuster toujours l'objet à cette échelle. Par exemple définir une épée avec un scale de 2 ne rendra pas l'épée deux fois plus grande lorsque le PJ la brandira. La seule façon d'obtenir ce résultat est de modifier l'échelle même du mesh (par exemple avec Nifskope).

Exemples d'applications de SetScale : - l'expansion de l'ego dans Nova Magica - La taille réglable des labyrinthes de LabyConnection.

Goodbye

Commande qui, appelée dans le résultat d'un dialogue, force la fermeture de la boîte de dialogue : le joueur ne peut plus accomplir aucune action dans cette session de dialogue.

Cette commande peut également être utilisée à la console et force automatiquement la fermeture de la boîte de dialogue. C'est donc un outil très pratique pour éviter de relancer le jeu si l'on se retrouve confronté à une bug de type boucle de dialogue infinie, comme par exemple le bug de la compagnie de l'empire oriental introduit par Bloodmoon.

HasItemEquipped

  ref ->HasItemEquipped objet_id

HasItemEquipped retourne 1 si l'acteur concerné tient l'objet appelé équipé, et 0 sinon. HasItemEquipped n'est documenté qu'avec Tribunal, cependant il semblerait que cette fonction soit parfaitement opérationnelle avec Morrowind seul.

Exemple : l'empalement des vampires dans Vampire Realism de Jaxalot (mod qui n'est pas Tribunal requis)

Position, PositionCell

     ref->Position x y z zrot

     ref->PositionCell x y z zrot cell_id

PositionCell place la référence concernée aux coordonnées x y z de la cell cell_id et avec la rotation autour de l'axe z d'angle zrot. Dans la commande Position, il n'y a pas de mention de la cell, cette commande fonctionne partout en extérieur, et peut téléporter à l'intérieur de la cell intérieure courante sans mention de celle-ci. PositionCell fonctionne aussi bien en extérieur qu'en intérieur et permet de téléporter d'une cell intérieure à une cell extérieure et vice-versa. Le paramètre zrot fonctionne aussi bien pour les PNJs que pour le PJ et les objets, mais il s'exprime en degrés pour les objets et le PJ, et en minutes d'arc pour les PNJs et les statics (1 degré = 60 minutes d'arc, donc 90°=5400 minutes).

Position peut créér des bugs graphiques sur les compagnons ainsi téléportés. Il est donc recommandable d'utiliser PositionCell dans ce cas.

D'après MSfD, utiliser PositionCell dans la case result d'un dialogue fonctionne mal et peut causer des crashes. Il est recommandé de lancer un script de téléportation à la place.

Get/Mod/Set

Caractéristiques

     Agility
     Endurance
     Intelligence
     Luck
     Personality
     Speed
     Strength
     Willpower

Compétences

Combat

     Armorer
     Athletics
     Axe
     Block
     BluntWeapon
     HandToHand
     HeavyArmor
     LightArmor
     LongBlade
     Marksman
     MediumArmor
     ShortBlade
     Spear
     Unarmored

Discrétion

     Mercantile
     Security
     Sneak
     Speechcraft

Magie

     Alchemy
     Alteration
     Conjuration
     Destruction
     Enchant
     Illusion
     Mysticism
     Restoration

Barres d'état

     Fatigue
     Health
     Magicka

Résistances

     ResistMagicka
     ResistFire
     ResistFrost
     ResistShock
     ResistDisease
     ResistBlight
     ResistCorprus
     ResistPoison
     ResistParalysis
     ResistNormalWeapons

Effets modificateurs actifs

     ArmorBonus
     AttackBonus
     DefendBonus

     Chameleon
     Invisible
     Flying
     SwimSpeed
     SuperJump
     WaterBreathing
     WaterWalking

     Blindness
     CastPenalty
     Paralysis
     Silence

Stats générales

     Level (only works with Set and Get)
     Reputation
     PCrimeLevel (PC Only)

IA

     Alarm (Changing this changes it for ALL references of the Actor)
     Fight (Changing this changes it for ALL references of the Actor)
     Flee (Changing this changes it for ALL references of the Actor)
     Hello (Changing this changes it for ALL references of the Actor)

Divers

     Scale (the 3D scale of the object)

Coût comparé des différentes fonctions de script

Les différents tests et fonctions de script ont été testés en utilisant le script suivant (cette méthologie n'est pas sans défaut, principalement à cause de l'utilisation de getSecondesPassed et de boucles while, mais a le mérite de pouvoir comparer entre elles les différentes fonctions de scripting du point de vue de leur coût d'exécution)

Begin test_cout_compare
long nombre_un
long nombre_deux
long compte
float timer
if ( timer < 30 )
while ( compte < n )
[instructions]
endwhile
set nombre_un to ( nombre_un + 1 )	
set compte to 0
else
MessageBox "N1 = %g  N2 = %g" nombre_un nombre_deux
stopscript Test_cout_compare
endif
set timer to ( timer + Getsecondspassed )
end

Les résultats expérimentaux suivants portent sur la valeur de n (nombre de boucles par frame) dans le script ci-dessus lorsqu'on place diverses fonctions dans le bloc [instructions]. Cette valeur de n est choisie telle que le script entraîne exactement une baisse de 10% du framerate dans une cell de test pratiquement vide. La marge d'erreur sur ces valeurs est d'environ 1 à 2%.

Boucle vide (pas d'instruction, cela représente donc le coût intrinsèque du script et de sa boucle while)	n = 495
MenuMode	490
GetPCCell	460
GetPCVisionBonus	460
Getjournalindex, GetScale, GetDisabled, HasItemEquipped, disable, startscript et toutes fonctions similaires	450
set	440
moveworld	440
GetDistance	440
GetDetected	440
HasSoulGem	405
if (si le comparant est un petit nombre)	295
if (si le comparant est une valeur à six chiffres)	250
rotateworld	200
setscale	105
removespell	< 3
MessageBox	< 1
removeitem	< 1
Journal	< 1

Quelques remarques et conséquences :

- if est une commande relativement lourde, beaucoup plus lourde en général que la fonction utilisée dans la condition de ce if

- le test d'une inégalité a à peu près le même coût que le test d'une égalité

- une boucle if .../ elseif... /elseif/ ... /else / endif a le coût d'un seul test environ (et donc beaucoup plus léger qu'une suite de if ... endif avec les mêmes conditions)

- tester des float, des long ou des short a à peu près le même coût

Exe externes

Morrowind Scripting Extender (MWSE)

Page du projet libre MWSE

Télécharger MWSE (version 0.94)