Guide du débutant

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édias 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 ce document 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édécesseur 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.

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, le langage que vous utilisez ne vous est pas familier.

• Écrivez quelques programmes non graphiques en Python :
  • un analyseur de fichiers textes ;
  • un jeu en texte ;
  • un programme à entrée journalière ou d'autres choses de ce style.
• Soyez à l'aise avec la manipulation des chaînes de caractères et des listes : sachez comment les découper et combiner les listes et les chaînes.
• Apprenez comment réutiliser le travail : essayez d'écrire un programme qui utilise plusieurs fichiers source 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îne 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-list, 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.

Étudier le fatras des classes indiquées dans l'index de la documentation de Pygame peut être vraiment déroutant. La chose importante 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 seront pas utilisées dans un premier temps : en un an, je n'ai pas touché aux modules Channel, Joystick, Cursors, Userrect, Surfarray et leurs différentes fonctions.

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 vous pouvez créer une surface qui contient 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.

Quand j'ai commencé à lire la documentation de surface.convert(), je pensais ne pas en avoir besoin. J'utilisais exclusivement le format PNG pour ne pas avoir de problème de format d'image et donc que 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/…). Ça 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 n'avez besoin de 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 6 x 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 - par exemple lorsque vous écrivez un logiciel de conversion d'image ou similaire, 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().

La cause principale d'un taux d'images inadéquates 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 et fera aussi la bonne chose si vous utilisez l'accélération matérielle en double tampon (doublebuffer), que vous n'avez pas, donc… ;

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 : elles mettent à jour la totalité de l'écran à chaque image. Le problème est que c'est extraordinairement 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 / 35 ms = 28 images par seconde 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 seconde 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 conservant 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 :

1. copie une partie de l'arrière-plan sur l'emplacement actuel du sprite, ce qui l'efface ;
2. ajoute le rectangle de l'emplacement actuel du sprite dans une liste appelée dirty_rects[] ;
3. déplace le sprite ;
4. dessine le sprite sur son nouvel emplacement ;
5. ajoute le nouvel emplacement du sprite sur ma liste de dirty_rects ;
6. appelle la fonction display.update(dirty_rects).

La différence en 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 parallaxe 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 rafraîchissement. Un jeu de stratégie, de style wargame, pourrait facilement s'accommoder de quelques images par seconde, dans ce cas, la complexité ajoutée par l'animation en dirty_rect ne serait pas nécessaire.

Si vous avez étudié les différentes options 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 ! Ça 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, n'est capable de fournir des surfaces matérielles que si Xorg4 est installé, si DGA2 fonctionne correctement, et que les lunes sont correctement alignées(1). 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 verrouiller la surface 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 le système d'exploitation 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, cela pourra être toujours 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 copié à 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 multiplateformes, il peut vous fournir une augmentation substantielle de vitesse. Cependant, il a un coût : augmenter les maux de tête 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.

Quelquefois, les programmeurs de jeux débutants passent énormément de temps à se soucier de questions qui ne sont pas vraiment critiques au 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 sur 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 d'avoir une assez bonne solution qui soit mise en œuvre, plutôt qu'une solution parfaite que vous ne savez pas comment coder.

L'enveloppe de Pete Shinner (Pygame) peut fournir de beaux effets de transparence et de bonnes vitesses 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 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 aucune relation avec les surfaces ou les fonctions graphiques, autre que le fait qu'ils les utilisent 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.

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

1. Vérifier si les rects entrent en collision. Sinon, les ignorer ;
2. Pour chaque pixel qui se chevauche, voir si les pixels correspondant aux 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.

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 à la fonction.

La seconde méthode utilise la file d'évènements 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 y a 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, ça 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ées 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. C'est 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, 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 finalement, 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.

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'apparaisse pas dans un rectangle. Il suffit d'appeler la fonction surface.set_colorkey(color), où color est un 3-uplets RGB, comme (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. L'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 copiez 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 qui est complètement transparente sur certains pixels et semi-transparente sur d'autres.

La transparence alpha par pixel est la seconde gestion du canal alpha et 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é différente lorsqu'il est blité 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.

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 système. Si votre code est encore lent et que vous avez appliqué les choses que j'ai mentionnées 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 de Pygame. Maintenant, allez é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.

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

Cette traduction est aussi disponible sur Wikibooks. La liste des contributeurs est disponible ici.

Merci à ClaudeLELOUP pour sa relecture orthographique.