Pyxel FAQ

Learning Pyxel

We recommend trying Pyxel's example code in the following order.

1. 01_hello_pyxel — Pyxel basics
2. 05_color_palette — Color palette
3. 03_draw_api — Drawing API
4. 04_sound_api — Sound API
5. 02_jump_game — Game implementation

You can copy the examples with pyxel copy_examples, or run them in your browser on Pyxel Showcase.

The official book is available in Japanese only.

API Specification and Usage

The update function is called every frame, but the draw function may be skipped if the processing time exceeds the allowable limit. Pyxel uses this design to reduce the impact of rendering load and OS interrupts, enabling smooth animation.

MML (Music Macro Language) is a language for defining sounds by describing notes, tempo, and other parameters as a string.

Pass an MML string to the Sound class's mml function, and that Sound will play back following the MML. Calling mml() with no arguments clears the MML setting.

pyxel.sounds[0].mml("CDEFGAB>C")

You can also play an MML string directly by passing it to the play function instead of a sound number.

pyxel.play(0, "CDEFG")

For available MML commands, see Pyxel MML Commands. For usage examples, see the demo and code of the 09_shooter.py example.

You can also create and share MML in your browser using Pyxel MML Studio.

File Operations and Data Management

Make sure that the current directory is set as intended when loading files.

When Pyxel's init function is called, the current directory is changed to the same location as the script file. After that, files can be specified using relative paths. However, loading may fail if you try to open a file before calling init or if the current directory is changed after calling init.

Pass the developer name (vendor_name) and application name (app_name) to the user_data_dir(vendor_name, app_name) function. It will create a directory suitable for data storage on the current platform and return its path. Use this directory to save and load your application's files.

Using Pyxel Tools

With Pyxel Code Maker, you can create and run Pyxel apps in your browser. However, it does not support multi-file projects, so a local environment is recommended for full-scale development.

Pyxel Showcase lets you browse and run sample code and apps in your browser.

There are three methods: Pyxel Web Launcher, app2html, and HTML Custom Elements. For details, see How to Use Pyxel for Web.

If you place a file with the same name but the .pyxpal extension in the same directory as the Pyxel resource file (.pyxres), Pyxel Editor will display the palette using those colors. Palette files can be created with the save_pal function, or manually as a text file with one RRGGBB hex color per line.

Migration Guide

In Pyxel 2.4, the sound engine and MML syntax have been revamped.

To make your code compatible with version 2.4, please make the following changes:

• Rename the waveform field of the Tone class to wavetable
• Change the tick argument of the play and playm functions to sec (a float value in seconds)
• Update code to handle the return value of the play_pos function, which is now (sound_no, sec)
• Change the count argument of the save function in the Sound and Music classes to sec
• If you need the playback duration of a sound, use the total_sec function of the Sound class
• For the Sound class's mml function, use code that follows the new MML syntax (old syntax is auto-detected; the old_mml function is deprecated)
• Change the excl_* option in the save and load functions to exclude_*
• Remove the incl_* option from the save and load functions

For details on the new MML syntax, see "How do I use Pyxel's MML?" above.

Licensing and Sponsorship

As long as you comply with the MIT License and clearly display the full text of the copyright and license in the source code or license file, you are free to sell or distribute your work without the author's permission. That said, Pyxel is developed by a single individual, so reaching out to the author or becoming a sponsor would be greatly appreciated.