Pygame/Chimp - Ligne par ligne
Traduit de l'anglais, original par "Pete Shinners" :
http://www.pygame.org/docs/tut/chimp/ChimpLineByLine.html
Introduction.
Dans les exemples de Pygame, il y a un petit exemple nommé "chimp". Cet exemple simule un singe à frapper qui bouge dans un petit écran avec des promesses de récompenses. Cet exemple est en lui-même vraiment simple, et réduit la recherche d'erreurs dans le code. Cet exemple de programme démontre les possibilités de Pygame, comme la création de fenêtres graphiques, le chargement de fichiers d'images et de sons, de rendu de texte TTF (police TrueType), et la gestion des évènements de bases et des mouvements de la souris.
Ce programme ainsi que les images sont disponibles dans les sources de Pygame. Pour la version 1.3 de Pygame, cet exemple a été complètement réécrit pour ajouter quelques fonctions et corriger quelques erreurs. Ceci fait que la taille de l'exemple a doublé par rapport à l'original, mais nous donne plus de matière à analyser, aussi bon que soit le code, je ne peux que vous recommander de le réutiliser pour vos propres projets.
Ce tutoriel analyse le code bloc par bloc, expliquant comment le code fonctionne. Il sera également mentionné la façon dont le code pourrait être amélioré et quel contrôle d'erreur peut nous venir en aide.
Ceci est un excellent tutoriel pour les personnes qui étudient pour la première fois du code Pygame. Une fois Pygame complètement installé, vous pourrez trouver et exécuter vous-même la démo de "chimp" dans le répertoire des exemples.
Importer des modules.
Voici le code qui importe tous les modules nécessaires dans notre programme. Il vérifie la disponibilité de certains des modules optionnels de Pygame.
import os, sys
import pygame
from pygame.locals import *
if not pygame.font: print 'Attention, polices désactivées'
if not pygame.mixer: print 'Attention, son désactivé'
D'abord, nous importons les modules standards de Python codice_1 et codice_2. Ceux-ci nous permettent de faire certaines choses comme créer des chemins de fichiers indépendants du système d'exploitation.
Dans la ligne suivante, nous importons l'ensemble des modules de Pygame. Quand Pygame est importé, tous les modules appartenant à Pygame sont importés. Certains modules sont optionnels, s'ils ne sont pas trouvés, leur valeur est définie à codice_3.
Il existe un module Pygame spécial nommé codice_4. Ce module contient un sous-ensemble de Pygame. Les membres de ce module utilisent couramment des constantes et des fonctions qui ont prouvé leur utilité à être incorporé dans l'espace de nom global de votre programme. Ce module de locales inclut des fonctions comme codice_5 pour un objet rectangle, et plusieurs constantes comme codice_6 qui sont utilisées pour interagir avec le reste de Pygame. L'importation de ce module de locales dans l'espace de nom global est complètement optionnel. Si vous choisissez de ne pas l'importer, tous les membres des locales sont toujours disponibles dans le module codice_7.
Enfin, nous avons décidé d'imprimer un joli message si les modules codice_8 ou codice_9 ne sont pas disponibles dans Pygame.
Chargement des Ressources.
Ici nous avons deux fonctions que nous pouvons utiliser pour charger des images et des sons. Nous examinerons chaque fonction individuellement dans cette section.
def load_image(name, colorkey=None):
 fullname = os.path.join('data', name)
 try:
 image = pygame.image.load(fullname)
 except pygame.error, message:
 print "Impossible de charger l'image :", name
 raise SystemExit, message
 image = image.convert()
 if colorkey is not None:
 if colorkey is -1:
 colorkey = image.get_at((0,0))
 image.set_colorkey(colorkey, RLEACCEL)
 return image, image.get_rect()
Cette fonction prend le nom de l'image à charger. Elle prend également un argument optionnel qui peut être utilisé pour définir une couleur clé à l'image. Une couleur clé est utilisée dans les graphismes pour représenter une couleur de l'image qui devra être transparente.
La première chose que cette fonction fait, est de créer un chemin de fichier complet vers le fichier. Dans cet exemple, toutes les ressources sont situées dans le sous-répertoire codice_10. En utilisant la fonction codice_11, un chemin sera créé qui fonctionnera quelle que soit la plateforme sur laquelle est lancé le jeu.
Ensuite, nous chargeons l'image en utilisant la fonction codice_12. Nous enveloppons cette fonction dans un bloc de codice_13, ainsi s'il y a un problème lors du chargement de l'image, nous pouvons quitter élégamment. Après que l'image soit chargée, nous faisons un appel important à la fonction codice_14. Ceci crée une nouvelle copie de la Surface et la convertit dans un format et une profondeur de couleurs qui correspondent à l'affichage en cours. Ceci signifie que le blitage de l'image sur l'écran sera aussi rapide que possible.
Enfin, nous définissons la couleur clé de l'image. Si l'utilisateur fournit un argument pour la couleur clé, nous utiliserons cette valeur de couleur clé pour l'image. Ceci devrait être habituellement une valeur RGB, comme (255, 255, 255) pour le blanc. Vous pouvez également passer la valeur codice_15 comme couleur clé. Dans ce cas, la fonction examinera la couleur en haut à gauche de l'image, et utilisera cette couleur comme couleur clé.
def load_sound(name):
 class NoneSound:
 def play(self): pass
 if not pygame.mixer:
 return NoneSound()
 fullname = os.path.join('data', name)
 try:
 sound = pygame.mixer.Sound(fullname)
 except pygame.error, message:
 print 'Impossible de charger le son :', wav
 raise SystemExit, message
 return sound
Vient ensuite la fonction de chargement de fichier son. La première chose que cette fonction fait est de contrôler si le module codice_16 a été importé correctement. Si non, elle retourne une petite instance de classe qui possède une méthode de lecture factice. Ceci agira comme un objet Son normal pour ce jeu qui tournera sans contrôle d'erreur supplémentaire.
Cette fonction est similaire à la fonction de chargement d'image, mais gère des problèmes différents. En premier lieu nous créons un chemin complet vers le fichier son, et chargeons ce fichier son à travers un bloc codice_13, qui nous retourne alors l'objet Son chargé.
Classes d'objet du Jeu.
Ici nous créons deux classes qui représentent les objets dans notre jeu. La plupart de la logique de jeu vient de ces deux classes. Nous les examinerons dans cette section.
class Fist(pygame.sprite.Sprite):
 """Déplacer un poing fermé sur l'écran qui suit la souris"""
 def __init__(self):
 pygame.sprite.Sprite.__init__(self) #Appel du constructeur de Sprite
 self.image, self.rect = load_image('fist.bmp', -1)
 self.punching = 0
 def update(self):
 "Déplace le poing sur la position de la souris"
 pos = pygame.mouse.get_pos()
 self.rect.midtop = pos
 if self.punching:
 self.rect.move_ip(5, 10)
 def punch(self, target):
 "Renvoie true si le poing entre en collision avec la cible"
 if not self.punching:
 self.punching = 1
 hitbox = self.rect.inflate(-5, -5)
 return hitbox.colliderect(target.rect)
 def unpunch(self):
 "Appelé pour faire revenir le poing"
 self.punching = 0
Ici nous créons une classe pour représenter le poing du joueur. Elle est dérivée de la classe Sprite inclue dans le module codice_18. La méthode codice_19 est appelée lorsqu'une nouvelle instance de cette classe est créée. La première chose que nous faisons est de s'assurer d'appeler la méthode codice_19 de notre classe de base. Ceci autorise la méthode codice_19 de Sprite à préparer notre objet pour l'utiliser comme un sprite. Ce jeu utilise un des groupes de classes de dessin de sprite. Ces classes peuvent dessiner des sprites qui possèdent un attribut codice_22 et codice_23. En changeant tout simplement ces deux attributs, le moteur de rendu dessinera les images actuelles à leur position actuelle.
Tous les sprites possède une méthode codice_24. Cette méthode est généralement appelée une fois par image. C'est le lieu où vous pouvez mettre le code qui déplace et actualise les variables de chaque sprite. La méthode codice_24 pour le poing déplace ce poing vers l'endroit où pointe la souris. Elle compense légèrement la position du poing si celui est en état de "frappe".
Les deux fonctions suivantes codice_26 et codice_27 modifie l'état du poing. La méthode codice_26 retourne la valeur codice_29 si le poing entre en collision avec le sprite cible.
class Chimp(pygame.sprite.Sprite): 
 """Déplace un singe à travers l'écran. Elle peut faire tournoyer
 le singe quand il est frappé."""
 def __init__(self):
 pygame.sprite.Sprite.__init__(self) #Appel du constructeur de Sprite
 self.image, self.rect = load_image('chimp.bmp', -1)
 screen = pygame.display.get_surface()
 self.area = screen.get_rect()
 self.rect.topleft = 10, 10
 self.move = 9
 self.dizzy = 0
 def update(self):
 "Déplace ou fait tournoyer, suivant l'état du singe"
 if self.dizzy:
 self._spin()
 else:
 self._walk()
 def _walk(self):
 "Déplacer le singe à travers l'écran, et le faire pivoter à la fin"
 newpos = self.rect.move((self.move, 0))
 if not self.area.contains(newpos):
 if self.rect.left < self.area.left or \
 self.rect.right > self.area.right:
 self.move = -self.move
 newpos = self.rect.move((self.move, 0))
 self.image = pygame.transform.flip(self.image, 1, 0)
 self.rect = newpos
 def _spin(self):
 "Faire tournoyer l'image du singe"
 center = self.rect.center
 self.dizzy += 12
 if self.dizzy >= 360:
 self.dizzy = 0
 self.image = self.original
 else:
 rotate = pygame.transform.rotate
 self.image = rotate(self.original, self.dizzy)
 self.rect = self.image.get_rect(center=center)
 def punched(self):
 "Entraine le tournoiement du singe"
 if not self.dizzy:
 self.dizzy = 1
 self.original = self.image
La classe Chimp fait un peu plus de travail que celle du poing, mais rien de complexe. Cette classe déplacera le chimpanzé de gauche à droite sur l'écran. Quand le singe sera frappé, il tournoiera sur lui-même dans un superbe effet. Cette classe est dérivée de la classe de base Sprite, et est initialisée de la même façon que celle du poing. Pendant l'initialisation, la classe définit l'attribut codice_30 comme dimension de l'affichage.
La fonction codice_24 du singe vérifie simplement l'état actuel, lequel est codice_29 quand le singe tournoie après un coup de poing. Elle appelle la méthode codice_33 ou codice_34. Ces fonctions sont préfixées d'un underscore. C'est un idiome Python qui suggère que ces méthodes devraient uniquement être utilisées à l'intérieur de la classe codice_35. Nous pourrions aller plus loin en leur attribuant un double underscore, qui indiquera à Python de réellement essayer d'en faire des méthodes privées, mais nous n'avons pas besoin de ce type de protection. :)
La méthode codice_34 crée une nouvelle position pour le singe, en déplaçant le codice_23 actuel d'un déplacement élémentaire. Si cette nouvelle position se situe à l'extérieur de la zone d'affichage de l'écran, elle inverse le déplacement élémentaire. Elle inverse également le sens de l'image en utilisant la fonction codice_38. C'est un effet rudimentaire qui permet au singe d'inverser le sens de son image suivant son déplacement.
La méthode codice_39 est appelée quand le singe est "étourdi" (codice_40). L'attribut codice_40 est utilisé pour enregistrer le nombre de rotation actuel. Quand le singe a entièrement tournoyé sur lui-même (360 degrés), il réinitialise l'image du singe à sa version droite originale. Avant d'appeler la fonction codice_42, vous verrez que le code crée une référence locale à la fonction nommée codice_43. Il n'y a pas lieu de la faire pour cet exemple, nous l'avons uniquement fait ici pour conserver une longueur raisonnable à la ligne suivante. À noter qu'en appelant la fonction codice_43, nous faisons toujours tounoyer l'image originale du singe. Pendant la rotation, il y a une légère perte de qualité. Effectuer une rotation de façon répétitive sur la même image entraîne au fur et à mesure une dégradation de l'image. Quand une image tourne sur elle-même, la dimension de cette image sera modifiée. Ceci est dû au fait que les coins de l'image sortent de la dimension originale pendant la rotation, et augmente alors les dimensions de l'image. Nous nous assurons que le centre de la nouvelle image correspond au centre de l'ancienne image, de cette façon elle tournoie sans se déplacer.
La dernière méthode codice_45 indique que le sprite entre dans son état "étourdi" (codice_40). Ceci entrainera le tournoiement de l'image. Elle fera également une copie de l'actuelle appelée codice_47.
Tout initialiser.
Avant d'aller plus loin avec Pygame, nous devons nous assurer que tous ces modules sont initialisés. Dans ce cas nous ouvrirons une simple fenêtre graphique. Maintenant nous sommes dans la fonction principale du programme, laquelle exécute tout.
pygame.init()
screen = pygame.display.set_mode((468, 60))
pygame.display.set_caption('Monkey Fever')
pygame.mouse.set_visible(0)
La première ligne d'initialisation de Pygame nous épargne un peu de travail. Elle contrôle les modules Pygame importés et tente d'initialiser chacun d'entre eux. Il est possible de vérifier si des modules n'ont pas échoué pendant l'initialisation, mais nous ne nous tracasserons pas avec ça. Il est ainsi possible d'effectuer un contrôle plus fin et d'initialiser chaque module spécifique à la main. Ce type de contrôle n'est généralement pas indispensable, mais il est disponible si besoin.
Ensuite, nous définissons le mode d'affichage. À noter que le module codice_48 est utilisé pour contrôler tous les paramètres d'affichage. Dans cet exemple, nous demandons une simple fenêtre. Il existe un tutoriel complet sur le paramétrage du mode graphique, mais nous n'en avons pas réellement besoin, Pygame effectue déjà un bon travail pour nous en obtenant quelque chose qui fonctionne. Pygame trouve la meilleure profondeur de couleur sans que nous lui en fournissions une.
Enfin nous définissons le titre de la fenêtre et désactivons le curseur de la souris de notre fenêtre. Très simple à faire, et maintenant nous avons une petite fenêtre noire prête à recevoir nos requêtes. En fait le curseur est par défaut visible, ainsi il n'y a pas réellement besoin de définir son état tant que nous ne voulons pas le cacher.
Créer l'arrière-plan.
Notre programme affichera un message textuel en arrière-plan. Il serait bon pour nous de créer une simple surface pour représenter l'arrière-plan et l'utiliser à chaque fois. La première étape sera de créer cette surface.
background = pygame.Surface(screen.get_size())
background = background.convert()
background.fill((250, 250, 250))
Ceci crée pour nous une nouvelle surface qui est de la même taille que la fenêtre d'affichage. À noter l'appel supplémentaire codice_14 après la création de la surface. La méthode codice_14 sans argument s'assure que notre arrière-plan est du même format que la fenêtre d'affichage, ce qui nous donnera des résultats plus rapides.
Nous remplissons alors entièrement l'arrière-plan avec une couleur blanchâtre. La méthode codice_51 prend un triplet RGB en argument de couleur.
Appliquer le texte sur l'arrière-plan et le centrer.
Maintenant que nous avons une surface d'arrière-plan, appliquons-lui un rendu de texte. Nous le ferons uniquement si nous voyons que le module codice_52 a été importé correctement. Si non, nous passons cette section.
if pygame.font:
 font = pygame.font.Font(None, 36)
 text = font.render("Pummel The Chimp, And Win $$$", 1, (10, 10, 10))
 textpos = text.get_rect(centerx=background.get_width()/2)
 background.blit(text, textpos)
Comme vous le voyez, il y a une paire d'étapes pour son obtention. D'abord nous créons un objet codice_8, et en faisons un rendu sur la nouvelle surface. Nous trouvons alors le centre de cette nouvelle surface et la "blitons" sur l'arrière-plan.
La police est créée avec le constructeur codice_54 du module codice_8. En fait, nous passons le nom du fichier de police truetype à cette fonction, mais nous pouvons aussi passer codice_3 et utiliser la police par défaut. Le constructeur codice_54 nécessite de connaître la taille de la police que nous désirons créer.
Nous faisons alors un rendu de cette police dans la nouvelle surface. La fonction codice_58 crée une nouvelle surface d'une taille appropriée à notre texte. Dans cet exemple, nous dirons aussi à la fonction codice_58 de créer un texte anti-aliasé (pour obtenir un effet lissé) et d'utiliser une couleur gris sombre.
Ensuite nous avons besoin de trouver le centre du texte sur l'affichage. Nous créons un objet codice_60 qui nous permet de l'assigner facilement au centre de l'écran.
Enfin, nous "blitons" le texte sur l'image d'arrière-plan.
Afficher l'arrière-plan une fois les paramètres définis.
Nous avons encore une fenêtre noire sur l'écran. Affichons notre arrière-plan pendant que nous attendons de charger les autres ressources.
screen.blit(background, (0, 0))
pygame.display.flip()
Ceci "blitera" notre arrière-plan complet sur la fenêtre d'affichage. Le "blit" est lui-même trivial, mais qu'en est-il de la routine codice_61 ?
Dans Pygame, les changements de la surface d'affichage ne sont pas immédiatement visibles. Normalement, un affichage doit être mis à jour dans les zones qui ont changé pour les rendre visibles à l'utilisateur. Avec l'affichage par double-tampon (double buffer), l'affichage doit être interverti pour rendre les changements visibles. Dans cet exemple, la fonction codice_61 fonctionne parfaitement parce qu'elle manipule la zone entière de la fenêtre et gère les surfaces en simple et double tampon.
Préparer les objets du jeu.
Ici nous créons tous les objets dont le jeu aura besoin.
whiff_sound = load_sound('whiff.wav')
punch_sound = load_sound('punch.wav')
chimp = Chimp()
fist = Fist()
allsprites = pygame.sprite.RenderPlain((fist, chimp))
clock = pygame.time.Clock()
D'abord nous chargeons deux effets sonores en utilisant la fonction codice_63. Ensuite nous créons une instance pour chacune de nos classes de sprite. Et enfin, nous créons un groupe de sprites qui contiendra tous nos sprites.
Nous utilisons en fait un groupe spécial de sprites nommé codice_64. Ce sprite peut dessiner tous les sprites qu'il contient à l'écran. Il est appelé codice_64 parce qu'il y a en fait plusieurs groupes de rendu avancés. Mais pour notre jeu, nous avons simplement besoin de les dessiner. Nous créons le groupe nommé codice_66 en passant une liste avec tous les sprites qui appartiennent au groupe. Nous pourrons plus tard ajouter ou supprimer des sprites de ce groupe, mais dans ce jeu, nous n'en aurons pas besoin.
L'objet codice_67 que nous créons, sera utilisé pour contrôler le taux d'images par seconde de notre jeu. Nous l'utiliserons dans la boucle principale de notre jeu pour s'assurer qu'il ne fonctionne pas trop vite.
La boucle principale.
Rien de spécial ici, simplement une boucle infinie.
while 1:
 clock.tick(60)
Tous les jeux exécutent ce type de boucle. L'ordre des choses est de vérifier l'état de l'ordinateur et des entrées utilisateur, déplacer et actualiser l'état de tous les objets, et ensuite de les dessiner sur l'écran. Vous verrez que cet exemple n'est pas différent.
Nous faisons ainsi appel à notre objet codice_67 qui s'assurera que notre jeu ne dépasse pas les 60 images par seconde.
Gérer tous les évènements d'entrée.
C'est un exemple extrêmement simple sur le fonctionnement de la pile d'évènement.
for event in pygame.event.get():
 if event.type == QUIT:
 return
 elif event.type == KEYDOWN and event.key == K_ESCAPE:
 return
 elif event.type == MOUSEBUTTONDOWN:
 if fist.punch(chimp):
 punch_sound.play() #frappé
 chimp.punched()
 else:
 whiff_sound.play() #raté
 elif event.type == MOUSEBUTTONUP:
 fist.unpunch()
D'abord, nous prenons tous les évènements disponibles de Pygame et faisons une boucle pour chacun d'eux. Les deux premiers testent si l'utilisateur a quitté notre jeu ou a appuyé sur la touche codice_69. Dans ces cas, nous retournons simplement dans la fonction principale et le programme se termine proprement.
Ensuite, nous vérifions si le bouton de la souris a été enfoncé ou relaché. Si le bouton est enfoncé, nous demandons à l'objet poing si il est entré en collision avec le chimpanzé. Nous jouons l'effet sonore approprié, et si le singe est frappé, nous lui demandons de tournoyer (en appelant sa méthode codice_45.
Actualiser les Sprites.
allsprites.update()
Les groupes de sprites possèdent une méthode codice_24, qui appelle la méthode codice_24 de tous les sprites qu'ils contiennent. Chacun des objets se déplacera, en fonction de l'état dans lequel ils sont. C'est ici que le chimpanzé se déplacera d'un pas d'un côté à l'autre, ou tournoiera un peu plus loin s'il a récemment été frappé.
Dessiner la scène entière.
Maintenant que tous les objets sont à la bonne place, il est temps de les dessiner.
screen.blit(background, (0, 0))
allsprites.draw(screen)
pygame.display.flip()
Le premier appel à codice_73 dessinera l'arrière-plan sur la totalité de la fenêtre. Ceci effacera tout ce que nous avons vu de la scène précédente (peu efficace, mais suffisant pour ce jeu). Ensuite nous appelons la méthode codice_74 du conteneur de sprites. Puisque ce conteneur de sprites est réellement une instance de groupe de sprites "DrawPlain", il sait comment dessiner nos sprites. Enfin grâce à la méthode codice_61, nous affichons le contenu du tampon de Pygame à l'écran. Tout ce que nous avons dessiné apparaît en une seule fois.
Game Over.
L'utilisateur a quitté, c'est l'heure du nettoyage.
Le nettoyage d'un jeu dans Pygame est extrêmement simple. En fait puisque que toutes les variables sont automatiquement détruites, nous n'avons pas réellement besoin de faire quoi que ce soit.