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. 
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 codice_2. 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 codice_2. Vous pouvez créer une surface qui contient une image en utilisant codice_4 ou du texte avec codice_5. Vous pouvez également créer une surface qui ne contient rien du tout avec codice_6.
La plupart des fonctions de manipulation de surface ne sont pas d'une utilité critique. Apprenez seulement codice_7, codice_8, codice_9 et codice_10 et tout ira bien.
Règle 4 : utilisez "surface.convert()".
Quand j'ai commencé à lire la documentation de codice_11, 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 codice_12. J'ai réalisé que j'avais vraiment, vraiment tort.
Le "format" auquel codice_12 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 codice_12 est nécessaire si vous ne voulez pas que votre affichage soit ralenti inutilement.
Comment devez-vous utiliser codice_12 ? Appelez-la après avoir créé une surface avec la fonction codice_4. 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 codice_12.
Les seules fois où vous ne voudrez pas utiliser la fonction codice_12, 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 codice_12.
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 codice_20. 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 codice_20. Il existe trois manières d'appeler cette fonction :
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 codice_22 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 codice_23 à la fin de l'image. En détail, pour le déplacement d'un sprite, je :
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 codice_2, 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 :
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 codice_28. Un codice_29 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 codice_30 en arguments ou des styles de codice_30, ou encore des séquences qui ont les mêmes valeurs qu'un codice_29. 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 codice_33. Elles incluent les fonctions de déplacement, de diminution et d'agrandissement des codice_30, de recherche de l'union de deux codice_30, 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 codice_36, 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 codice_29, je n'ai qu'à faire :
sprites_clicked = [sprite for sprite in toute_ma_liste_de_sprites if sprite.rect.collidepoint(x, y)]
Les codice_33 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 codice_30, 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 :
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 codice_29 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 codice_41 ou codice_42. 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 codice_43 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 et 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 est enfoncée et n'a pas encore été relâchée lorsque vous contrôlez l'état de la touche . 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 à codice_44 soit fait, le bouton de la souris retournera 0. La fonction codice_45 rate complètement la pression du bouton de la souris. Les deux évènements, codice_46 et codice_47 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 codice_48, utilisez la fonction codice_45 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 codice_50 et codice_51 :
Toutefois, codice_52 utilisera 100% de la charge du processeur lors de son fonctionnement et il remplira la file d'évènements avec des codice_55. Préférer l'utilisation de la fonction codice_56 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 codice_57, où codice_58 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.