[DIDACTICIEL] Création de mod pour Dragon Age

[Isaya]

Cette série d'articles est tirée du blog Beyond Ferelden. Il s'agit de traductions de certains des didacticiels proposés par l'éditeur de ce site, John Vanderbeck. Il est aussi l'auteur du programme DAModder.

Table des matières

• Didacticiels de création proprement dits
  • Débuter : créer un module donnant un objet à votre personnage
  • Un meilleur moyen de vérifier l'existence d'objets avant de les créer
• Informations complémentaires
  • Comment empêcher la trousse à outils de ruiner votre jeu

S'il vous plaît, ne posez pas de questions et ne faites pas de remarques dans ce sujet. Laissez la place pour l'ajout ultérieur d'autres didacticiels en rapport avec les premiers postés.
S'il n'existe pas encore de sujet de discussion à propos de cette série de didacticiels, créez-en un. Merci d'avance.

[Isaya]

NdT : ce document est une traduction du didacticiel Preventing the Toolset from Breaking Your Game.

Comment empêcher la trousse à outils de ruiner votre jeu

Très franchement, c'est l'un des premiers didacticiels que j'aurais dû poster, mais ça m'est complètement sorti de l'esprit. Une fois que vous avez commencé à faire quelque chose par habitude, il est facile d'oublier que vous le faites.

De nombreuses personnes rencontrent des problèmes avec le fait que la trousse à outils provoque des dysfonctionnements dans leur jeu en Single Player, consécutivement à la création d'un mod.
[NdT : Single Player fait référence à la compagne originale de Dragon Age, car elle est appelée ainsi dans la trousse à outils.]

Dans cet article, nous verrons pourquoi cela se produit et comment vous pouvez réduire les risques que cela arrive.


N'éditez jamais le module Single Player

C'est la règle la plus évidente en premier, mais il faut bien le dire. Vous ne devriez jamais éditer, ni même ouvrir, le module Single Player. Il n'y en a pas besoin, tout simplement. Plus j'apprends, plus je me rends compte que vous ne pouvez rien faire là-dedans que vous ne puissiez faire avec votre propre module, de toute façon, donc n'y touchez pas. Faites comme s'il n'existait même pas.


Faites le ménage après avoir exporté

C'est la règle principale, et aussi la raison pour laquelle la plupart des gens ont des problèmes. Il ne s'agit vraiment pas de quelque chose que vous fassiez mal, mais plutôt d'une bizarrerie de la trousse à outils. A présent la trousse à outils est excessivement agressive. Quand vous exportez une ressource, même si vous spécifiez "without dependent ressources" [NdT : sans les ressources qui en dépendent ou dont elle dépend, A VERIFIER], la trousse à outils exporte bien plus qu'il n'a besoin de le faire.

Cela est rendu encore plus compliqué par un bug de la trousse à outils. Vous voyez, la base de données de la trousse à outils contient de mauvais indicateurs d'intrigue [NdT: en anglais, plot] venant d'une ancienne version du jeu. En conséquence, quand la trousse à outils exporte, si elle exporte des ressources d'intrigue, ces ressources vont provoquer le chaos total dans votre jeu.
[NdT : cet article a été écrit peu de temps après la mise à disposition de la trousse à outils version 1.0, bien avant la sortie de la version 1.01 de la trousse à outils, qui corrige de gros problèmes de base de données relatifs à la compagne originale. Par conséquent ce second défaut évoqué par l'auteur n'est probablement plus présent avec la version la plus récente de la trousse à outils.]

La façon de contourner ces deux problèmes consiste à être attentif à la fois à ce que vous voulez exporter et à ce qui est effectivement exporté. Une fois que vous avez exporté une ressource, ouvrez le répertoire "packages\core\override\toolsetexport" et supprimez les éléments en excédent dont vous n'avez pas besoin. Ne conservez que ce que vous aviez vraiment l'intention d'exporter.

NdT : dans les commentaires de l'article, en réponse à une question, l'auteur précise plusieurs points :

• il faut savoir précisément ce que l'on cherche à exporter (quelles ressources, sous quel nom) de façon à identifier ces éléments dans le répertoire "toolsetexport" au milieu des fichiers parasites
• les fichiers .nss peuvent être effacés sans crainte ; il s'agit des fichiers sources des scripts, le jeu n'utilise que les versions compilées, qui ont l'extension .ncs
• habituellement les fichiers créés pour un module sont exportés dans le répertoire "addins" sous le nom du module. Seuls les fichiers d'origine "core" (les ressources de base utilisables par tous les modules) auxquels on apporte des modifications et qui se retrouvent dans le répertoire "packages\core\override\toolsetexport" au moment de l'export nécessitent d'être conservés.

[Isaya]

NdT : ce document est une traduction du didacticiel A Start: Creating a Module to Give Your Player an Item.

Dans ce didacticiel, nous allons jeter un coup d'oeil à quelque chose d'assez simple mais qui vous donnera un bon aperçu de la trousse à outils. C'est aussi quelque chose que de nombreuses personnes cherchent à faire. Bande de tricheurs !

Nous allons créer un nouveau module qui enrichit [NdT : extend, en anglais] la campagne Single Player. Bioware appellerait cela une extension [NdT : en anglais, un add-in]. Essentiellement cela signifie que nous n'allons pas modifier du tout la campagne Single Player. Notre extension va au contraire enrichir la campagne originale en lui ajoutant du nouveau contenu. Ceci est fondamental parce que, si nous essayions de modifier la campagne originale en l'éditant, nous pourrions l'endommager d'une façon ou d'une autre, et nous le ferions probablement. Il en va ainsi avec la trousse à outils. Pensez à cela comme à une mini-tour de Shale, d'une certaine façon. Nous allons simplement ajouter du nouveau contenu.

Dans le cadre de ce didacticiel, je vais considérer que vous avez déjà installé la trousse à outils. Malheureusement il y a eu beaucoup de problèmes avec cette installation, mais je ne peux pas vraiment vous aider sur ce point. Consultez le wiki et les forums [NdT : ceux de Bioware] pour trouver des réponses aux problèmes les plus courants.
[NdT : vous pouvez aussi consulter les principaux articles traduits en français dans ce sujet.]

Ensuite, je vais aussi supposer que vous avez fait un peu le tour de la trousse à outils, et très probablement à partir du module Single Player, qui est la campagne originale du jeu. Très franchement, c'est une mauvaise idée, à même de ruiner la campagne. La première chose que vous devriez faire, c'est de choisir, depuis la trousse à outils, l'option Tools -> Export -> Empty Export Directories. Cela va nettoyer toutes traces des changements que vous avez effectués. Cela va vider toutes les surcharges [NdT : override] vis à vis de Single Player mais c'est important pour préserver un fonctionnement correct de la campagne. Une fois que vous avez fait ça, n'ouvrez plus jamais le module Single Player !

Créer un nouveau module

Pour commencer, nous avons besoin de créer notre nouveau module. L'option File -> Manage Modules va ouvrir la fenêtre dont nous avons besoin. Cliquez sur New pour créer un nouveau module.
La fenêtre qui apparaît est la fenêtre "Module Properties". Nous avons besoin de fixer certaines choses à l'intérieur. Tout d'abord, donnez un nom à votre module. Pour ce didacticiel je vais appeler le mien "Bow of Athena". Appelez le vôtre comme bon vous semble. La chose suivante est de fixer son UID. Il s'agit d'un IDentifiant Unique, alors il faut qu'il soit unique parmi tous les modules que vous créez mais aussi par rapport à tous les modules créés par n'importe qui d'autre, sinon il pourrait y avoir des conflits. Il doit être écrit en minuscules et vous pouvez utiliser des lettres et des soulignés. Peut-être aussi les chiffres et d'autres symboles, mais je n'ai pas essayé. Une excellente façon d'aider à garantir que vos UIDs seront uniques est de vous trouver un préfixe de 3 ou 4 lettres qui vous soit d'une certaine façon spécifique et de l'utiliser systématiquement, en plus d'un identifiant pour le module. Dans mon cas, je fais nombres de choses sous le pseudonyme "Agathorn", alors j'ai tendance à préfixer mes trucs par "aga_".

La dernière chose qu'il vous faut faire est de définir que ce module enrichit la campagne originale, qui constitue le module "Single Player". Pour ce faire, faites défiler la fenêtre des propriétés jusqu'à la section suivante, "Info", et changez la propriété "Extended Module" en "Single Player". Une fois que c'est fait, cliquez sur OK.
Vous allez vous retrouver dans la fenêtre Manage Modules et votre nouveau module figurera dans la liste et devrait être sélectionné. S'il n'est pas sélectionné, sélectionnez-le. Maintenant cliquez sur Open pour ouvrir votre nouveau module. Il reste une dernière chose que nous avons besoin de faire dans la fenêtre Manage Modules, aussi retournez dans File -> Manage Modules une dernière fois. Sélectionnez votre module et cliquez sur Hierarchy.... A cet endroit, cochez à côté de Single Player.
Remarque : si tous les modules sont grisés dans cette fenêtre et que vous ne pouvez pas les sélectionner, cela signifie que vous n'avez pas ouvert le module avant, comme indiqué ci-dessus.

Cliquez sur OK pour fermer la fenêtre Hierarchy, puis fermez également la fenêtre Manage Modules. Nous en avons terminé pour le moment.


Créer votre objet

La prochaine chose qu'il nous faut faire est véritablement créer l'objet que nous voulons donner au joueur. Si vous voulez donner au joueur un objet qui existe déjà dans le jeu, vous pouvez sauter cette section.

Pour ce didacticiel, nous allons créer un bel arc, utilisable à bas niveau mais qui possède un peu de puissance afin de vous montrer quelques-unes des options. Dans la fenêtre de palette sur la droite, cliquez sur l'icône de l'épée pour basculer vers les objets. Quand vous ferez cela, vous verrez en dessous un groupe de dossiers s'ouvrir. Ces dossiers n'ont aucune signification pour le jeu mais sont présents simplement pour l'organisation. Cependant je n'ai pas encore découvert comment ajouter en pratique vos propres dossiers, alors jusqu'à présent j'ai tout placé dans la racine.

Avec le bouton droit, cliquez n'importe où dans l'espace libre en dessous des dossiers et choisissez New -> Item. Dans la fenêtre qui apparaît, nous avons plusieurs choses à faire. D'abord nous avons besoin d'un nom de ressource, dans Resource Name. Comme votre UID, il faut qu'il soit unique alors réfléchissez-y. Folder désigne juste où l'objet sera placé dans l'arborescence des dossiers au dessus. Cela n'a aucune d'importance sinon pour votre organisation. J'ai placé le mien dans la racine "\". C'est vous qui décidez. Ensuite vient le Module et ceci est très important. A cet instant le Module sera fixé au module que vous êtes en train de créer mais nous voulons au contraire que l'objet soit ajouté aux "Core Resources" du jeu. La raison est que, de cette façon, nous enrichissons Single Player comme prévu et que notre module peut cohabiter avec les autres qui font de même. En mettant cet objet dans Core Resources, n'importe quel autre module qui enrichit Single Player peut aussi s'en servir. Par conséquent, choisissez "Core Game Resources" dans la propriété Module. Tout le reste peut rester aux valeurs par défaut, Owner Module étant votre module. Cliquez sur OK et l'objet sera créé et réservé [NdT : en anglais, checked-out] afin que vous puissiez le modifier.
Parlons un petit peu de cette histoire de checkout. Cette trousse à outils est pour l'essentiel ce que Bioware a employé pour créer le module Single Player et, bien entendu, le module n'a pas été écrit par une seule personne. Il y avait de nombreuses personnes qui travaillaient dessus. Dans tout projet en groupe, il y a une notion de "Gestion des Versions". En quelques mots, il s'agit d'un moyen pour que plusieurs personnes puissent travailler sur les mêmes fichiers sans se marcher sur les pieds. Le processus est simple. Si vous souhaitez travailler sur un fichier, vous commencez par l'obtenir de la bibliothèque de gestion, en quelque sorte. Cela prévient le système que vous allez travailler sur le fichier et cela vous donne une copie locale que vous pouvez modifier. Ensuite, une fois que avez terminé vos modifications, vous le restituez à la bibliothèque, qui va alors comparer votre exemplaire à sa propre version, voir ce que vous avez changé et générer une nouvelle version en combinant les deux. De cette manière, si quelqu'un d'autre et vous avez modifié le même fichier en même temps, vos modifications se trouvent fusionnées pour créer le fichier final.
[NdT : pour d'autres informations sur cette notion de checkout, vous pouvez consulter ce document du Wiki de la trousse à outils traduit en français.]

Bon, vous n'avez pas vraiment besoin de vous soucier de tout cela ni même de vous en souvenir, mais ce que vous devez absolument retenir, c'est que, chaque fois que vous voulez modifier une ressource, il vous faut l'obtenir [NdT : checkout], et ensuite, quand vous avez terminé avec elle, vous l'enregistrez puis il vous faut la restituer [NdT : checkin]. Dans le cas qui nous intéresse, le système nous fera obtenir automatiquement la nouvelle ressource. S'il s'agissait d'une ressource existante, nous pourrions cliquer sur elle avec le bouton droit et choisir Check out. Dans tous les cas, vous pourrez désormais voir le nouvel objet s'ouvrir dans la fenêtre principale de la trousse à outils. Sur le côté gauche figurent ses propriétés et sur la droite, un modèle en 3D de l'objet. Dans la vue 3D, la molette de la souris provoquera un agrandissement ou un rétrécissement et Ctrl + Bouton droit de la souris fera tourner le modèle.

Cependant, ce qui nous intéresse, ce sont les propriétés sur le côté gauche. Base Item Type [NdT : type d'objet de base] indique le type d'objet dont il s'agit. Est-ce une épée longue (par défaut) ou peut-être une armure légère ? Le type de base détermine l'origine de beaucoup de propriétés. Par exemple, une épée longue possède certaines valeurs de dégâts de base, de facteur de vitesse, de chance de coup critique, etc. Dans notre cas, nous réalisons un arc, aussi j'ai choisi "Weapon - Longbow" [NdT : Arme - Arc long]. Vous remarquerez que cela affecte aussi le modèle 3D. Ensuite vous pouvez lui attribuer une Description. Vous pouvez écrire directement dans le champ de saisie ou, si vous cliquez sur les trois points à droite du champ, cela ouvrira un boîte de saisie plus grande pour une édition multi-lignes. Elle possède aussi un correcteur orthographique intégré. [NdT : en anglais uniquement]

Une fois que vous avez décrit votre objet, il a besoin d'une icône, aussi cliquez sur la propriété Icon puis cliquez sur les trois points pour ouvrir un sélecteur de fichier. Malheureusement ce sélecteur de fichier ne vous permet pas de voir les vignettes des images et il y en a beaucoup. Cependant, nous voulons un fichier icône et ils commencent tous par "ico_". J'ai choisi "ico_longbow".

Le champ suivant est Inventory Subgroup [NdT : sous-groupe d'inventaire]. Je ne suis pas certain à 100 % de ce qu'il affecte, mais la meilleure chose à faire est de mettre pareil que dans un autre objet de ce type de base. Par conséquent, sur la droite, ouvrez le dossier _Global, puis le dossier Weapons, Ranged [NdT : armes à distance], et enfin le dossier Longbows [NdT : arc long]. Cliquez avec le bouton gauche sur n'importe quel arc de la liste. J'ai cliqué sur le dernier qui correspond à l'arc long générique. Quand vous cliquez, ses propriétés vont s'afficher dans la fenêtre au dessous. Vous pouvez voir qu'il a une valeur de sous-groupe de 212000, alors nous allons simplement mettre la même valeur pour le nôtre.

Item Variation [NdT : variation d'objet] vous permet de choisir parmi quelques modèles 3D différents pour votre objet. Choisissez celui que vous voulez.

Ensuite viennent Material Progression [NdT : progression du matériau] et Material Type [NdT : type de matériau]. Ceux-ci déterminent le grade de l'arme et la texture du modèle 3D. J'ai mis les deux à "Bow, Horn" [NdT : arc, orme], qui correspond au grade 1.

Un aparté sur Material Progression et l'adaptation des objets : dans la liste des objets, vous avez peut-être remarqué qu'il n'y avait qu'un seul arc long de base. Vous ne trouvez pas de Horn Longbow, Ash Longbow, etc [NdT : arc en orme, en bois de frêne]. Juste un seul "Longbow" en plus de quelques types spéciaux tels que Darkspawn Longbow ou Dalish Longbow. La raison est que Dragon Age fonctionne d'une façon différente de ce à quoi vous êtes peut-être habitué si vous avez déjà créé des modules pour par exemple Neverwinter Nights, comme moi. Dans NWN, vous créiez chaque objet un par un. Si vous vouliez des versions plus ou moins performantes d'un objet, alors vous créiez plusieurs versions et ajustiez les caractéristiques pour chacune d'entre elles. De son côté, Dragon Age opère en graduant automatiquement les objets pour qu'ils conviennent au joueur. Vous constaterez aussi que, nulle part dans les propriétés de notre arc, vous ne pouvez fixer des valeurs telles que les dégâts, les chances de coup critique, etc. Tout ceci fait partie de l'objet de base et du grade du matériau. Un arc long de base a une valeur de dégâts de 6 et ensuite chaque grade de matériau applique un multiplicateur à cette valeur. Par exemple un Elm bow [NdT : arc en orme] a un multiplicateur de 1.0 mais un Dragonthorn bow [NdT : arc en griffe de dragon ?] a un multiplicateur de 1.6. Alors comment tout cela est-il lié ? La façon dont cela fonctionne est, je crois, que la propriété Material Progression indique aux scripts du jeu quels grades de matériau possibles l'objet peut utiliser quand il fait sa mise à niveau automatique. Vous noterez qu'une des options est "All Woods" [NdT : tout type de bois]. Je pense que cela signifie que le script peut le mettre à n'importe quel grade qui lui convient. Par contre, si vous mettez Material Progression à "Bow, Ironbark", je pense que cela indiquerait au script qu'Ironbark est le grade minimum qu'il peut avoir. D'où tout cela vient-il ? Des fichiers 2da, qui dépassent vraiment le cadre de ce didacticiel, mais j'en parlerai dans un prochain didacticiel. Je voulais juste présenter un peu les principes fondamentaux ici.

Bien, maintenant que nous avons fixé le grade de notre matériau, il nous faut donner à notre objet un nom (Name) et un Tag [NdT : étiquette]. Pas besoin d'explication pour le nom. Le Tag est un identifiant que vous pouvez utiliser dans les scripts pour faire référence à cet objet. Par défaut le tag est identique au Resource Name et je vais simplement le laisser ainsi.

La section suivante, Attributes, nous permet d'appliquer quelques aspects amusants tels que les modificateurs et les effets au toucher sur notre objet, ainsi que de fixer son prix. En premier figure Cost, qui est simplement ce que l'objet devrait coûter, en pièces de cuivre. 100 cuivre = 1 argent, 100 argent = 1 or. Donnons à notre arc quelques modificateurs géniaux. Cliquez sur le champ Item Properties puis cliquez sur les trois points. Cela va ouvrir la fenêtre Item Properties, où vous pouvez affecter jusqu'à 5 "abilities" [NdT : capacités] à l'objet. Je me souviens que dans NWN, plus vous ajoutiez de capacités à un objet, et plus elles étaient puissantes, plus l'objet devenait de haut niveau. Je ne sais pas si cela marche de la même manière dans Dragon Age ou non. Dans notre cas, nous allons lui donner deux capacités. Sur la gauche se trouvent toutes les capacités que vous pouvez affecter. Sélectionnez d'abord celle qui s'appelle "Faster Aim (0.1s per power)" [NdT : visée plus rapide] puis cliquez sur le bouton Add -> pour l'ajouter à l'objet. Une fois que vous aurez fait ça, vous la verrez apparaître sur la partie droite de la fenêtre. Sur la droite, vous verrez trois colonnes et celle la plus à droite est tronquée et indique simplement "Po...". Il s'agit en réalité de "Power" [NdT : puissance, pouvoir] et elle indique à quel point cette capacité est puissante. Par défaut, elle vaut 0. Avez-vous remarqué que le nom de notre capacité indique "0.1s per power" [NdT : 0,1 s par niveau de puissance] ? Cela signifie que chaque niveau de puissance rendra le temps de visée plus court de 0,1 seconde. Pour fixer le niveau de puissance, cliquez simplement sur le 0 et remplacez le par 1 puis tapez Entrée. Ensuite ajoutez une autre capacité, "Increase Electricity Resistance (5 per power)" [NdT : augmenter la résistance aux dégâts électriques] et mettez-la à un niveau de puissance de 1 également. Une fois que vous avez terminé, cliquez sur OK pour fermer cette fenêtre. Maintenant la propriété suivante juste au-dessous est OnHit Effect [NdT : effet au toucher] et nous allons l'utiliser pour donner à notre arc la capacité de faire des dégâts électriques. Cliquez sur l'icône de liste déroulante et sélectionnez le choix qui s'intitule +electricity damage.
Nous avons maintenant achevé l'édition de notre objet. Alors que faisons-nous ? Enregistrer et restituer (check in). Save ressemble simplement à la plupart des applications Windows et possède un raccourci, Ctrl-S ; autrement vous pouvez aller dans le menu File ou encore cliquer sur la petite icône de disquette dans la barre d'outils. Faites comme vous voulez. Allez-y et enregistrez l'objet. Maintenant nous avons besoin de le restituer. Vous pouvez le faire en cliquant sur l'objet avec le bouton droit dans la vue arborescente sur la droite, ou bien vous pouvez aussi cliquer avec le bouton droit sur le nom de fichier de l'objet dans la liste des onglets en haut. Ici aussi, faites comme vous préférez. Cliquez avec le bouton droit et choisissez Check in. La fenêtre de restitution va apparaître. Taper un commentaire est assez inutile pour l'utilisateur moyen mais c'est vous qui voyez. Si vous ne voulez pas indiquer quoi que ce soit, cliquez simplement sur la case qui stipule "I do not wish to enter a comment" [NdT : je ne souhaite pas entrer de commentaire] plus cliquez sur OK. Cela va restituer l'objet. Veuillez noter deux choses. D'abord, le sommet de la fenêtre a désormais une bordure rouge et indique READ ONLY COPY [NdT : exemplaire en lecture seule]. Vous ne pouvez plus éditer cet objet désormais. Observez également que, sur la droite, dans la vue arborescente, l'objet a une marque verte quand il est en édition (check out), et que cette marque a disparu maintenant qu'il a été restitué.

Si, pour une raison quelconque, vous voulez modifier cet objet de nouveau, cliquez simplement sur lui avec le bouton droit et choisissez Check out. Soulignons qu'il est important d'être bien conscient de tout ce processus obtenir / restituer (check out / check in).


Créer un script d'événement pour donner l'objet

Nous avons presque terminé. Une dernière ressource à créer et nous pourrons commencer à tout exporter pour jouer avec ! Maintenant que nous avons l'objet, nous avons besoin d'un moyen de le donner effectivement à notre personnage. Nous allons le faire au travers de l'emploi d'un script d'événement [NdT : event script], aussi appelé script coeur du module [NdT : module core script]. Voyez-vous, lorsque se produisent dans le jeu certaines choses qui influent sur votre module, le moteur de jeu appelle le script coeur du module et lui passe un événement à traiter. Nous allons utiliser cela pour se greffer sur un événement qui sera envoyé quand le module se chargera, et lui faire introduire l'objet dans l'inventaire du personnage à ce moment-là.

Dans Dragon Age, les scripts sont en C++ standard et l'enseignement de ce langage est d'une tout autre envergure que ce didacticiel, aussi je vais me contenter de vous fournir un script fortement commenté que vous pouvez utiliser. Tout d'abord il nous faut créer un nouveau script. Dans la fenêtre de la palette, cliquez sur l'icône de la seconde rangée juste à gauche de l'icône représentant une feuille avec un C. Il s'agit de l'icône représentant une feuille avec plusieurs lignes. Comme auparavant, cliquez avec le bouton droit au-dessus d'un espace libre et choisissez New -> Script. Cela fera apparaître la même fenêtre de création de ressource que nous avons déjà vue. Donnez un nom à votre script, j'ai appelé le mien "module_core_bowathena". Indiquez un dossier également, comme l'autre fois. La principale différence cette fois-ci est qu'il nous faut affecter le script de Module à votre module et non pas à Core. Aussi bien Module que Owner Module doivent désigner votre module. Cliquez sur OK pour créer et réserver le nouveau script.

Code : Tout sélectionner

// Tous les événements du module
#include "utility_h"
#include "wrappers_h"
#include "events_h"
void main()
{
    event ev   = GetCurrentEvent();
    int nEvent = GetEventType(ev);
    Log_Events("", ev);
    switch (nEvent)
    {
        ////////////////////////////////////////////////////////////////////////
        // Envoyé par : le moteur de jeu
        // Quand : le module se charge à partir d'une partie sauvegardée, ou pour  la première fois. Cet événement
        //       peut se déclencher plus d'une fois pour un module unique ou une partie unique.
        ////////////////////////////////////////////////////////////////////////
        case EVENT_TYPE_MODULE_LOAD:
        {
            // Cet événement peut se déclencher à plusieurs reprises et nous ne voulons faire cela
            // qu'une seule fois. Par conséquent nous enregistrons un indicateur dans une variable
            // numérique. Nous la vérifions ici et si elle est déjà initialisée, nous savons que nous
            // avons déjà fait cela auparavant. Vous pouvez mettre ce que vous voulez comme
            // nom de variable entre guillemets.
            int iModuleLoaded = GetLocalInt(OBJECT_SELF, "aga_bowathena");
            if (iModuleLoaded == 1)
                break;

            // Obtenir l'objet qui contient le joueur
            object oPlayer = GetHero();

            // L'indicateur que nous enregistrons ne perdurera pas au-delà de la session de jeu, aussi c'est une
            // bonne idée de vérifier vraiment si le joueur possède déjà l'objet, à moins que vous ne VOULIEZ
            // qu'il en obtienne un autre. Le nom entre guillemets est le TAG de l'objet. Nous vérifions combien
            // d'exemplaires de l'objet le joueur possède déjà et, si c'est 0, nous savons que nous ne lui avons
            // pas encore donné l'objet (ou qu'il l'a vendu :p ).
            int iItemCount = CountItemsByTag(oPlayer, "aga_bowofathena");
            // Si c'est 0, alors donnons lui l'objet. Ce premier paramètre est un identifiant de RESSOURCE.
            // Remarquez comment il est formé : R"nom_de_fichier_ressource"
            // Le préfixe "R" est important et l'identifie comme une ressource. Le nom de fichier est simplement
            // le nom du fichier de la ressource. Vous pouvez le voir dans la trousse à outils sur les onglets en haut.
            // Le nombre 1 signifie qu'on donne 1 objet.
            if (iItemCount  == 0)
                UT_AddItemToInventory(R"aga_bowofathena.uti",1);

            // Pour finir nous initialisons cette variable numérique dont nous avons parlé plus tôt,
            // afin d'enregistrer le fait que nous avons déjà donné l'objet.
            SetLocalInt(OBJECT_SELF, "aga_bowathena", 1);
            break;
        }
        default:
        {
            break;
        }
    }
}

Note de l'éditeur : depuis le moment où j'ai écrit le didacticiel original, de meilleures façons de procéder sont apparues. Même si ce qui précède est une bonne initiation simple, ce n'est pas la meilleure façon de le faire dans un mod publié. Veuillez lire la suite dans cet article [NdT : dont voici une traduction française].

Une fois que vous avez recopié le script, enregistrez-le. Dans le cas d'un script, l'enregistrement va prendre un peu plus de temps. La trousse à outils doit compiler le script pour vous. Une fois que c'est fait, restituez le fichier [NdT : check in] également. Maintenant il nous faut dire au module d'utiliser ce script en tant que script coeur [NdT : core]. Pour ce faire, il nous faut éditer de nouveau les propriétés de notre module, aussi retournez dans File -> Manage Modules, sélectionnez notre module puis cliquez sur Properties. Cliquez sur la propriété Script, puis sur les trois points et sélectionnez le script que vous venez de créer.

Si vous avez sauté la création d'un nouvel objet et que vous vouliez juste vous donner un objet existant, il vous faut quand même connaître le "tag" et le nom de fichier de ressource [NdT : "resource filename"] de l'objet. Vous pouvez le trouver tout simplement en sélectionnant l'objet dans la vue arborescente sur la droite.


Exporter votre module

Nous sommes maintenant parvenus à l'étape finale. Tout le travail difficile est achevé, désormais tout ce qu'il faut faire est d'exporter vos ressources et votre module afin qu'il apparaisse dans votre partie. Pour ce faire, il nous faut d'abord exporter chaque ressource que nous avons créée. Si vous avez créé un objet, vous devez l'exporter. Cliquez de nouveau sur l'icône de l'épée pour retourner dans les objets puis cliquez avec le bouton droit sur votre nouvel objet et choisissez Export -> Export without dependent resources [NdT : exporter sans les ressources dont elle a besoin]. Ensuite allez dans les scripts et faites la même chose pour votre script. Enfin, pour exporter votre module, allez dans le menu Tools -> Export -> Generate Module XML [NdT : générer le fichier XML du module] puis dans Tools -> Export -> Generate Manifest XML [NdT : générer le fichier XML de manifeste].

Maintenant, allez-y, lancez le jeu et vous devriez apercevoir votre module dans le contenu installé. Commencez une nouvelle partie ou chargez une sauvegarde existante et vous devriez retrouver votre nouvel objet dans votre inventaire. Amusez-vous bien !

SUITE : une suite à cet article [NdT : en anglais uniquement, pour l'instant] traite de certains des problèmes et des erreurs les plus courants que les gens rencontrent ou font.


[NdT : certains choix de terme d'une traduction sont souvent discutables. Faute de traduction officielle par l'éditeur, j'ai fait des choix. J'aurais pu traduire "core" par "noyau", par exemple, par analogie avec les systèmes d'exploitation, mais je n'ai pas trouvé ce terme très approprié (le noyau, ce serait plutôt le moteur de jeu lui-même, dans ce cas). Si certains termes vous choquent ou si vous avez des propositions d'améliorations, n'hésitez pas à me contacter.]

[Isaya]

NdT : ce document est une traduction du didacticiel A Better Way to Check for Existing Items Before Spawning.

Un meilleur moyen de vérifier l'existence d'objets avant de les créer

Beaucoup d'entre vous qui ont suivi mon tout premier didacticiel pour créer un objet ont fait face un problème. Quand le script vérifie si vous avez déjà l'objet avant d'en créer un nouveau, il ne cherche essentiellement que dans vos sacs. Si l'objet n'est pas dans vos sacs, il ne peut pas le trouver alors il en crée un nouveau.

Dans ce petit didacticiel, nous verrons un meilleur moyen de vérifier l'existence de l'objet avant d'en créer un nouveau. Une méthode qui devrait trouver l'objet avec précision même s'il n'est plus dans vos sacs.


CountItemsByTag

Code : Tout sélectionner

int CountItemsByTag ( object oPossessor,
string sTag
)

Compte les objets portant le tag indiqué dans le récipient ou l'inventaire indiqué.

Paramètres :
oPossessor - Le récipient (placeable) ou la créature dont il faut compter les objets
sTag - Le tag des objets à compter.

Dans le didacticiel d'origine, nous utilisions la fonction CountItemsByTag pour voir si le joueur possédait déjà l'objet. Pour l'essentiel, cette fonction compte combien d'objets portant le tag indiqué se trouvent actuellement dans l'inventaire des éléments (object) spécifiés. Si ce nombre valait 0, nous considérions que le joueur n'avait pas l'objet et nous en créions un nouveau.

Cela fonctionne, mais il y a plusieurs inconvénients. Cela ne vérifie que les sacs du joueur. Si le joueur avait l'objet mais qu'il l'avait placé ailleurs, le compte reviendrait quand même à 0, alors nous finirions par en créer un nouveau. Ceci se produit couramment quand vous équipez de l'objet le joueur ou un membre du groupe, ou si vous le mettez dans votre coffre de stockage.

Le problème avec CountItemsByTag est essentiellement sa portée limitée. Elle ne cherche qu'à un seul endroit. Il nous faut quelque chose qui ait une portée plus étendue, qui cherche l'objet à davantage d'endroits.


GetObjectByTag

Code : Tout sélectionner

object GetObjectByTag ( string sTag,
int nNth = 0
)

Retourne le nième [NdT : spécifié par nNth] objet portant le tag approprié, ou OBJECT_INVALID en cas d'échec

Paramètres :
sTag - Le tag de référence servant à trouver l'objet
nNth - S'il y a un plusieurs objets portant le même tag, obtenir le nième objet indiqué.

Retour :
l'objet demandé ou OBJECT_INVALID en cas d'échec

GetObjectByTag est une fonction plus générique relative aux objets et correspond exactement à ce dont nous avons besoin. La fonction possède une portée bien plus large et retournera n'importe quel objet, où qu'il soit, qui correspond au tag indiqué dès lors que l'objet est actuellement chargé par le jeu.

Néanmoins vous remarquerez que cette fonction opère un peu différemment. Au lieu de nous retourner le nombre d'objets portant le tag indiqué, elle retourne à la place le véritable objet en question. Par défaut, elle retournera le premier qu'elle trouve. Pour que cela fasse ce dont nous avons besoin, il nous faut la combiner avec une autre fonction.


IsObjectValid

Code : Tout sélectionner

int IsObjectValid ( object oObject )

Retourne TRUE si l'objet oObject existe et constitue un objet valide, FALSE autrement.

Paramètres :
oObject - L'objet qui est peut-être valide.

Retour :
Retourne TRUE si l'objet existe et est valide, FALSE autrement.

Remarques :
Cette fonction est très similaire à une vérification que l'objet n'est pas égal à la constante OBJECT_INVALID, mais il s'agit d'un contrôle plus robuste. Un objet qui a été passé en paramètre dans un appel de fonction à retardement ou qui a été stocké en tant qu'un objet local ne sera pas égal à la constante OBJECT_INVALID si l'objet a été détruit après avoir été passé ou stocké. Cependant cette fonction retournera FALSE dans ces circonstances. Il n'y a aucun cas où un objet puisse être égal à la constante OBJECT_INVALID et où cette fonction retourne TRUE.

Cette fonction est très simple et fait exactement ce que son nom laisse à penser. Elle nous indique si l'objet spécifié est un objet valide ou non.

Alors comment utiliserions-nous tout ceci pour vérifier l'existence d'un objet avant d'un créer un nouveau ? En pseudo-code :

Code : Tout sélectionner

Sword = GetObjectByTag("mon_tag_d_epee")
If IsObjectValid(Epee) Then
     Ne rien faire : nous avons déjà l'objet
Else
     Créer une nouvelle épée

Voici comment ceci pourrait s'intégrer dans notre script d'origine :

Code : Tout sélectionner

// Tous les événements du module
#include "utility_h"
#include "wrappers_h"
#include "events_h"
void main()
{
    event ev   = GetCurrentEvent();
    int nEvent = GetEventType(ev);
    Log_Events("", ev);
    switch (nEvent)
    {
        case EVENT_TYPE_MODULE_LOAD:
        {
            // obtenir l'objet qui contient le joueur
            object oPlayer = GetHero();

            object oBow = GetObjectByTag("aga_bowofathena");
            if (!IsObjectValid(oBow))
                UT_AddItemToInventory(R"aga_bowofathena.uti",1);
            break;
        }
        default:
        {
            break;
        }
    }
}

[NdT : Attention à la distinction entre la notion d'objet dans le jeu (épée, lettre, ...) et la notion d'objet en programmation, qui est un terme générique pour désigner un élément manipulé par les fonctions de scripts et que l'on peut considérer comme une généralisation du terme de variable. En anglais, le terme "item" désigne l'objet réel (on pourrait aussi dire l'article, comme dans un magasin) et le terme "object" désigne la notion de programmation.
Ici la fonction GetObjectByTag permet de récupérer l'objet informatique associé à l'objet arc d'Athena afin de pouvoir utiliser l'objet de programmation pour l'opération suivante, vérifier sa validité.]


Remerciements

Ce didacticiel est basé sur un écrit d'Attono sur DAMods.

[NdT : les traductions des descriptions sont basées sur celle du didacticiel original, écrit alors que seule la version 1.00 de la trousse à outils. Ces descriptions peuvent évoluer au fil du temps. Il vaut mieux toujours se référer à la description fournie dans la trousse à outils, qui est la plus à jour, en principe.]