Module Jeu de Plateforme

######## MODULE DE PLATEFORME - VERSION 1.0beta #############
####### Auteur : Kitai ############
####   #####
#   Développé sous AGS 3.2.1    #


Plan de ce fichier :
 1. Description
 2. Liste des variables et fonctions publiques du module
 3. Changements apportés depuis la version précédente
 4. Manuel d'utilisation
 # Importation et installation minimale
  du module
 # Utilisation  pour  certaines  pièces
  uniquement
 # Utilisation pour certains personnages
  uniquement
 # Personnalisation des paramètres
 # Solidité des personnages et des objets
 # Gestion des rencontres des personnages
  et des objets


1. Description :

 Ce module est un moteur de plateforme. Il a été développé
 pour  permettre  de   réaliser  simplement  des  jeux  de
 plateforme 2D basiques avec Adventure Game Studio.
 Le principe est simple : les "Regions" d'AGS représentent
 les sols/murs/plafond (parties solides) de la pièce et le
 moteur  se charge de placer  et  déplacer automatiquement
 les personnages.
 

2. Liste des variables et fonctions publiques du module :

 . struct Plateforme
 . struct Plateforme_Regions
 . Plateforme PF_Persos[]
 . Plateforme_Regions PF_Regions[16]
 . function PF_GetNumber(Character* this)
 . enum PF_Axe
 . #define PF_PROP_PIECES
 . #define PF_PROP_PERSOS
 . #define PF_NB_PERSOS
 . #define PF_ACCELERATION
 . #define PF_RESISTANCE_X
 . #define PF_VITESSE_LIMITE_X
 . #define PF_VITESSE_LIMITE_Y
 . #define PF_FORCE_GRAVITE
 . #define PF_FORCE_SAUT
 . #define PF_TOUCHE_GAUCHE
 . #define PF_TOUCHE_DROITE
 . #define PF_TOUCHE_SAUT


3. Changements apportés depuis la version précédente (1.0alpha)
 
 . Ajout   d'une   fonction   Plateforme::Marche  pour  que
  l'utilisateur puisse gérer les PNJs
 . Ajout  des  propriétés blockupward/downward/lefttoright/
  righttoleft à Plateforme_Regions
 . Révision  de  la fonction Plateforme::Scrute > évite les
  bugs de placemnt
 . Révision de la gestion de l'inclinaison
 . Révision  de  la gestion de levée de pied : le nombre de
  pixels  est  désormais relatif à la hauteur définie pour
  le personnage



4. Manuel d'utilisation

 # Importation et installation minimale du module :

 Pour importer le module, faites un clic droit sur l'onglet
 "Scripts"  d'AGS   et  choisissez  "Import script..." puis
 sélectionnez le fichier "Plateforme_1.0_beta.scm".
 Ensuite,  vous devez déclarer le nombre de personnages qui
 seront concernés  par le moteur  en modifiant le nombre de
 indiqué dans la ligne "#define PF_NB_PERSOS 1".
 Si vous voulez rendre les choses simples, donnez la valeur
 correspondant au  nombre total de  personnages  dans votre
 projet.


 # Utilisation pour certaines pièces uniquement :

 Une fois le module  importé,  il  s'applique par défaut  à
 toutes les pièces de votre jeu.  Si vous  voulez  qu'il ne
 s'applique  qu'à  certaines  pièces  en particulier,  vous
 devez  créer  une  propriété  booléenne  "Plateforme"  qui
 concerne les pièces.
 Pour cela,  éditez  une  pièce  et allez dans ses réglages
 (par défaut en bas à droite de l'éditeur)  et  cliquez sur
 la ligne "Properties". La fenêtre des propriétés s'ouvre.
 Cliquez  sur  "Edit schema..."  pour  ouvrir  une nouvelle
 fenêtre  dans  laquelle  vous effectuez un clic droit pour
 choisir "Add new property...".  Mettez  alors "Plateforme"
 dans  le  champ  "Name"  et  choisissez le type "Boolean".
 Donnez 0 comme "Default value".
 Fermez  les  fenêtres  de  façon  à revenir sur la fenêtre
 principale  d'édition  de  la  pièce  puis  recliquez  sur
 "Properties". La  nouvelle propriété  apparaît. Choisissez
 la valeur "True"  si  vous voulez que le module s'applique
 pour cette pièce, laissez "False" sinon.
 Cliquez  ensuite  sur   "Plateforme.ash"   sous   l'onglet
 "Scripts" et  mettez  "true"  à la place de  "false"  à la
 ligne 6 : "#define PF_PROP_PIECES false".

 
 # Utilisation pour certains personnages uniquement :

 Editez  un  personnage  de votre jeu (n'importe lequel) et
 allez  dans  ses  réglages (par  défaut en bas à droite de
 l'éditeur)  et  cliquez  sur  la  ligne  "Properties".  La
 fenêtre des propriétés s'ouvre.
 Cliquez  sur  "Edit schema..."  pour  ouvrir  une nouvelle
 fenêtre  dans  laquelle  vous effectuez un clic droit pour
 choisir "Add new property...".  Mettez  alors "Plateforme"
 dans  le  champ  "Name"  et  choisissez le type "Boolean".
 Donnez 0 comme "Default value".
 Fermez  les  fenêtres  de  façon  à revenir sur la fenêtre
 principale  d'édition  du  personnage  puis  recliquez sur
 "Properties".  La nouvelle propriété apparaît.  Choisissez
 la valeur  "True"  si vous voulez que le module s'applique
 pour ce personnage, laissez "False" sinon.
 Cliquez  ensuite  sur   "Plateforme.ash"   sous   l'onglet
 "Scripts" et  mettez  "true"  à la place de  "false"  à la
 ligne 10 : "#define PF_PROP_PERSOS false".


 # Personnalisation des paramètres :
 
 Une  liste  de  valeurs  par défaut est définie en haut du
 fichier  d'en-tête  "Plateforme.ash".  Selon la valeur que
 vous  leur  donnerez,  le  moteur  se  comportera de façon
 sensiblement différente.
 Pour donner des valeurs spécifiques à certains personnages
 vous  pouvez  placer du code dans la fonction "game_start"
 de  votre  script global ou dans les fonctions associées à
 l'événement "Player enters room (before fade-in)".
 Voici  un  exemple de code que vous pouvez placer dans ces
 fonctions :
 
 // On récupère l'ID de référencement de cSuperman
 int id = cSuperman.PF_GetNumber();
 // Si le personnage est bien référencé (sûreté)
 if (id > -1)
 // La gravité ne l'affecte pas
 PF_Persos[id].gravite = 0.0;


 Vous  pouvez  également personnaliser les régions grâce au
 tableau PF_Regions. Vous pouvez définir pour chaque région
 si elle doit freiner le personnage  (propriété "solid") et
 quel est son taux de résistance aux déplacements.
 Par  défaut  toutes  les régions exceptée la région 0 sont
 solides et ont un taux de résistance de PF_RESISTANCE_X.
 Voici un exemple de code :
 
 // La région 2 ne fera pas obstacle au personnage
 PF_Regions[region[2].ID].solid = false;
 // La région 3 fera beaucoup glisser (givre)
 PF_Regions[region[3].ID].resistance = 0.01;


 # Solidité des personnages et des objets :
 
 La propriété  "Solid"  qu'AGS attribue aux personnages et
 aux  objets  est  utilisée  par le moteur plateforme pour
 déterminer  si  le  personnage/objet représente ou non un
 obstacle sur le chemin du personnage.
 Pour rendre un objet ou un personnage "traversable", vous
 pouvez faire comme suit :

 oNuage.Solid = false;
 cOmbre.Solid = false;

 
 # Gestion des rencontres personnages/objets

 Vous trouverez  dans le corps du module "Plateforme.asc"
 une  fonction   "Touche_Personnage"   et   une  fonction
 "Touche_Objet",  qui  sont  appelées  chaque  fois qu'un
 personnage en  rencontre  un  autre  ou touche un objet.
 Vous  pouvez y placer du code pour gérer ce qui se passe
 lorsqu'un tel événement survient.
 Cette fonction est locale au module, vous ne pouvez donc
 pas  y  utiliser  de  variable  d'objet comme "oSeau" ou
 autre, mais vous pouvez utiliser le tableau object[].
 Une  astuce  pour gérer ces rencontres dans le script de
 la pièce consiste à utiliser des variables globales dont
 vous  modifiez  la valeur dans la fonction "Touche_*" du
 module et que  vous vérifiez dans la fonction Rep_Exec()
 de la pièce.
 En voici un exemple succinct :

 // Dans "Plateforme.asc" :
 bool Plateforme::Touche_Objet(Object* objet) {
  
 // On change la variable globale
 // qu'on a définie par défaut à -1
 Objet_Touche = objet.ID;

 // Suite du code...

 // Dans le script de la pièce
 function room_RepExec() {
 
 // Si l'objet touché est le seau
 if (Objet_Touche == oSeau.ID)

 // S'il n'est pas encore tombé
 if (oSeau.View != SEAU_TOMBE)
 {
  player.Say("Oups !");
  oSeau.SetView(SEAU_TOMBE);
 }

 // On réinitialise la variable à chaque
 // cycle
 Objet_Touche = -1;

 }