How To Use Pyxel Web

Pyxel Web is a web version of Pyxel that does not require Python or Pyxel installation and runs on PCs as well as smartphones and tablets with supported web browsers.

There are three ways to use Pyxel Web:

• Use Pyxel Web Launcher by specifying a GitHub repository
  By specifying a GitHub repository in the Pyxel Web Launcher URL, you can run the application on a web browser without any prior preparation.
  This is the easiest way to do it if you publish your app on GitHub.

• Convert a Pyxel app to an HTML file
  If your app is in Pyxel application format (.pyxapp), you can convert it to an HTML file with Pyxel's app2html command.
  The created HTML file does not require a server and can be run independently.

• Write an HTML file with Pyxel custom tags
  Write an HTML file that runs your app using custom tags for Pyxel.
  The created HTML file needs to be hosted on a server, but detailed customization is possible, such as embedding it in an existing HTML page.

In the following sections, each way will be explained.

Use Pyxel Web Launcher by specifying a GitHub repository

If you have a Python script file or a Pyxel app (.pyxapp) published on GitHub, you can run it directly in Pyxel Web Launcher.

The URL format of the Pyxel Web Launcher is as follows:

https://kitao.github.io/pyxel/wasm/launcher/?<Command>=<GitHub username>.<Repository Name>.<App Directories>.<File Name Without Extension>

The command can be run to run a Python script, play to run a Pyxel app, or edit to start Pyxel Editor.

For example, if your username is taro, your repository name is my_repo, your file's directory is src/scenes, and your Python script file is title.py, the URL would be:

https://kitao.github.io/pyxel/wasm/launcher/?run=taro.my_repo.src.scenes.title

Similarly, the URL for running shooter.pyxapp in dist/games would be:

https://kitao.github.io/pyxel/wasm/launcher/?play=taro.my_repo.dist.games.shooter

Also, the run and play commands can have a gamepad attribute to enable the virtual gamepad and a packages attribute to specify additional packages.

For example, to enable the virtual gamepad and use NumPy and Pandas as additional packages, the URL would be:

https://kitao.github.io/pyxel/wasm/launcher/?run=taro.my_repo.src.scenes.title&gamepad=enabled&packages=numpy,pandas

Packages that can be added are only packages built in Pyodide.

The edit command allows you to specify the startup screen of Pyxel Editor with the editor attribute.

For example, the URL for editing the shooter.pyxres file in the assets directory with the tilemap editor as the startup screen is as follows:

https://kitao.github.io/pyxel/wasm/launcher/?run=taro.my_repo.assets.shooter&editor=tilemap

The app launch URL can also be created automatically by entering the required information on Pyxel Web Launcher page.

Convert a Pyxel app to an HTML file

A Pyxel application file (.pyxapp) can be converted into a stand-alone HTML file with the following command:

pyxel app2html your_app.pyxapp

The generated HTML file has the virtual gamepad enabled by default, but you can disable it by editing the custom tags in the HTML file.

Write an HTML file with Pyxel custom tags

You can run a Pyxel app by writing custom tags for Pyxel in your HTML file.

Pyxel custom tags can be used by adding the following script tag to your HTML file:

<script src="https://cdn.jsdelivr.net/gh/kitao/pyxel/wasm/pyxel.js"></script>

If you want to run Python code directly, write the code you want to run in the script attribute of the pyxel-run tag as follows:

<pyxel-run script="
import pyxel
pyxel.init(200, 150)
pyxel.cls(8)
pyxel.line(20, 20, 180, 130, 7)
pyxel.show()
"></pyxel-run>

If you want to load and run a separate file instead of writing Python code directly in the HTML file, add the root and name attributes to the pyxel-run tag.

root is the starting directory to search for files, and name is the file path. Write the file name with a relative path from the starting point.

For example, if the previous Python code is named test.py and placed in the same directory as the HTML file, write it as follows:

<pyxel-run root="." name="test.py"></pyxel-run>

If the starting point is the current directory ('.'), the root attribute can be omitted.

This file requires hosting on a server in order to run, as it is forbidden to load another local file directly from a local HTML file.

If you can use Python, you can start the simple server by executing the following command in the directory where the file is placed:

python -m http.server
# use python3 instead of python for mac and linux

After starting the server, you can access it like http://localhost:8000/test.html from your web browser.

Similarly, Pyxel apps (.pyxapp) can be run with the pyxel-play tag.

<pyxel-play root="https://cdn.jsdelivr.net/gh/kitao/pyxel/python/pyxel/examples" name="megaball.pyxapp"
></pyxel-play>

This example specifies a URL instead of a file path for the root attribute.

As with Pyxel Web Launcher, the pyxel-run and pyxel-play tags can have a gamepad attribute to enable the virtual gamepad and a packages attribute to specify additional packages. I can do it.

For example, to enable the virtual gamepad and use NumPy and Pandas as additional packages:

<pyxel-run name="test.py" gamepad="enabled" packages="numpy,pandas"></pyxel-run>

Packages that can be added are only packages built in Pyodide.

You can also launch Pyxel Editor with the pyxel-edit tag. Similarly to Pyxel Web Laucnher, it is also possible to specify the launch screen with the editor attribute as follows:

<pyxel-edit root="assets" name="sample.pyxres" editor="image"></pyxel-edit>