[Tuto]Une fonction personnalisée : FaceDirection

Niveau : Débutant
Prérequis : Avoir lu le tutoriel officiel sur le script (vous le trouverez dans l'aide incluse à AGS, ou ici en français).

Objectif : Coder une fonction FaceDirection. Apprendre à faire une fonction personnalisée.

Connaissez-vous la fonction FaceLocation ? Elle permet de changer l'orientation d'un personnage, pour qu'il fasse face aux coordonnées rentrées. En pratique je la trouve un peu pénible à utiliser car elle requiert de rentrer des coordonnées absolues. Je vous propose de coder une petite fonction nommée FaceDirection, qui changera l'orientation de nos personnages en prenant comme paramètre une direction :

Code:

cEgo.FaceDirection(eRight) //cEgo, regarde donc à droite s'il te plaît.

Théorie des fonctions. (facultatif)
Vous êtes novice en programmation ? Le script AGS est votre premier langage ? Ce chapitre est fait pour vous !
Vous souvenez-vous de vos cours de Math ? Vous y avez peut-être vu des fonctions mathématiques sous la forme :

Les Mathématiques a écrit:

y = f(x)

Ici notre fonction nommée f prend pour paramètre x et le transforme en y. Les fonctions informatiques ont le même fonctionnement. Elles prennent des paramètres d'entrée, agissent en boîte noire et retournent un résultat. Les paramètres et résultats retournés peuvent être de diverses natures et de nombre variable. Il existe même de nombreux exemples de fonctions informatiques qui ne demandent aucun paramètre (!) ou qui ne retournent rien (!).

La pratique !
Notre fonction FaceDirection prendra trois paramètres de natures différentes : le personnage qui changera de direction (cEgo, par exemple), la direction que ce personnage devra prendre (haut up, bas down, gauche left, droite right), et le caractère bloquant ou non de la fonction. Problème, les directions en tant que variables ne sont pas implémentées nativement dans AGS. Pas de soucis, on va l'implémenter nous même !
Pour cela on utilisera un enum, terme bien curieux, diminutif d’énumération, dont vous pourrez découvrir tous les secrets ici.
Où déclare-t-on un enum, et comment ?
Comme on voudra y accéder de partout, le plus simple est de le déclarer dans un en-tête de script (header, les fichiers de scripts se finissant par .ash), donc soit dans le GlobalScript.ash, soit (et c'est mieux) dans un fichier script que vous aurez créé (clic droit sur Scripts -> New Script) et que vous aurez appelé FontionsDiverses (ou MiscFunctions) par exemple.
Dans ce header, donc, nous pouvons déclarer notre enum :

Code:

enum SpecifyDirection { //notre enum s'appelle SpecifyDirection
  eUp, //chaque élément commence par e, pour enum
  eLeft, //une virgule à la fin, sauf pour le dernier
  eRight,
  eDown,
  eNone // None, ou aucune direction en français, nous y reviendrons.
}; //fin de l'enum, n'oubliez pas le ;

Voilà, nous pouvons maintenant nous attaquer à la fonction même. Nous allons la définir dans le corps de notre script (.asc), comme ceci :

Code:

function FaceDirection(this Character*, SpecifyDirection Dir, BlockingStyle BStyle)
{

}

En français, avec function, nous disons à AGS que nous allons déclarer une fonction. Elle s’appellera FaceDirection, s'appliquera à un personnage (Character*), identifié ci-après par this (ça, en anglais), prendra comme paramètre un premier enum de type SpecifyDriection appelé ci-après Dir et un deuxième enum (prédéfini dans AGS cette fois) de type BlockingStyle appelé ci-après BStyle.
Il est temps de la remplir !

Code:

function FaceDirection(this Character*, SpecifyDirection Dir, BlockingStyle BStyle)
{
  if(Dir == eUp) this.FaceLocation(this.x, this.y-1, BStyle); //Consultez l'aide pour FaceLocation pour mieux comprendre ce script
  else if(Dir == eLeft) this.FaceLocation(this.x-1, this.y, BStyle); //En gros, lorsque la direction c'est gauche, on demande à this de regarder à gauche.
  else if(Dir == eRight) this.FaceLocation(this.x+1, this.y, BStyle);
  else if(Dir == eDown) this.FaceLocation(this.x, this.y+1, BStyle);
}

Cette fonction sera bloquante ou non en fonction du BlockingStyle.
Ainsi définie, notre fonction n'est accessible que localement (dans ce fichier script), il nous faut l'importer dans tous les autres fichiers scripts du jeu pour pouvoir y accéder partout. Cela se fait très facilement via la commande import dans l'entête du script (vous savez, le header ou .ash) où notre fonction a été définie, par exemple juste sous notre déclaration d'enum :

Code:

enum SpecifyDirection {
  eUp,
  eLeft,
  eRight,
  eDown,
  eNone
};
import function FaceDirection(this Character*, SpecifyDirection , BlockingStyle);

Profitons-en pour définir des valeurs par défaut, vu que c'est là qu'on peut le faire :

Code:

enum SpecifyDirection {
  eUp,
  eLeft,
  eRight,
  eDown,
  eNone
};
import function FaceDirection(this Character*, SpecifyDirection = eNone, BlockingStyle = eBlock);

Et voilà ! Maintenant vous pouvez utiliser cette fonction n'importe où, y compris et surtout dans chaque script de room, par exemple :

Code:

function hHotspot1_Interact()
{
  player.FaceDirection(eUp); //Notez qu'il n'y a pas besoin de spécifier le BlockingStyle qui sera par défaut eBlock
  player.Say("This hostpot made me look up.");
}

Pour aller plus loin

Lecteur bien informé a écrit:

Mais dis-moi, n'y a-t-il pas un mot pour déclarer une fonction qui ne retourne rien ? Genre void ?

Oui, tout à fait. En fait, function déclare une fonction qui renvoie un int, mais une absence de retour est tolérée quand même. On peut alternativement utiliser void (vaccant, en anglais) pour déclarer nos fonctions qui ne renvoient rien (ma source, pour les incrédules qui ne voient cette info mentionnée nul part dans le manuel). Dont acte, dans le header :

Code:

enum SpecifyDirection {
  eUp,
  eLeft,
  eRight,
  eDown,
  eNone
};
import void FaceDirection(this Character*, SpecifyDirection = eNone, BlockingStyle = eBlock);

Et dans le corps du script :

Code:

void FaceDirection(this Character*, SpecifyDirection Dir, BlockingStyle BStyle)
{
  if(Dir == eUp) this.FaceLocation(this.x, this.y-1, BStyle);
  else if(Dir == eLeft) this.FaceLocation(this.x-1, this.y, BStyle);
  else if(Dir == eRight) this.FaceLocation(this.x+1, this.y, BStyle);
  else if(Dir == eDown) this.FaceLocation(this.x, this.y+1, BStyle);
}

baloulef a écrit:

Oui mais moi mon personnage il a huit directions, nananinananére !

Rien de plus simple, dans le header :

Code:

enum SpecifyDirection {
  eUp,
  eLeft,
  eRight,
  eDown,
  eUpRight,
  eUpLeft,
  eDownRight,
  eDownLeft,
  eNone
};

Et dans le corps du script :

Code:

void FaceDirection(this Character*, SpecifyDirection Dir, BlockingStyle BStyle)
{
  if(Dir == eUp) this.FaceLocation(this.x, this.y-1, BStyle); //Consultez l'aide pour FaceLocation pour mieux comprendre ce script
  else if(Dir == eLeft) this.FaceLocation(this.x-1, this.y, BStyle); //En gros, lorsque la direction c'est gauche, on demande à this de regarder à gauche.
  else if(Dir == eRight) this.FaceLocation(this.x+1, this.y, BStyle);
  else if(Dir == eDown) this.FaceLocation(this.x, this.y+1, BStyle);
  else if(Dir == eUpRight) this.FaceLocation(this.x+1, this.y-1, BStyle);
  else if(Dir == eUpLeft) this.FaceLocation(this.x-1, this.y-1, BStyle);
  else if(Dir == eDownRight) this.FaceLocation(this.x+1, this.y+1, BStyle);
  else if(Dir == eDownLeft) this.FaceLocation(this.x-1, this.y+1, BStyle);
}

Mitai a écrit:

Moi j'aurais mis des if partout pour vérifier des trucs.

Oui, on peut rajouter des if si on veut.

Code:

void FaceDirection(this Character*, SpecifyDirection Dir, BlockingStyle BStyle)
{
  if(Dir == eUp) {
    if (this.Loop !=3) this.FaceLocation(this.x, this.y-1, BStyle);
  }
  else if(Dir == eLeft) {
    if (this.Loop !=1) this.FaceLocation(this.x-1, this.y, BStyle);
  }
  else if(Dir == eRight) {
    if (this.Loop !=2) this.FaceLocation(this.x+1, this.y, BStyle);
  }
  else if(Dir == eDown) {
    if (this.Loop !=0) this.FaceLocation(this.x, this.y+1, BStyle);
  }
}

Lecteur dubitatif a écrit:

Hé mais dis-donc là, le eNone, y sert à rien !

Pour l'instant oui, cEgo.FaceDirection(eNone) n'aura strictement aucun effet. Mais on peut imaginer plein de situations où c'est utile ! Par exemple une petit fonction Utilise qui lance une animation d'utilisation sur le personnage en question :

Code:

void Utilise(this Character*, SpecifyDirection Dir)
{
  int view;
  if (this == cEgo) {
      view = 10; //La view Utilise de Ego
  }
  else if (this == cRoger) {
      view = 15; //La view Utilise de Roger
  }
  else {
      return;
  }
  this.FaceDirection(Dir, eBlock);
  this.LockView(view);
  this.Animate(this.Loop, 5, eOnce, eBlock);
  this.UnlockView();
  }
}

Et dans le header :

Code:

import void Utilise(this Character*, SpecifyDirection = eNone);

On comprend mieux l’intérêt de eNone : notre fonction Utilise peut s'utiliser avec ou sans imposer une direction particulière :

Code:

cEgo.Utilise(eUp); //Joue l'animation Utilise de Ego dans la direction vers le haut.
cRoger.Utilise(); //Joue l'animation Utilise de Roger en utilisant sa direction actuelle.

lecteur étourdi a écrit:

J'ai oublié comment fonctionnait cette fonction, l'autocomplétion ne pourrait-elle pas me le rappeler ?

Bien sûr !

Code:

enum SpecifyDirection {
  eUp,
  eLeft,
  eRight,
  eDown,
  eNone
};
/// Force le personnage à regarder dans la direction spécifiée.
import void FaceDirection(this Character*, SpecifyDirection = eNone, BlockingStyle = eBlock);

Postface
Ce tutoriel est bien sur assez redondant avec 1) le manuel AGS et 2) le tutoriel de Kitai, mais il y avait une demande... La fonction FaceDirection est implémentée dans certains templates ou éditions spéciales d'AGS (la Drakonian edition, entre autres). Je me suis très fortement inspiré de ce post en particulier. Merci de m'avoir lu ! Comme c'est mon premier tuto, n'hésitez pas à me faire des remarques sur la mise en forme, le style ou le fond.

c'est super, ça !
Je trouve le tuto clair, bien construit et accessible.

J'ai juste un problème avec le eNone, mais avant ça, une petite remarque :
Après une citation, mieux vaut sauter une ligne, car ça gêne un peu pour la lecture.
[Parenthèse ON]D'ailleurs, je trouve qu'un cadre autour d'une citation apporterait une meilleure lisibilité et compréhension qu'il s'agit d'une citation.[Parenthèse OFF]



En ce qui concerne mon incompréhension concernant le eNone.
Je ne comprends pas la ligne this.FaceLocation(Dir, eBlock);.

Déjà, est-ce que tu ne voulais pas plutôt écrire this.FaceDirection(Dir, eBlock); ?
Et si oui, que mets-tu dans le else quand Dir == eNone ?

Ensuite pour this.LockView(VJUTILISE);, n'est-ce pas plutôt this.LockView(view); ?

De même, que viens faire view dans this.Animate(this.Loop, view, eOnce, eBlock); alors que ce devrait être le délai d'indiquer.
Outre cela, je comprends que cette instruction a pour effet de dire : "anime le personnage pour la view lockée juste avant, pour la loop actuellement active du personnage". Mais dans ce cas, quel est l'intérêt d'avoir un FaceDirection avec eNone juste avant ?


Avec mes corrections, il me semble que ton code, vers la fin, est :

Code:

  this.FaceDirection(Dir, eBlock);
  this.LockView(view);
  this.Animate(this.Loop, 10, eOnce, eBlock);
  this.UnlockView();

Et je ne comprends pas à quoi sert la première instruction si Dir vaut eNone ?

Super boulot pour ton tuto Billbis !

Tout d'abord j'avais bien vu dans agsdefns.sh qu'on pouvait renseigner des paramètres uniquement avec leur type (aucun nom de variable) lors d'une importation, mais je ne sais pas dans quelle mesure c'est supporté (ça marche aussi avec les types natifs -- int, float, etc. ?) et dans quelle mesure ça peut perturber les gens pour la présentation.

Ensuite je partage la réaction de Skippy face à eNone, il m'a fallu un petit temps pour comprendre.
En fait Skippy, tu vois que eNone n'apparaît nulle part dans les conditionnels de la définition de FaceDirection : passer eNone comme paramètre aura donc pour effet... de n'avoir aucun effet !
Dès lors, la fonction Utilise peut être utilisée de deux manières : soit on exige que le personnage se tourne dans une certaine direction avant d'utiliser, soit on ne passe aucune direction et le personnage restera dans la direction dans laquelle il se trouve pour exécuter l'utilisation.
Je pense en effet qu'il faut expliquer un peu plus cette partie.

Sinon bien vu pour les quelques (peu nombreuses) coquilles Skippy.

Billbis, veux-tu que je corrige les quelques (à peine plus nombreuses) fautes d'orthographe ?

Hum ça m'a l'air d'être un très bon travail. Tu me fais penser qu'il faudrait que j'ajoute les tutos officiels au sommaire. En attendant, j'ajoute celui-ci.

EDIT : J'adore tes citations

Merci pour vos relectures attentives, Skippy, Kitai et valoulef !
Désolé de t'avoir embrouillé, Skippy, tu as parfaitement raison sur la fonction Utilise. J'ai corrigé. Je suis définitivement incapable de transférer un code de mon projet vers un truc plus général sans introduire pleins de coquilles.

Kitai a parfaitement expliqué l’intérêt du eNone dans ce contexte. J'ai essayer de clarifier un poil le texte.

Kitai a écrit:

Billbis, veux-tu que je corrige les quelques (à peine plus nombreuses) fautes d'orthographe ?

Avec plaisir ! Je me suis relut, mais l'orthographe n'est pas mon fort, et la relecture non plus. Je suis trop étourdit.

Je tiens à rétablir la vérité, je ne peux pas être intégré dans les "relectures attentives"

Je n'ai pour l'instant que survolé le post, mais ça m'a l'air très bien fait. Ah et je tiens à ajouter même si c'est HS, que les nouvelles fenêtres de code, ajoutées j'imagine par Kitai, sont vraiment géniales, bien plus lisibles, et ça rend les tutos et différentes explications encore plus propres visuellement.

Kitai a écrit:

Tout d'abord j'avais bien vu dans agsdefns.sh qu'on pouvait renseigner des paramètres uniquement avec leur type (aucun nom de variable) lors d'une importation, mais je ne sais pas dans quelle mesure c'est supporté (ça marche aussi avec les types natifs -- int, float, etc. ?) et dans quelle mesure ça peut perturber les gens pour la présentation.

Tu parles de cette ligne ?

Code:

import function FaceDirection(this Character*, SpecifyDirection , BlockingStyle);

a changer en ça ?

Code:

import function FaceDirection(this Character*, SpecifyDirection Dir, BlockingStyle BStyle);

En effet, je ne sais pas quelle solution est la mieux. Pour des enums, c'est assez explicite sans le nom de variable, mais pour des int, c'est vrai que le nom de variable aide beaucoup.
En parlant de l'import, y a t'il une différence entre importer la fonction dans l'en-tête du script (celui où la fonction est définie) ou l'importer dans l'en-tête du GlobalScript ? Les deux solutions semblent fonctionner.

Billbis a écrit:

Tu parles de cette ligne ?

Code:

import function FaceDirection(this Character*, SpecifyDirection , BlockingStyle);

a changer en ça ?

Code:

import function FaceDirection(this Character*, SpecifyDirection Dir, BlockingStyle BStyle);

En effet, je ne sais pas quelle solution est la mieux. Pour des enums, c'est assez explicite sans le nom de variable, mais pour des int, c'est vrai que le nom de variable aide beaucoup.

Oui, c'est bien de ça que je parle.
En fait je trouve ça tout simplement étonnant qu'on puisse omettre le nom du paramètre dans la déclaration d'importation. Tu as essayé d'importer un int sans mettre le nom de paramètre ? Je me demande si ça passe aussi.

Billbis a écrit:

En parlant de l'import, y a t'il une différence entre importer la fonction dans l'en-tête du script (celui où la fonction est définie) ou l'importer dans l'en-tête du GlobalScript ? Les deux solutions semblent fonctionner.

Je n'ai aucune idée, et à vrai dire si tu ne m'avais pas dit que ça fonctionnait je n'aurais pas juré que placer l'importation dans l'entête du Global Script marchait. D'ailleurs, d'après ce que j'ai écrit ici, ce que tu importes dans l'entête du Global Script ne devrait être accessible qu'à celui-ci et aux scripts des pièces, mais pas aux modules qui se trouvent au-dessus du Global Script. Si je ne me suis pas trompé en écrivant ça, ça fait donc cette première différence.
À part ça, je pense qu'il n'y a pas d'autre différence, mais ce n'est qu'une "intuition".

Kitai a écrit:

En fait je trouve ça tout simplement étonnant qu'on puisse omettre le nom du paramètre dans la déclaration d'importation. Tu as essayé d'importer un int sans mettre le nom de paramètre ? Je me demande si ça passe aussi.

De façon tout à fait amusante, la plupart des exemples d'imort dans l'aide d'AGS se font sans déclarer le nom de la variabble / paramêtre, juste son type. Par exemple ici, ou là. Des exemples contraires existent aussi.

Kitai a écrit:

d'après ce que j'ai écrit ici, ce que tu importes dans l'entête du Global Script ne devrait être accessible qu'à celui-ci et aux scripts des pièces, mais pas aux modules qui se trouvent au-dessus du Global Script. Si je ne me suis pas trompé en écrivant ça, ça fait donc cette première différence.
À part ça, je pense qu'il n'y a pas d'autre différence, mais ce n'est qu'une "intuition".

Ton intuition me semble logique. Merci pour cette précision !

Super, ça marche ! Voilà un tuto qui simplifiera la vie de nombreux utilisateurs d'AGS comme moi.

Mais peut-être serait-il bien que Chris Jones implémente cette fonction dans une future version d'AGS, vu son caractère "basique" ?

Edit : Ah ouais mais non, ça rendrait ce magnifique tuto obsolète

valoulef a écrit:

Mais peut-être serait-il bien que Chris Jones implémente cette fonction dans une future version d'AGS, vu son caractère "basique" ?

Chris Jones a arrêté le développement d'AGS depuis quelques années.
Mais le développement continu grâce à de généreux contributeurs !
Cela dit, la fonction est tellement simple a coder en AGS script qu'elle a bien plus sa place dans un template -et éventuellement dans le template par défaut- que codé en dur dans AGS...

Billbis a écrit:

Chris Jones a arrêté le développement d'AGS depuis quelques années.

Ah, je n'avais pas noté ça C'est regrettable, il y avait tant à faire encore (j'imagine qu'il est dès lors impossible d'envisager une version 4 un jour ?).

valoulef a écrit:

j'imagine qu'il est dès lors impossible d'envisager une version 4 un jour ?

On aurai pu le craindre, mais non ! Comme je l'ai dit, une communauté de codeurs acharnés continue a développer AGS. Outre les port Linux / PSP / Android / iOS, ils sont en train de finaliser AGS 3.3.0 (6ém béta déjà !) et de travailler sur AGS 3.4.0 (au menu, plein de limites supprimées / repoussées, et la possibilité de modifier la valeur de ses custom properties lors du jeu !  

Une petite question, comme ça (oui parce que au cas où vous ne l'auriez pas remarqué, j'aime bien poser des questions) : On ne peut pas créer une fonction avec un argument optionnel, comme c'est le cas pour certaines fonctions implémentées dans AGS ?

Oui tout à fait, cela ce fait au niveau du header du script, dans l'import de la fonction.
Dans le premier post, un peu plus haut :

Billbis a écrit:

Profitons-en pour définir des valeurs par défaut, vu que c'est là qu'on peut le faire :

 
En fait, les arguments dont tu précises une valeur par défaut deviennent optionnel.
C'est marrant, mais je ne retrouve plus où j'ai appris cette information... ?

Billbis a écrit:

C'est marrant, mais je ne retrouve plus où j'ai appris cette information... ?

Ici ?

Au passage, la déclaration d'importation n'a pas obligatoirement besoin de se trouver dans l'en-tête du script (mais bien sûr si on ne l'y met pas, la fonction ne sera pas accessible depuis les autres scripts). Ma source.

Kitai a écrit:

Ici ?

Oui, tout à fait. Merci.

Mais pour reprendre l'exemple auquel vous faites allusion, si la valeur par défaut du paramètre "choses" dépend du paramètre "trucs", il faut donc créer une variable définie en fonction d'une condition, c'est possible ça ? Où faudrait-il donc définir cette variable ?

Code:

//Header
enum PereDeBillbisEst {
    eVivant,
    eMort
};

enum BillbisEst {
    eRoi,
    ePrince,
    eDefault
};

import function Proclamer( BillbisEst BE = eDefault, PereDeBillbisEst PDBE  =eVivant);

//Script
function Proclamer( BillbisEst BE, PereDeBillbisEst PDBE) {
  if (BE ==  eDefault) {
    if (PDBE == eVivant) {
      player.Say("Billbis est Prince !");
    } else {
      player.Say("Billbis est le Roi du Monde !");
    }
  } else if (BE == ePrince) {
    player.Say("Billbis est Prince !");
  } else {
    player.Say("Billbis est le Roi du Monde !");
  }
}

  
Tu peux bien sur utiliser des int à la place des enums, mais le principe est là.

Ok donc si je comprends bien, le paramètre par défaut ne peut pas varier en fonction d'un autre, mais il faut plutôt ruser en faisant en sorte que la fonction se comporte d'une telle manière si on ne rentre aucun paramètre à cet endroit. Je sais à peu près comment je ferai.

Merci.

L'exemple suivant me paraît plus proche de ce que j'ai compris de ta question valoulef :

Code:

import bool Yatildesborgnes(int individus = 10, int yeux = -1);

function Yatildesborgnes(int individus, int yeux) {
  // Si YEUX < 0, on n'a passé aucune valeur : on définit donc à 2 * INDIVIDUS
  if (yeux < 0) yeux = individus * 2;
  // Cette condition s'exécutera qu'on ait passé une valeur pour YEUX ou non
  if (individus > 0 && yeux == 2*individus) return true;
  else return false;
}

Donc en effet, il faut ruser.

OMG le gros déterrage de topic ,
Salut Billbis je voudrais utilisé la premiere fonctions que tu as faite mais quand je l'implemente
j'obtient un message d'erreur : "Parameter type does not match prototype"

Quelle version d'AGS utilises-tu ? Parce que je crois que depuis la 3.4, la fonction FaceDirection est intégrée nativement, donc il ne faut pas la redéfinir.

Ha bah justement je suis sous la 3.6 du coup sa change quoi ?

Je crois que la 3.6 n'existe pas, tu dois parler de la 3.4.0.6 (encore appelée "3.4 alpha 6"). Ça change que tu n'as pas besoin de faire tout ce qu'a décrit Billbis, la commande FaceDirection est déjà implémentée. Tu peux d'ores et déjà l'utiliser sans avoir à la définir toi-même.