Home

Awesome

<img src="docs/images/pyxel_logo_152x64.png">

Downloads GitHub Repo stars GitHub forks GitHub Sponsors

ko-fi

[ English | 中文 | Deutsch | Español | Français | Italiano | 日本語 | 한국어 | Português | Русский | Türkçe | Українська ]

Pyxel is a retro game engine for Python.

With simple specifications inspired by retro gaming consoles, such as displaying only 16 colors and supporting 4 sound channels, you can easily enjoy making pixel-art-style games.

<img src="docs/images/pyxel_message.png" width="480">

The development of Pyxel is driven by user feedback. Please give Pyxel a star on GitHub!

<p> <a href="https://kitao.github.io/pyxel/wasm/examples/10_platformer.html"> <img src="docs/images/10_platformer.gif" width="290"> </a> <a href="https://kitao.github.io/pyxel/wasm/examples/30sec_of_daylight.html"> <img src="docs/images/30sec_of_daylight.gif" width="350"> </a> <a href="https://kitao.github.io/pyxel/wasm/examples/02_jump_game.html"> <img src="docs/images/02_jump_game.gif" width="330"> </a> <a href="https://kitao.github.io/pyxel/wasm/examples/megaball.html"> <img src="docs/images/megaball.gif" width="310"> </a> <a href="https://kitao.github.io/pyxel/wasm/examples/image_editor.html"> <img src="docs/images/image_tilemap_editor.gif" width="320"> </a> <a href="https://kitao.github.io/pyxel/wasm/examples/sound_editor.html"> <img src="docs/images/sound_music_editor.gif" width="320"> </a> </p>

Pyxel's specifications and APIs are inspired by PICO-8 and TIC-80.

Pyxel is open source under the MIT License and free to use. Let's start making retro games with Pyxel!

Specifications

Color Palette

<img src="docs/images/05_color_palette.png"> <img src="docs/images/pyxel_palette.png">

How to Install

Windows

After installing Python3 (version 3.8 or higher), run the following command:

pip install -U pyxel

When installing Python using the official installer, make sure to check the Add Python 3.x to PATH option to enable the pyxel command.

Mac

After installing Homebrew, run the following commands:

brew install pipx
pipx ensurepath
pipx install pyxel

To upgrade Pyxel after installation, run pipx upgrade pyxel.

Linux

After installing the SDL2 package (libsdl2-dev for Ubuntu), Python3 (version 3.8 or higher), and python3-pip, run the following command:

sudo pip3 install -U pyxel

If the previous command fails, consider building Pyxel from source by following the instructions in the Makefile.

Web

The web version of Pyxel does not require Python or Pyxel installation and runs on PCs, smartphones, and tablets with supported web browsers.

For detailed instructions, please refer to this page.

Try Examples

After installing Pyxel, you can copy the examples to the current directory with the following command:

pyxel copy_examples

The following examples will be copied to your current directory:

<table> <tr> <td>01_hello_pyxel.py</td> <td>Simplest application</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/01_hello_pyxel.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/01_hello_pyxel.py">Code</a></td> </tr> <tr> <td>02_jump_game.py</td> <td>Jump game with Pyxel resource file</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/02_jump_game.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/02_jump_game.py">Code</a></td> </tr> <tr> <td>03_draw_api.py</td> <td>Demonstration of drawing APIs</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/03_draw_api.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/03_draw_api.py">Code</a></td> </tr> <tr> <td>04_sound_api.py</td> <td>Demonstration of sound APIs</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/04_sound_api.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/04_sound_api.py">Code</a></td> </tr> <tr> <td>05_color_palette.py</td> <td>Color palette list</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/05_color_palette.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/05_color_palette.py">Code</a></td> </tr> <tr> <td>06_click_game.py</td> <td>Mouse click game</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/06_click_game.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/06_click_game.py">Code</a></td> </tr> <tr> <td>07_snake.py</td> <td>Snake game with BGM</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/07_snake.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/07_snake.py">Code</a></td> </tr> <tr> <td>08_triangle_api.py</td> <td>Demonstration of triangle drawing APIs</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/08_triangle_api.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/08_triangle_api.py">Code</a></td> </tr> <tr> <td>09_shooter.py</td> <td>Shoot'em up game with screen transitions</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/09_shooter.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/09_shooter.py">Code</a></td> </tr> <tr> <td>10_platformer.py</td> <td>Side-scrolling platform game with map</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/10_platformer.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/10_platformer.py">Code</a></td> </tr> <tr> <td>11_offscreen.py</td> <td>Offscreen rendering with Image class</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/11_offscreen.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/11_offscreen.py">Code</a></td> </tr> <tr> <td>12_perlin_noise.py</td> <td>Perlin noise animation</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/12_perlin_noise.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/12_perlin_noise.py">Code</a></td> </tr> <tr> <td>13_bitmap_font.py</td> <td>Drawing a bitmap font</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/13_bitmap_font.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/13_bitmap_font.py">Code</a></td> </tr> <tr> <td>14_synthesizer.py</td> <td>Synthesizer using audio expansion features</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/14_synthesizer.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/14_synthesizer.py">Code</a></td> </tr> <tr> <td>15_tiled_map_file.py</td> <td>Loading and drawing a Tile Map File (.tmx)</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/15_tiled_map_file.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/15_tiled_map_file.py">Code</a></td> </tr> <tr> <td>16_transform.py</td> <td>Image rotation and scaling</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/16_transform.html">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/16_transform.py">Code</a></td> </tr> <tr> <td>99_flip_animation.py</td> <td>Animation with flip function (non-web platforms only)</td> <td><a href="https://github.com/kitao/pyxel/blob/main/docs/images/99_flip_animation.gif">Demo</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/99_flip_animation.py">Code</a></td> </tr> <tr> <td>30sec_of_daylight.pyxapp</td> <td>1st Pyxel Jam winning game by <a href="https://x.com/helpcomputer0">Adam</a></td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/30sec_of_daylight.html">Demo</a></td> <td><a href="https://github.com/kitao/30sec_of_daylight">Code</a></td> </tr> <tr> <td>megaball.pyxapp</td> <td>Arcade ball physics game by <a href="https://x.com/helpcomputer0">Adam</a></td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/megaball.html">Demo</a></td> <td><a href="https://github.com/helpcomputer/megaball">Code</a></td> </tr> <tr> <td>8bit-bgm-gen.pyxapp</td> <td>Background music generator by <a href="https://x.com/frenchbread1222">frenchbread</a></td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/8bit-bgm-gen.html">Demo</a></td> <td><a href="https://github.com/shiromofufactory/8bit-bgm-generator">Code</a></td> </tr> </table>

The examples can be executed with the following commands:

cd pyxel_examples
pyxel run 01_hello_pyxel.py
pyxel play 30sec_of_daylight.pyxapp

How to Use

Create Application

In your Python script, import the Pyxel module, specify the window size with the init function, and then start the Pyxel application with the run function.

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)

The arguments of the run function are the update function, which processes frame updates, and the draw function, which handles screen drawing.

In an actual application, it is recommended to wrap Pyxel code in a class, as shown below:

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()

For creating simple graphics without animation, you can use the show function to simplify your code.

import pyxel

pyxel.init(120, 120)
pyxel.cls(1)
pyxel.circb(60, 60, 40, 7)
pyxel.show()

Run Application

A created script can be executed using the python command:

python PYTHON_SCRIPT_FILE

It can also be run with the pyxel run command:

pyxel run PYTHON_SCRIPT_FILE

Additionally, the pyxel watch command monitors changes in a specified directory and automatically re-runs the program when changes are detected:

pyxel watch WATCH_DIR PYTHON_SCRIPT_FILE

Directory monitoring can be stopped by pressing Ctrl(Command)+C.

Special Key Controls

The following special key actions are available while a Pyxel application is running:

How to Create Resources

Pyxel Editor can create images and sounds used in a Pyxel application.

You can start Pyxel Editor with the following command:

pyxel edit PYXEL_RESOURCE_FILE

If the specified Pyxel resource file (.pyxres) exists, it will be loaded. If it does not exist, a new file with the specified name will be created. If the resource file is omitted, a new file named my_resource.pyxres will be created.

After starting Pyxel Editor, you can switch to another resource file by dragging and dropping it onto Pyxel Editor.

The created resource file can be loaded using the load function.

Pyxel Editor has the following editing modes.

Image Editor

The mode for editing the image in each image bank.

<a href="https://kitao.github.io/pyxel/wasm/examples/image_editor.html"> <img src="docs/images/image_editor.gif"> </a>

You can drag and drop an image file (PNG/GIF/JPEG) into the image editor to load the image into the currently selected image bank.

Tilemap Editor

The mode for editing tilemaps that arrange images from the image banks in a tile pattern.

<a href="https://kitao.github.io/pyxel/wasm/examples/tilemap_editor.html"> <img src="docs/images/tilemap_editor.gif"> </a>

Drag and drop a TMX file (Tiled Map File) onto the tilemap editor to load its layer in the drawing order that corresponds to the currently selected tilemap number.

Sound Editor

The mode for editing sounds used for melodies and sound effects.

<a href="https://kitao.github.io/pyxel/wasm/examples/sound_editor.html"> <img src="docs/images/sound_editor.gif"> </a>

Music Editor

The mode for editing musics in which the sounds are arranged in order of playback.

<a href="https://kitao.github.io/pyxel/wasm/examples/music_editor.html"> <img src="docs/images/music_editor.gif"> </a>

Other Resource Creation Methods

Pyxel images and tilemaps can also be created using the following methods:

Pyxel sounds can also be created using the following method:

Refer to the API reference for the usage of these functions.

How to Distribute Applications

Pyxel supports a dedicated application distribution file format (Pyxel application file) that is cross-platform.

A Pyxel application file (.pyxapp) is created using the pyxel package command:

pyxel package APP_DIR STARTUP_SCRIPT_FILE

If you need to include resources or additional modules, place them in the application directory.

Metadata can be displayed at runtime by specifying it in the following format within the startup script. Fields other than title and author are optional.

# title: Pyxel Platformer
# author: Takashi Kitao
# desc: A Pyxel platformer example
# site: https://github.com/kitao/pyxel
# license: MIT
# version: 1.0

The created application file can be run using the pyxel play command:

pyxel play PYXEL_APP_FILE

A Pyxel application file can also be converted to an executable or an HTML file using the pyxel app2exe or pyxel app2html commands.

API Reference

System

Resource

Input

Graphics

<img src="docs/images/blt_figure.png"> <img src="docs/images/bltm_figure.png">

Audio

Math

Image Class

Tilemap Class

Sound Class

Music Class

Advanced API

Pyxel includes an "Advanced API" that is not mentioned in this reference, as it may confuse users or require specialized knowledge to use.

If you are confident in your skills, try creating amazing works using this as a guide!

How to Contribute

Submitting Issues

Use the Issue Tracker to submit bug reports and feature or enhancement requests. Before submitting a new issue, make sure there are no similar open issues.

Functional Testing

Anyone who manually tests the code and reports bugs or suggestions for enhancements in the Issue Tracker is very welcome!

Submitting Pull Requests

Patches and fixes are accepted in the form of pull requests (PRs). Make sure that the issue the pull request addresses is open in the Issue Tracker.

Submitting a pull request implies that you agree to license your contribution under the MIT License.

Other Information

License

Pyxel is licensed under the MIT License. It can be reused in proprietary software, provided that all copies of the software or its substantial portions include a copy of the MIT License terms and a copyright notice.

Recruiting Sponsors

Pyxel is looking for sponsors on GitHub Sponsors. Please consider sponsoring Pyxel to support its continued maintenance and feature development. As a benefit, sponsors can consult directly with the Pyxel developer. For more details, please visit this page.