Updated the instructions for using the Web version of Pyxel

CHANGELOG.md

@@ -3,8 +3,8 @@
 ## 2.2.4
 
 - Updated the license description in the READMEs
-- Removed the outdated Q&A link from the READMEs
-- Updated the Web version of Pyxel instructions in the READMEs
+- Updated the instructions for using the Web version of Pyxel
+- Updated the Q&A
 
 ## 2.2.3
 

docs/pyxel-web-en.md

@@ -0,0 +1,150 @@
+# How to Use the Web Version of Pyxel
+
+With the Web version of Pyxel, you can run Pyxel applications on a web browser from a PC, smartphone, or tablet without needing to install Python or Pyxel.
+
+There are three ways to use the Web version of Pyxel.
+
+- **Specify a GitHub repository in Pyxel Web Launcher**<br>
+  By specifying the name of a GitHub repository in the URL of the Pyxel Web Launcher, the repository is directly loaded, and you can run the app in a web browser. This is the easiest way if the app is published on GitHub.
+
+- **Convert a Pyxel app to an HTML file**<br>
+  If your app is in Pyxel application format (.pyxapp), you can convert it to an HTML file using `pyxel app2html` command. The resulting HTML file can be run standalone without needing a server.
+
+- **Create an HTML file using Pyxel custom tags**<br>
+  You can create an HTML file to run an app using Pyxel-specific custom tags. The HTML file needs to be hosted on a server, but it allows for embedding into existing HTML pages and various customizations.
+
+Each method is explained below.
+
+## Specify a GitHub Repository in Pyxel Web Launcher
+
+If your Python code or Pyxel app (.pyxapp) is published on GitHub, you can run it directly using Pyxel Web Launcher.
+
+The URL format for Pyxel Web Launcher is as follows:
+
+```
+https://kitao.github.io/pyxel/wasm/launcher/?<Command>=<GitHub username>.<Repository Name>.<App Directories>.<File Name Without Extension>
+```
+
+Three commands can be specified.
+
+- `run`: Execute a Python script
+- `play`: Run a Pyxel app
+- `edit`: Launch the Pyxel Editor
+
+For example, if the username is taro, the repository is named my_repo, the file directory is src/scenes, and the Python script is title.py, the URL would be:
+
+```
+https://kitao.github.io/pyxel/wasm/launcher/?run=taro.my_repo.src.scenes.title
+```
+
+Similarly, if you want to run a shooter.pyxapp located in dist/games, the URL would be:
+
+```
+https://kitao.github.io/pyxel/wasm/launcher/?play=taro.my_repo.dist.games.shooter
+```
+
+The `run` and `play` commands can have additional attributes such as `gamepad` to enable a virtual gamepad and `packages` to specify additional packages.
+
+For example, if you want 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
+```
+
+Note that the packages that can be added are limited to those supported by [Packages built in Pyodide](https://pyodide.org/en/stable/usage/packages-in-pyodide.html).
+
+When using the `edit` command, you can specify the Pyxel Editor's startup screen using the `editor` attribute.
+
+For example, to open the shooter.pyxres file located in the assets directory with the Tilemap Editor screen, use the following URL:
+
+```html
+https://kitao.github.io/pyxel/wasm/launcher/?run=taro.my_repo.assets.shooter&editor=tilemap
+```
+
+You can also automatically generate the app launch URL by entering the necessary information on the [Pyxel Web Launcher page](https://kitao.github.io/pyxel/wasm/launcher/).
+
+## Convert a Pyxel App to an HTML File
+
+You can convert a Pyxel application file (.pyxapp) into a standalone HTML file using the following command:
+
+```sh
+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.
+
+## Create an HTML File Using Pyxel Custom Tags
+
+You can run a Pyxel app by writing Pyxel-specific custom tags in an HTML file.
+
+To use Pyxel custom tags, add the following script tag to your HTML file:
+
+```html
+<script src="https://cdn.jsdelivr.net/gh/kitao/pyxel/wasm/pyxel.js"></script>
+```
+
+To run Python code directly, specify the code in the script attribute of the `pyxel-run` tag, as shown below:
+
+```html
+<pyxel-run
+  script="
+import pyxel
+pyxel.init(200, 150)
+pyxel.cls(8)
+pyxel.line(20, 20, 180, 130, 7)
+pyxel.show()
+"
+></pyxel-run>
+```
+
+To run external Python files, specify the `root` and `name` attributes in the `pyxel-run` tag.
+
+`root` is the directory where the search begins, and `name` is the file path.
+
+For example, if you save the above code as test.py in the same directory as the HTML file, write the following:
+
+```html
+<pyxel-run root="." name="test.py"></pyxel-run>
+```
+
+If `root` is the current directory (`root="."`), the `root` attribute can be omitted.
+
+To read external files from a local HTML file, you need to host it on a server.
+
+If you have a Python environment, you can start a simple server with the following command:
+
+```python
+python -m http.server
+# use python3 instead of python for mac and linux
+```
+
+After starting the server, you can access it in a browser at `http://localhost:8000/test.html`.
+
+Similarly, you can run a Pyxel app (.pyxapp) using the `pyxel-play` tag:
+
+```html
+<pyxel-play
+  root="https://cdn.jsdelivr.net/gh/kitao/pyxel/python/pyxel/examples"
+  name="megaball.pyxapp"
+></pyxel-play>
+```
+
+In this example, the `root` attribute specifies a URL.
+
+Both the `pyxel-run` and `pyxel-play` tags support the `gamepad` attribute to enable a virtual gamepad and the `packages` attribute to specify additional packages.
+
+For example, to enable the virtual gamepad and use NumPy and Pandas, write the following:
+
+```html
+<pyxel-run name="test.py" gamepad="enabled" packages="numpy,pandas"></pyxel-run>
+```
+
+The available packages are limited to those supported by [Packages built in Pyodide](https://pyodide.org/en/stable/usage/packages-in-pyodide.html).
+
+You can also launch Pyxel Editor using the `pyxel-edit` tag.
+
+For example, to edit the shooter.pyxres file in the assets directory with the Image Editor screen, write the following:
+
+```html
+<pyxel-edit root="assets" name="sample.pyxres" editor="image"></pyxel-edit>
+```

docs/pyxel-web-ja.md

@@ -0,0 +1,150 @@
+# Web 版 Pyxel の使い方
+
+Web 版 Pyxel を使うと Python や Pyxel をインストールせずに、PC、スマートフォン、タブレット等の Web ブラウザーで Pyxel のアプリケーションを実行できます。
+
+Web 版 Pyxel の利用方法には、次の 3 種類があります。
+
+- **Pyxel Web Launcher に GitHub リポジトリを指定する**<br>
+  Pyxel Web Launcher の URL に GitHub のリポジトリ名を指定すると、指定したリポジトリを直接読み込み、Web ブラウザ上でアプリを実行できます。アプリを GitHub で公開している場合、最も簡単な実行方法です。
+
+- **Pyxel アプリを HTML ファイルに変換する**<br>
+  アプリが Pyxel アプリケーション形式 (.pyxapp) になっている場合は、`pyxel app2html`コマンドを使って HTML ファイルに変換できます。変換後の HTML ファイルはサーバーを必要とせず、単体で実行可能です。
+
+- **Pyxel カスタムタグを使って HTML ファイルを作成する**<br>
+  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のユーザー名>.<リポジトリ名>.<アプリのディレクトリ>.<拡張子を取ったファイル名>
+```
+
+コマンドには次の３つが指定できます。
+
+- `run`: Python スクリプトを実行する
+- `play`: Pyxel アプリを実行する
+- `edit`: Pyxel Editor を起動する
+
+例えば、ユーザー名が 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 対応パッケージ](https://pyodide.org/en/stable/usage/packages-in-pyodide.html)に限られます。
+
+`edit`コマンドを使用する場合、`editor`属性で Pyxel Editor の起動画面を指定できます。
+
+例えば、assets ディレクトリにある shooter.pyxres ファイルをタイルマップエディタ画面で起動するには、以下の URL を使用します。
+
+```html
+https://kitao.github.io/pyxel/wasm/launcher/?run=taro.my_repo.assets.shooter&editor=tilemap
+```
+
+[Pyxel Web Launcher ページ](https://kitao.github.io/pyxel/wasm/launcher/)で必要な情報を入力して、アプリの起動 URL を自動作成することも可能です。
+
+## Pyxel アプリを HTML ファイルに変換する
+
+Pyxel アプリケーションファイル (.pyxapp) は、次のコマンドで単独で動作する HTML ファイルに変換できます。
+
+```sh
+pyxel app2html your_app.pyxapp
+```
+
+作成された HTML ファイルでは、バーチャルゲームパッドがデフォルトで有効になっていますが、カスタムタグを編集することで無効にすることも可能です。
+
+## Pyxel カスタムタグを使って HTML ファイルを作成する
+
+HTML ファイルに Pyxel 専用のカスタムタグを記述することで、Pyxel アプリを実行できます。
+
+Pyxel カスタムタグを利用するには、以下のスクリプトタグを HTML ファイルに追加します。
+
+```html
+<script src="https://cdn.jsdelivr.net/gh/kitao/pyxel/wasm/pyxel.js"></script>
+```
+
+Python コードを直接実行するには、次のように`pyxel-run`タグの`script`属性にコードを記述します。
+
+```html
+<pyxel-run
+  script="
+import pyxel
+pyxel.init(200, 150)
+pyxel.cls(8)
+pyxel.line(20, 20, 180, 130, 7)
+pyxel.show()
+"
+></pyxel-run>
+```
+
+外部の Python ファイルを読み込んで実行する場合は、`pyxel-run`タグに`root`と`name`属性を指定します。
+
+`root`は検索の起点となるディレクトリ、`name`はファイルパスです。
+
+例えば先ほどのコードを test.py というファイルに保存し、HTML ファイルと同じディレクトリに配置した場合、次のように記述します。
+
+```html
+<pyxel-run root="." name="test.py"></pyxel-run>
+```
+
+`root`がカレントディレクトリの場合(`root="."`)、`root`属性は省略可能です。
+
+ローカルの HTML ファイルから外部ファイルを読み込むにはサーバーでのホスティングが必要です。
+
+Python 環境があれば、次のコマンドで簡易サーバーを起動できます。
+
+```python
+python -m http.server
+# MacやLinuxの場合はpython3を使用してください
+```
+
+サーバー起動後、ブラウザで`http://localhost:8000/test.html`にアクセスできます。
+
+同様に、Pyxel アプリ(.pyxapp)は`pyxel-play`タグで実行できます。
+
+```html
+<pyxel-play
+  root="https://cdn.jsdelivr.net/gh/kitao/pyxel/python/pyxel/examples"
+  name="megaball.pyxapp"
+></pyxel-play>
+```
+
+この例では、`root`属性に URL を指定しています。
+
+`pyxel-run`タグと`pyxel-play`タグには、バーチャルゲームパッドを有効にする`gamepad`属性や、追加パッケージを指定する`packages`属性を指定できます。
+
+例えば、バーチャルゲームパッドを有効にし、NumPy と Pandas を使用する場合は次のようになります。
+
+```html
+<pyxel-run name="test.py" gamepad="enabled" packages="numpy,pandas"></pyxel-run>
+```
+
+使用できるパッケージは[Pyodide 対応パッケージ](https://pyodide.org/en/stable/usage/packages-in-pyodide.html)に限られます。
+
+また、pyxel-edit タグを使って Pyxel Editor を起動できます。
+
+例えば、assets ディレクトリにある shooter.pyxres ファイルをイメージエディタ画面で起動するには、次のように記述します。
+
+```html
+<pyxel-edit root="assets" name="sample.pyxres" editor="image"></pyxel-edit>
+```