[ English | 中文 | Deutsch | Español | Français | Italiano | 日本語 | 한국어 | Português | Русский | Türkçe | Українська ]
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.
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 and TIC-80.
Pyxel is open source under the MIT License and free to use. Let's start making retro games with Pyxel!
- 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 composed of sounds
- Keyboard, mouse, and gamepad inputs
- Image and sound editing tools
- User-extensible colors, sound channels, and banks
After installing Python 3 (version 3.8 or higher), run the following command:
pip install -U pyxelWhen installing Python using the official installer, make sure to check the Add Python 3.x to PATH option to enable the pyxel command.
After installing Homebrew, run the following commands:
brew install pipx
pipx ensurepath
pipx install pyxelTo upgrade Pyxel after installation, run pipx upgrade pyxel.
After installing Python 3 (version 3.8 or higher), run the following command:
pip install -U pyxelIf the previous command fails, consider building Pyxel from source by following the instructions in the Makefile.
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.
For other usage patterns, such as embedding Pyxel apps on your own site, please refer to this page.
With the Pyxel Visual Studio Code extension, you can run and develop Pyxel apps in VS Code without installing Python or Pyxel.
Installing Pyxel adds the pyxel command. Specify a command name after pyxel to perform various operations.
Run it without arguments to see the list of available commands:
pyxelPyxel, a retro game engine for Python
usage:
pyxel run PYTHON_SCRIPT_FILE(.py)
pyxel watch WATCH_DIR PYTHON_SCRIPT_FILE(.py)
pyxel play PYXEL_APP_FILE(.pyxapp)
pyxel edit [PYXEL_RESOURCE_FILE(.pyxres)]
pyxel package APP_DIR STARTUP_SCRIPT_FILE(.py)
pyxel app2exe PYXEL_APP_FILE(.pyxapp)
pyxel app2html PYXEL_APP_FILE(.pyxapp)
pyxel copy_examples
The following command copies Pyxel examples to the current directory:
pyxel copy_examplesYou can run examples locally with the following commands:
# 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.pyxappExamples can also be viewed and run in the browser from Pyxel Showcase.
In your Python script, import Pyxel, set the window size with init, and start the application with run.
import pyxel
pyxel.init(160, 120)
def update():
if pyxel.btnp(pyxel.KEY_Q):
pyxel.quit()
def draw():
pyxel.cls(0)
pyxel.rect(10, 10, 20, 20, 11)
pyxel.run(update, draw)The arguments of the run function are the update function, which processes frame updates, and the draw function, which handles screen drawing.
In an actual application, it is recommended to wrap Pyxel code in a class, as shown below:
import pyxel
class App:
def __init__(self):
pyxel.init(160, 120)
self.x = 0
pyxel.run(self.update, self.draw)
def update(self):
self.x = (self.x + 1) % pyxel.width
def draw(self):
pyxel.cls(0)
pyxel.rect(self.x, 0, 8, 8, 9)
App()For creating simple graphics without animation, you can use the show function to simplify your code.
import pyxel
pyxel.init(120, 120)
pyxel.cls(1)
pyxel.circb(60, 60, 40, 7)
pyxel.show()A created script can be executed using the python command:
python PYTHON_SCRIPT_FILEIt can also be run with the pyxel run command:
pyxel run PYTHON_SCRIPT_FILEAdditionally, the pyxel watch command monitors changes in a specified directory and automatically re-runs the program when changes are detected:
pyxel watch WATCH_DIR PYTHON_SCRIPT_FILEStop directory monitoring by pressing Ctrl(Command)+C.
The following special key actions are available while a Pyxel application is running:
Esc
Quit the applicationAlt(Option)+RorA+B+X+Y+BACKon gamepad
Reset 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 a screen capture video to the desktop (up to 10 seconds)Alt(Option)+8orA+B+X+Y+DLon gamepad
Toggle screen scaling between maximum and integerAlt(Option)+9orA+B+X+Y+DRon gamepad
Switch between screen modes (Crisp/Smooth/Retro)Alt(Option)+0orA+B+X+Y+DUon gamepad
Toggle the performance monitor (FPS/updatetime/drawtime)Alt(Option)+EnterorA+B+X+Y+DDon gamepad
Toggle fullscreenShift+Alt(Option)+1/2/3
Save image bank 0, 1, or 2 to the desktopShift+Alt(Option)+0
Save the current color palette to the desktop
Pyxel Editor creates images and sounds used in a Pyxel application.
You can start Pyxel Editor with the following command:
pyxel edit PYXEL_RESOURCE_FILEIf 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.
Pyxel images and tilemaps can also be created using the following methods:
- Create images or tilemaps from lists of strings with the
Image.setorTilemap.setfunctions - Load palette-ready image files (PNG/GIF/JPEG) with the
Image.loadfunction
Pyxel sounds and music can also be created using the following method:
- Create them from strings with the
Sound.setorMusic.setfunctions
Refer to the API reference for the usage of these functions.
Pyxel supports a cross-platform distribution format called a Pyxel application file.
Create a Pyxel application file (.pyxapp) with the pyxel package command:
pyxel package APP_DIR STARTUP_SCRIPT_FILEIf you need to include resources or additional modules, place them in the application directory.
Metadata can be displayed at runtime by specifying it in the following format within the startup script. Fields other than title and author are optional.
# title: Pyxel Platformer
# author: Takashi Kitao
# desc: A Pyxel platformer example
# site: https://github.com/kitao/pyxel?target=https://github.com
# license: MIT
# version: 1.0The created application file can be run using the pyxel play command:
pyxel play PYXEL_APP_FILEA Pyxel application file can also be converted to an executable or an HTML file using the pyxel app2exe or pyxel app2html commands.
A complete list of Pyxel APIs is available at Pyxel API Reference.
Pyxel also includes an "Advanced API" that requires specialized knowledge. You can view it by checking the "Advanced" checkbox on the reference page.
If you're confident in your skills, try using the Advanced API to create truly amazing works!
Use the Issue Tracker to submit bug reports and feature or enhancement requests. Before submitting a new issue, make sure there are no similar open issues.
Anyone who manually tests the code and reports bugs or suggestions for enhancements in the Issue Tracker is very welcome!
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.
- Pyxel Showcase
- Pyxel API Reference
- Pyxel Web Launcher
- Pyxel Code Maker
- Pyxel MML Studio
- Pyxel VS Code Extension
- Pyxel MCP Server
Pyxel is licensed under the MIT License. It can be reused in proprietary software, provided that all copies of the software or its substantial portions include a copy of the MIT License terms and a copyright notice.
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.
