Skip to content

Latest commit

 

History

History
130 lines (80 loc) · 5.62 KB

faq-en.md

File metadata and controls

130 lines (80 loc) · 5.62 KB

Pyxel FAQ

Learning Pyxel

Where do I start to learn Pyxel?

It is recommended to try 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.

Are there any books on Pyxel?

The official book is available in Japanese only.

API Specification and Usage

What is the difference between the update and draw functions?

The update function is called every frame, but the draw function may be skipped if the processing time exceeds the allowable limit. This design in Pyxel reduces the impact of rendering load and OS interruptions, enabling smooth animation.

How do I use Pyxel's MML?

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

Passing an MML string to the mml function of the Sound class causes that Sound to be played according to the MML content. 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

File cannot be loaded. It may fail when the environment changes.

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.

How can I save application-specific data like high scores or game progress?

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

Using Pyxel Tools

Can I try Pyxel without installing it?

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.

How do I publish my Pyxel app on the web?

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

Can I change the palette colors in Pyxel Editor?

By placing a file with the same name but with the .pyxpal extension in the same directory as the Pyxel resource file (.pyxres), the palette display colors in Pyxel Editor will be updated. Palette files can be created with the save_pal function, or manually as a text file with one hex color code per line.

Migration Guide

How to migrate code to version 2.4

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
  • To use the old MML syntax, use the Sound class's old_mml function
  • 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

Can I use Pyxel for commercial purposes without the author's permission?

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 it without the author's permission. However, since Pyxel is developed by a single individual, it would be appreciated if you could contact the author or consider sponsoring their work if possible.