How To Use Pyxel Web (日本語)

Pyxel Web は、Python や Pyxel のインストールを必要とせず、PC だけではなく、対応する Web ブラウザーを持つスマートフォンやタブレット端末でも動作する、Web 版の Pyxel です。

Pyxel Web の利用方法には、次の 3 種類があります。

Pyxel Web Launcher に GitHub リポジトリを指定する
Pyxel Web Launcher の URL に GitHub のリポジトリを指定すると、事前の準備なしで Web ブラウザ上でアプリを動かすことができます。
アプリを GitHub で公開している場合は最も簡単な実行方法です。
Pyxel アプリを HTML ファイルに変換する
アプリが Pyxel アプリケーション形式 (.pyxapp) になっている場合は、Pyxel のapp2htmlコマンドで HTML ファイルに変換できます。
作成した HTML ファイルはサーバーを必要とせず、単体で動作させることができます。
Pyxel カスタムタグで HTML ファイルを記述する
Pyxel 専用のカスタムタグを使用して、アプリを実行する HTML ファイルを記述します。
作成した HTML ファイルはサーバーでホスティングする必要がありますが、既存の HTML ページへの組み込み等、細かいカスタマイズが可能です。

それぞれの利用方法について説明します。

Pyxel Web Launcher に GitHub リポジトリを指定する

Python コードのファイルや Pyxel アプリ (.pyxapp) が GitHub 上で公開されている場合は、Pyxel Web Launcher で直接実行することができます。

Pyxel Web Launcher の URL の書式は以下の通りです。

https://kitao.github.io/pyxel/wasm/launcher/?<コマンド>=<githubのユーザー名>.<リポジトリ名>.<アプリのディレクトリ>.<拡張子を取ったファイル名>

コマンドには、Python スクリプトを実行するrun、Pyxel アプリを実行するplay、Pyxel エディターを起動するeditが指定できます。

例えば、ユーザー名が taro、リポジトリ名が my_repo、ファイルのディレクトリが src/scenes、Python スクリプトファイルが title.py の場合は、URL は次のようになります。

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

同様に、dist/games にある shooter.pyxapp を実行する場合の URL は次のようになります。

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

また、runコマンドとplayコマンドには、バーチャルゲームパッドを有効にするgamepad属性と、追加パッケージを指定するpackages属性を指定することができます。

例えば、バーチャルゲームパッドを有効にして、追加パッケージとして NumPy と Pandas を使用する場合は、URL は次のようになります。

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

なお、追加可能なパッケージは、Pyodide 対応済みパッケージのみになります。

editコマンドでは、editor属性で Pyxel エディターの起動画面を指定することができます。

たとえば、assets ディレクトリにある shooter.pyxres ファイルを、Tilemap エディタ画面を起動画面にして編集する場合の URL は次のようになります。

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

アプリの起動 URL はPyxel Web Launcher ページに必要な情報を入力することで自動作成することもできます。

Pyxel アプリケーションファイル (.pyxapp) は以下のコマンドで単体で動作する HTML ファイルに変換することができます。

pyxel app2html your_app.pyxapp

作成された HTML ファイルはバーチャルゲームパッドがデフォルトで有効になっていますが、HTML ファイル内のカスタムタグを編集することで無効にすることも可能です。

HTML ファイルで Pyxel 専用のカスタムタグを記述すると Pyxel アプリを実行することができます。

Pyxel カスタムタグは HTML ファイルに以下のスクリプトタグを追加すると使用できるようになります。

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

Python コードを直接実行したい場合は、以下のようにpyxel-runタグのscript属性に実行したいコードを記述します。

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

HTML ファイルの中に Python コードを直接書かずに、別ファイルを読み込んで実行したい場合は、pyxel-runタグにroot属性とname属性を追加します。

rootはファイルを検索する起点となるディレクトリ、nameはファイルパスになります。ファイル名は起点からの相対パスで記述します。

例えば先ほどの Python コードを test.py というファイル名で、HTML ファイルと同じディレクトリに置いた場合は以下のように記述します。

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

なお、起点がカレントディレクトリ('.')である場合は、root属性は省略可能です。

ローカルの HTML ファイルから別のローカルファイルを直接読み込むことは禁止されているため、このファイルを実行するには、サーバーでのホスティングが必要になります。

Python が使える環境であれば、ファイルを置いたディレクトリで以下のコマンドを実行すると、簡易サーバーを起動することができます。

python -m http.server
# MacやLinuxの場合はpythonの代わりにpython3を使ってください

サーバー起動後に、ブラウザからhttp://localhost:8000/test.htmlのようにアクセスできます。

同様に Pyxel アプリ(.pyxapp)もpyxel-playタグで実行できます。

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

この例ではroot属性にファイルパスの代わりに URL を指定しています。

Pyxel Web Launcher と同様に、pyxel-runタグとpyxel-playタグには、バーチャルゲームパッドを有効にするgamepad属性と、追加パッケージを指定するpackages属性を指定することができます。

例えば、バーチャルゲームパッドを有効にして、追加パッケージとして NumPy と Pandas を使用する場合は、次のような記述になります。

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

追加可能なパッケージはPyodide 対応済みパッケージのみになります。

pyxel-editタグで、Pyxel エディターを起動することもできます。Pyxel Web Laucnher 同様に、editor属性で次のように起動画面を指定することも可能です。

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