====== Pyxel ======

Biblioteca de [[informatica:programacion:python|Python]] para desarrollar juegos retro.

Inspirado en consolas retro, aplica varias restricciones como una paleta de 16 colores y 4 canales de audio.


  * [[https://github.com/kitao/pyxel|Repositorio de código]]

===== Características =====

  * Multiplataforma (Windows, Mac, Linux y web)
  * Programable con Python (aunque está hecho en Rust)
  * Paleta de 16 colores
  * 3 bancos de imágenes de 256x256
  * 8 tilemaps de 256x256
  * 4 canales con 64 sonidos diferentes
  * 8 pistas de música combinando cualquier sonido
  * Compatible con teclado, ratón y mando
  * Herramientas para la edición de imágenes y sonidos
  * Bancos, canales y colores extensibles por el usuario
===== Instalación =====

En Linux, sería de la siguiente manera:

<code>
sudo pip3 install -U pyxel
</code>

<WRAP center round info 60%>
Necesario el paquete SDL2 (''libsdl2-dev'' en Ubuntu), Python3 (version 3.8 o superior), y ''python3-pip''
</WRAP>

En Arch Linux, está disponible mediante el paquete ''python-pyxel'', en AUR.

===== Hola, mundo =====

Ejemplo más sencillo que muestra un texto por pantalla:

<code python>
import pyxel

class App:
    def __init__(self):
        pyxel.init(160,120,title="Hello, world")
        pyxel.run(self.update, self.draw)

    def update(self):
        # Se ejecutará 60 veces por segundo (FPS)
        if pyxel.btnp(pyxel.KEY_Q):
            pyxel.quit()

    def draw(self):
        pyxel.cls(0)
        pyxel.text(55, 41, "Hello, world!", 5)

App()
</code>

Si guardamos el fichero como ''main.py'', lo podríamos ejecutar con:

<code>
pyxel run main.py
</code>

==== pyxel.init ====

Esta función inicializa el motor de Pyxel y genera la ventana.

<code python>
pyxel.init(160,120,title="Hello, world")
</code>

La anterior instrucción crea una ventana de 160 x 120 pixeles con el título //Hello, world//.

Firma de la función:

<code>
init(width, height, [title], [fps], [quit_key], [display_scale], [capture_scale], [capture_sec])
</code>

  * ''width'': anchura de la pantalla.
  * ''height'': altura de la pantalla.
  * ''title'': título de la ventana.
  * ''fps'': frames por segundo.
  * ''quit_key'': tecla para cerrar la aplicación.
  * ''display_scale'': 
  * ''capture_scale''
  * ''capture_sec'': duración máxima (segundos) de la captura de vídeo.
==== pyxel.run ====

Esta función inicia la aplicación Pyxel. Necesita recibir por parámetro 2 funciones:

  * ''update'': actualiza los valores del juego (controles, física, etc) en cada //frame//.
  * ''draw'': dibuja elementos en pantalla

<code python>
pyxel.run(self.update, self.draw)
</code>

Por defecto, la función ''update'' se ejecuta 30 veces por segundo.
===== API =====

Todas las funciones disponibles de la API de Pyxel se pueden consultar en:

  * [[https://github.com/kitao/pyxel?tab=readme-ov-file#api-reference|API Reference]]
===== Ejecutar una aplicación =====

Al tratarse de scripts en Python, los juegos hechos con Pyxel se pueden lanzar de la siguiente manera:

<code bash>
python mijuego.py
</code>

También puede ejecutarse con el comando ''pyxel run'':

<code bash>
pyxel run mijuego.py
</code>

Si queremos que Pyxel esté pendiente de los cambios en un directorio y relance el programa cuando esto suceda:

<code bash>
pyxel watch <DIRECTORIO_CON_APLICACION_PYXEL>
</code>

==== Controles durante la ejecución de la aplicación ====

^ Tecla   ^ Descripción  ^
| <kbd>Esc</kbd>  | Cierra la aplicación  |
| <kbd>Alt</kbd> + <kbd>1</kbd>  | Guarda una captura de pantalla en el escritorio  |
| <kbd>Alt</kbd> + <kbd>2</kbd>  | Reinicia el tiempo de inicio de grabación de una captura de vídeo  |
| <kbd>Alt</kbd> + <kbd>3</kbd>  | Guarda una captura de vídeo en el escritorio (de 10 segundos)  |
| <kbd>Alt</kbd> + <kbd>8</kbd>  | Alterna el escalado de pantalla  |
| <kbd>Alt</kbd> + <kbd>9</kbd>  | Cambia entre modos de pantalla (Crisp/Smooth/Retro)  |
| <kbd>Alt</kbd> + <kbd>0</kbd>  | Alterna el monitor de rendimiento (fps/update time/draw time)  |
| <kbd>Alt</kbd> + <kbd>Enter</kbd>  | Alterna pantalla completa  |
| <kbd>Shift</kbd> + <kbd>Alt</kbd> + <kbd>1</kbd> | Guarda el banco de imágenes 0 al escritorio  |
| <kbd>Shift</kbd> + <kbd>Alt</kbd> + <kbd>2</kbd> | Guarda el banco de imágenes 1 al escritorio  |
| <kbd>Shift</kbd> + <kbd>Alt</kbd> + <kbd>3</kbd> | Guarda el banco de imágenes 2 al escritorio  |
| <kbd>Shift</kbd> + <kbd>Alt</kbd> + <kbd>0</kbd> | Guarda la paleta de colores actual en el escritorio  |

===== Distribuir una aplicación =====

==== Paquete Pyxel (pyxapp) ====

Pyxel dispone de un formato propio de distribución multiplataforma. Se crea de la siguiente manera:

<code bash>
pyxel package <DIRECTORIO_APLICACION_PYXEL> <FICHERO_PRINCIPAL>
</code>

Tanto los ficheros con el código como los recursos estarán contenidos en un único fichero.

El paquete creado se puede ejecutar con:

<code bash>
pyxel play <fichero.pyxapp>
</code>

==== Ejecutable Windows ====

<code bash>
pyxel app2exe <fichero.pyxapp>
</code>

<WRAP center round info 60%>
Utiliza [[https://pyinstaller.org/en/stable/|PyInstaller]] para crear el ejecutable
</WRAP>

==== Fichero HTML ====

<code bash>
pyxel app2html <fichero.pyxapp>
</code>

El fichero ''.html'' resultante podremos abrirlo con cualquier navegador y el juego se ejecutará en él.

<WRAP center round info 60%>
Pyxel utiliza [[https://pyodide.org/en/stable/|Pyodide]] para que código Python se pueda ejecutar en un navegador
</WRAP>

===== Pyxel Editor: editor de recursos =====

Pyxel incluye un editor visual desde el que podremos crear recursos:

  * Imágenes (sprites)
  * Tilemap (mapas)
  * Efectos de sonido
  * Música

Para abrir este editor:

<code bash>
pyxel edit <fichero.pyxres>
</code>

<WRAP center round info 60%>
Si no indicamos ningún nombre de fichero, se creará uno con el nombre ''my_resource.pyxres''. 
</WRAP>

==== Editor de imágenes ====

El editor tiene 3 bancos de imágenes (0, 1, 2) con lo que podremos guardar hasta 3 imágenes de 256x256. 

También se puede arrastrar una imagen (PNG, GIF o JPEG) y se mostrará en un banco de imágenes del editor.

==== Editor de mapas ====

El editor de //tilemaps// nos permite hacer mosaicos que luego se utilizarán para crear mapas en el juego.

Podemos hacer mapas a partir de los elementos que hay en los bancos de imágenes.

Podemos tener hasta 7 mapas usando los 3 bancos de imágenes.

==== Editor de sonidos ====

Permite generar hasta 64 sonidos diferentes.

Los sonidos son MIDI y se pueden añadir efectos sobre los sonidos.

===== Colores =====

Por defecto, Pyxel soporta 16 colores que están representados por números enteros (del 0 al 15), pero también se pueden usar constantes definidas en este fichero: https://github.com/kitao/pyxel/blob/main/python/pyxel/__init__.pyi

Por ejemplo:

^ Color  ^ Número  ^ Uso con Pyxel  ^
| Negro  | 0  | ''pyxel.COLOR_BLACK''  |
| Blanco | 7  | ''pyxel.COLOR_WHITE''  |

===== Teclas =====

Se pueden consultar la definición de las teclas, entre otras cosas, en este fichero: https://github.com/kitao/pyxel/blob/main/python/pyxel/__init__.pyi

Por ejemplo:

^ Tecla  ^ Uso con Pyxel  ^
| <kbd>A</kbd>  | ''KEY_A''  |
| <kbd>Q</kbd>  | ''KEY_Q''  |
| <kbd>→</kbd>  | ''KEY_RIGHT''  |
| <kbd>←</kbd>  | ''KEY_LEFT''  |

===== Controles / entrada =====

Desde Pyxel también se puede usar el ratón y mandos (hasta 4 mandos).

Se pueden consultar la definición de las teclas, entre otras cosas, en este fichero: https://github.com/kitao/pyxel/blob/main/python/pyxel/__init__.pyi

Por ejemplo:

^ Tecla  ^ Uso con Pyxel  ^ 
| Botón derecho del ratón  | ''pyxel.MOUSE_BUTTON_RIGHT''  |
| Botón izquierdo del ratón  | ''pyxel.MOUSE_BUTTON_LEFT''  |
| Botón A del primer mando  | ''pyxel.GAMEPAD1_BUTTON_A''  |
| Arriba en el mando 2  | ''pyxel.GAMEPAD2_BUTTON_DPAD_UP''  |
===== Juegos de ejemplo =====

En el repositorio de Pyxel hay varios scripts con ejemplos de juegos que se pueden hacer con esta biblioteca:

  * https://github.com/kitao/pyxel/tree/main/python/pyxel/examples

Se recomienda seguir el siguiente orden para aprender Pyxel: 01, 05, 03, 04, 02.

Otros ejemplos en esta wiki:

   * [[informatica:programacion:python:pyxel:juego_tipo_pong|Pong clon]]
   * [[informatica:programacion:python:pyxel:juego_tipo_breakout|Breakout clon]]
   * [[informatica:programacion:python:pyxel:juego_tipo_endless_runner|Endless Runner clon]]
   * [[informatica:programacion:python:pyxel:juego_tipo_snake|Snake clon]]
   * [[informatica:programacion:python:pyxel:juego_tipo_space_invaders|Space Invaders clon]]
   * [[informatica:programacion:python:pyxel:juego_tipo_tetris|Tetris clon]]
   * [[informatica:programacion:python:pyxel:juego_tipo_flappy_bird|Flappy Bird clon]]


===== Recursos =====

  * https://github.com/kitao/pyxel/wiki/Pyxel-User-Examples
  * https://github.com/shivanju/pyxel-games
  * https://github.com/gonzalocarreterohdz/Super-Mario-Bros-Game
  * https://github.com/dascruz/mario-bros-revisited
  * https://github.com/timbledum/snake
  * https://github.com/nadi726/Rocket-Flight
  * [[https://www.youtube.com/watch?v=Qg16VhEo2Qs|Python Retro Game Tutorial]] (vídeo)
  * [[https://www.youtube.com/watch?v=8Glx88BVMLs|Create a Retro Game with Pyxel in Python (Breakout)]] (vídeo) 
  * [[https://www.youtube.com/watch?v=qcpLwnFNsxA|Taller de Pyxel | Gamejam]] (vídeo)
  * [[https://www.youtube.com/watch?v=Z6-eGh3KJyA|Victor Suarez - Pyxel: Los 8 bits Retro Pythoneros]] (vídeo)
  * [[https://www.youtube.com/watch?v=0g0L5iGKv9g|¡Crea fácilmente juegos retro con Pyxel! ¡Incluso los principiantes pueden hacer juegos en Python!]] (vídeo, audio en japonés, pero hay subtítulos en español)