[ English | 中文 | Deutsch | Español | Français | Italiano | 日本語 | 한국어 | Português | Русский ]
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.
![](https://raw.githubusercontent.com/dora-0/pyxel/main/doc/images/01_hello_pyxel.gif)
![](https://raw.githubusercontent.com/dora-0/pyxel/main/doc/images/02_jump_game.gif)
![](https://raw.githubusercontent.com/dora-0/pyxel/main/doc/images/03_draw_api.gif)
![](https://raw.githubusercontent.com/dora-0/pyxel/main/doc/images/04_sound_api.gif)
![](https://raw.githubusercontent.com/dora-0/pyxel/main/doc/images/image_tilemap_editor.gif)
![](https://raw.githubusercontent.com/dora-0/pyxel/main/doc/images/sound_music_editor.gif)
The specifications of Pyxel are referring to awesome PICO-8 and TIC-80.
Pyxel is open source and free to use. Let's start making a retro game with Pyxel!
- Run on Windows, Mac, and Linux
- 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
There are two types of Pyxel, a packaged version and a standalone version.
The packaged version of Pyxel uses Pyxel as a Python extension module.
Recommended for those who are familiar with managing Python packages using the pip
command or who want to develop full-fledged Python applications.
Windows
After installing Python3 (version 3.7 or higher), run the following command:
pip install -U pyxel
Mac
After installing Python3 (version 3.7 or higher), run the following command:
pip3 install -U pyxel
Linux
After installing the SDL2 package (libsdl2-dev
for Ubuntu), Python3 (version 3.7 or higher), and python3-pip
, run the following command:
sudo pip3 install -U pyxel
If the above doesn't work, try self-building by following the steps below after installing cmake
and rust
:
git clone https://github.com/kitao/pyxel.git
cd pyxel
make clean all
sudo pip3 install .
The standalone version of Pyxel uses Pyxel as a standalone tool that does not depend on Python.
Recommended for those who want to start programming easily without worrying about Python settings, or those who want to play Pyxel games immediately.
Windows
Download and run the latest version of the Windows installer (pyxel-[version]-windows-setup.exe
) from the Download Page.
Mac
After installing Homebrew, run the following commands:
brew tap kitao/pyxel
brew install pyxel
Linux
After installing the SDL2 package (libsdl2-dev
for Ubuntu) and installing Homebrew, run the following commands:
brew tap kitao/pyxel
brew install pyxel
If the above doesn't work, try self-building the packaged version.
After installing Pyxel, the examples of Pyxel will be copied to the current directory with the following command:
pyxel copy_examples
The examples to be copied are as follows:
- 01_hello_pyxel.py - Simplest application
- 02_jump_game.py - Jump game with Pyxel resource file
- 03_draw_api.py - Demonstration of drawing APIs
- 04_sound_api.py - Demonstration of sound APIs
- 05_color_palette.py - Color palette list
- 06_click_game.py - Mouse click game
- 07_snake.py - Snake game with BGM
- 08_triangle_api.py - Demonstration of triangle drawing APIs
- 09_shooter.py - Shoot'em up game with screen transition
- 10_platformer.py - Side-scrolling platform game with map
- 11_offscreen.py - Offscreen rendering with Image class
- 30SecondsOfDaylight.pyxapp - 1st Pyxel Jam winning game by Adam
- megaball.pyxapp - Arcade ball physics game by Adam
An examples can be executed with the following commands:
cd pyxel_examples
pyxel run 01_hello_pyxel.py
pyxel play 30SecondsOfDaylight.pyxapp
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.
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:
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()
It is also possible to write simple code using show
function and flip
function to draw simple graphics and animations.
show
function displays the screen and waits until the Esc
key is pressed.
import pyxel
pyxel.init(120, 120)
pyxel.cls(1)
pyxel.circb(60, 60, 40, 7)
pyxel.show()
flip
function updates the screen once.
import pyxel
pyxel.init(120, 80)
while True:
pyxel.cls(3)
pyxel.rectb(pyxel.frame_count % 160 - 40, 20, 40, 40, 7)
pyxel.flip()
The created Python script can be executed with the following command:
pyxel run PYTHON_SCRIPT_FILE
For the packaged version, it can be executed like a normal Python script:
cd pyxel_examples
python3 PYTHON_SCRIPT_FILE
(For Windows, type python
instead of python3
)
The following special controls can be performed while a Pyxel application is running:
Esc
Quit the applicationAlt(Option)+1
Save the screenshot to the desktopAlt(Option)+2
Reset the recording start time of the screen capture videoAlt(Option)+3
Save the screen capture video to the desktop (up to 10 seconds)Alt(Option)+0
Toggle the performance monitor (fps, update time, and draw time)Alt(Option)+Enter
Toggle full screen
Pyxel Editor can create images and sounds used in a Pyxel application.
It starts with the following command:
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.
By dragging and dropping an image file (png/gif/jpeg) onto the Image Editor screen, the image can be loaded 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.
Sound Editor:
The mode to edit sounds.
Music Editor:
The mode to edit musics in which the sounds are arranged in order of playback.
Pyxel images and tilemaps can also be created by the following methods:
- Create an image from a list of strings with
Image.set
function orTilemap.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 orMusic.set
function
Please refer to the API reference for usage of these functions.
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:
pyxel package APP_ROOT_DIR STARTUP_SCRIPT_FILE
If the application should include resources or additional modules, place them in the application folder.
The created application file can be executed with the following command:
pyxel play PYXEL_APP_FILE
-
width
,height
The width and height of the screen -
frame_count
The number of the elapsed frames -
init(width, height, [title], [fps], [quit_key], [capture_scale], [capture_sec])
Initialize the Pyxel application with screen size (width
,height
). The following can be specified as options: the window title withtitle
, the frame rate withfps
, the key to quit the application withquit_key
, the scale of the screen capture withcapture_scale
, and the maximum recording time of the screen capture video withcapture_sec
.
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)
Start the Pyxel application and callupdate
function for frame update anddraw
function for drawing. -
show()
Show the screen and wait until theEsc
key is pressed. (Do not use in normal applications) -
flip()
Updates the screen once. (Do not use in normal applications) -
quit()
Quit the Pyxel application.
load(filename, [image], [tilemap], [sound], [music])
Load the resource file (.pyxres). IfFalse
is specified for the resource type (image/tilemap/sound/music
), the resource will not be loaded.
-
mouse_x
,mouse_y
The current position of the mouse cursor -
mouse_wheel
The current value of the mouse wheel -
btn(key)
ReturnTrue
ifkey
is pressed, otherwise returnFalse
. (Key definition list) -
btnp(key, [hold], [period])
ReturnTrue
ifkey
is pressed at that frame, otherwise returnFalse
. Whenhold
andperiod
are specified,True
will be returned at theperiod
frame interval when thekey
is held down for more thanhold
frames. -
btnr(key)
ReturnTrue
ifkey
is released at that frame, otherwise returnFalse
. -
mouse(visible)
Ifvisible
isTrue
, show the mouse cursor. IfFalse
, hide it. Even if the mouse cursor is not displayed, its position is updated.
-
colors
List of the palette display colors. The display color is specified by a 24-bit numerical value. Usecolors.from_list
andcolors.to_list
to directly assign and retrieve Python lists.
e.g.org_colors = pyxel.colors.to_list(); pyxel.colors[15] = 0x112233; pyxel.colors.from_list(org_colors)
-
image(img)
Operate the image bankimg
(0-2). (See the Image class)
e.g.pyxel.image(0).load(0, 0, "title.png")
-
tilemap(tm)
Operate the tilemaptm
(0-7). (See the Tilemap class) -
clip(x, y, w, h)
Set the drawing area of the screen from (x
,y
) to widthw
and heighth
. Reset the drawing area to full screen withclip()
. -
camera(x, y)
Change the upper left corner coordinates of the screen to (x
,y
). Reset the upper left corner coordinates to (0
,0
) withcamera()
. -
pal(col1, col2)
Replace colorcol1
withcol2
at drawing.pal()
to reset to the initial palette. -
cls(col)
Clear screen with colorcol
. -
pget(x, y)
Get the color of the pixel at (x
,y
). -
pset(x, y, col)
Draw a pixel of colorcol
at (x
,y
). -
line(x1, y1, x2, y2, col)
Draw a line of colorcol
from (x1
,y1
) to (x2
,y2
). -
rect(x, y, w, h, col)
Draw a rectangle of widthw
, heighth
and colorcol
from (x
,y
). -
rectb(x, y, w, h, col)
Draw the outline of a rectangle of widthw
, heighth
and colorcol
from (x
,y
). -
circ(x, y, r, col)
Draw a circle of radiusr
and colorcol
at (x
,y
). -
circb(x, y, r, col)
Draw the outline of a circle of radiusr
and colorcol
at (x
,y
). -
tri(x1, y1, x2, y2, x3, y3, col)
Draw a triangle with vertices (x1
,y1
), (x2
,y2
), (x3
,y3
) and colorcol
. -
trib(x1, y1, x2, y2, x3, y3, col)
Draw the outline of a triangle with vertices (x1
,y1
), (x2
,y2
), (x3
,y3
) and colorcol
. -
blt(x, y, img, u, v, w, h, [colkey])
Copy the region of size (w
,h
) from (u
,v
) of the image bankimg
(0-2) to (x
,y
). If negative value is set forw
and/orh
, it will reverse horizontally and/or vertically. Ifcolkey
is specified, treated as transparent color.
bltm(x, y, tm, u, v, w, h, [colkey])
Copy the region of size (w
,h
) from (u
,v
) of the tilemaptm
(0-7) to (x
,y
). If negative value is set forw
and/orh
, it will reverse horizontally and/or vertically. Ifcolkey
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)
.
text(x, y, s, col)
Draw a strings
of colorcol
at (x
,y
).
-
sound(snd)
Operate the soundsnd
(0-63). (See the Sound class)
e.g.pyxel.sound(0).speed = 60
-
music(msc)
Operate the musicmsc
(0-7). (See the Music class) -
play_pos(ch)
Get the sound playback position of channelch
(0-3) as a tuple of(sound no, note no)
. ReturnsNone
when playback is stopped. -
play(ch, snd, loop=False)
Play the soundsnd
(0-63) on channelch
(0-3). Ifsnd
is a list, it will be played in order. IfTrue
is specified forloop
, loop playback is performed. -
playm(msc, loop=False)
Play the musicmsc
(0-7). IfTrue
is specified forloop
, loop playback is performed. -
stop([ch])
Stops playback of the specified channelch
(0-3).stop()
to stop playing all channels.
-
width
,height
The width and height of the image -
set(x, y, data)
Set the image at (x
,y
) by a list of strings.
e.g.pyxel.image(0).set(10, 10, ["0123", "4567", "89ab", "cdef"])
-
load(x, y, filename)
Load the image file (png/gif/jpeg) at (x
,y
). -
pget(x, y)
Get the pixel color at (x
,y
). -
pset(x, y, col)
Draw a pixel of colorcol
at (x
,y
).
-
width
,height
The width and height of the tilemap -
refimg
The image bank (0-2) referenced by the tilemap -
set(x, y, data)
Set the tilemap at (x
,y
) by a list of strings.
e.g.pyxel.tilemap(0).set(0, 0, ["000102", "202122", "a0a1a2", "b0b1b2"])
-
pget(x, y)
Get the tile at (x
,y
). A tile is a tuple of(tile_x, tile_y)
. -
pset(x, y, tile)
Draw atile
at (x
,y
). A tile is a tuple of(tile_x, tile_y)
.
-
notes
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
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) -
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 with a string. If the tones, volumes, and effects length are shorter than the notes, it is repeated from the beginning. -
set_notes(notes)
Set the notes with a string made of 'CDEFGAB'+'#-'+'0123' or 'R'. Case-insensitive and whitespace is ignored.
e.g.pyxel.sound(0).set_note("G2B-2D3R RF3F3F3")
-
set_tones(tones)
Set the tones with a string made of 'TSPN'. Case-insensitive and whitespace is ignored.
e.g.pyxel.sound(0).set_tone("TTSS PPPN")
-
set_volumes(volumes)
Set the volumes with a string made of '01234567'. Case-insensitive and whitespace is ignored.
e.g.pyxel.sound(0).set_volume("7777 7531")
-
set_effects(effects)
Set the effects with a string made of 'NSVF'. Case-insensitive and whitespace is ignored.
e.g.pyxel.sound(0).set_effect("NFNF NVVS")
-
sequences
Two-dimensional list of sounds (0-63) listed by the number of channels -
set(seq0, seq1, seq2, seq3)
Set the lists of sound (0-63) of all channels. If an empty list is specified, that channel is not used for playback.
e.g.pyxel.music(0).set([0, 1], [2, 3], [4], [])
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 as a clue!
Use the Issue Tracker to submit bug reports and feature/enhancement requests. Before submitting a new issue, ensure that there is no similar open issue.
Anyone manually testing the code and reporting bugs or suggestions for enhancements in the Issue Tracker are very welcome!
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.
Pyxel is under MIT 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.
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 for details.