# <img src="https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/pyxel_logo_152x64.png">
[](https://pypi.org/project/pyxel/)
[](https://github.com/kitao/pyxel)
[](https://github.com/kitao/pyxel)
[](https://github.com/sponsors/kitao)
[](https://ko-fi.com/H2H27VDKD)
[ [English](https://github.com/kitao/pyxel/blob/main//README.md) | [中文](https://github.com/kitao/pyxel/blob/main//docs/README.cn.md) | [Deutsch](https://github.com/kitao/pyxel/blob/main//docs/README.de.md) | [Español](https://github.com/kitao/pyxel/blob/main//docs/README.es.md) | [Français](https://github.com/kitao/pyxel/blob/main//docs/README.fr.md) | [Italiano](https://github.com/kitao/pyxel/blob/main//docs/README.it.md) | [日本語](https://github.com/kitao/pyxel/blob/main//docs/README.ja.md) | [한국어](https://github.com/kitao/pyxel/blob/main//docs/README.ko.md) | [Português](https://github.com/kitao/pyxel/blob/main//docs/README.pt.md) | [Русский](https://github.com/kitao/pyxel/blob/main//docs/README.ru.md) ]
**Pyxel** is a retro game engine for Python.
Thanks to its simple specifications inspired by retro gaming consoles, such as only 16 colors can be displayed and only 4 sounds can be played back at the same time, you can feel free to enjoy making pixel art style games.
<img src="https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/pyxel_message.png" width="480">
The motivation for the development of Pyxel is the feedback from users. Please give Pyxel a star on GitHub!
<p>
<a href="https://kitao.github.io/pyxel/wasm/examples/01_hello_pyxel.html">
<img src="https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/01_hello_pyxel.gif" width="320">
</a>
<a href="https://kitao.github.io/pyxel/wasm/examples/02_jump_game.html">
<img src="https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/02_jump_game.gif" width="320">
</a>
<a href="https://kitao.github.io/pyxel/wasm/examples/03_draw_api.html">
<img src="https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/03_draw_api.gif" width="320">
</a>
<a href="https://kitao.github.io/pyxel/wasm/examples/04_sound_api.html">
<img src="https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/04_sound_api.gif" width="320">
</a>
<a href="https://kitao.github.io/pyxel/wasm/examples/image_editor.html">
<img src="https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/image_tilemap_editor.gif" width="320">
</a>
<a href="https://kitao.github.io/pyxel/wasm/examples/sound_editor.html">
<img src="https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/sound_music_editor.gif" width="320">
</a>
</p>
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 and free to use. Let's start making a retro game with Pyxel!
## Specifications
- Runs on Windows, Mac, Linux, and Web
- Programming with Python
- 16 color palette
- 256x256 sized 3 image banks
- 256x256 sized 8 tilemaps
- 4 channels with 64 definable sounds
- 8 musics which can combine arbitrary sounds
- Keyboard, mouse, and gamepad inputs
- Image and sound editor
### Color Palette
<img src="https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/05_color_palette.png">
<img src="https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/pyxel_palette.png">
## How to Install
### Windows
After installing [Python3](https://www.python.org/) (version 3.7 or higher), run the following command:
```sh
pip install -U pyxel
```
If you install Python using the official installer, please check the `Add Python 3.x to PATH` checkbox to enable `pyxel` command.
### Mac
After installing [Homebrew](https://brew.sh/), run the following commands:
```sh
brew install pipx
pipx ensurepath
pipx install pyxel
```
To update the version after installing Pyxel, run `pipx upgrade pyxel`.
### Linux
After installing the SDL2 package (`libsdl2-dev` for Ubuntu), [Python3](https://www.python.org/) (version 3.7 or higher), and `python3-pip`, run the following command:
```sh
sudo pip3 install -U pyxel
```
If the above doesn't work, try self-building according to the instructions in [Makefile](https://github.com/kitao/pyxel/blob/main//Makefile).
### Web
The web version of Pyxel does not require Python or Pyxel installation and runs on PCs as well as smartphones and tablets with supported web browsers.
For specific instructions, please refer to [this page](https://github.com/kitao/pyxel/wiki/How-To-Use-Pyxel-Web).
### Try Pyxel Examples
After installing Pyxel, the examples of Pyxel will be copied to the current directory with the following command:
```sh
pyxel copy_examples
```
The examples to be copied are as follows:
<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 transition</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 utilizing audio expantion 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>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>30SecondsOfDaylight.pyxapp</td>
<td>1st Pyxel Jam winning game by <a href="https://twitter.com/helpcomputer0">Adam</a></td>
<td><a href="https://kitao.github.io/pyxel/wasm/examples/30SecondsOfDaylight.html">Demo</a></td>
<td><a href="https://github.com/kitao/30SecondsOfDaylight">Code</a></td>
</tr>
<tr>
<td>megaball.pyxapp</td>
<td>Arcade ball physics game by <a href="https://twitter.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://twitter.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>
An examples can be executed with the following commands:
```sh
cd pyxel_examples
pyxel run 01_hello_pyxel.py
pyxel play 30SecondsOfDaylight.pyxapp
```
## How to Use
### Create Pyxel Application
After importing the Pyxel module in your python script, specify the window size with `init` function first, then starts the Pyxel application with `run` function.
```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 `run` function are `update` function to update each frame and `draw` function to draw screen when necessary.
In an actual application, it is recommended to wrap pyxel code in a class as 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()
```
When creating simple graphics without animation, `show` function can be used to make the code more concise.
```python
import pyxel
pyxel.init(120, 120)
pyxel.cls(1)
pyxel.circb(60, 60, 40, 7)
pyxel.show()
```
### Run Pyxel Application
The created Python script can be executed with the following command:
```sh
pyxel run PYTHON_SCRIPT_FILE
```
It can also be executed like a normal Python script:
```sh
python3 PYTHON_SCRIPT_FILE
```
### Special Controls
The following special controls can be performed while a Pyxel application is running:
- `Esc`<br>
Quit the application
- `Alt(Option)+1`<br>
Save the screenshot to the desktop
- `Alt(Option)+2`<br>
Reset the recording start time of the screen capture video
- `Alt(Option)+3`<br>
Save the screen capture video to the desktop (up to 10 seconds)
- `Alt(Option)+9`<br>
Switch between screen modes (Crisp/Smooth/Retro)
- `Alt(Option)+0`<br>
Toggle the performance monitor (fps, update time, and draw time)
- `Alt(Option)+Enter`<br>
Toggle full screen
- `Shift+Alt(Option)+1/2/3`<br>
Save the corresponding image bank to the desktop
- `Shift+Alt(Option)+0`<br>
Save the current color palette to the desktop
### How to Create Resources
Pyxel Editor can create images and sounds used in a Pyxel application.
It starts with the following command:
```sh
pyxel edit PYXEL_RESOURCE_FILE
```
If the specified Pyxel resource file (.pyxres) exists, the file is loaded, and if it does not exist, a new file is created with the specified name.
If the resource file is omitted, the name is `my_resource.pyxres`.
After starting Pyxel Editor, the file can be switched by dragging and dropping another resource file. If the resource file is dragged and dropped while holding down `Ctrl(Cmd)` key, only the resource type (Image/Tilemap/Sound/Music) that is currently being edited will be loaded. This operation enables to combine multiple resource files into one.
The created resource file can be loaded with `load` function.
Pyxel Editor has the following edit modes.
**Image Editor**
The mode to edit the image banks.
<a href="https://kitao.github.io/pyxel/wasm/examples/image_editor.html">
<img src="https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/image_editor.gif">
</a>
Drag and drop an image file (PNG/GIF/JPEG) onto the Image Editor to load the image into the currently selected image bank.
**Tilemap Editor**
The mode to edit tilemaps in which images of the image banks are arranged in a tile pattern.
<a href="https://kitao.github.io/pyxel/wasm/examples/tilemap_editor.html">
<img src="https://raw.githubusercontent.com/kitao/pyxel/main//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 to edit sounds.
<a href="https://kitao.github.io/pyxel/wasm/examples/sound_editor.html">
<img src="https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/sound_editor.gif">
</a>
**Music Editor**
The mode to edit 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="https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/music_editor.gif">
</a>
### Other Resource Creation Methods
Pyxel images and tilemaps can also be created by the following methods:
- Create an image from a list of strings with `Image.set` function or `Tilemap.set` function
- Load an image file (PNG/GIF/JPEG) in Pyxel palette with `Image.load` function
Pyxel sounds can also be created in the following method:
- Create a sound from strings with `Sound.set` function or `Music.set` function
Please refer to the API reference for usage of these functions.
### How to Distribute Applications
Pyxel supports a dedicated application distribution file format (Pyxel application file) that works across platforms.
Create the Pyxel application file (.pyxapp) with the following command:
```sh
pyxel package APP_DIR STARTUP_SCRIPT_FILE
```
If the application should include resources or additional modules, place them in the application directory.
The created application file can be executed with the following command:
```sh
pyxel play PYXEL_APP_FILE
```
Pyxel application file also can be converted to an executable or an HTML file with the `pyxel app2exe` or `pyxel app2html` commands.
## API Reference
### System
- `width`, `height`<br>
The width and height of the screen
- `frame_count`<br>
The number of the elapsed frames
- `init(width, height, [title], [fps], [quit_key], [display_scale], [capture_scale], [capture_sec])`<br>
Initialize the Pyxel application with screen size (`width`, `height`). The following can be specified as options: the window title with `title`, the frame rate with `fps`, the key to quit the application with `quit_key`, the scale of the display with `display_scale`, the scale of the screen capture with `capture_scale`, and the maximum recording time of the screen capture video with `capture_sec`.<br>
e.g. `pyxel.init(160, 120, title="My Pyxel App", fps=60, quit_key=pyxel.KEY_NONE, capture_scale=3, capture_sec=0)`
- `run(update, draw)`<br>
Start the Pyxel application and call `update` function for frame update and `draw` function for drawing.
- `show()`<br>
Show the screen and wait until the `Esc` key is pressed.
- `flip()`<br>
Refresh the screen by one frame. The application exits when the `Esc` key is pressed. This function does not work in the web version.
- `quit()`<br>
Quit the Pyxel application.
### Resource
- `load(filename, [excl_images], [excl_tilemaps], [excl_sounds], [excl_musics])`<br>
Load the resource file (.pyxres). If an option is `True`, the resource will not be loaded. If a palette file (.pyxpal) of the same name exists in the same location as the resource file, the palette display color will also be changed. The palette file is a hexadecimal entry of the display colors (e.g. `1100FF`), separated by newlines. The palette file can also be used to change the colors displayed in Pyxel Editor.
### Input
- `mouse_x`, `mouse_y`<br>
The current position of the mouse cursor
- `mouse_wheel`<br>
The current value of the mouse wheel
- `btn(key)`<br>
Return `True` if `key` is pressed, otherwise return `False`. ([Key definition list](https://github.com/kitao/pyxel/blob/main//python/pyxel/__init__.pyi))
- `btnp(key, [hold], [repeat])`<br>
Return `True` if `key` is pressed at that frame, otherwise return `False`. When `hold` and `repeat` are specified, `True` will be returned at the `repeat` frame interval when the `key` is held down for more than `hold` frames.
- `btnr(key)`<br>
Return `True` if `key` is released at that frame, otherwise return `False`.
- `mouse(visible)`<br>
If `visible` is `True`, show the mouse cursor. If `False`, hide it. Even if the mouse cursor is not displayed, its position is updated.
### Graphics
- `colors`<br>
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.<br>
e.g. `old_colors = pyxel.colors.to_list(); pyxel.colors.from_list([0x111111, 0x222222, 0x333333]); pyxel.colors[15] = 0x112233`
- `images`<br>
List of the image banks (0-2). (See the Image class)<br>
e.g. `pyxel.images[0].load(0, 0, "title.png")`
- `tilemaps`<br>
List of the tilemaps (0-7). (See the Tilemap class)
- `clip(x, y, w, h)`<br>
Set the drawing area of the screen from (`x`, `y`) to width `w` and height `h`. Reset the drawing area to full screen with `clip()`.
- `camera(x, y)`<br>
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)`<br>
Replace color `col1` with `col2` at drawing. `pal()` to reset to the initial palette.
- `dither(alpha)`<br>
Applies dithering (pseudo-transparency) at drawing. Set `alpha` in the range 0.0-1.0, where 0.0 is transparent and 1.0 is opaque.
- `cls(col)`<br>
Clear screen with color `col`.
- `pget(x, y)`<br>
Get the color of the pixel at (`x`, `y`).
- `pset(x, y, col)`<br>
Draw a pixel of color `col` at (`x`, `y`).
- `line(x1, y1, x2, y2, col)`<br>
Draw a line of color `col` from (`x1`, `y1`) to (`x2`, `y2`).
- `rect(x, y, w, h, col)`<br>
Draw a rectangle of width `w`, height `h` and color `col` from (`x`, `y`).
- `rectb(x, y, w, h, col)`<br>
Draw the outline of a rectangle of width `w`, height `h` and color `col` from (`x`, `y`).
- `circ(x, y, r, col)`<br>
Draw a circle of radius `r` and color `col` at (`x`, `y`).
- `circb(x, y, r, col)`<br>
Draw the outline of a circle of radius `r` and color `col` at (`x`, `y`).
- `elli(x, y, w, h, col)`<br>
Draw an ellipse of width `w`, height `h` and color `col` from (`x`, `y`).
- `ellib(x, y, w, h, col)`<br>
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)`<br>
Draw a triangle with vertices (`x1`, `y1`), (`x2`, `y2`), (`x3`, `y3`) and color `col`.
- `trib(x1, y1, x2, y2, x3, y3, col)`<br>
Draw the outline of a triangle with vertices (`x1`, `y1`), (`x2`, `y2`), (`x3`, `y3`) and color `col`.
- `fill(x, y, col)`<br>
Fill the area connected with the same color as (`x`, `y`) with color `col`.
- `blt(x, y, img, u, v, w, h, [colkey])`<br>
Copy the region of size (`w`, `h`) from (`u`, `v`) of the image bank `img`(0-2) to (`x`, `y`). If negative value is set for `w` and/or `h`, it will reverse horizontally and/or vertically. If `colkey` is specified, treated as transparent color.
<img src="https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/blt_figure.png">
- `bltm(x, y, tm, u, v, w, h, [colkey])`<br>
Copy the region of size (`w`, `h`) from (`u`, `v`) of the tilemap `tm`(0-7) to (`x`, `y`). If negative value is set for `w` and/or `h`, it will reverse horizontally and/or vertically. If `colkey` is specified, treated as transparent color. The size of a tile is 8x8 pixels and is stored in a tilemap as a tuple of `(tile_x, tile_y)`.
<img src="https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/bltm_figure.png">
- `text(x, y, s, col)`<br>
Draw a string `s` of color `col` at (`x`, `y`).
### Audio
- `sounds`<br>
List of the sounds (0-63). (See the Sound class)<br>
e.g. `pyxel.sounds[0].speed = 60`
- `musics`<br>
List of the musics (0-7). (See the Music class)
- `play(ch, snd, [tick], [loop])`<br>
Play the sound `snd`(0-63) on channel `ch`(0-3). If `snd` is a list, it will be played in order. The playback start position can be specified by `tick`(1 tick = 1/120 seconds). If `True` is specified for `loop`, loop playback is performed.
- `playm(msc, [tick], [loop])`<br>
Play the music `msc`(0-7). The playback start position can be specified by `tick`(1 tick = 1/120 seconds). If `True` is specified for `loop`, loop playback is performed.
- `stop([ch])`<br>
Stops playback of the specified channel `ch`(0-3). `stop()` to stop playing all channels.
- `play_pos(ch)`<br>
Get the sound playback position of channel `ch`(0-3) as a tuple of `(sound no, note no)`. Returns `None` when playback is stopped.
### Math
- `ceil(x)`<br>
Returns the smallest integer greater than or equal to `x`.
- `floor(x)`<br>
Returns the largest integer less than or equal to `x`.
- `sgn(x)`<br>
Returns 1 when `x` is positive, 0 when it is zero, and -1 when it is negative.
- `sqrt(x)`<br>
Returns the square root of `x`.
- `sin(deg)`<br>
Returns the sine of `deg` degrees.
- `cos(deg)`<br>
Returns the cosine of `deg` degrees.
- `atan2(y, x)`<br>
Returns the arctangent of `y`/`x` in degrees.
- `rseed(seed)`<br>
Sets the seed of the random number generator.
- `rndi(a, b)`<br>
Returns an random integer greater than or equal to `a` and less than or equal to `b`.
- `rndf(a, b)`<br>
Returns a random decimal greater than or equal to `a` and less than or equal to `b`.
- `nseed(seed)`<br>
Sets the seed of Perlin noise.
- `noise(x, [y], [z])`<br>
Returns the Perlin noise value for the specified coordinates.
### Image Class
- `width`, `height`<br>
The width and height of the image
- `set(x, y, data)`<br>
Set the image at (`x`, `y`) by a list of strings.<br>
e.g. `pyxel.images[0].set(10, 10, ["0123", "4567", "89ab", "cdef"])`
- `load(x, y, filename)`<br>
Load the image file (PNG/GIF/JPEG) at (`x`, `y`).
- `pget(x, y)`<br>
Get the pixel color at (`x`, `y`).
- `pset(x, y, col)`<br>
Draw a pixel of color `col` at (`x`, `y`).
### Tilemap Class
- `width`, `height`<br>
The width and height of the tilemap
- `imgsrc`<br>
The image bank (0-2) referenced by the tilemap
- `set(x, y, data)`<br>
Set the tilemap at (`x`, `y`) by a list of strings.<br>
e.g. `pyxel.tilemap(0).set(0, 0, ["0000 0100 a0b0", "0001 0101 a1b1"])`
- `load(x, y, filename, layer)`<br>
Load the layer in the drawing order `layer`(0-) from the TMX file (Tiled Map File) at (`x`, `y`).
- `pget(x, y)`<br>
Get the tile at (`x`, `y`). A tile is a tuple of `(tile_x, tile_y)`.
- `pset(x, y, tile)`<br>
Draw a `tile` at (`x`, `y`). A tile is a tuple of `(tile_x, tile_y)`.
### Sound Class
- `notes`<br>
List of notes (0-127). The higher the number, the higher the pitch, and at 33 it becomes 'A2'(440Hz). The rest is -1.
- `tones`<br>
List of tones (0:Triangle / 1:Square / 2:Pulse / 3:Noise)
- `volumes`<br>
List of volumes (0-7)
- `effects`<br>
List of effects (0:None / 1:Slide / 2:Vibrato / 3:FadeOut)
- `speed`<br>
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)`<br>
Set notes, tones, volumes, and effects with a string. If the tones, volumes, and effects length are shorter than the notes, it is repeated from the beginning.
- `set_notes(notes)`<br>
Set the notes with a string made of 'CDEFGAB'+'#-'+'01234' or 'R'. Case-insensitive and whitespace is ignored.<br>
e.g. `pyxel.sounds[0].set_notes("G2B-2D3R RF3F3F3")`
- `set_tones(tones)`<br>
Set the tones with a string made of 'TSPN'. Case-insensitive and whitespace is ignored.<br>
e.g. `pyxel.sounds[0].set_tones("TTSS PPPN")`
- `set_volumes(volumes)`<br>
Set the volumes with a string made of '01234567'. Case-insensitive and whitespace is ignored.<br>
e.g. `pyxel.sounds[0].set_volumes("7777 7531")`
- `set_effects(effects)`<br>
Set the effects with a string made of 'NSVF'. Case-insensitive and whitespace is ignored.<br>
e.g. `pyxel.sounds[0].set_effects("NFNF NVVS")`
### Music Class
- `seqs`<br>
Two-dimensional list of sounds (0-63) with the number of channels
- `set(seq0, seq1, seq2, ...)`<br>
Set the lists of sound (0-63) of channels. If an empty list is specified, that channel is not used for playback.<br>
e.g. `pyxel.musics[0].set([0, 1], [], [3])`
### Advanced APIs
Pyxel has "advanced APIs" that are not mentioned in this reference because they "may confuse users" or "need specialized knowledge to use".
If you are familiar with your skills, try to create amazing works with [this](https://github.com/kitao/pyxel/blob/main//python/pyxel/__init__.pyi) as a clue!
## How to Contribute
### Submitting Issues
Use the [Issue Tracker](https://github.com/kitao/pyxel/issues) to submit bug reports and feature/enhancement requests. Before submitting a new issue, ensure that there is no similar open issue.
### Manual Testing
Anyone manually testing the code and reporting bugs or suggestions for enhancements in the [Issue Tracker](https://github.com/kitao/pyxel/issues) are very welcome!
### Submitting Pull Requests
Patches/fixes are accepted in form of pull requests (PRs). Make sure the issue the pull request addresses is open in the Issue Tracker.
Submitted pull request is deemed to have agreed to publish under [MIT License](https://github.com/kitao/pyxel/blob/main//LICENSE).
## Other Information
- [Q&A](https://github.com/kitao/pyxel/wiki/Pyxel-Q&A)
- [User Examples](https://github.com/kitao/pyxel/wiki/Pyxel-User-Examples)
- [Developer's Twitter account](https://twitter.com/kitao)
## License
Pyxel is under [MIT License](https://github.com/kitao/pyxel/blob/main//LICENSE). It can be reused within proprietary software, provided that all copies of the software or its substantial portions include a copy of the terms of the MIT License and also a copyright notice.
## Recruiting Sponsors
Pyxel is looking for sponsors on GitHub Sponsors. Consider sponsoring Pyxel for continued maintenance and feature additions. Sponsors can consult about Pyxel as a benefit. Please see [here](https://github.com/sponsors/kitao) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "pyxel",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "game, gamedev",
"author": "Takashi Kitao <takashi.kitao@gmail.com>",
"author_email": "Takashi Kitao <takashi.kitao@gmail.com>",
"download_url": null,
"platform": null,
"description": "# <img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/pyxel_logo_152x64.png\">\n\n[](https://pypi.org/project/pyxel/)\n[](https://github.com/kitao/pyxel)\n[](https://github.com/kitao/pyxel)\n[](https://github.com/sponsors/kitao)\n\n[](https://ko-fi.com/H2H27VDKD)\n\n[ [English](https://github.com/kitao/pyxel/blob/main//README.md) | [\u4e2d\u6587](https://github.com/kitao/pyxel/blob/main//docs/README.cn.md) | [Deutsch](https://github.com/kitao/pyxel/blob/main//docs/README.de.md) | [Espa\u00f1ol](https://github.com/kitao/pyxel/blob/main//docs/README.es.md) | [Fran\u00e7ais](https://github.com/kitao/pyxel/blob/main//docs/README.fr.md) | [Italiano](https://github.com/kitao/pyxel/blob/main//docs/README.it.md) | [\u65e5\u672c\u8a9e](https://github.com/kitao/pyxel/blob/main//docs/README.ja.md) | [\ud55c\uad6d\uc5b4](https://github.com/kitao/pyxel/blob/main//docs/README.ko.md) | [Portugu\u00eas](https://github.com/kitao/pyxel/blob/main//docs/README.pt.md) | [\u0420\u0443\u0441\u0441\u043a\u0438\u0439](https://github.com/kitao/pyxel/blob/main//docs/README.ru.md) ]\n\n**Pyxel** is a retro game engine for Python.\n\nThanks to its simple specifications inspired by retro gaming consoles, such as only 16 colors can be displayed and only 4 sounds can be played back at the same time, you can feel free to enjoy making pixel art style games.\n\n<img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/pyxel_message.png\" width=\"480\">\n\nThe motivation for the development of Pyxel is the feedback from users. Please give Pyxel a star on GitHub!\n\n<p>\n<a href=\"https://kitao.github.io/pyxel/wasm/examples/01_hello_pyxel.html\">\n<img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/01_hello_pyxel.gif\" width=\"320\">\n</a>\n<a href=\"https://kitao.github.io/pyxel/wasm/examples/02_jump_game.html\">\n<img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/02_jump_game.gif\" width=\"320\">\n</a>\n<a href=\"https://kitao.github.io/pyxel/wasm/examples/03_draw_api.html\">\n<img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/03_draw_api.gif\" width=\"320\">\n</a>\n<a href=\"https://kitao.github.io/pyxel/wasm/examples/04_sound_api.html\">\n<img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/04_sound_api.gif\" width=\"320\">\n</a>\n<a href=\"https://kitao.github.io/pyxel/wasm/examples/image_editor.html\">\n<img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/image_tilemap_editor.gif\" width=\"320\">\n</a>\n<a href=\"https://kitao.github.io/pyxel/wasm/examples/sound_editor.html\">\n<img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/sound_music_editor.gif\" width=\"320\">\n</a>\n</p>\n\nPyxel's specifications and APIs are inspired by [PICO-8](https://www.lexaloffle.com/pico-8.php) and [TIC-80](https://tic80.com/).\n\nPyxel is open source and free to use. Let's start making a retro game with Pyxel!\n\n## Specifications\n\n- Runs on Windows, Mac, Linux, and Web\n- Programming with Python\n- 16 color palette\n- 256x256 sized 3 image banks\n- 256x256 sized 8 tilemaps\n- 4 channels with 64 definable sounds\n- 8 musics which can combine arbitrary sounds\n- Keyboard, mouse, and gamepad inputs\n- Image and sound editor\n\n### Color Palette\n\n<img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/05_color_palette.png\">\n\n<img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/pyxel_palette.png\">\n\n## How to Install\n\n### Windows\n\nAfter installing [Python3](https://www.python.org/) (version 3.7 or higher), run the following command:\n\n```sh\npip install -U pyxel\n```\n\nIf you install Python using the official installer, please check the `Add Python 3.x to PATH` checkbox to enable `pyxel` command.\n\n### Mac\n\nAfter installing [Homebrew](https://brew.sh/), run the following commands:\n\n```sh\nbrew install pipx\npipx ensurepath\npipx install pyxel\n```\n\nTo update the version after installing Pyxel, run `pipx upgrade pyxel`.\n\n### Linux\n\nAfter installing the SDL2 package (`libsdl2-dev` for Ubuntu), [Python3](https://www.python.org/) (version 3.7 or higher), and `python3-pip`, run the following command:\n\n```sh\nsudo pip3 install -U pyxel\n```\n\nIf the above doesn't work, try self-building according to the instructions in [Makefile](https://github.com/kitao/pyxel/blob/main//Makefile).\n\n### Web\n\nThe web version of Pyxel does not require Python or Pyxel installation and runs on PCs as well as smartphones and tablets with supported web browsers.\n\nFor specific instructions, please refer to [this page](https://github.com/kitao/pyxel/wiki/How-To-Use-Pyxel-Web).\n\n### Try Pyxel Examples\n\nAfter installing Pyxel, the examples of Pyxel will be copied to the current directory with the following command:\n\n```sh\npyxel copy_examples\n```\n\nThe examples to be copied are as follows:\n\n<table>\n<tr>\n<td>01_hello_pyxel.py</td>\n<td>Simplest application</td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/01_hello_pyxel.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/01_hello_pyxel.py\">Code</a></td>\n</tr>\n<tr>\n<td>02_jump_game.py</td>\n<td>Jump game with Pyxel resource file</td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/02_jump_game.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/02_jump_game.py\">Code</a></td>\n</tr>\n<tr>\n<td>03_draw_api.py</td>\n<td>Demonstration of drawing APIs</td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/03_draw_api.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/03_draw_api.py\">Code</a></td>\n</tr>\n<tr>\n<td>04_sound_api.py</td>\n<td>Demonstration of sound APIs</td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/04_sound_api.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/04_sound_api.py\">Code</a></td>\n</tr>\n<tr>\n<td>05_color_palette.py</td>\n<td>Color palette list</td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/05_color_palette.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/05_color_palette.py\">Code</a></td>\n</tr>\n<tr>\n<td>06_click_game.py</td>\n<td>Mouse click game</td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/06_click_game.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/06_click_game.py\">Code</a></td>\n</tr>\n<tr>\n<td>07_snake.py</td>\n<td>Snake game with BGM</td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/07_snake.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/07_snake.py\">Code</a></td>\n</tr>\n<tr>\n<td>08_triangle_api.py</td>\n<td>Demonstration of triangle drawing APIs</td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/08_triangle_api.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/08_triangle_api.py\">Code</a></td>\n</tr>\n<tr>\n<td>09_shooter.py</td>\n<td>Shoot'em up game with screen transition</td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/09_shooter.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/09_shooter.py\">Code</a></td>\n</tr>\n<tr>\n<td>10_platformer.py</td>\n<td>Side-scrolling platform game with map</td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/10_platformer.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/10_platformer.py\">Code</a></td>\n</tr>\n<tr>\n<td>11_offscreen.py</td>\n<td>Offscreen rendering with Image class</td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/11_offscreen.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/11_offscreen.py\">Code</a></td>\n</tr>\n<tr>\n<td>12_perlin_noise.py</td>\n<td>Perlin noise animation</td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/12_perlin_noise.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/12_perlin_noise.py\">Code</a></td>\n</tr>\n<tr>\n<td>13_bitmap_font.py</td>\n<td>Drawing a bitmap font</td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/13_bitmap_font.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/13_bitmap_font.py\">Code</a></td>\n</tr>\n<tr>\n<td>14_synthesizer.py</td>\n<td>Synthesizer utilizing audio expantion features</td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/14_synthesizer.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/14_synthesizer.py\">Code</a></td>\n</tr>\n<tr>\n<td>15_tiled_map_file.py</td>\n<td>Loading and drawing a Tile Map File (.tmx)</td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/15_tiled_map_file.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/15_tiled_map_file.py\">Code</a></td>\n</tr>\n<tr>\n<td>99_flip_animation.py</td>\n<td>Animation with flip function (non-web platforms only)</td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/docs/images/99_flip_animation.gif\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/99_flip_animation.py\">Code</a></td>\n</tr>\n<tr>\n<td>30SecondsOfDaylight.pyxapp</td>\n<td>1st Pyxel Jam winning game by <a href=\"https://twitter.com/helpcomputer0\">Adam</a></td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/30SecondsOfDaylight.html\">Demo</a></td>\n<td><a href=\"https://github.com/kitao/30SecondsOfDaylight\">Code</a></td>\n</tr>\n<tr>\n<td>megaball.pyxapp</td>\n<td>Arcade ball physics game by <a href=\"https://twitter.com/helpcomputer0\">Adam</a></td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/megaball.html\">Demo</a></td>\n<td><a href=\"https://github.com/helpcomputer/megaball\">Code</a></td>\n</tr>\n<tr>\n<td>8bit-bgm-gen.pyxapp</td>\n<td>Background music generator by <a href=\"https://twitter.com/frenchbread1222\">frenchbread</a></td>\n<td><a href=\"https://kitao.github.io/pyxel/wasm/examples/8bit-bgm-gen.html\">Demo</a></td>\n<td><a href=\"https://github.com/shiromofufactory/8bit-bgm-generator\">Code</a></td>\n</tr>\n</table>\n\nAn examples can be executed with the following commands:\n\n```sh\ncd pyxel_examples\npyxel run 01_hello_pyxel.py\npyxel play 30SecondsOfDaylight.pyxapp\n```\n\n## How to Use\n\n### Create Pyxel Application\n\nAfter importing the Pyxel module in your python script, specify the window size with `init` function first, then starts the Pyxel application with `run` function.\n\n```python\nimport pyxel\n\npyxel.init(160, 120)\n\ndef update():\n if pyxel.btnp(pyxel.KEY_Q):\n pyxel.quit()\n\ndef draw():\n pyxel.cls(0)\n pyxel.rect(10, 10, 20, 20, 11)\n\npyxel.run(update, draw)\n```\n\nThe arguments of `run` function are `update` function to update each frame and `draw` function to draw screen when necessary.\n\nIn an actual application, it is recommended to wrap pyxel code in a class as below:\n\n```python\nimport pyxel\n\nclass App:\n def __init__(self):\n pyxel.init(160, 120)\n self.x = 0\n pyxel.run(self.update, self.draw)\n\n def update(self):\n self.x = (self.x + 1) % pyxel.width\n\n def draw(self):\n pyxel.cls(0)\n pyxel.rect(self.x, 0, 8, 8, 9)\n\nApp()\n```\n\nWhen creating simple graphics without animation, `show` function can be used to make the code more concise.\n\n```python\nimport pyxel\n\npyxel.init(120, 120)\npyxel.cls(1)\npyxel.circb(60, 60, 40, 7)\npyxel.show()\n```\n\n### Run Pyxel Application\n\nThe created Python script can be executed with the following command:\n\n```sh\npyxel run PYTHON_SCRIPT_FILE\n```\n\nIt can also be executed like a normal Python script:\n\n```sh\npython3 PYTHON_SCRIPT_FILE\n```\n\n### Special Controls\n\nThe following special controls can be performed while a Pyxel application is running:\n\n- `Esc`<br>\n Quit the application\n- `Alt(Option)+1`<br>\n Save the screenshot to the desktop\n- `Alt(Option)+2`<br>\n Reset the recording start time of the screen capture video\n- `Alt(Option)+3`<br>\n Save the screen capture video to the desktop (up to 10 seconds)\n- `Alt(Option)+9`<br>\n Switch between screen modes (Crisp/Smooth/Retro)\n- `Alt(Option)+0`<br>\n Toggle the performance monitor (fps, update time, and draw time)\n- `Alt(Option)+Enter`<br>\n Toggle full screen\n- `Shift+Alt(Option)+1/2/3`<br>\n Save the corresponding image bank to the desktop\n- `Shift+Alt(Option)+0`<br>\n Save the current color palette to the desktop\n\n### How to Create Resources\n\nPyxel Editor can create images and sounds used in a Pyxel application.\n\nIt starts with the following command:\n\n```sh\npyxel edit PYXEL_RESOURCE_FILE\n```\n\nIf the specified Pyxel resource file (.pyxres) exists, the file is loaded, and if it does not exist, a new file is created with the specified name.\nIf the resource file is omitted, the name is `my_resource.pyxres`.\n\nAfter starting Pyxel Editor, the file can be switched by dragging and dropping another resource file. If the resource file is dragged and dropped while holding down `Ctrl(Cmd)` key, only the resource type (Image/Tilemap/Sound/Music) that is currently being edited will be loaded. This operation enables to combine multiple resource files into one.\n\nThe created resource file can be loaded with `load` function.\n\nPyxel Editor has the following edit modes.\n\n**Image Editor**\n\nThe mode to edit the image banks.\n\n<a href=\"https://kitao.github.io/pyxel/wasm/examples/image_editor.html\">\n<img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/image_editor.gif\">\n</a>\n\nDrag and drop an image file (PNG/GIF/JPEG) onto the Image Editor to load the image into the currently selected image bank.\n\n**Tilemap Editor**\n\nThe mode to edit tilemaps in which images of the image banks are arranged in a tile pattern.\n\n<a href=\"https://kitao.github.io/pyxel/wasm/examples/tilemap_editor.html\">\n<img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/tilemap_editor.gif\">\n</a>\n\nDrag 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.\n\n**Sound Editor**\n\nThe mode to edit sounds.\n\n<a href=\"https://kitao.github.io/pyxel/wasm/examples/sound_editor.html\">\n<img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/sound_editor.gif\">\n</a>\n\n**Music Editor**\n\nThe mode to edit musics in which the sounds are arranged in order of playback.\n\n<a href=\"https://kitao.github.io/pyxel/wasm/examples/music_editor.html\">\n<img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/music_editor.gif\">\n</a>\n\n### Other Resource Creation Methods\n\nPyxel images and tilemaps can also be created by the following methods:\n\n- Create an image from a list of strings with `Image.set` function or `Tilemap.set` function\n- Load an image file (PNG/GIF/JPEG) in Pyxel palette with `Image.load` function\n\nPyxel sounds can also be created in the following method:\n\n- Create a sound from strings with `Sound.set` function or `Music.set` function\n\nPlease refer to the API reference for usage of these functions.\n\n### How to Distribute Applications\n\nPyxel supports a dedicated application distribution file format (Pyxel application file) that works across platforms.\n\nCreate the Pyxel application file (.pyxapp) with the following command:\n\n```sh\npyxel package APP_DIR STARTUP_SCRIPT_FILE\n```\n\nIf the application should include resources or additional modules, place them in the application directory.\n\nThe created application file can be executed with the following command:\n\n```sh\npyxel play PYXEL_APP_FILE\n```\n\nPyxel application file also can be converted to an executable or an HTML file with the `pyxel app2exe` or `pyxel app2html` commands.\n\n## API Reference\n\n### System\n\n- `width`, `height`<br>\n The width and height of the screen\n\n- `frame_count`<br>\n The number of the elapsed frames\n\n- `init(width, height, [title], [fps], [quit_key], [display_scale], [capture_scale], [capture_sec])`<br>\n Initialize the Pyxel application with screen size (`width`, `height`). The following can be specified as options: the window title with `title`, the frame rate with `fps`, the key to quit the application with `quit_key`, the scale of the display with `display_scale`, the scale of the screen capture with `capture_scale`, and the maximum recording time of the screen capture video with `capture_sec`.<br>\n e.g. `pyxel.init(160, 120, title=\"My Pyxel App\", fps=60, quit_key=pyxel.KEY_NONE, capture_scale=3, capture_sec=0)`\n\n- `run(update, draw)`<br>\n Start the Pyxel application and call `update` function for frame update and `draw` function for drawing.\n\n- `show()`<br>\n Show the screen and wait until the `Esc` key is pressed.\n\n- `flip()`<br>\n Refresh the screen by one frame. The application exits when the `Esc` key is pressed. This function does not work in the web version.\n\n- `quit()`<br>\n Quit the Pyxel application.\n\n### Resource\n\n- `load(filename, [excl_images], [excl_tilemaps], [excl_sounds], [excl_musics])`<br>\n Load the resource file (.pyxres). If an option is `True`, the resource will not be loaded. If a palette file (.pyxpal) of the same name exists in the same location as the resource file, the palette display color will also be changed. The palette file is a hexadecimal entry of the display colors (e.g. `1100FF`), separated by newlines. The palette file can also be used to change the colors displayed in Pyxel Editor.\n\n### Input\n\n- `mouse_x`, `mouse_y`<br>\n The current position of the mouse cursor\n\n- `mouse_wheel`<br>\n The current value of the mouse wheel\n\n- `btn(key)`<br>\n Return `True` if `key` is pressed, otherwise return `False`. ([Key definition list](https://github.com/kitao/pyxel/blob/main//python/pyxel/__init__.pyi))\n\n- `btnp(key, [hold], [repeat])`<br>\n Return `True` if `key` is pressed at that frame, otherwise return `False`. When `hold` and `repeat` are specified, `True` will be returned at the `repeat` frame interval when the `key` is held down for more than `hold` frames.\n\n- `btnr(key)`<br>\n Return `True` if `key` is released at that frame, otherwise return `False`.\n\n- `mouse(visible)`<br>\n If `visible` is `True`, show the mouse cursor. If `False`, hide it. Even if the mouse cursor is not displayed, its position is updated.\n\n### Graphics\n\n- `colors`<br>\n 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.<br>\n e.g. `old_colors = pyxel.colors.to_list(); pyxel.colors.from_list([0x111111, 0x222222, 0x333333]); pyxel.colors[15] = 0x112233`\n\n- `images`<br>\n List of the image banks (0-2). (See the Image class)<br>\n e.g. `pyxel.images[0].load(0, 0, \"title.png\")`\n\n- `tilemaps`<br>\n List of the tilemaps (0-7). (See the Tilemap class)\n\n- `clip(x, y, w, h)`<br>\n Set the drawing area of the screen from (`x`, `y`) to width `w` and height `h`. Reset the drawing area to full screen with `clip()`.\n\n- `camera(x, y)`<br>\n Change the upper left corner coordinates of the screen to (`x`, `y`). Reset the upper left corner coordinates to (`0`, `0`) with `camera()`.\n\n- `pal(col1, col2)`<br>\n Replace color `col1` with `col2` at drawing. `pal()` to reset to the initial palette.\n\n- `dither(alpha)`<br>\n Applies dithering (pseudo-transparency) at drawing. Set `alpha` in the range 0.0-1.0, where 0.0 is transparent and 1.0 is opaque.\n\n- `cls(col)`<br>\n Clear screen with color `col`.\n\n- `pget(x, y)`<br>\n Get the color of the pixel at (`x`, `y`).\n\n- `pset(x, y, col)`<br>\n Draw a pixel of color `col` at (`x`, `y`).\n\n- `line(x1, y1, x2, y2, col)`<br>\n Draw a line of color `col` from (`x1`, `y1`) to (`x2`, `y2`).\n\n- `rect(x, y, w, h, col)`<br>\n Draw a rectangle of width `w`, height `h` and color `col` from (`x`, `y`).\n\n- `rectb(x, y, w, h, col)`<br>\n Draw the outline of a rectangle of width `w`, height `h` and color `col` from (`x`, `y`).\n\n- `circ(x, y, r, col)`<br>\n Draw a circle of radius `r` and color `col` at (`x`, `y`).\n\n- `circb(x, y, r, col)`<br>\n Draw the outline of a circle of radius `r` and color `col` at (`x`, `y`).\n\n- `elli(x, y, w, h, col)`<br>\n Draw an ellipse of width `w`, height `h` and color `col` from (`x`, `y`).\n\n- `ellib(x, y, w, h, col)`<br>\n Draw the outline of an ellipse of width `w`, height `h` and color `col` from (`x`, `y`).\n\n- `tri(x1, y1, x2, y2, x3, y3, col)`<br>\n Draw a triangle with vertices (`x1`, `y1`), (`x2`, `y2`), (`x3`, `y3`) and color `col`.\n\n- `trib(x1, y1, x2, y2, x3, y3, col)`<br>\n Draw the outline of a triangle with vertices (`x1`, `y1`), (`x2`, `y2`), (`x3`, `y3`) and color `col`.\n\n- `fill(x, y, col)`<br>\n Fill the area connected with the same color as (`x`, `y`) with color `col`.\n\n- `blt(x, y, img, u, v, w, h, [colkey])`<br>\n Copy the region of size (`w`, `h`) from (`u`, `v`) of the image bank `img`(0-2) to (`x`, `y`). If negative value is set for `w` and/or `h`, it will reverse horizontally and/or vertically. If `colkey` is specified, treated as transparent color.\n\n<img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/blt_figure.png\">\n\n- `bltm(x, y, tm, u, v, w, h, [colkey])`<br>\n Copy the region of size (`w`, `h`) from (`u`, `v`) of the tilemap `tm`(0-7) to (`x`, `y`). If negative value is set for `w` and/or `h`, it will reverse horizontally and/or vertically. If `colkey` is specified, treated as transparent color. The size of a tile is 8x8 pixels and is stored in a tilemap as a tuple of `(tile_x, tile_y)`.\n\n<img src=\"https://raw.githubusercontent.com/kitao/pyxel/main//docs/images/bltm_figure.png\">\n\n- `text(x, y, s, col)`<br>\n Draw a string `s` of color `col` at (`x`, `y`).\n\n### Audio\n\n- `sounds`<br>\n List of the sounds (0-63). (See the Sound class)<br>\n e.g. `pyxel.sounds[0].speed = 60`\n\n- `musics`<br>\n List of the musics (0-7). (See the Music class)\n\n- `play(ch, snd, [tick], [loop])`<br>\n Play the sound `snd`(0-63) on channel `ch`(0-3). If `snd` is a list, it will be played in order. The playback start position can be specified by `tick`(1 tick = 1/120 seconds). If `True` is specified for `loop`, loop playback is performed.\n\n- `playm(msc, [tick], [loop])`<br>\n Play the music `msc`(0-7). The playback start position can be specified by `tick`(1 tick = 1/120 seconds). If `True` is specified for `loop`, loop playback is performed.\n\n- `stop([ch])`<br>\n Stops playback of the specified channel `ch`(0-3). `stop()` to stop playing all channels.\n\n- `play_pos(ch)`<br>\n Get the sound playback position of channel `ch`(0-3) as a tuple of `(sound no, note no)`. Returns `None` when playback is stopped.\n\n### Math\n\n- `ceil(x)`<br>\n Returns the smallest integer greater than or equal to `x`.\n\n- `floor(x)`<br>\n Returns the largest integer less than or equal to `x`.\n\n- `sgn(x)`<br>\n Returns 1 when `x` is positive, 0 when it is zero, and -1 when it is negative.\n\n- `sqrt(x)`<br>\n Returns the square root of `x`.\n\n- `sin(deg)`<br>\n Returns the sine of `deg` degrees.\n\n- `cos(deg)`<br>\n Returns the cosine of `deg` degrees.\n\n- `atan2(y, x)`<br>\n Returns the arctangent of `y`/`x` in degrees.\n\n- `rseed(seed)`<br>\n Sets the seed of the random number generator.\n\n- `rndi(a, b)`<br>\n Returns an random integer greater than or equal to `a` and less than or equal to `b`.\n\n- `rndf(a, b)`<br>\n Returns a random decimal greater than or equal to `a` and less than or equal to `b`.\n\n- `nseed(seed)`<br>\n Sets the seed of Perlin noise.\n\n- `noise(x, [y], [z])`<br>\n Returns the Perlin noise value for the specified coordinates.\n\n### Image Class\n\n- `width`, `height`<br>\n The width and height of the image\n\n- `set(x, y, data)`<br>\n Set the image at (`x`, `y`) by a list of strings.<br>\n e.g. `pyxel.images[0].set(10, 10, [\"0123\", \"4567\", \"89ab\", \"cdef\"])`\n\n- `load(x, y, filename)`<br>\n Load the image file (PNG/GIF/JPEG) at (`x`, `y`).\n\n- `pget(x, y)`<br>\n Get the pixel color at (`x`, `y`).\n\n- `pset(x, y, col)`<br>\n Draw a pixel of color `col` at (`x`, `y`).\n\n### Tilemap Class\n\n- `width`, `height`<br>\n The width and height of the tilemap\n\n- `imgsrc`<br>\n The image bank (0-2) referenced by the tilemap\n\n- `set(x, y, data)`<br>\n Set the tilemap at (`x`, `y`) by a list of strings.<br>\n e.g. `pyxel.tilemap(0).set(0, 0, [\"0000 0100 a0b0\", \"0001 0101 a1b1\"])`\n\n- `load(x, y, filename, layer)`<br>\n Load the layer in the drawing order `layer`(0-) from the TMX file (Tiled Map File) at (`x`, `y`).\n\n- `pget(x, y)`<br>\n Get the tile at (`x`, `y`). A tile is a tuple of `(tile_x, tile_y)`.\n\n- `pset(x, y, tile)`<br>\n Draw a `tile` at (`x`, `y`). A tile is a tuple of `(tile_x, tile_y)`.\n\n### Sound Class\n\n- `notes`<br>\n List of notes (0-127). The higher the number, the higher the pitch, and at 33 it becomes 'A2'(440Hz). The rest is -1.\n\n- `tones`<br>\n List of tones (0:Triangle / 1:Square / 2:Pulse / 3:Noise)\n\n- `volumes`<br>\n List of volumes (0-7)\n\n- `effects`<br>\n List of effects (0:None / 1:Slide / 2:Vibrato / 3:FadeOut)\n\n- `speed`<br>\n 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.\n\n- `set(notes, tones, volumes, effects, speed)`<br>\n Set notes, tones, volumes, and effects with a string. If the tones, volumes, and effects length are shorter than the notes, it is repeated from the beginning.\n\n- `set_notes(notes)`<br>\n Set the notes with a string made of 'CDEFGAB'+'#-'+'01234' or 'R'. Case-insensitive and whitespace is ignored.<br>\n e.g. `pyxel.sounds[0].set_notes(\"G2B-2D3R RF3F3F3\")`\n\n- `set_tones(tones)`<br>\n Set the tones with a string made of 'TSPN'. Case-insensitive and whitespace is ignored.<br>\n e.g. `pyxel.sounds[0].set_tones(\"TTSS PPPN\")`\n\n- `set_volumes(volumes)`<br>\n Set the volumes with a string made of '01234567'. Case-insensitive and whitespace is ignored.<br>\n e.g. `pyxel.sounds[0].set_volumes(\"7777 7531\")`\n\n- `set_effects(effects)`<br>\n Set the effects with a string made of 'NSVF'. Case-insensitive and whitespace is ignored.<br>\n e.g. `pyxel.sounds[0].set_effects(\"NFNF NVVS\")`\n\n### Music Class\n\n- `seqs`<br>\n Two-dimensional list of sounds (0-63) with the number of channels\n\n- `set(seq0, seq1, seq2, ...)`<br>\n Set the lists of sound (0-63) of channels. If an empty list is specified, that channel is not used for playback.<br>\n e.g. `pyxel.musics[0].set([0, 1], [], [3])`\n\n### Advanced APIs\n\nPyxel has \"advanced APIs\" that are not mentioned in this reference because they \"may confuse users\" or \"need specialized knowledge to use\".\n\nIf you are familiar with your skills, try to create amazing works with [this](https://github.com/kitao/pyxel/blob/main//python/pyxel/__init__.pyi) as a clue!\n\n## How to Contribute\n\n### Submitting Issues\n\nUse the [Issue Tracker](https://github.com/kitao/pyxel/issues) to submit bug reports and feature/enhancement requests. Before submitting a new issue, ensure that there is no similar open issue.\n\n### Manual Testing\n\nAnyone manually testing the code and reporting bugs or suggestions for enhancements in the [Issue Tracker](https://github.com/kitao/pyxel/issues) are very welcome!\n\n### Submitting Pull Requests\n\nPatches/fixes are accepted in form of pull requests (PRs). Make sure the issue the pull request addresses is open in the Issue Tracker.\n\nSubmitted pull request is deemed to have agreed to publish under [MIT License](https://github.com/kitao/pyxel/blob/main//LICENSE).\n\n## Other Information\n\n- [Q&A](https://github.com/kitao/pyxel/wiki/Pyxel-Q&A)\n- [User Examples](https://github.com/kitao/pyxel/wiki/Pyxel-User-Examples)\n- [Developer's Twitter account](https://twitter.com/kitao)\n\n## License\n\nPyxel is under [MIT License](https://github.com/kitao/pyxel/blob/main//LICENSE). It can be reused within proprietary software, provided that all copies of the software or its substantial portions include a copy of the terms of the MIT License and also a copyright notice.\n\n## Recruiting Sponsors\n\nPyxel is looking for sponsors on GitHub Sponsors. Consider sponsoring Pyxel for continued maintenance and feature additions. Sponsors can consult about Pyxel as a benefit. Please see [here](https://github.com/sponsors/kitao) for details.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A retro game engine for Python",
"version": "2.0.12",
"project_urls": {
"Changelog": "https://github.com/kitao/pyxel/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/kitao/pyxel",
"Repository": "https://github.com/kitao/pyxel.git"
},
"split_keywords": [
"game",
" gamedev"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "84b4d94efadd8a9b5701d5c50fe72f917d49fd1557aa813535c1a451f423355d",
"md5": "1529a594d9c5c916257cb498134ad740",
"sha256": "a0f112b87a00a8cb4dad6e40d31a696cb7ae4f21e294225de2afa5133a222533"
},
"downloads": -1,
"filename": "pyxel-2.0.12-cp37-abi3-macosx_10_12_x86_64.whl",
"has_sig": false,
"md5_digest": "1529a594d9c5c916257cb498134ad740",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 3175255,
"upload_time": "2024-05-04T23:35:47",
"upload_time_iso_8601": "2024-05-04T23:35:47.376579Z",
"url": "https://files.pythonhosted.org/packages/84/b4/d94efadd8a9b5701d5c50fe72f917d49fd1557aa813535c1a451f423355d/pyxel-2.0.12-cp37-abi3-macosx_10_12_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "248e65aa809237160d2bfc677f3ea69725e8056fa2ca94334acdd2184353e9f8",
"md5": "62a736bbf8e27baaf555291bc159561c",
"sha256": "730864882881cbf9c7576978c57b24f7c415d6124ee99d4d548462265890cbc0"
},
"downloads": -1,
"filename": "pyxel-2.0.12-cp37-abi3-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "62a736bbf8e27baaf555291bc159561c",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 3007397,
"upload_time": "2024-05-04T23:35:50",
"upload_time_iso_8601": "2024-05-04T23:35:50.569720Z",
"url": "https://files.pythonhosted.org/packages/24/8e/65aa809237160d2bfc677f3ea69725e8056fa2ca94334acdd2184353e9f8/pyxel-2.0.12-cp37-abi3-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a022e0c9dedff2c32337220a3ab901e05f2126145c401131cf07907bed33c88e",
"md5": "3e3c1032db839ef713925ff9d60a118e",
"sha256": "6e7cbef282b294824c2905a29cf8f92c95c731e0e324fd54aba37c4166ae0742"
},
"downloads": -1,
"filename": "pyxel-2.0.12-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "3e3c1032db839ef713925ff9d60a118e",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2791047,
"upload_time": "2024-05-04T23:35:52",
"upload_time_iso_8601": "2024-05-04T23:35:52.775547Z",
"url": "https://files.pythonhosted.org/packages/a0/22/e0c9dedff2c32337220a3ab901e05f2126145c401131cf07907bed33c88e/pyxel-2.0.12-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a33e0df6a6c917380165e572c9358ce9cb74f8c96b35a5db00b2e4338b870afa",
"md5": "e2185d4fbc0e1f8b09abe8a82582a234",
"sha256": "c38d7bd1e6e9aef0191aa2d88bf0808e4b60b6afcfdca970d6769312e8ba21f3"
},
"downloads": -1,
"filename": "pyxel-2.0.12-cp37-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl",
"has_sig": false,
"md5_digest": "e2185d4fbc0e1f8b09abe8a82582a234",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2766261,
"upload_time": "2024-05-04T23:35:55",
"upload_time_iso_8601": "2024-05-04T23:35:55.057126Z",
"url": "https://files.pythonhosted.org/packages/a3/3e/0df6a6c917380165e572c9358ce9cb74f8c96b35a5db00b2e4338b870afa/pyxel-2.0.12-cp37-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "169d615752ac3cdfa7d9c73e0e7dc932d3241956877c7a53699b02d3407660f8",
"md5": "b48a1c7e5a08f2b8cd860c6effcef2e5",
"sha256": "50235e4b1b4ff45102a0b1676ae42ec36d7a6cd76e2734616f0658ff3408105e"
},
"downloads": -1,
"filename": "pyxel-2.0.12-cp37-abi3-manylinux_2_17_i686.manylinux2014_i686.whl",
"has_sig": false,
"md5_digest": "b48a1c7e5a08f2b8cd860c6effcef2e5",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2976084,
"upload_time": "2024-05-04T23:35:57",
"upload_time_iso_8601": "2024-05-04T23:35:57.264216Z",
"url": "https://files.pythonhosted.org/packages/16/9d/615752ac3cdfa7d9c73e0e7dc932d3241956877c7a53699b02d3407660f8/pyxel-2.0.12-cp37-abi3-manylinux_2_17_i686.manylinux2014_i686.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7cbbc922ffab7cb5c67669991313821c76ac1b015be3ae66345b2a0163e5892b",
"md5": "e7b0093f591897e59ee608186c5a0501",
"sha256": "0e56468d0ec679ae93ce52c56fc3b4b030a07c2961ee5bb53b746561b0930047"
},
"downloads": -1,
"filename": "pyxel-2.0.12-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "e7b0093f591897e59ee608186c5a0501",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2794162,
"upload_time": "2024-05-04T23:35:59",
"upload_time_iso_8601": "2024-05-04T23:35:59.065135Z",
"url": "https://files.pythonhosted.org/packages/7c/bb/c922ffab7cb5c67669991313821c76ac1b015be3ae66345b2a0163e5892b/pyxel-2.0.12-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5d68a284ebb1fb5fcb5a8bde04533cf6848215d66ce06d393c6ebd18414ac9eb",
"md5": "da75640f212b9ce3664f629b777ef41d",
"sha256": "7d75c0bbc019acaed8d8b36793088400f4fe0f931a8a66ddda55cc01333293b9"
},
"downloads": -1,
"filename": "pyxel-2.0.12-cp37-abi3-win32.whl",
"has_sig": false,
"md5_digest": "da75640f212b9ce3664f629b777ef41d",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2751428,
"upload_time": "2024-05-04T23:36:01",
"upload_time_iso_8601": "2024-05-04T23:36:01.655460Z",
"url": "https://files.pythonhosted.org/packages/5d/68/a284ebb1fb5fcb5a8bde04533cf6848215d66ce06d393c6ebd18414ac9eb/pyxel-2.0.12-cp37-abi3-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "44a0697b0873f4716f3c6b3b5558c1e2519e8d15c1f8166a02ab15d8238f40b7",
"md5": "ce5ceb718cf6c7054e820397965b9029",
"sha256": "b5d22bef0ba94b061f83a79a3919625564c88abf644a9fc7cfa3db6a3a8924b3"
},
"downloads": -1,
"filename": "pyxel-2.0.12-cp37-abi3-win_amd64.whl",
"has_sig": false,
"md5_digest": "ce5ceb718cf6c7054e820397965b9029",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2915869,
"upload_time": "2024-05-04T23:36:04",
"upload_time_iso_8601": "2024-05-04T23:36:04.311465Z",
"url": "https://files.pythonhosted.org/packages/44/a0/697b0873f4716f3c6b3b5558c1e2519e8d15c1f8166a02ab15d8238f40b7/pyxel-2.0.12-cp37-abi3-win_amd64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-04 23:35:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kitao",
"github_project": "pyxel",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyxel"
}
JSON
