Pygame/Guide du débutant

ou Les choses que j'ai apprises à force d'essais et d'erreurs, et que vous n'aurez pas à reproduire

ou Comment j'ai appris à arrêter de paniquer et à aimer le blit

Traduit de l'anglais, original par David Clark :
http://www.pygame.org/docs/tut/newbieguide.html

Pygame est une enveloppe de la SDL (Simply DirectMedia Layer) pour le langage Python, écrite par Pete Shinners. Ce qui signifie que, en utilisant Pygame, vous pouvez écrire des jeux ou d'autres applications multimédia en Python qui fonctionneront de manière identique sur toutes les plateformes supportant la SDL (Windows, Unix, Mac, beOS et autres).

Pygame peut être facile à apprendre mais le monde de la programmation graphique peut sembler déroutant pour un nouveau venu. J'ai écrit ceci pour essayer de rassembler les connaissances pratiques que j'ai acquises tout au long de l'année passée en travaillant sur Pygame et son prédecesseur pySDL. J'ai essayé de classer ces suggestions par ordre d'importance mais la pertinence de tel ou tel conseil dépendra de votre expérience personnelle et des détails de votre projet.

Règle 1 : soyez à l'aise dans votre utilisation de Python

La chose la plus importante est d'être à l'aise avec l'utilisation de Python. Apprendre quelque chose est potentiellement compliqué et la programmation graphique sera une vraie corvée si de plus, vous n'êtes pas familier avec le langage que vous utilisez.

Écrivez quelques programmes non-graphiques en Python :
- un parser de fichiers textes,
- un jeu à invite de texte,
- un programme à entrée journalière ou d'autres choses de ce style.
Soyez à l'aise avec la manipulation de chaînes de caractères et de listes : sachez comment les découper, les slicer et combiner les listes et les chaînes.
Apprenez comment réutiliser le travail : essayez d'écrire un programme qui utilise plusieurs fichiers sources réunis.
Écrivez vos propres fonctions et entraînez-vous à la manipulation des nombres et des caractères,
apprenez comment convertir les nombres en chaînes et inversement.
Venez-en au point où la syntaxe d'utilisation des listes et des dictionnaires est une seconde nature : vous ne devez pas avoir besoin de lire la documentation à chaque fois que vous avez besoin de découper une liste ou de trier une série de clés de dictionnaire.
Résistez à la tentation d'utiliser une mailing liste, comp.lang.python, irc ou un forum de discussion lorsque vous rencontrerez des problèmes.
Au lieu de ça, saignez votre interpréteur et jouez avec le problème quelques heures.
Imprimez le guide de référence rapide de Python et gardez-le près de votre ordinateur.

Cela peut vous paraître incroyablement ennuyeux mais l'assurance que vous aurez gagnée en vous familiarisant avec Python fonctionnera à merveille lorsque viendra le moment d'écrire votre jeu. Le temps que vous passerez à faire de Python votre seconde nature ne sera rien comparé au temps que vous gagnerez lorsque vous serez en train d'écrire du vrai code.

Règle 2 : identifiez les parties de Pygame dont vous aurez réellement besoin

Étudier le fatras des classes indiquées dans l'index de la documentation de Pygame peut être vraiment déroutant. L'important est de se rendre compte que l'on peut faire beaucoup avec un petit sous-ensemble de fonctions. Une grande partie des classes disponibles ne sera pas utilisée dans un premier temps : en un an, je n'ai pas touché aux modules Channel, Joystick, Cursors, Userrect, Surfarray ni à leurs différentes fonctions.

Règle 3 : comprenez ce qu'est une Surface

La partie la plus importante de Pygame concerne la manipulation de surfaces. Imaginez-vous qu'une surface n'est qu'un morceau de papier blanc : vous pouvez dessiner des lignes dessus, remplir certaines parties avec de la couleur, et y copier ou en extraire chaque valeur des pixels qui la constituent. Une surface peut être de n'importe quelle taille (dans la limite du raisonnable) et vous pouvez en manipuler autant que vous voulez (toujours dans la limite du raisonnable). Une seule surface est particulière : celle que vous créez avec la fonction pygame.display.set_mode(). Cette surface d'affichage représente l'écran : ce que vous y faites apparaîtra sur l'écran de l'utilisateur. Vous ne pouvez en avoir qu'une seule à la fois : c'est une limitation de la SDL, pas de Pygame.

Donc, comment créer des surfaces ? Comme mentionné ci-dessus, vous créez la surface spéciale surface d'affichage avec pygame.display.set_mode(). Vous pouvez créer une surface qui contient une image en utilisant image.load() ou du texte avec font.render(). Vous pouvez également créer une surface qui ne contient rien du tout avec Surface().

La plupart des fonctions de manipulation de surface ne sont pas d'une utilité critique. Apprenez seulement blit(), fill(), set_at() et get_at() et tout ira bien.

Règle 4 : utilisez surface.convert()

Quand j'ai commencé à lire la documentation de surface.convert(), je pensais ne pas en avoir besoin car j'utilisais exclusivement le format PNG pour ne pas avoir de problème de format d'image ; je n'avais pas besoin de convert(). J'ai réalisé que j'avais vraiment, vraiment tort.

Le format auquel convert() fait référence n'est pas un format de fichier (comme PNG, JPEG, GIF), c'est ce qui s'appelle l'espace colorimétrique (RGB/HSV/YUV/...). Cela se réfère à la façon particulière qu'a une surface, d'enregistrer les différentes couleurs dans un pixel spécifique. Si le format de la surface n'est pas le même que le format d'affichage, SDL devra convertir à la volée chaque blit, ce qui est très coûteux en temps de calcul. Ne vous souciez pas plus que ça des explications : souvenez-vous seulement que convert() est nécessaire si vous ne voulez pas que votre affichage soit ralenti inutilement.

Comment devez-vous utiliser convert() ? Appelez-la après avoir créé une surface avec la fonction image.load(). Au lieu de faire :

surface = pygame.image.load('foo.png')

Privilégiez :

surface = pygame.image.load('foo.png').convert()

C'est simple, vous avez besoin de ne l'appeler qu'une seule fois par surface, lorsque vous chargez votre image depuis le disque et vous serez enchanté des résultats. J'ai remarqué un gain de performance sur les blits de l'ordre de 6x en utilisant la fonction convert().

Les seules fois où vous ne voudrez pas utiliser la fonction convert(), est lorsque vous avez absolument besoin de garder un contrôle absolu sur le format interne de l'image - comme par exemple lorsque vous écrivez un logiciel de conversion d'image ou s'en approchant et que vous devez vous assurer que le fichier de sortie possède le même espace colorimétrique que le fichier d'entrée. Si vous écrivez un jeu, vous avez besoin de vitesse, donc utilisez la fonction convert().

Règle 5 : l'animation par dirty_rect

La cause principale d'un taux d'images inadéquate dans un programme Pygame résulte d'un malentendu sur la fonction pygame.display.update(). Avec Pygame, le seul tracé sur la surface d'affichage n'engendre pas son apparition sur l'écran : vous avez besoin d'appeler la fonction pygame.display.update(). Il existe trois manières d'appeler cette fonction :

pygame.display.update(): Celle-ci actualise la fenêtre entière (ou l'écran entier lors d'un affichage en plein écran).
pygame.display.flip(): Celle-là fait la même chose mais devrait être celle utilisée si vous utilisez l'accélération matérielle en double tampon (doublebuffer), que vous n'avez pas, ainsi sur...
pygame.display.update (un rectangle ou une liste de rectangles): Cette dernière actualise uniquement les zones rectangulaires de l'écran que vous avez spécifiées.

La plupart des personnes débutantes en programmation graphique utilisent la première : ils mettent à jour la totalité de l'écran à chaque image. Le problème est que c'est inacceptablement lent pour la plupart des personnes. Appeler update() prends 35 millisecondes sur ma machine, ce qui n'est pas énorme, jusqu'à ce que vous réalisiez que 1000 ms / 3 5ms = 28 images par secondes maximum. Et ceci sans la logique de jeu, sans blits, sans entrées, sans intelligence artificielle, sans rien. Je n'ai simplement fait qu'actualiser l'écran et 28 images par secondes est mon taux maximal. Hum...

La solution est appelée dirty rect animation. Au lieu d'actualiser l'écran entier à chaque image, seule la partie qui a changé depuis la dernière image est actualisée. J'obtiens ceci en suivant ces rectangles dans une liste, ensuite j'appelle update(the_dirty_rectangles) à la fin de l'image. En détail, pour le déplacement d'un sprite, je :

Blit une partie de l'arrière-plan sur l'emplacement actuel du sprite, ce qui l'efface.
Ajoute le rectangle de l'emplacement actuel du sprite dans une liste appelée dirty_rects[].
Déplace le sprite.
Dessine le sprite sur son nouvel emplacement.
Ajoute le nouvel emplacement du sprite sur ma liste de dirty_rects.
Appelle la fonction display.update(dirty_rects).

La différence de vitesse est stupéfiante. En considérant que Solarwolf possède des douzaines de sprites en mouvement mis à jour de façon fluide et qu'il lui reste encore assez de temps pour afficher un champ d'étoiles en parallax en arrière-plan et l'actualiser lui aussi.

Il existe deux cas où cette technique ne fonctionne pas. Le premier est lorsque la fenêtre ou l'écran entier doit être actualisé entièrement : pensez à un moteur de scrolling fluide comme une vue aérienne de jeu de stratégie en temps réel ou un jeu à défilement latéral. Alors que faites-vous dans ces cas-là ? Voici la réponse courte : N'écrivez pas ce genre de jeu avec Pygame. La réponse longue est de faire défiler par étapes une grosse quantité de pixels à la fois. N'essayez pas d'obtenir un scrolling parfaitement fluide. Vos joueurs apprécieront un jeu qui défile rapidement et ne vous tiendront pas trop rigueur sur les sauts de l'arrière-plan.

Un dernier mot : tous les jeux ne requièrent pas de fort taux de rafraichissement. Un jeu de stratégie, de style wargame, pourrait facilement s'accommoder de quelques images par secondes ; dans ce cas, la complexité ajoutée par l'animation en dirty_rect ne serait pas nécessaire.

Règle 6 : les surfaces matérielles engendrent plus de problèmes que d'avantages

Si vous avez étudié les différents drapeaux utilisables dans la fonction pygame.display.set_mode(), vous pouvez vous dire: "Aaah, HWSURFACE ! Cool, c'est ce dont j'ai besoin, qui n'utilise pas l'accélération matérielle ? Oooh DOUBLEBUF ! Ca m'a l'air rapide, je pense que je vais l'utiliser aussi !". Ce n'est pas votre faute, nous avons été habitués, par les jeux 3D, à croire que l'accélération matérielle est meilleure et que le rendu logiciel est lent.

Malheureusement, l'accélération matérielle engendre une longue liste d'inconvénients :

Elle ne fonctionne que sur certaines plateformes. Les machines Windows peuvent habituellement accéder aux surfaces matérielles si vous les demandez. La plupart des autres plateformes ne le peuvent pas. Linux, par exemple, est capable de fournir des surfaces matérielles si Xorg4 est installé, si DGA2 fonctionne correctement et que les lunes sont correctement alignées (NdT : Ce guide doit dater un peu, ça fait quelques temps que les pilotes sont devenus potables. Don't feed the troll ;)). Si les surfaces matérielles ne sont pas disponibles, la SDL vous fournira une surface logicielle à la place.
Elle fonctionne uniquement en plein écran.
Elle complique les accès aux pixels. Si vous avez une surface matérielle, vous avez besoin de la verrouiller avant d'écrire ou de lire la valeur d'un seul pixel de celle-ci. Si vous ne le faites pas, de mauvaises choses arriveront. Alors vous devrez rapidement déverrouiller la surface, avant que l'OS s'embrouille et commence à paniquer. La plupart de ces processus sont automatisés par Pygame, mais ce sont des éléments à prendre en compte.
Vous perdez le pointeur de la souris. Si vous spécifiez HWSURFACE (et que vous l'obtenez), votre pointeur va simplement s'évaporer (ou pire, s'accrocher à droite ou à gauche et commencer à scintiller). Vous aurez besoin de créer un sprite pour le pointeur de la souris, et vous aurez besoin de faire attention à l'accélération du pointeur et à sa sensibilité. Que de complications...
Toutefois, ce pourra toujours être lent. La plupart des pilotes ne sont pas accélérés pour le type de tracé que nous faisons et puisque que tout doit être blité à travers le bus vidéo (à moins que vous ne puissiez fourrer votre surface source dans la mémoire vidéo aussi), ça pourra finir par être aussi lent qu'un accès logiciel.

Le rendu matériel garde son utilité. Il fonctionne de manière fiable sous Windows ; si vous n'êtes pas intéressé par des performances multi-plateforme, il peut vous fournir une augmentation de vitesse substantielle. Cependant, il a un coût : augmenter les maux de têtes et la complexité. Il est préférable de conserver les bonnes vieilles SWSURFACES fiables, jusqu'à ce que vous soyez certains de ce que vous faites.

Règle 7 : ne soyez pas distrait par des questions secondaires

Parfois, les programmeurs de jeux débutants passent énormément de temps à se soucier de questions qui ne sont pas vraiment critiques pour le succès de leur jeu. Le désir de satisfaire des objectifs secondaires est compréhensible mais au début du processus de la création d'un jeu, vous ne pouvez pas savoir quelles sont les questions importantes, sans parler des réponses que vous devrez choisir. Le résultat peut engendrer de nombreuses tergiversations inutiles.

Par exemple, considérons la question : comment organiser les fichiers de vos graphismes. Est-ce que chaque image devrait avoir son propre fichier ? ou chaque sprite ? Peut-être que tous les graphismes devraient être zippés dans une archive ? Énormément de temps a été perdu pour beaucoup de projets en posant ces questions sur des listes de diffusion, en débattant des réponses, en peaufinant, etc. Ce ne sont que des questions secondaires, chaque instant passé à discuter devrait être passé à coder le jeu.

En résumé, il est de loin préférable de mettre en œuvre une assez bonne solution avec succès, plutôt que de tenter en vain une solution parfaite que l'on ne sait pas comment coder.

Règle 8 : les Rects sont vos amis

L'enveloppe de Pete Shinner (Pygame) peut fournir de beaux effets de transparence et de bonnes vitesse de blit mais je dois admettre que ma partie préférée de Pygame est la modeste classe Rect. Un rect est un simple rectangle, défini par la position de son coin supérieur gauche, sa largeur et sa hauteur. Beaucoup de fonctions de Pygame prennent des rects en arguments ou des styles de rects, ou encore des séquences qui ont les mêmes valeurs qu'un rect. Ainsi, si je veux un rectangle qui définit une zone entre 10, 20 et 40, 50, je peux faire une des choses suivantes :

rect = pygame.Rect(10, 20, 30, 30)
rect = pygame.Rect((10, 20, 30, 30))
rect = pygame.Rect((10, 20), (30, 30))
rect = (10, 20, 30, 30)
rect = ((10, 20, 30, 30))

Si vous utilisez une des trois premières versions, quelle qu'elle soit, vous aurez accès aux fonctions utilitaires des Rects. Elles incluent les fonctions de déplacement, de diminution et d'agrandissement des rects, de recherche de l'union de deux rects, et d'une variété de fonctions de détection de collision.

Par exemple, je suppose que j'aimerais obtenir une liste de tous les sprites qui contiennent le point (x, y), peut-être que le joueur a cliqué ici, ou peut-être est-ce l'emplacement actuel d'une balle. C'est très simple si chaque sprite possède un attribut rect, je n'ai qu'à faire :

sprites_clicked = [sprite for sprite in toute_ma_liste_de_sprites if sprite.rect.collidepoint(x, y)]

Les Rects n'ont avec les surfaces ou les fonctions graphiques aucune autre relation que le fait de les utiliser comme arguments. Vous pouvez les utiliser à des endroits qui n'ont rien à voir avec le graphisme mais que vous avez besoin de définir comme des rectangles. À chaque projet, je découvre de nouvelles façons d'utiliser des rects, là où je n'avais jamais pensé en avoir besoin.

Règle 9 : ne vous tracassez pas avec une détection de collision au pixel près

Vous avez donc vos sprites qui se déplacent et vous avez besoin de savoir s'ils entrent en collision ou non. Vous pouvez tenter d'écrire quelque chose comme ceci :

Vérifier si les rects entrent en collision. Sinon, les ignorer.
Pour chaque pixel qui se chevauche avec un autre, voir si les pixels correspondant des deux sprites sont opaques. Si oui, il y a collision.

Il existe d'autres solutions, en ajoutant des masques de sprites, mais comme vous devez le faire dans Pygame, ce sera probablement trop lent. Pour la plupart des jeux, il sera préférable de tester une collision de sous-rect : en créant un rect pour chaque sprite qui sera un peu plus petit que l'image actuelle et l'utiliser pour les collisions. Ce sera bien plus rapide et dans la plupart des cas, le joueur ne vous tiendra pas rigueur de l'imprécision.

Règle 10 : gestion du sous-système d'évènements

Le système d'évènements de Pygame est quelque peu complexe. Il existe en fait deux manières différentes de savoir ce que fait un périphérique d'entrée (clavier, souris, joystick).

Le premier est de contrôler directement l'état du périphérique. Vous réalisez ceci en appelant pygame.mouse.get_pos() ou pygame.key.get_pressed(). Ceci vous donnera l'état du périphérique au moment de l'appel de la fonction.

La seconde méthode utilise la file d'évènement de la SDL. Cette file est une liste d'évènements : les évènements sont ajoutés à la suite de la file lorsqu'ils sont détectés et ils sont effacés de la file lorsqu'ils ont été consultés.

Il existe des avantages et des inconvénients pour chaque système. Le contrôle d'état (système 1) vous donne la précision : vous savez exactement quelle entrée a été effectuée ; si mouse.get_pressed([0]) est vrai, cela signifie que le bouton gauche de la souris est actuellement enfoncé. La file d'évènements, elle, ne fait que rapporter que le bouton de la souris a été enfoncé à un certain moment dans le passé. Si vous vérifiez la file relativement souvent, ça fonctionnera, mais si vous tardez à la consulter, la latence peut s'agrandir. Un autre avantage du système de contrôle d'état est qu'il détecte facilement les accords de touches, qui sont plusieurs états au même moment. Si vous voulez savoir si les touches T et F sont pressé en même temps, il suffit de vérifier :

if (key.get_pressed[K_t] and key.get_pressed[K_f]):
     print "Yup!"

Toutefois, dans le système de file, chaque pression de touche entre dans la file comme un évènement complètement séparé ; ainsi, vous devez vous rappeler que la touche T est enfoncée et n'a pas encore été relâchée lorsque vous contrôlez l'état de la touche F. Un peu plus complexe.

Le système d'état possède toutefois une grande faiblesse. Il rapporte seulement quel est l'état d'un périphérique au moment où il est appelé. Si l'utilisateur enfonce le bouton de la souris et qu'il le relâche juste avant que l'appel à mouse.get_pressed() soit fait, le bouton de la souris retournera 0. La fonction get_pressed() rate complètement la pression du bouton de la souris. Les deux évènements, MOUSEBUTTONDOWN et MOUSEBUTTONUP seront toutefois toujours dans la file d'évènements, attendant d'être retrouvés et mis en application.

La leçon à retenir est : choisissez le système qui convient à vos besoins. Si vous n'avez pas beaucoup de continuité dans votre boucle, c'est-à-dire que vous attendez une entrée, dans une boucle while 1:, utilisez la fonction get_pressed() ou une autre fonction d'état, la latence sera réduite. D'un autre côté, si toutes les touches enfoncées sont cruciales, mais que la latence n'est pas importante, comme par exemple si l'utilisateur est en train d'écrire quelque chose dans une boite d'édition, utilisez la file d'évènements. Certaines pressions de touches pourront être un peu en retard mais au final, vous les aurez toutes.

Un mot à propos de la différence entre les fonctions event.poll() et event.wait() :

poll() peut sembler meilleure puisqu'elle n'interdit pas votre programme de faire autre chose que d'attendre une entrée.
wait() suspend la programme jusqu'à ce qu'un évènement soit reçu.

Toutefois, poll() utilisera 100% de la charge du processeur lors de son fonctionnement et il remplira la file d'évènements avec des NOEVENTS. Préférer l'utilisation de la fonction set_blocked() pour sélectionner uniquement les types d'évènements qui vous intéressent, votre file n'en sera que plus gérable.

Règle 11 : Couleur Clé contre Transparence Alpha

Il y existe de nombreuses confusions autour de ces deux techniques et beaucoup proviennent de la terminologie utilisée.

Le blit par Couleur Clé implique de dire à Pygame que, dans une certaine image, tous les pixels d'une certaine couleur (la Couleur Clé en question) apparaîtront comme transparents au lieu de s'afficher dans leur vraie couleur. C'est de cette façon que l'on crée un sprite qui n’apparaît pas dans un rectangle. Il suffit d'appeler la fonction surface.set_colorkey(color), où color est un 3-uplets RGB, comme par exemple (0,0,0). Ceci fera que tous les pixels noirs de l'image source apparaîtront comme transparents.

La Transparence Alpha est différente et implique deux gestions différentes. Image Alpha s'applique à toute l'image et correspond probablement à ce que vous désirez. Connu aussi sous le nom de translucidité, le canal alpha applique à chaque pixel de l'image source une opacité partielle. Par exemple, si vous définissez le canal alpha d'une surface à 192, et que vous le blitez sur un arrière-plan, 3/4 de la couleur de chaque pixel proviendra de l'image source et 1/4 de l'arrière-plan. Le canal alpha se mesure de 255 à 0, où 0 est complètement transparent et 255 est complètement opaque. À noter que la Couleur Clé et le blit Transparence Alpha peuvent être combinés : cela produit une image complètement transparente sur certains pixels et semi-transparente sur d'autres.

La Transparence Alpha par Pixel est la seconde gestion du canal alpha, elle est plus complexe. Concrètement, chaque pixel d'une image source possède sa propre valeur de canal alpha, de 0 à 255. Chaque pixel peut donc avoir une opacité spécifique lorsqu'il est blités sur un arrière-plan. Ce type d'alpha ne peut pas se combiner avec une couleur clé et il désactive l'autre gestion de la Transparence Alpha. La Transparence Alpha par Pixel est rarement utilisée dans les jeux et pour l'utiliser vous devez enregistrer vos images sources à l'aide d'un éditeur graphique qui gère le canal alpha. C'est compliqué, ne l'utilisez pas pour l'instant.

Règle 12 : faites les choses de manière Pythonique

Un dernier mot (ce n'est pas le moins important, c'est seulement le dernier). Pygame est une enveloppe plutôt légère de la SDL, qui elle-même est une enveloppe plutôt légère des appels graphiques de votre OS. Si votre code est encore lent et que vous avez appliqué les choses que j'ai mentionnée plus haut, il y a de fortes chances que le problème vienne de la façon dont vous avez adressé vos données en Python. En Python, certains idiomes resteront lents, quoi que vous fassiez. Heureusement, Python est un langage très clair - Si une partie du code vous semble maladroite ou difficile à manier, il y a de fortes chances qu'elle puisse être optimisée en vitesse. Lisez Python Performance Tips pour trouver de précieux conseils sur la façon dont vous pouvez augmenter la vitesse de votre code. Ceci dit, une optimisation prématurée est foncièrement mauvaise, si ce n'est pas assez rapide, ne torturez pas le code pour l'accélérer. Certaines choses ne sont pas censées l'être :)

Alors voilà, maintenant vous en savez pratiquement autant que moi sur l'utilisation Pygame, allez donc écrire votre jeu !

David Clark est un utilisateur avide de Pygame et l'éditeur du Pygame Code Repository, une vitrine de codes de jeu Python soumis à la communauté. C'est également l'auteur de Twitch, un jeu d'arcade entièrement fait avec Pygame.