# [![Downloads](https://static.pepy.tech/personalized-badge/pyxel?period=total&units=international_system&left_color=grey&right_color=blue&left_text=PyPI%20downloads)](https://pypi.org/project/pyxel/) [![GitHub Repo stars](https://img.shields.io/github/stars/kitao/pyxel?style=social)](https://github.com/kitao/pyxel) [![GitHub forks](https://img.shields.io/github/forks/kitao/pyxel?style=social)](https://github.com/kitao/pyxel) [![GitHub Sponsors](https://img.shields.io/github/sponsors/kitao?label=Sponsor%20me&logo=github%20sponsors&style=social)](https://github.com/sponsors/kitao) [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/H2H27VDKD) [ [English](README.md) | [中文](docs/README.cn.md) | [Deutsch](docs/README.de.md) | [Español](docs/README.es.md) | [Français](docs/README.fr.md) | [Italiano](docs/README.it.md) | [日本語](docs/README.ja.md) | [한국어](docs/README.ko.md) | [Português](docs/README.pt.md) | [Русский](docs/README.ru.md) | [Türkçe](docs/README.tr.md) | [Українська](docs/README.uk.md) ] **Pyxel** (/ˈpɪksəl/) 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. [](https://github.com/kitao/pyxel/wiki/Pyxel-User-Examples) [](https://gihyo.jp/book/2025/978-4-297-14657-3) The development of Pyxel is driven by user feedback. Please give Pyxel a star on GitHub!

Pyxel's specifications and APIs are inspired by [PICO-8](https://www.lexaloffle.com/pico-8.php) and [TIC-80](https://tic80.com/). Pyxel is open source under the [MIT License](LICENSE) and free to use. Let's start making retro games with Pyxel! ## Specifications - Runs on Windows, Mac, Linux, and Web - Programming in Python - Customizable screen size - 16-color palette - 3 256x256 image banks - 8 256x256 tilemaps - 4 channels with 64 definable sounds - 8 music tracks combining any sounds - Keyboard, mouse, and gamepad inputs - Image and sound editing tools - User-extensible colors, channels, and banks ### Color Palette ## How to Install ### Windows After installing [Python3](https://www.python.org/) (version 3.8 or higher), run the following command: ```sh 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](https://brew.sh/), run the following commands: ```sh 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](https://www.python.org/) (version 3.8 or higher), and `python3-pip`, run the following command: ```sh sudo pip3 install -U pyxel ``` If the previous command fails, consider building Pyxel from source by following the instructions in the [Makefile](Makefile). ### Web The web version of Pyxel works on PCs, smartphones, and tablets with a compatible browser, without installing Python or Pyxel. The easiest way to use it is through the online IDE [Pyxel Code Maker](https://kitao.github.io/pyxel/wasm/code-maker/). For other usage patterns, such as embedding Pyxel apps on your own site, please refer to [this page](docs/pyxel-web-en.md). ### Try Examples After installing Pyxel, you can copy the examples to the current directory with the following command: ```sh pyxel copy_examples ``` The following examples will be copied to the current directory:
01_hello_pyxel.py Simplest application Demo Code
02_jump_game.py Jump game with Pyxel resource file Demo Code
03_draw_api.py Demonstration of drawing APIs Demo Code
04_sound_api.py Demonstration of sound APIs Demo Code
05_color_palette.py Color palette list Demo Code
06_click_game.py Mouse click game Demo Code
07_snake.py Snake game with BGM Demo Code
08_triangle_api.py Demonstration of triangle drawing APIs Demo Code
09_shooter.py Shoot'em up game with screen transitions and MML Demo Code
10_platformer.py Side-scrolling platform game with map Demo Code
11_offscreen.py Offscreen rendering with Image class Demo Code
12_perlin_noise.py Perlin noise animation Demo Code
13_custom_font.py Drawing a custom font Demo Code
14_synthesizer.py Synthesizer using audio expansion features Demo Code
15_tiled_map_file.py Loading and drawing a Tile Map File (.tmx) Demo Code
16_transform.py Image rotation and scaling Demo Code
17_app_launcher.py Pyxel app launcher (you can play various games!) Demo Code
99_flip_animation.py Animation with flip function (non-web platforms only) Demo Code
The examples can be executed with the following commands: ```sh # Run example in examples directory cd pyxel_examples pyxel run 01_hello_pyxel.py # Run app in examples/apps directory cd apps pyxel play 30sec_of_daylight.pyxapp ``` ## How to Use ### Create Application In your Python script, import Pyxel, set the window size with `init`, and start the application with `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) ``` 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: ```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() ``` For creating simple graphics without animation, you can use the `show` function to simplify your code. ```python 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: ```sh python PYTHON_SCRIPT_FILE ``` It can also be run with the `pyxel run` command: ```sh 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: ```sh pyxel watch WATCH_DIR PYTHON_SCRIPT_FILE ``` Stop directory monitoring by pressing `Ctrl(Command)+C`. ### Special Key Controls The following special key actions are available while a Pyxel application is running: - `Esc`
Quit the application - `Alt(Option)+R` or `A+B+X+Y+BACK` on gamepad
Reset the application - `Alt(Option)+1`
Save the screenshot to the desktop - `Alt(Option)+2`
Reset the recording start time of the screen capture video - `Alt(Option)+3`
Save a screen capture video to the desktop (up to 10 seconds) - `Alt(Option)+8` or `A+B+X+Y+DL` on gamepad
Toggle screen scaling between maximum and integer - `Alt(Option)+9` or `A+B+X+Y+DR` on gamepad
Switch between screen modes (Crisp/Smooth/Retro) - `Alt(Option)+0` or `A+B+X+Y+DU` on gamepad
Toggle the performance monitor (FPS/`update` time/`draw` time) - `Alt(Option)+Enter` or `A+B+X+Y+DD` on gamepad
Toggle fullscreen - `Shift+Alt(Option)+1/2/3`
Save image bank 0, 1, or 2 to the desktop - `Shift+Alt(Option)+0`
Save the current color palette to the desktop ### How to Create Resources Pyxel Editor creates images and sounds used in a Pyxel application. You can start Pyxel Editor with the following command: ```sh 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 the 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 images in each **image bank**. 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. Drag and drop a TMX file (Tiled Map File) onto the tilemap editor to load its layer 0 into the currently selected tilemap. **Sound Editor** The mode for editing **sounds** used for melodies and sound effects. **Music Editor** The mode for editing **music tracks** in which the sounds are arranged in order of playback. ### Other Resource Creation Methods Pyxel images and tilemaps can also be created using the following methods: - Create images or tilemaps from lists of strings with the `Image.set` or `Tilemap.set` functions - Load palette-ready image files (PNG/GIF/JPEG) with the `Image.load` function Pyxel sounds and music can also be created using the following method: - Create them from strings with the `Sound.set` or `Music.set` functions Refer to the API reference for the usage of these functions. ### How to Distribute Applications Pyxel supports a cross-platform distribution format called a Pyxel application file. Create a Pyxel application file (.pyxapp) with the `pyxel package` command: ```sh 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. ```python # 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: ```sh 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 - `width`, `height`
The width and height of the screen - `frame_count`
The number of elapsed frames - `init(width, height, [title], [fps], [quit_key], [display_scale], [capture_scale], [capture_sec])`
Initialize the Pyxel application with the screen size (`width`, `height`). The following options can be specified: the window title with `title`, the frame rate with `fps`, the key to quit the application with `quit_key`, the display scale with `display_scale`, the screen capture scale with `capture_scale`, and the maximum recording time of the screen capture video with `capture_sec`.
Example: `pyxel.init(160, 120, title="My Pyxel App", fps=60, quit_key=pyxel.KEY_NONE, capture_scale=3, capture_sec=0)` - `run(update, draw)`
Start the Pyxel application and call the `update` function for frame update and the `draw` function for drawing. - `show()`
Show the screen and wait until the `Esc` key is pressed. - `flip()`
Refresh the screen by one frame. The application exits when the `Esc` key is pressed. This function is not available in the web version. - `quit()`
Quit the Pyxel application. - `reset()`
Reset the Pyxel application. Environment variables are preserved after reset. ### Resource - `load(filename, [exclude_images], [exclude_tilemaps], [exclude_sounds], [exclude_musics])`
Load the resource file (.pyxres). If an option is set to `True`, the corresponding resource will be excluded from loading. If a palette file (.pyxpal) with the same name exists in the same location as the resource file, the palette display colors will also be updated. The palette file contains hexadecimal entries for the display colors (e.g. `1100ff`), separated by newlines. The palette file can also be used to change the colors displayed in Pyxel Editor. - `user_data_dir(vendor_name, app_name)`
Return the user data directory created based on `vendor_name` and `app_name`. If the directory does not exist, it will be created automatically. It is used to store high scores, game progress, and similar data.
Example: `print(pyxel.user_data_dir("Takashi Kitao", "Pyxel Shooter"))` ### Input - `mouse_x`, `mouse_y`
The current position of the mouse cursor - `mouse_wheel`
The current value of the mouse wheel - `btn(key)`
Return `True` if the `key` is pressed, otherwise return `False`. ([Key definition list](python/pyxel/__init__.pyi)) - `btnp(key, [hold], [repeat])`
Return `True` if the `key` is pressed in that frame, otherwise return `False`. If `hold` and `repeat` are specified, after the `key` has been held down for `hold` frames or more, `True` is returned every `repeat` frames. - `btnr(key)`
Return `True` if the `key` is released in that frame, otherwise return `False`. - `mouse(visible)`
Show the mouse cursor if `visible` is `True`, and hide it if `visible` is `False`. The cursor's position continues to update even when it is hidden. ### Graphics - `colors`
List of the palette display colors. The display color is specified by a 24-bit numerical value. Use `colors.from_list` and `colors.to_list` to directly assign and retrieve Python lists.
Example: `old_colors = pyxel.colors.to_list(); pyxel.colors.from_list([0x111111, 0x222222, 0x333333]); pyxel.colors[15] = 0x112233` - `images`
List of the image banks (instances of the Image class) (0-2)
Example: `pyxel.images[0].load(0, 0, "title.png")` - `tilemaps`
List of the tilemaps (instances of the Tilemap class) (0-7) - `clip(x, y, w, h)`
Set the drawing area of the screen from (`x`, `y`) with a width of `w` and a height of `h`. Call `clip()` to reset the drawing area to full screen. - `camera(x, y)`
Change the upper-left corner coordinates of the screen to (`x`, `y`). Call `camera()` to reset the upper-left corner coordinates to (`0`, `0`). - `pal(col1, col2)`
Replace color `col1` with `col2` when drawing. Call `pal()` to reset to the initial palette. - `dither(alpha)`
Apply dithering (pseudo-transparency) when drawing. Set `alpha` in the range `0.0`-`1.0`, where `0.0` is transparent and `1.0` is opaque. - `cls(col)`
Clear screen with color `col`. - `pget(x, y)`
Get the color of the pixel at (`x`, `y`). - `pset(x, y, col)`
Draw a pixel of color `col` at (`x`, `y`). - `line(x1, y1, x2, y2, col)`
Draw a line of color `col` from (`x1`, `y1`) to (`x2`, `y2`). - `rect(x, y, w, h, col)`
Draw a rectangle of width `w`, height `h` and color `col` from (`x`, `y`). - `rectb(x, y, w, h, col)`
Draw the outline of a rectangle of width `w`, height `h` and color `col` from (`x`, `y`). - `circ(x, y, r, col)`
Draw a circle of radius `r` and color `col` at (`x`, `y`). - `circb(x, y, r, col)`
Draw the outline of a circle of radius `r` and color `col` at (`x`, `y`). - `elli(x, y, w, h, col)`
Draw an ellipse of width `w`, height `h` and color `col` from (`x`, `y`). - `ellib(x, y, w, h, col)`
Draw the outline of an ellipse of width `w`, height `h` and color `col` from (`x`, `y`). - `tri(x1, y1, x2, y2, x3, y3, col)`
Draw a triangle with vertices (`x1`, `y1`), (`x2`, `y2`), (`x3`, `y3`) and color `col`. - `trib(x1, y1, x2, y2, x3, y3, col)`
Draw the outline of a triangle with vertices (`x1`, `y1`), (`x2`, `y2`), (`x3`, `y3`) and color `col`. - `fill(x, y, col)`
Fill the area connected with the same color as (`x`, `y`) with color `col`. - `blt(x, y, img, u, v, w, h, [colkey], [rotate], [scale])`
Copy the region of size (`w`, `h`) from (`u`, `v`) of the image bank `img`(0-2) to (`x`, `y`). If a negative value is assigned to `w` and/or `h`, the region will be flipped horizontally and/or vertically. If `colkey` is specified, it will be treated as a transparent color. If `rotate`(in degrees), `scale`(1.0 = 100%), or both are specified, the corresponding transformations will be applied. - `bltm(x, y, tm, u, v, w, h, [colkey], [rotate], [scale])`
Copy the region of size (`w`, `h`) from (`u`, `v`) of the tilemap `tm`(0-7) to (`x`, `y`). If a negative value is assigned to `w` and/or `h`, the region will be flipped horizontally and/or vertically. If `colkey` is specified, it will be treated as a transparent color. If `rotate`(in degrees), `scale`(1.0 = 100%), or both are specified, the corresponding transformations will be applied. The size of a tile is 8x8 pixels and is stored in a tilemap as a tuple of `(image_tx, image_ty)`. - `text(x, y, s, col)`
Draw a string `s` in color `col` at (`x`, `y`). ### Audio - `sounds`
List of the sounds (instances of the Sound class) (0-63)
Example: `pyxel.sounds[0].speed = 60` - `musics`
List of music tracks (instances of the Music class) (0-7) - `play(ch, snd, [sec], [loop], [resume])`
Play the sound `snd`(0-63) on channel `ch`(0-3). `snd` can be a sound number, a list of sound numbers, or an MML string. The playback start position can be specified in seconds with `sec`. If `loop` is set to `True`, the sound will loop. To resume the previous sound after playback ends, set `resume` to `True`. - `playm(msc, [sec], [loop])`
Play the music `msc`(0-7). The playback start position can be specified in seconds with `sec`. If `loop` is set to `True`, the music will loop. - `stop([ch])`
Stop playback of the specified channel `ch`(0-3). Call `stop()` to stop all channels. - `play_pos(ch)`
Get the sound playback position of channel `ch`(0-3) as a tuple of `(sound_no, sec)`. Return `None` when playback has stopped. ### Math - `ceil(x)`
Return the smallest integer that is greater than or equal to `x`. - `floor(x)`
Return the largest integer that is less than or equal to `x`. - `sgn(x)`
Return `1` when `x` is positive, `0` when it is `0`, and `-1` when it is negative. - `sqrt(x)`
Return the square root of `x`. - `sin(deg)`
Return the sine of `deg` degrees. - `cos(deg)`
Return the cosine of `deg` degrees. - `atan2(y, x)`
Return the arctangent of `y`/`x` in degrees. - `rseed(seed)`
Set the seed of the random number generator. - `rndi(a, b)`
Return a random integer greater than or equal to `a` and less than or equal to `b`. - `rndf(a, b)`
Return a random floating-point number greater than or equal to `a` and less than or equal to `b`. - `nseed(seed)`
Set the seed of Perlin noise. - `noise(x, [y], [z])`
Return the Perlin noise value for the specified coordinates. ### Image Class - `width`, `height`
The width and height of the image - `set(x, y, data)`
Set the image at (`x`, `y`) using a list of strings.
Example: `pyxel.images[0].set(10, 10, ["0123", "4567", "89ab", "cdef"])` - `load(x, y, filename)`
Load an image file (PNG/GIF/JPEG) at (`x`, `y`). - `pget(x, y)`
Get the color of the pixel at (`x`, `y`). - `pset(x, y, col)`
Draw a pixel with the color `col` at (`x`, `y`). ### Tilemap Class - `width`, `height`
The width and height of the tilemap - `imgsrc`
The image bank (0-2) referenced by the tilemap - `set(x, y, data)`
Set the tilemap at (`x`, `y`) using a list of strings.
Example: `pyxel.tilemaps[0].set(0, 0, ["0000 0100 a0b0", "0001 0101 a1b1"])` - `load(x, y, filename, layer)`
Load the `layer` (0-) from the TMX file (Tiled Map File) at (`x`, `y`). - `pget(x, y)`
Get the tile at (`x`, `y`). A tile is represented as a tuple of `(image_tx, image_ty)`. - `pset(x, y, tile)`
Draw a `tile` at (`x`, `y`). A tile is represented as a tuple of `(image_tx, image_ty)`. ### Sound Class - `notes`
List of notes (0-127). Higher values produce higher pitches. Note `33` is 'A2' (440 Hz). Rests are `-1`. - `tones`
List of tones (0:Triangle / 1:Square / 2:Pulse / 3:Noise) - `volumes`
List of volumes (0-7) - `effects`
List of effects (0:None / 1:Slide / 2:Vibrato / 3:FadeOut / 4:Half-FadeOut / 5:Quarter-FadeOut) - `speed`
Playback speed. `1` is the fastest, and the larger the number, the slower the playback speed. At `120`, the length of one note becomes 1 second. - `set(notes, tones, volumes, effects, speed)`
Set notes, tones, volumes, and effects using a string. If the length of tones, volumes, or effects are shorter than the notes, they will be repeated from the beginning. - `set_notes(notes)`
Set the notes using a string made of `CDEFGAB`+`#-`+`01234` or `R`. It is case-insensitive, and whitespace is ignored.
Example: `pyxel.sounds[0].set_notes("g2b-2d3r rf3f3f3")` - `set_tones(tones)`
Set the tones with a string made of `TSPN`. Case-insensitive and whitespace is ignored.
Example: `pyxel.sounds[0].set_tones("ttss pppn")` - `set_volumes(volumes)`
Set the volumes with a string made of `01234567`. Case-insensitive and whitespace is ignored.
Example: `pyxel.sounds[0].set_volumes("7777 7531")` - `set_effects(effects)`
Set the effects with a string made of `NSVFHQ`. Case-insensitive and whitespace is ignored.
Example: `pyxel.sounds[0].set_effects("nfnf nvvs")` - `mml(code)`
Passing a [MML (Music Macro Language)](https://en.wikipedia.org/wiki/Music_Macro_Language) string switches to MML mode and plays the sound according to its content. In this mode, normal parameters such as `notes` and `speed` are ignored. To exit MML mode, call `mml()`. For more details about MML, see [this page](docs/faq-en.md).
Example: `pyxel.sounds[0].mml("T120 Q90 @1 V100 O5 L8 C4&CC.C.D16 @VIB1{10,20,20} E2C2")` - `save(filename, sec, [ffmpeg])`
Creates a WAV file that plays the sound for the specified seconds. If FFmpeg is installed and `ffmpeg` is set to `True`, an MP4 file is also created. - `total_sec()`
Return the playback time of the sound in seconds. Return `None` if an infinite loop is used in MML. ### Music Class - `seqs`
A two-dimensional list of sounds (0-63) across multiple channels - `set(seq0, seq1, seq2, ...)`
Set the lists of sounds (0-63) for each channel. If an empty list is specified, that channel will not be used for playback.
Example: `pyxel.musics[0].set([0, 1], [], [3])` - `save(filename, sec, [ffmpeg])`
Creates a WAV file that plays the music for the specified seconds. If FFmpeg is installed and `ffmpeg` is set to `True`, an MP4 file is also created. ### 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](python/pyxel/__init__.pyi) as a guide! ## How to Contribute ### Submitting Issues Use the [Issue Tracker](https://github.com/kitao/pyxel/issues) 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](https://github.com/kitao/pyxel/issues) 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](LICENSE). ## Web Tools & Examples - [Pyxel Web Examples](https://kitao.github.io/pyxel/wasm/examples/) - [Pyxel Web Launcher](https://kitao.github.io/pyxel/wasm/launcher/) - [Pyxel Code Maker](https://kitao.github.io/pyxel/wasm/code-maker/) [[User Manual](https://qiita.com/kitao/items/b5b3fb28ebf9781eda2e)] - [Pyxel MML Studio](https://kitao.github.io/pyxel/wasm/mml-studio/) [[User Manual](https://qiita.com/kitao/items/a86de4f7d6a0ed656a89)] ## Other Information - [FAQ](docs/faq-en.md) - [User Examples](https://github.com/kitao/pyxel/wiki/Pyxel-User-Examples) - [Developer's X Account](https://x.com/kitao) - [Discord Server (English)](https://discord.gg/Z87eYHN) - [Discord Server (Japanese)](https://discord.gg/qHA5BCS) ## License Pyxel is licensed under the [MIT License](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](https://github.com/sponsors/kitao).