Référence Pyxel

 **Pyxel** est un moteur de jeu vidéo rétro pour Python. Grâce à ses spécifications simples inspirées par les consoles rétro, comme le fait que seulement 16 couleurs peuvent être affichées et que seulement 4 sons peuvent être lus en même temps, vous pouvez vous sentir libre de créer des jeux vidéo dans le style pixel art.  ## Spécifications - Fonctionne sur Windows, Mac, Linux et Web - Programmable en Python - Palette de 16 couleurs - 3 banques d’images de taille 256x256 - 8 tilemaps (niveaux ou scènes) de taille 256x256 - 4 canaux avec 64 sons configurables - 8 musiques pouvant combiner des sons arbitraires - Entrées clavier, souris et manettes - Éditeur d’images et de sons ## Palette de couleurs   ## Comment utiliser ### Créer une application Pyxel Après avoir importé le module Pyxel dans votre script Python, spécifiez d’abord la taille de la fenêtre avec la fonction `init`, puis lancez l’application Pyxel avec la fonction `run`. ```python import pyxel pyxel.init(160, 120) def update(): if pyxel.btnp(pyxel.KEY_Q): pyxel.quit() def draw(): pyxel.cls(0) pyxel.rect(10, 10, 20, 20, 11) pyxel.run(update, draw) ``` Les arguments de la fonction `run` sont la fonction `update` pour mettre à jour chaque frame et la fonction `draw` pour dessiner sur l’écran quand c’est nécessaire. Dans une vraie application, il est recommandé de mettre le code Pyxel dans une classe comme ci-dessous : ```python import pyxel class App: def __init__(self): pyxel.init(160, 120) self.x = 0 pyxel.run(self.update, self.draw) def update(self): self.x = (self.x + 1) % pyxel.width def draw(self): pyxel.cls(0) pyxel.rect(self.x, 0, 8, 8, 9) App() ``` Lors de la création de graphiques simples sans animation, la fonction `show` peut être utilisée pour rendre le code plus concis. ```python import pyxel pyxel.init(120, 120) pyxel.cls(1) pyxel.circb(60, 60, 40, 7) pyxel.show() ``` ### Lancer une application Pyxel Le script Python créé peut être lancé en utilisant la commande suivante : ```sh pyxel run PYTHON_SCRIPT_FILE ``` Il peut également être exécuté comme un script Python normal : ```sh python3 PYTHON_SCRIPT_FILE ``` ### Contrôles spéciaux Les contrôles spéciaux suivants peuvent être lancés pendant qu’une application Pyxel tourne : - `Esc`
Quitte l’application - `Alt(Option)+1`
Sauvegarde la capture d’écran sur le bureau - `Alt(Option)+2`
Réinitialise le temps de départ de la capture vidéo - `Alt(Option)+3`
Sauvegarde la capture d’écran sur le bureau (jusqu’à 10 secondes) - `Alt(Option)+9`
Passer d'un mode d'écran à l'autre (Crisp, Smooth, Retro) - `Alt(Option)+0`
Bascule vers le moniteur de performance (fps, temps de mise à jour et temps de dessin) - `Alt(Option)+Enter`
Met en plein écran - `Shift+Alt(Option)+1/2/3`
Enregistrer la banque d'images correspondante sur le bureau - `Shift+Alt(Option)+0`
Enregistrer la palette de couleurs actuelle sur le bureau ### Comment créer une ressource L’éditeur Pyxel peut créer des images et des sons utilisables dans des applications Pyxel. Il se lance avec la commande suivante : ```sh pyxel edit PYXEL_RESOURCE_FILE ``` Si le fichier de ressource Pyxel (.pyxres) existe déjà, le fichier est chargé, sinon, un nouveau fichier avec le nom indiqué est créé. Si le fichier de ressource n’est pas spécifié, le nom est `my_resource.pyxres`. Après avoir lancé l’éditeur Pyxel, le fichier peut être changé en glissant-dépossant un autre fichier de ressource. Si le fichier est glissé-déposé en appuyant sur la touche `Ctrl(Cmd)`, seul le type de la ressource actuellement éditée (Image / Tilemap / Son / Musique) sera chargé. Cette opération permet de combiner plusieurs ressources dans un seul fichier. La ressource créée peut être chargée avec la fonction `load`. L’éditeur Pyxel a les modes suivants. **Éditeur d’images ** Mode pour éditer les banques d’images.  Glisser-déposer un fichier image (PNG/GIF/JPEG) dans l'éditeur d'images pour charger l'image dans la banque d'images actuellement sélectionnée. **Éditeur de tilemap ** Mode pour éditer les tilemaps, dans lesquelles les images des banques d’images sont ordonnées en motifs de tuiles.  Glisser-déposer un fichier TMX (Tiled Map File) dans l'éditeur de mosaïques pour charger sa couche dans l'ordre de dessin correspondant au numéro de la mosaïque sélectionnée. **Éditeur de sons ** Mode pour éditer les sons.  **Éditeur de musiques ** Mode pour éditer les musiques dans lesquelles les sons sont ordonnés par ordre de lecture.  ### Autres méthodes pour créer des ressources Les images et tilemaps Pyxel peuvent être aussi créées avec les méthodes suivantes : - Créer une image depuis une liste de chaînes de caractères avec la fonction `Image.set` ou la fonction `Tilemap.set` - Charger une image (PNG/GIF/JPEG) dans la palette Pyxel avec la fonction `Image.load` Les sons Pyxel peuvent aussi être créés avec la méthode suivante : - Créer un son à partir d’une chaîne de caractères avec la fonction `Sound.set` ou la fonction `Music.set` Référez vous à la documentation de l’API pour l’utilisation de ces fonctions. ### Comment partager une application Pyxels a un format de fichier spécifique (fichier d’application Pyxel) qui fonctionne sur les différentes plateformes. Créez le fichier d’application Pyxel (.pyxapp) avec la commande suivante : ```sh pyxel package APP_DIR STARTUP_SCRIPT_FILE ``` Si l'application doit inclure des ressources ou des modules supplémentaires, placez-les dans le répertoire de l'application. L’application créée peut être exécutée avec la commande suivante : ```sh pyxel play PYXEL_APP_FILE ``` Le fichier d'application Pyxel peut aussi être converti en un exécutable ou un fichier HTML avec les commandes `pyxel app2exe` ou `pyxel app2html`. ## Documentation de l’API ### Système - `width`, `height` La largeur et la hauteur de l’écran - `frame_count` Le nombre de frames passées - `init(width, height, [title], [fps], [quit_key], [display_scale], [capture_scale], [capture_sec])`
Initialise l’application Pyxel avec un écran de taille (`width`, `height`). Il est possible de passer comme options : le titre de la fenêtre avec `title`, le nombre d’images par seconde avec `fps`, la touche pour quitter l’application avec `quit_key`, l'échelle de l'affichage avec `display_scale`, l’échelle des captures d’écran avec `capture_scale`, et le temps maximum d’enregistrement vidéo avec `capture_sec`.
Par exemple : `pyxel.init(160, 120, title="My Pyxel App", fps=60, quit_key=pyxel.KEY_NONE, capture_scale=3, capture_sec=0)` - `run(update, draw)` Lance l’application Pyxel et appelle la fonction `update` et la fonction `draw`. - `show()` Affiche l’écran jusqu’à ce que la touche `Esc` soit appuyée. - `flip()` Rafraîchit l'écran d'une image. L'application se termine lorsque la touche `Esc` est pressée. Cette fonction ne fonctionne pas dans la version web. - `quit()` Quitte l’application Pyxel. ### Ressources - `load(filename, [excl_images], [excl_tilemaps], [excl_sounds], [excl_musics])` Charge la ressource (.pyxres). Si une option est `True`, la ressource ne sera pas chargée. Si un fichier de palette (.pyxpal) du même nom existe au même endroit que le fichier de ressource, la couleur d'affichage de la palette sera également modifiée. Le fichier de palette est une entrée hexadécimale des couleurs d'affichage (par exemple `1100FF`), séparée par des nouvelles lignes. Le fichier de palette peut également être utilisé pour changer les couleurs affichées dans l'éditeur Pyxel. ### Entrées - `mouse_x`, `mouse_y` La position actuelle du curseur de la souris - `mouse_wheel` La valeur actuelle de la molette de la souris - `btn(key)` Renvoie `True` si la touche `key` est appuyée, sinon renvoie `False`. ([liste des touches](__init__.pyi)) - `btnp(key, [hold], [repeat])` Renvoie `True` si la touche `key` est appuyée à cette frame, sinon renvoie `False`. Quand `hold` et `repeat` sont spécifiés, `True` sera renvoyé à l’intervalle de frame `repeat` quand la touche `key` est appuyée pendant plus de `hold` frames. - `btnr(key)` Renvoie `True` si la touche `key` est relâchée à cette frame, sinon renvoie `False` - `mouse(visible)` Si `visible` est `True`, affiche le curseur de la souris. Si `False`, le curseur est caché. Même si le curseur n’est pas affiché, sa position est actualisée. ### Graphiques - `colors` Liste les couleurs de la palette. Les couleurs sont spécifiées avec une valeur 24-bit. Vous pouvez utiliser `colors.from_list` et `colors.to_list` pour directement donner et recevoir une liste Python. Par exemple `old_colors = pyxel.colors.to_list(); pyxel.colors.from_list([0x111111, 0x222222, 0x333333]); pyxel.colors[15] = 0x112233` - `images` Liste des banques d'images (0-2). (Voir la classe Image) Par exemple `pyxel.images[0].load(0, 0, "title.png")` - `tilemaps` Liste des cartes de tuiles (0-7). (voir la classe Tilemap) - `clip(x, y, w, h)` Défini la zone de dessin (`x`, `y`) avec une largeur `w` et une hauteur `h`. Réinitialiser la zone de dessin au plein écran avec `clip()` - `camera(x, y)` Change the upper left corner coordinates of the screen to (`x`, `y`). Reset the upper left corner coordinates to (`0`, `0`) with `camera()`. - `pal(col1, col2)` Remplace la couleur `col1` avec `col2` au dessin. `pal()` pour réinitialiser la palette de couleurs. - `dither(alpha)` Applique le tramage (pseudo-transparence) au dessin. Fixe `alpha` dans l'intervalle 0.0-1.0, où 0.0 est transparent et 1.0 est opaque. - `cls(col)` Efface l’écran avec la couleur `col` - `pget(x, y)` Renvoie la couleur au pixel (`x`, `y`). - `pset(x, y, col)` Dessine un pixel de couleur `col` à (`x`, `y`). - `line(x1, y1, x2, y2, col)` Dessine une ligne de couleur `col` de (`x1`, `y1`) à (`x2`, `y2`). - `rect(x, y, w, h, col)` Dessine un rectangle de largeur `w`, de hauteur `h` et de couleur `col` à partir de (`x`, `y`). - `rectb(x, y, w, h, col)` Dessine les contours d’un rectangle de largeur `w`, de hauteur `h` et de couleur `col` à partir de (`x`, `y`). - `circ(x, y, r, col)` Dessine un cercle de rayon `r` et de couleur `col` à (`x`, `y`). - `circb(x, y, r, col)` Dessine le contour d’un cercle de rayon `r` et de couleur `col` à (`x`, `y`). - `elli(x, y, w, h, col)` Dessinez une ellipse de largeur `w`, de hauteur `h` et de couleur `col` à partir de (`x`, `y`). - `ellib(x, y, w, h, col)` Dessinez le contour d'une ellipse de largeur `w`, de hauteur `h` et de couleur `col` à partir de (`x`, `y`). - `tri(x1, y1, x2, y2, x3, y3, col)` Dessine un triangle avec les sommets (`x1`, `y1`), (`x2`, `y2`), (`x3`, `y3`) et de couleur `col` - `trib(x1, y1, x2, y2, x3, y3, col)` Dessine les contours d’un triangle avec les sommets (`x1`, `y1`), (`x2`, `y2`), (`x3`, `y3`) et de couleur `col` - `fill(x, y, col)` Dessine une ellipse de largeur `w`, de hauteur `h` et de couleur `col` à partir de (`x`, `y`). - `blt(x, y, img, u, v, w, h, [colkey])` Copie la région de taille (`w`, `h`) de (`u`, `v`) de la banque d’image `img`(0-2) à (`x`, `y`). Si une valeur négative est mise pour `w`(ou `h`), la copie sera inversée horizontalement (ou verticalement). Si `colkey` est spécifiée, elle sera traitée comme une couleur transparente.  - `bltm(x, y, tm, u, v, w, h, [colkey])`
Copie la région de taille (`w`, `h`) de (`u`, `v`) de la tilemap `tm`(0-7) à (`x`, `y`). Si une valeur négative est mise pour `w`(ou `h`), la copie sera inversée horizontalement (ou verticalement). Si `colkey` est spécifiée, elle sera traitée comme une couleur transparente. La taille d’une tuile est 8x8 pixels et elle est storée dans une tilemap en tant que paire `(tile_x, tile_y)`.  - `text(x, y, s, col)`
Dessine une chaîne de caractères `s` de couleur `col` à (`x`, `y`). ### Audio - `sounds` Liste des sons (0-63). (voir la classe Sound)
par exemple : `pyxel.sounds[0].speed = 60` - `musics` Liste des musiques (0-7). (voir la classe Music) - `play(ch, snd, [tick], [loop])` Joue le son `snd`(0-63) sur le canal `ch`(0-3). Si `snd` est une liste, les sons seront joués dans l’ordre. La position de début de lecture peut être spécifiée par `tick`(1 tick = 1/120 secondes). Si `loop` est à `True`, le son est joué en boucle. - `playm(msc, [tick], [loop])` Joue la musique `msc`(0-7). La position de début de lecture peut être spécifiée par `tick`(1 tick = 1/120 secondes). Si `loop` est mis à `True`, la musique est joué en boucle. - `stop([ch])` Arrête le son du canal spécifié `ch`(0-3). `stop()` arrête tous les canaux. - `play_pos(ch)` Récupère la position du son du canal `ch`(0-3) comme un tuple `(sound no, note no)`. Renvoie `None` quand le son est arrêté. ### Mathématiques - `ceil(x)` Renvoie le plus petit nombre entier supérieur ou égal à `x`. - `floor(x)` Renvoie le plus grand nombre entier inférieur ou égal à `x`. - `sgn(x)` Renvoie 1 lorsque `x` est positif, 0 lorsqu'il est nul, et -1 lorsqu'il est négatif. - `sqrt(x)` Renvoie la racine carrée de `x`. - `sin(deg)` Renvoie le sinus de `deg` degrés. - `cos(deg)` Renvoie le cosinus de `deg` degrés. - `atan2(y, x)` Retourne l'arctangente de `y`/`x` en degrés. - `rseed(seed)` Définit la graine du générateur de nombres aléatoires. - `rndi(a, b)` Renvoie un nombre entier aléatoire supérieur ou égal à `a` et inférieur ou égal à `b`. - `rndf(a, b)` Renvoie une décimale aléatoire supérieure ou égale à `a` et inférieure ou égale à `b`. - `nseed(seed)` Définit la graine du bruit de Perlin. - `noise(x, [y], [z])` Renvoie la valeur du bruit de Perlin pour les coordonnées spécifiées. ### Classe Image - `width`, `height` La largeur et la hauteur d’une image - `get(x, y)` Renvoie les données de l’image à (`x`, `y`). - `set(x, y, data)` Met la valeur de l’image à (`x`, `y`) suivant une liste de chaînes. Par exemple `pyxel.images[0].set(10, 10, ["0123", "4567", "89ab", "cdef"])` - `load(x, y, filename)` Charge l’image (PNG/GIF/JPEG) à (`x`, `y`). ### Classe Tilemap - `width`, `height` La largeur et la hauteur de la tilemap - `imgsrc` La banque d’image (0-2) référencée par la tilemap - `set(x, y, data)` Met la tilemap à (`x`, `y`) suivant une liste de chaînes. Par exemple `pyxel.tilemap(0).set(0, 0, ["0000 0100 a0b0", "0001 0101 a1b1"])` - `load(x, y, filename, layer)` Chargez la couche dans l'ordre de dessin `couche`(0-) à partir du fichier TMX (Tiled Map File) à (`x`, `y`). - `pget(x, y)` Renvoie la tile à (`x`, `y`). Une tile est un tuple `(tile_x, tile_y)`. - `pset(x, y, tile)` Dessine une `tile` à (`x`, `y`). Une tile est un tuple `(tile_x, tile_y)`. ### Classe Sound - `notes` Liste des notes (0-127). Plus le nombre est haut, plus la note est haute, et à 33 ça devient 'A2' (440Hz). Le reste est à -1. - `tones` Liste les tons (0:Triangle / 1:Square / 2:Pulse / 3:Noise) - `volumes` Liste les volumes (0-7) - `effects` Liste les effets (0:None / 1:Slide / 2:Vibrato / 3:FadeOut) - `speed` Vitesse de lecture. 1 est le plus rapide, et plus le nombre est grand, plus la vitesse est lente. à 120, la longueur d’une note est de 1 second. - `set(notes, tones, volumes, effects, speed)` Met les valeurs de notes, tones, volumes et effects avec une chaîne. Si les tons, volumes et effets sont plus courts que les notes, ils sont répétés depuis le début. - `set_notes(notes)` Met les notes avec une chaîne de 'CDEFGAB'+'#-'+'01234' ou 'R'. Insensible à la casse et les espaces sont ignorés.
Par exemple `pyxel.sounds[0].set_notes("G2B-2D3R RF3F3F3")` - `set_tones(tones)` Met les tons avec une chaîne de 'TSPN'. Insensible à la casse et les espaces sont ignorés.
Par exemple `pyxel.sounds[0].set_tones("TTSS PPPN")` - `set_volumes(volumes)` Met les volumes avec une chaîne de '01234567'. Insensible à la casse et les espaces sont ignorés.
Par exemple `pyxel.sounds[0].set_volumes("7777 7531")` - `set_effects(effects)` Met les effets avec une chaîne de 'NSVF'. Insensible à la casse et les espaces sont ignorés.
Par exemple `pyxel.sounds[0].set_effects("NFNF NVVS")` ### Classe Music - `seqs` Liste bidimensionnelle de sons (0-63) avec le nombre de canaux - `set(seq0, seq1, seq2, ...)` Régler les listes de sons (0-63) des canaux. Si une liste vide est passée, ce canal n’est pas utilisé. Par exemple `pyxel.musics[0].set([0, 1], [], [3])` ### API avancée Pyxel a une "API avancée" qui n’est pas présentée ici car elle peut porter à confusion ou qu’elle nécessite des connaissances spécifiques pour être utilisée. Si vous savez ce que vous faîtes, essayez de créer des applications incroyables avec [ceci](__init__.pyi) comme indice !