Zeste de Code – Guide participants – Snake
+Ce document est une documentation complète des fonctions de la bibliothèque de l'atelier Zeste de Code ; n'hésitez pas à vous référer à lui afin de rechercher une fonctionnalité. Si quelque chose ne vous semble pas clair, vous pouvez toujours appeler un animateur, qui viendra alors vous aider.
+Les bases de Python
+Cette partie est un rappel des notions abordées ci-avant, dans le cas où tu aurais besoin de revoir les bases du langage, pendant l'atelier ou chez toi.
+Quelques calculs simples
+Pour rappel, le langage Python interprétera et exécutera tout calcul présent dans son code. Quelques exemples sont proposés ci-dessous :
+>>> 1 + 1
+2
+>>> 6 * 7
+42
+>>> 4-2
+2
+>>> 2-4
+-2
+>>> (4-2)*2
+4
+>>> 3.6/2
+1.8
+>>> 3*5.2
+15.6
+Les variables et fonctions
+Variable : boite dans laquelle on peut mettre une valeur.
+Fonction : morceau de code que quelqu'un d'autre a déjà écrit pour vous, qu'on appelle avec son nom pour ne pas le ré-écrire. On peut également écrire nos propres fonctions (comme mentionné un peu plus bas).
+Quelques rappels issus de l'initiation au code :
+# Appel de la fonction d'affichage, avec pour paramètre "Bonjour !"
+print("Bonjour !")
+>>> Bonjour !
+
+x=3
+print(x)
+>>> 3
+On notera ici que x est passée directement à la fonction. En effet, une variable est une boîte qu'on peut donner tel quel et Python comprend très bien qu'on veut donner à la fonction le contenu de la boîte. Pour le cas du texte "Bonjour !", il est passé entre guillemets, ce qui indique que la chaîne de caractères "Bonjour !" est donnée directement en argument.
Pour rappel, seule une nouvelle déclaration changera la valeur d'une variable :
+x=3
+x+1
+>>> 4
+print(x)
+>>> 3
+x=x+1
+>>> 4
+print(x)
+>>> 4
+Enfin, on rappelle les deux types de variables :
+-
+
- locale : disponible uniquement dans la fonction en cours ; +
- interne : disponible partout où l'objet concerné est présent (pratique pour passer une variable de
initialisationàboucle, par exemple).
+
Les deux types de fonctions sont de même nature :
+-
+
- principale : disponible pour le fichier en cours ; +
- interne : peut être utilisée par le jeu lui-même (c'est le cas de
boucle, par exemple) ou utilisée depuis la variable jeu (jeu.quitter()par exemple).
+
Comme mentionné en introduction, on peut créer (on dit « déclarer ») des fonctions nous-même. Ça ressemble toujours à ceci :
+def nom_de_la_fonction(premier_argument, second_argument, ...):
+ print("Contenu de la fonction")
+Par exemple, notre fonction boucle ressemble à ceci :
def boucle(jeu):
+ # Mettre ici le code de la fonction
+Elle attend donc un argument appelé jeu, qui lui sera passé par la bibliothèque avant d'exécuter le contenu de la fonction ; cet objet contiendra tout ce qui est nécessaire pour l'affichage de notre jeu.
+Structures conditionnelles
+Condition : Expression qui exécute un morceau de code seulement si elle est vérifiée.
+Aucun rappel particulier n'est nécessaire pour les conditions, mais nous te proposons le code final de l'initiation afin d'avoir les idées claires. En cas de question, n'hésite pas à appeler un animateur.
+age = 15
+# Si l'âge est supérieur ou égal à 21…
+if age >= 21:
+ print("Majorité internationale")
+# Sinon, si l'âge est supérieur à 18…
+elif age >= 18:
+ print("Tu es majeur")
+# Sinon…
+else:
+ print("Tu es mineur")
+Aussi, les tests dont nous pourrions avoir besoin par la suite sont les suivants :
+-
+
>supérieur à ;
+<inférieur à ;
+==strictement égal à ;
+!=différent de.
+
Les boucles
+Boucle : Morceau de code répété un certain nombre de fois, jusqu'à ce qu'une condition soit vraie.
+Ici encore, tout devrait aller, et pour référence, voici le code écrit en introduction. Dans la documentation ci-après, les méthodes destinées à être utilisées dans une boucle sont toujours explicitement mentionnées comme tel.
+for carreau in jeu.grille():
+ if jeu.est_un_bord(carreau):
+ print(carreau)
+Fonctions du jeu
+Présentation générale
+Déclaration de l'objet Jeu
+Après avoir importé la bibliothèque Zeste de Code, tu auras accès aux fonctions principales du jeu ; pour rappel, un objet Jeu est créé comme suit :
+mon_jeu = Jeu(initialisation, boucle)
+Où initialisation et boucle sont deux fonctions qui doivent avoir été définies précédemment (voir la partie d'initiation au code) ; ces fonctions prendront en paramètre l'instance du jeu afin de pouvoir la modifier.
Gestion des événements
+Variables passées à la boucle
+Lorsque le jeu est récupéré à l'intérieur de la boucle, il dispose de variables accessibles de façon directe (hors fonctions / méthodes) :
+-
+
mon_jeu.largeur, qui contient la largeur de la fenêtre ;
+mon_jeu.hauteur, qui contient la hauteur de la fenêtre ;
+mon_jeu.evenements, qui contient la liste des événements déclenchés depuis le dernier tour de boucle.
+
La variable evenments nous intéressera particulièrement, et nous pourrons vérifier si un certain événement est déclenché en utilisant une condition :
if Evenements.QUITTER in mon_jeu.evenements:
+ print("Je veux quitter")
+Variables de la bibliothèque
+Dans la suite de ce guide, nous te présenterons les fonctions ayant attrait à la zone de jeu et au serpent. Toutefois, certains objets transcendent et ne peuvent aller dans aucune des deux catégories ; ces objets sont importés par défaut et ne requièrent donc pas l'appel par une méthode.
+Le premier objet concerne la gestion des événements, et est naturellement nommé Evenements ; nous l'avons vu ci-dessus sans bien comprendre à quoi il correspondait ; cet objet contient deux variantes qui nous intéressent :
# Déclenché lorsque le joueur demande à fermer le jeu
+Evenements.QUITTER
+# Déclenché lorsqu'une touche est appuyée
+Evenements.TOUCHE_APPUYEE
+Récupération de la touche appuyée
+Une fois l'événement de TOUCHE_APPUYEE intercepté, il serait bon de savoir sur quelle touche le joueur a appuyé afin de déplacer le serpent dans la bonne direction ; pour cela, il suffit de tester mon_jeu.evenements[Evenement.TOUCHE_APPUYEE], magique non ? La valeur peut alors être égale à (notons la seconde variable interne de la bibliothèque : Touches) :
Touches.FLECHE_DROITE
+Touches.FLECHE_GAUCHE
+Touches.FLECHE_HAUT
+Touches.FLECHE_BAS
+Touches.ESPACE
+Pas plus de détails ici afin de vous faire chercher par vous-même ; n'oublie pas en tout cas qu'en informatique, il faut tester, tu ne peux rien casser. En cas de problème persistant, un animateur sera heureux de te guider.
+Ajout d'images et de texte
+Déclaration des variables internes
+Une fois l'objet de jeu créé, et récupéré dans une des fonctions initialisation ou boucle, il est possible de déclarer à tout moment une image par la méthode ajouter_image, appelée avec le nom à donner à l'image ainsi que le chemin relatif de l'image. Par la suite, on pourra afficher notre image où on veut dans la fenêtre en l'appelant par son nom (voir un peu plus loin comment faire).
Le chemin relatif d'un fichier est l'endroit où il se trouve par rapport au fichier actuel. Par exemple, l'image image.png située dans le dossier images du dossier du fichier actuel est de chemin relatif images/image.png.
Puisqu'un exemple vaut mieux qu'un long discours :
+# Déclaration de l'image du cactus
+mon_jeu.ajouter_image("Cactus", "images/cactus.png")
+La méthode permettant d'ajouter du texte fonctionne de la même façon, mais prend comme second paramètre le texte à afficher ; elle est nommée ajouter_texte.
Récupération et dessin
+Afin de dessiner une image ou un texte précédemment déclaré, il faut faire appel à la fonction dessin ; cette fonction prend en paramètre :
-
+
- le nom déclaré de l'image ou du texte ; +
- un objet de paramètres, pouvant prendre deux clefs :
positionetrotation, toute valeur différente sera ignorée.
+
Par exemple, pour dessiner un cactus (déclaré précédemment), en haut à gauche de l'écran, il suffit d’appeler la fonction :
+mon_jeu.dessiner("Cactus", { "position": (0, 0) })
+Une autre fonction de dessin utile est la fonction effacer_ecran, qui permet d'effacer entièrement le contenu de la zone de jeu ; elle ne prend aucun paramètre en entrée :
mon_jeu.effacer_ecran()
+Gestion des positions et collisions
+Itérateur principal
+Dès le second objectif, vous aurez besoin de réaliser une boucle sur l'ensemble de la grille du jeu ; pour cela, un itérateur grille existe, et donne la position (x, y) d'un morceau de grille à chaque itération ; pour bien comprendre, voici un petit exemple d'utilisation :
for carreau in mon_jeu.grille():
+ print(carreau)
+Ce code affichera la liste de tous les carreaux possibles dans la console.
+Fonctions utiles
+Afin de vérifier une collision entre deux objets, il existe une fonction collision qui renvoie True lorsqu'il y a collision et False sinon. Cette fonction prend deux paramètres, la position du premier objet, et la position du second ; cette fonction est principalement destinée à être utilisée dans des conditions, par exemple :
if mon_jeu.collision(pomme, morceau.position):
+ print("Collision Serpent-Pomme")
+Vérifiera s'il y a collision entre la pomme et la variable nommée morceau.position.
Afin d'afficher les cactus sur un bord, tu pourrais avoir besoin de savoir si une position correspond ou non à un bord, pour cela, une fonction est_un_bord existe, et prend comme unique paramètre la position à tester ; elle retourne un booléen. Pas d'exemple ici, on vous laisse essayer d'utiliser cette fonction par vous-même afin de bien comprendre son principe.
Divers
+Enfin, si tu es très avancé, tu pourras essayer d'afficher une pomme à l'écran et faire en sorte que le serpent puisse la manger. Pour générer la position de la pomme, deux solutions sont possibles :
+-
+
- la solution simple, utiliser
position_aleatoire_pomme, fonction intégrée retournant simplement une position (x, y) aléatoire bien choisie ;
+ - la solution plus complexe, qui consiste à créer cette fonction par toi-même ; nous donnerons évidemment des indices aux participants arrivant jusqu'ici. +
L'idée est de commencer par utiliser la fonction intégrée puis éventuellement de la (re)coder soi-même par la suite.
+Fonctions diverses et bonus
+Cette partie regroupe les fonctions qui ne trouvent leur place nulle part ailleurs ; l'une d'entre elle est très utile, les autres sont des bonus destinés aux participants les plus avancés.
+Quitter le jeu
+La fonction très utile mentionnée ci-dessus est la fonction quitter, qui fermera simplement le jeu ; il sera nécessaire de l'utiliser lors de l'appui sur la croix de fermeture par le joueur, ou à la mort du serpent... éventuellement 
.
Fonctions bonus
+Quelques détails du jeu vous ont été cachés dans les parties précédentes, mais les objectifs bonus nous obligent à révéler certains de nos secrets les mieux gardés.
+Tout d'abord, la fonction d'initialisation prend en réalité non pas deux mais bien quatre paramètres ; il est en effet possible de changer la taille de la fenêtre de jeu en passant en paramètres la largeur puis la hauteur, par exemple :
+mon_jeu = Jeu(initialisation, boucle, 1024, 576)
+créera une fenêtre plus grande que celle par défaut.
+Il faudra veiller à ce que les deux paramètres de largeur et de hauteur soient des multiples de 32, sinon... à toi de tester.
La deuxième fonction utile pour les bonus permet d'afficher du texte en plus grand que celui par défaut ; il s'agit de la fonction init_text. Cette méthode est pour être exact déjà appelée lors de l'initialisation du jeu (mais masquée, bien entendu). Elle permet de régler la police et la taille du texte ; un exemple pour comprendre :
init_text("sans-serif", 32)
+Cet appel rendra le texte en police sans-serif, et en taille 32, ce sont d’ailleurs les paramètres par défaut.
+Fonctions du serpent
+Présentation générale
+Déclaration de l'objet Serpent
+Après avoir importé la bibliothèque Zeste de Code, tu auras accès aux fonctions concernant le serpent. Une nouvelle instance de serpent devra ensuite être créée, préférentiellement à l'intérieur du jeu :
+def init(jeu):
+ jeu.serpent = Serpent()
+Constantes du serpent
+Dans l'objet Serpent précédemment créé, en plus des méthodes mentionnées ci-dessous, tu trouveras trois constantes (variables qui ne changent pas) importantes.
+Gestion de la direction
+La première, jeu.serpent.DIRECTIONS permet de donner au serpent une direction ; elle est particulièrement utilisée avec la fonction deplacer, qui la prend en argument. Cet objet se décline en cinq clefs :
# Le serpent va vers la droite
+jeu.serpent.DIRECTIONS.DROITE
+# Le serpent se déplace à gauche
+jeu.serpent.DIRECTIONS.GAUCHE
+# Le serpent monte
+jeu.serpent.DIRECTIONS.HAUT
+# Le serpent part en bas
+jeu.serpent.DIRECTIONS.BAS
+# Le serpent s'arrête (pas tout à fait une direction)
+jeu.serpent.DIRECTIONS.STOP
+Gestion des rotations
+Pour les plus avancés d'entre vous, il sera nécessaire de détecter quand le serpent tourne et dans quel sens. C'est à cet effet qu'a été créé la constante ROTATIONS :
# Le serpent tourne dans le sens des aiguilles d'une montre
+jeu.serpent.ROTATIONS.HORAIRE
+# Le serpent tourne dans le sens inverse
+jeu.serpent.ROTATIONS.ANTI_HORAIRE
+Parties du serpent
+Le serpent se décompose automatiquement en diverses partie :
+-
+
- une tête, pour indiquer l'avant ; +
- une queue, pour indiquer l'arrière ; +
- le reste est composé de morceaux de corps. +
Afin de détecter ces différentes parties, une constante jeu.serpent.PARTIES existe, et peut prendre les valeurs suivantes :
# Renseigne la tête du serpent (donc l'avant)
+jeu.serpent.PARTIES.TETE
+# Renseigne une partie de corps du serpent
+jeu.serpent.PARTIES.CORPS
+# Renseigne la queue du serpent (donc l'arrière)
+jeu.serpent.PARTIES.QUEUE
+Notons que lors de l'itération, les parties sont ordonnées dans le sens inverse (et si tu ne comprends rien à cette phrase, reviens plus tard).
+Lorsque le serpent grandit, la bibliothèque ajoute automatiquement un morceau de corps juste après la tête, ce qui a pour effet de l'allonger.
+Déplacement et taille
+Dans cette partie sont détaillées les fonctions concernant la taille du serpent ainsi que la gestion de ses déplacements.
+Taille du serpent et agrandissement
+En premier lieu, voyons une fonction très utile, qui permet d'obtenir la taille du serpent : serpent.taille(). Cette fonction ne nécessite aucun paramètre ; elle retourne simplement la taille brute du serpent. Par exemple, au début du jeu, elle renverra 3.
Pour faire grandir le serpent, nous en avons parlé plus haut, il est possible d'appeler la fonction serpent.grandir(). Elle ne prend aucun paramètre et ne retourne rien, mais modifie en interne la taille du serpent en ajoutant en morceau juste après la tête.
Fonction de déplacement
+Afin de déplacer le serpent, il faut appeler la méthode serpent.deplacer(direction) avec direction une des constantes de direction vue ci-dessus. Par exemple, pour déplacer le serpent d'une case vers le haut :
serpent.deplacer(jeu.serpent.DIRECTIONS.HAUT)
+Position du serpent
+Un itérateur existe et permet d'obtenir tous les morceaux de serpent dans l'ordre allant de la queue à la tête, il s'agit de serpent.morceaux(taille) ; le seul argument est la taille du serpent, ou plus simplement le nombre de morceaux à prendre. Pour afficher les positions successives du serpent :
for morceau in jeu.serpent.morceaux(taille):
+ print(morceau.position)
+Comme tu peux le voir, morceau contient une information position, mais aussi une information direction_rotation, qui contient une des constantes de rotation vue ci-dessus, et enfin type, qui contient une constante de partie du serpent (tête, queue ou corps).
Pour obtenir la position de la tête du serpent, une fonction peut te simplifier la vie, c'est la fonction serpent.position_tete, qui retourne simplement la position (x, y) de la tête du serpent.
Nous espérons que cet atelier vous plaît, merci pour votre participation !
\ No newline at end of file diff --git a/documentation/manifest.json b/documentation/manifest.json new file mode 100644 index 0000000..fa2f112 --- /dev/null +++ b/documentation/manifest.json @@ -0,0 +1,27 @@ +{ + "type" : "TUTORIAL", + "object" : "container", + "slug" : "zeste-de-code--guide-participants--snake", + "title" : "Zeste de Code – Guide participants – Snake", + "introduction" : "introduction.md", + "conclusion" : "conclusion.md", + "children" : [ { + "object" : "extract", + "slug" : "les-bases-de-python", + "title" : "Les bases de Python", + "text" : "les-bases-de-python.md" + }, { + "object" : "extract", + "slug" : "fonctions-du-jeu", + "title" : "Fonctions du jeu", + "text" : "fonctions-du-jeu.md" + }, { + "object" : "extract", + "slug" : "fonctions-du-serpent", + "title" : "Fonctions du serpent", + "text" : "fonctions-du-serpent.md" + } ], + "version" : 2, + "licence" : "Tous droits réservés", + "description" : "Une documentation complète des fonctions du jeu Snake à destination des participants (et organisateurs) des Zeste de Code." +} diff --git a/documentation/md/conclusion.md b/documentation/md/conclusion.md new file mode 100644 index 0000000..81d0261 --- /dev/null +++ b/documentation/md/conclusion.md @@ -0,0 +1 @@ +Nous espérons que cet atelier vous plaît, merci pour votre participation ! diff --git a/documentation/md/fonctions-du-jeu.md b/documentation/md/fonctions-du-jeu.md new file mode 100644 index 0000000..39bf8bb --- /dev/null +++ b/documentation/md/fonctions-du-jeu.md @@ -0,0 +1,158 @@ +# Présentation générale + +## Déclaration de l'objet Jeu + +Après avoir importé la bibliothèque Zeste de Code, tu auras accès aux fonctions principales du jeu ; pour rappel, un objet Jeu est créé comme suit : + +```py +mon_jeu = Jeu(initialisation, boucle) +``` + +Où `initialisation` et `boucle` sont deux fonctions qui doivent avoir été définies précédemment (voir la partie d'initiation au code) ; ces fonctions prendront en paramètre l'instance du jeu afin de pouvoir la modifier. + +## Gestion des événements + +### Variables passées à la boucle + +Lorsque le jeu est récupéré à l'intérieur de la boucle, il dispose de variables accessibles de façon directe (hors fonctions / méthodes) : + +- `mon_jeu.largeur`, qui contient la largeur de la fenêtre ; +- `mon_jeu.hauteur`, qui contient la hauteur de la fenêtre ; +- `mon_jeu.evenements`, qui contient la liste des événements déclenchés depuis le dernier tour de boucle. + +La variable `evenments` nous intéressera particulièrement, et nous pourrons vérifier si un certain événement est déclenché en utilisant une condition : + +```py +if Evenements.QUITTER in mon_jeu.evenements: + print("Je veux quitter") +``` + +### Variables de la bibliothèque + +Dans la suite de ce guide, nous te présenterons les fonctions ayant attrait à la zone de jeu et au serpent. Toutefois, certains objets transcendent et ne peuvent aller dans aucune des deux catégories ; ces objets sont importés par défaut et ne requièrent donc pas l'appel par une méthode. + +Le premier objet concerne la gestion des événements, et est naturellement nommé `Evenements` ; nous l'avons vu ci-dessus sans bien comprendre à quoi il correspondait ; cet objet contient deux variantes qui nous intéressent : + +```py +# Déclenché lorsque le joueur demande à fermer le jeu +Evenements.QUITTER +# Déclenché lorsqu'une touche est appuyée +Evenements.TOUCHE_APPUYEE +``` + +### Récupération de la touche appuyée + +Une fois l'événement de `TOUCHE_APPUYEE` intercepté, il serait bon de savoir sur quelle touche le joueur a appuyé afin de déplacer le serpent dans la bonne direction ; pour cela, il suffit de tester `mon_jeu.evenements[Evenement.TOUCHE_APPUYEE]`, magique non ? La valeur peut alors être égale à (notons la seconde variable interne de la bibliothèque : `Touches`) : + +```py +Touches.FLECHE_DROITE +Touches.FLECHE_GAUCHE +Touches.FLECHE_HAUT +Touches.FLECHE_BAS +Touches.ESPACE +``` + +Pas plus de détails ici afin de vous faire chercher par vous-même ; n'oublie pas en tout cas qu'en informatique, il faut tester, tu ne peux rien casser. En cas de problème persistant, un animateur sera heureux de te guider. + +# Ajout d'images et de texte + +## Déclaration des variables internes + +Une fois l'objet de jeu créé, et récupéré dans une des fonctions `initialisation` ou `boucle`, il est possible de déclarer à tout moment une image par la méthode `ajouter_image`, appelée avec le nom à donner à l'image ainsi que le chemin relatif de l'image. Par la suite, on pourra afficher notre image où on veut dans la fenêtre en l'appelant par son nom (voir un peu plus loin comment faire). + +[[information]] +| Le chemin relatif d'un fichier est l'endroit où il se trouve par rapport au fichier actuel. Par exemple, l'image `image.png` située dans le dossier `images` du dossier du fichier actuel est de chemin relatif `images/image.png`. + +Puisqu'un exemple vaut mieux qu'un long discours : + +```py +# Déclaration de l'image du cactus +mon_jeu.ajouter_image("Cactus", "images/cactus.png") +``` + +La méthode permettant d'ajouter du texte fonctionne de la même façon, mais prend comme second paramètre le texte à afficher ; elle est nommée `ajouter_texte`. + +## Récupération et dessin + +Afin de dessiner une image ou un texte précédemment déclaré, il faut faire appel à la fonction `dessin` ; cette fonction prend en paramètre : + +1. le nom déclaré de l'image ou du texte ; +2. un objet de paramètres, pouvant prendre deux clefs : `position` et `rotation`, **toute valeur différente sera ignorée**. + +Par exemple, pour dessiner un cactus (déclaré précédemment), en haut à gauche de l'écran, il suffit d’appeler la fonction : + +```py +mon_jeu.dessiner("Cactus", { "position": (0, 0) }) +``` + +Une autre fonction de dessin utile est la fonction `effacer_ecran`, qui permet d'effacer entièrement le contenu de la zone de jeu ; elle ne prend aucun paramètre en entrée : + +```py +mon_jeu.effacer_ecran() +``` + +# Gestion des positions et collisions + +## Itérateur principal + +Dès le second objectif, vous aurez besoin de réaliser une boucle sur l'ensemble de la grille du jeu ; pour cela, un itérateur `grille` existe, et donne la position (x, y) d'un morceau de grille à chaque itération ; pour bien comprendre, voici un petit exemple d'utilisation : + +```py +for carreau in mon_jeu.grille(): + print(carreau) +``` + +Ce code affichera la liste de tous les carreaux possibles dans la console. + +## Fonctions utiles + +Afin de vérifier une collision entre deux objets, il existe une fonction `collision` qui renvoie `True` lorsqu'il y a collision et `False` sinon. Cette fonction prend deux paramètres, la position du premier objet, et la position du second ; cette fonction est principalement destinée à être utilisée dans des conditions, par exemple : + +```py +if mon_jeu.collision(pomme, morceau.position): + print("Collision Serpent-Pomme") +``` + +Vérifiera s'il y a collision entre la pomme et la variable nommée `morceau.position`. + +Afin d'afficher les cactus sur un bord, tu pourrais avoir besoin de savoir si une position correspond ou non à un bord, pour cela, une fonction `est_un_bord` existe, et prend comme unique paramètre la position à tester ; elle retourne un booléen. Pas d'exemple ici, on vous laisse essayer d'utiliser cette fonction par vous-même afin de bien comprendre son principe. + +## Divers + +Enfin, si tu es très avancé, tu pourras essayer d'afficher une pomme à l'écran et faire en sorte que le serpent puisse la manger. Pour générer la position de la pomme, deux solutions sont possibles : + +- la solution simple, utiliser `position_aleatoire_pomme`, fonction intégrée retournant simplement une position (x, y) aléatoire bien choisie ; +- la solution plus complexe, qui consiste à créer cette fonction par toi-même ; nous donnerons évidemment des indices aux participants arrivant jusqu'ici. + +L'idée est de commencer par utiliser la fonction intégrée puis éventuellement de la (re)coder soi-même par la suite. + +# Fonctions diverses et bonus + +Cette partie regroupe les fonctions qui ne trouvent leur place nulle part ailleurs ; l'une d'entre elle est très utile, les autres sont des bonus destinés aux participants les plus avancés. + +## Quitter le jeu + +La fonction très utile mentionnée ci-dessus est la fonction `quitter`, qui fermera simplement le jeu ; il sera nécessaire de l'utiliser lors de l'appui sur la croix de fermeture par le joueur, ou à la mort du serpent... éventuellement ;) . + +## Fonctions bonus + +Quelques détails du jeu vous ont été cachés dans les parties précédentes, mais les objectifs bonus nous obligent à révéler certains de nos secrets les mieux gardés. + +Tout d'abord, la fonction d'initialisation prend en réalité non pas deux mais bien quatre paramètres ; il est en effet possible de changer la taille de la fenêtre de jeu en passant en paramètres la largeur puis la hauteur, par exemple : + +```py +mon_jeu = Jeu(initialisation, boucle, 1024, 576) +``` + +créera une fenêtre plus grande que celle par défaut. + +[[attention]] +| Il faudra veiller à ce que les deux paramètres de largeur et de hauteur soient des multiples de 32, sinon... à toi de tester. + +La deuxième fonction utile pour les bonus permet d'afficher du texte en plus grand que celui par défaut ; il s'agit de la fonction `init_text`. Cette méthode est pour être exact déjà appelée lors de l'initialisation du jeu (mais masquée, bien entendu). Elle permet de régler la police et la taille du texte ; un exemple pour comprendre : + +```py +init_text("sans-serif", 32) +``` + +Cet appel rendra le texte en police sans-serif, et en taille 32, ce sont d’ailleurs les paramètres par défaut. diff --git a/documentation/md/fonctions-du-serpent.md b/documentation/md/fonctions-du-serpent.md new file mode 100644 index 0000000..eb28a12 --- /dev/null +++ b/documentation/md/fonctions-du-serpent.md @@ -0,0 +1,96 @@ +# Présentation générale + +## Déclaration de l'objet Serpent + +Après avoir importé la bibliothèque Zeste de Code, tu auras accès aux fonctions concernant le serpent. Une nouvelle instance de serpent devra ensuite être créée, préférentiellement à l'intérieur du jeu : + +```python +def init(jeu): + jeu.serpent = Serpent() +``` + +## Constantes du serpent + +Dans l'objet Serpent précédemment créé, en plus des méthodes mentionnées ci-dessous, tu trouveras trois constantes (variables qui ne changent pas) importantes. + +### Gestion de la direction + +La première, `jeu.serpent.DIRECTIONS` permet de donner au serpent une direction ; elle est particulièrement utilisée avec la fonction `deplacer`, qui la prend en argument. Cet objet se décline en cinq clefs : + +```python +# Le serpent va vers la droite +jeu.serpent.DIRECTIONS.DROITE +# Le serpent se déplace à gauche +jeu.serpent.DIRECTIONS.GAUCHE +# Le serpent monte +jeu.serpent.DIRECTIONS.HAUT +# Le serpent part en bas +jeu.serpent.DIRECTIONS.BAS +# Le serpent s'arrête (pas tout à fait une direction) +jeu.serpent.DIRECTIONS.STOP +``` + +### Gestion des rotations + +Pour les plus avancés d'entre vous, il sera nécessaire de détecter quand le serpent tourne et dans quel sens. C'est à cet effet qu'a été créé la constante `ROTATIONS` : + +```python +# Le serpent tourne dans le sens des aiguilles d'une montre +jeu.serpent.ROTATIONS.HORAIRE +# Le serpent tourne dans le sens inverse +jeu.serpent.ROTATIONS.ANTI_HORAIRE +``` + +### Parties du serpent + +Le serpent se décompose automatiquement en diverses partie : + +- une tête, pour indiquer l'avant ; +- une queue, pour indiquer l'arrière ; +- le reste est composé de morceaux de corps. + +Afin de détecter ces différentes parties, une constante `jeu.serpent.PARTIES` existe, et peut prendre les valeurs suivantes : + +```python +# Renseigne la tête du serpent (donc l'avant) +jeu.serpent.PARTIES.TETE +# Renseigne une partie de corps du serpent +jeu.serpent.PARTIES.CORPS +# Renseigne la queue du serpent (donc l'arrière) +jeu.serpent.PARTIES.QUEUE +``` + +Notons que lors de l'itération, les parties sont ordonnées dans le sens inverse (et si tu ne comprends rien à cette phrase, reviens plus tard). + +Lorsque le serpent grandit, la bibliothèque ajoute automatiquement un morceau de corps juste après la tête, ce qui a pour effet de l'allonger. + +# Déplacement et taille + +Dans cette partie sont détaillées les fonctions concernant la taille du serpent ainsi que la gestion de ses déplacements. + +## Taille du serpent et agrandissement + +En premier lieu, voyons une fonction très utile, qui permet d'obtenir la taille du serpent : `serpent.taille()`. Cette fonction ne nécessite aucun paramètre ; elle retourne simplement la taille brute du serpent. Par exemple, au début du jeu, elle renverra 3. + +Pour faire grandir le serpent, nous en avons parlé plus haut, il est possible d'appeler la fonction `serpent.grandir()`. Elle ne prend aucun paramètre et ne retourne rien, mais modifie en interne la taille du serpent en ajoutant en morceau juste après la tête. + +## Fonction de déplacement + +Afin de déplacer le serpent, il faut appeler la méthode `serpent.deplacer(direction)` avec direction une des constantes de direction vue ci-dessus. Par exemple, pour déplacer le serpent d'une case vers le haut : + +```python +serpent.deplacer(jeu.serpent.DIRECTIONS.HAUT) +``` + +# Position du serpent + +Un itérateur existe et permet d'obtenir tous les morceaux de serpent dans l'ordre allant de la queue à la tête, il s'agit de `serpent.morceaux(taille)` ; le seul argument est la taille du serpent, ou plus simplement le nombre de morceaux à prendre. Pour afficher les positions successives du serpent : + +```python +for morceau in jeu.serpent.morceaux(taille): + print(morceau.position) +``` + +Comme tu peux le voir, morceau contient une information `position`, mais aussi une information `direction_rotation`, qui contient une des constantes de rotation vue ci-dessus, et enfin `type`, qui contient une constante de partie du serpent (tête, queue ou corps). + +Pour obtenir la position de la tête du serpent, une fonction peut te simplifier la vie, c'est la fonction `serpent.position_tete`, qui retourne simplement la position (x, y) de la tête du serpent. diff --git a/documentation/md/introduction.md b/documentation/md/introduction.md new file mode 100644 index 0000000..df4ef9e --- /dev/null +++ b/documentation/md/introduction.md @@ -0,0 +1 @@ +Ce document est une documentation complète des fonctions de la bibliothèque de l'atelier Zeste de Code ; n'hésitez pas à vous référer à lui afin de *rechercher une fonctionnalité*. Si quelque chose ne vous semble pas clair, vous pouvez toujours *appeler un animateur*, qui viendra alors vous aider. diff --git a/documentation/md/les-bases-de-python.md b/documentation/md/les-bases-de-python.md new file mode 100644 index 0000000..68d5807 --- /dev/null +++ b/documentation/md/les-bases-de-python.md @@ -0,0 +1,121 @@ +Cette partie est un rappel des notions abordées ci-avant, dans le cas où tu aurais besoin de revoir les bases du langage, pendant l'atelier ou chez toi. + +# Quelques calculs simples + +Pour rappel, le langage Python interprétera et exécutera tout calcul présent dans son code. Quelques exemples sont proposés ci-dessous : + + +```python +>>> 1 + 1 +2 +>>> 6 * 7 +42 +>>> 4-2 +2 +>>> 2-4 +-2 +>>> (4-2)*2 +4 +>>> 3.6/2 +1.8 +>>> 3*5.2 +15.6 +``` + +# Les variables et fonctions + +**Variable** : boite dans laquelle on peut mettre une valeur. + +**Fonction** : morceau de code que quelqu'un d'autre a déjà écrit pour vous, qu'on appelle avec son nom pour ne pas le ré-écrire. On peut également écrire nos propres fonctions (comme mentionné un peu plus bas). + +Quelques rappels issus de l'initiation au code : + +```python +# Appel de la fonction d'affichage, avec pour paramètre "Bonjour !" +print("Bonjour !") +>>> Bonjour ! + +x=3 +print(x) +>>> 3 +``` + +On notera ici que `x` est passée directement à la fonction. En effet, une variable est une boîte qu'on peut donner tel quel et Python comprend très bien qu'on veut donner à la fonction le *contenu* de la boîte. Pour le cas du texte "Bonjour !", il est passé entre guillemets, ce qui indique que la chaîne de caractères "Bonjour !" est donnée directement en argument. + +Pour rappel, seule une nouvelle déclaration changera la valeur d'une variable : + +```python +x=3 +x+1 +>>> 4 +print(x) +>>> 3 +x=x+1 +>>> 4 +print(x) +>>> 4 +``` + +Enfin, on rappelle les deux types de variables : + +- **locale** : disponible uniquement dans la fonction en cours ; +- **interne** : disponible partout où l'objet concerné est présent (pratique pour passer une variable de `initialisation` à `boucle`, par exemple). + +Les deux types de fonctions sont de même nature : + +- **principale** : disponible pour le fichier en cours ; +- **interne** : peut être utilisée par le jeu lui-même (c'est le cas de `boucle`, par exemple) ou utilisée depuis la variable jeu (`jeu.quitter()` par exemple). + +Comme mentionné en introduction, on peut créer (on dit « déclarer ») des fonctions nous-même. Ça ressemble toujours à ceci : + +```python +def nom_de_la_fonction(premier_argument, second_argument, ...): + print("Contenu de la fonction") +``` + +Par exemple, notre fonction `boucle` ressemble à ceci : + +```python +def boucle(jeu): + # Mettre ici le code de la fonction +``` + +Elle attend donc un argument appelé jeu, qui lui sera passé par la bibliothèque avant d'exécuter le contenu de la fonction ; cet objet contiendra tout ce qui est nécessaire pour l'affichage de notre jeu. + +# Structures conditionnelles + +**Condition** : Expression qui exécute un morceau de code seulement si elle est vérifiée. + +Aucun rappel particulier n'est nécessaire pour les conditions, mais nous te proposons le code final de l'initiation afin d'avoir les idées claires. En cas de question, n'hésite pas à appeler un animateur. + +```python +age = 15 +# Si l'âge est supérieur ou égal à 21… +if age >= 21: + print("Majorité internationale") +# Sinon, si l'âge est supérieur à 18… +elif age >= 18: + print("Tu es majeur") +# Sinon… +else: + print("Tu es mineur") +``` + +Aussi, les tests dont nous pourrions avoir besoin par la suite sont les suivants : + +- `>` supérieur à ; +- `<` inférieur à ; +- `==` strictement égal à ; +- `!=` différent de. + +# Les boucles + +**Boucle** : Morceau de code répété un certain nombre de fois, jusqu'à ce qu'une condition soit vraie. + +Ici encore, tout devrait aller, et pour référence, voici le code écrit en introduction. Dans la documentation ci-après, les méthodes destinées à être utilisées dans une boucle sont toujours explicitement mentionnées comme tel. + +```python +for carreau in jeu.grille(): + if jeu.est_un_bord(carreau): + print(carreau) +```