README.ja.md

[ English | 中文 | Español | Italiano | 日本語 | 한국어 | Português | Русский ]

Pyxel (ピクセル) はPython向けのレトロゲームエンジンです。

使える色は16色のみ、同時に再生できる音は4音までなど、レトロゲーム機を意識したシンプルな仕様で、Pythonでドット絵スタイルのゲームづくりが気軽に楽しめます。

Pyxelのゲーム機の仕様やAPIは、 PICO-8やTIC-80のデザインを参考にしています。

Pyxelはオープンソースで、無料で自由に使えます。Pyxelでレトロゲームづくりを始めましょう！

仕様

• Windows、Mac、Linux対応
• Python3によるコード記述
• 16色固定パレット
• 256x256サイズ、3画像バンク
• 256x256サイズ、8タイルマップ
• 4音同時再生、定義可能な64サウンド
• 任意のサウンドを組み合わせ可能な8ミュージック
• キーボード、マウス、ゲームパッド
• 画像・サウンド編集ツール

カラーパレット

インストール方法

Windows

最初にPython3 (バージョン3.6.8以上) をインストールします。

公式のPythonインストーラーを使用する場合は、次のボタンをチェックして、Pythonをパスに追加してください。

続いて、コマンドプロンプトから、以下のpipコマンドでPyxelをインストールします。

pip install -U pyxel

Mac

最初に、Homebrewを導入した環境で、以下のコマンドでPython3 (バージョン3.6.8以上) と必要なパッケージをインストールします。

brew install python3 gcc sdl2 sdl2_image gifsicle

Python3は他の方法でインストールしても問題ありませんが、他のライブラリのインストールは必須なので注意してください。

続いて、ターミナルを再起動した後に、pip3コマンドでPyxelをインストールします。

pip3 install -U pyxel

Linux

各ディストリビューションに適した方法でPython3 (バージョン3.6.8以上) と必要なパッケージをインストールしてください。

Ubuntu:

sudo apt install python3 python3-pip libsdl2-dev libsdl2-image-dev gifsicle
sudo -H pip3 install -U pyxel

その他の環境

上記以外の環境 (32bit版LinuxやRaspberry PI等) にPyxelをインストールするには、次の手順でビルドを行なってください。

必要となるツールやパッケージをインストールする

• C++のビルド環境 (gcc、makeコマンドを含む)
• libsdl2-dev、libsdl2-image-dev
• Python3 (バージョン3.6.8以上)、pipコマンド

任意のフォルダで以下のコマンドを実行する

git clone https://github.com/kitao/pyxel.git
cd pyxel
make -C pyxel/core clean all
pip3 install .

サンプルのインストール

Pyxelインストール後に、以下のコマンドでカレントディレクトリにPyxelのサンプルコード一式をコピーできます。

install_pyxel_examples

コピーされるサンプルは以下の通りです。

• 01_hello_pyxel.py - シンプルなアプリケーション
• 02_jump_game.py - Pyxelリソースファイルを使ったジャンプゲーム
• 03_draw_api.py - 描画APIのデモ
• 04_sound_api.py - サウンドAPIのデモ
• 05_color_palette.py - カラーパレット一覧
• 06_click_game.py - マウスクリックゲーム
• 07_snake.py - BGM付きスネークゲーム
• 08_triangle_api.py - 三角形描画APIのデモ
• 09_shooter.py - 画面遷移のあるシューティングゲーム

サンプルは通常のPythonコードと同様に実行できます。

Windows:

cd pyxel_examples
python 01_hello_pyxel.py

Mac / Linux:

cd pyxel_examples
python3 01_hello_pyxel.py

使い方

アプリケーションの作成方法

Pythonコード内でPyxelモジュールをインポートして、init関数でウィンドウサイズを指定した後に、run関数でPyxelアプリケーションを開始します。

import pyxel

pyxel.init(160, 120)

def update():
    if pyxel.btnp(pyxel.KEY_Q):
        pyxel.quit()

def draw():
    pyxel.cls(0)
    pyxel.rect(10, 10, 20, 20, 11)

pyxel.run(update, draw)

run関数の引数にはフレーム更新処理を行うupdate関数と、描画処理を行うdraw関数を指定します。

実際のアプリケーションでは、以下のようにクラスでPyxelの処理をラップするのがおすすめです。

import pyxel

class App:
    def __init__(self):
        pyxel.init(160, 120)
        self.x = 0
        pyxel.run(self.update, self.draw)

    def update(self):
        self.x = (self.x + 1) % pyxel.width

    def draw(self):
        pyxel.cls(0)
        pyxel.rect(self.x, 0, 8, 8, 9)

App()

また、シンプルなグラフィックスやアニメーションを作成する場合は、show関数やflip関数を使った簡易的な記述も可能です。

show関数は画面を表示して、ESCキーが押されるまで待機します。

import pyxel

pyxel.init(120, 120)
pyxel.cls(1)
pyxel.circb(60, 60, 40, 7)
pyxel.show()

flip関数は画面を一度更新します。

import pyxel

pyxel.init(120, 80)

while True:
    pyxel.cls(3)
    pyxel.rectb(pyxel.frame_count % 160 - 40, 20, 40, 40, 7)
    pyxel.flip()

特殊操作

Pyxelアプリケーション実行中に、以下の特殊操作を行うことができます。

• Esc
  アプリケーションを終了する
• Alt(Option)+1
  スクリーンショットをデスクトップに保存する
• Alt(Option)+2
  画面キャプチャ動画の録画開始時刻をリセットする
• Alt(Option)+3
  画面キャプチャ動画 (gif) をデスクトップに保存する (最大30秒)
• Alt(Option)+0
  パフォーマンスモニタ (fps、update時間、draw時間) の表示を切り替える
• Alt(Option)+Enter
  フルスクリーン表示を切り替える

リソースの作成方法

付属するPyxel EditorでPyxelアプリケーションで使用する画像やサウンドを作成することができます。

Pyxel Editorは以下のコマンドで起動します。

pyxeleditor [Pyxelリソースファイル]

指定したPyxelリソースファイル (.pyxres) が存在する場合は読み込み、存在しない場合は指定した名前で新規にファイルを作成します。リソースファイルを省略した場合はmy_resource.pyxresがファイル名になります。

Pyxel Editorの起動後に、別のリソースファイルをドラッグ＆ドロップすることでファイルを切り替えることができます。また、Ctrl(Cmd)キーを押しながらリソースファイルをドラッグ＆ドロップすると、現在編集中のリソースタイプ(イメージ/タイルマップ/サウンド/ミュージック)のみが読み込まれます。この操作により、複数のリソースファイルを1つにまとめることができます。

作成したリソースファイルはPyxelアプリケーションからload関数で読み込めます。

Pyxel Editorには次の編集モードがあります。

イメージエディタ:

イメージバンクの画像を編集する画面です。

イメージエディタ画面にpngファイルをドラッグ＆ドロップすると、画像を選択中のイメージバンクに読み込むことができます。

タイルマップエディタ:

イメージバンクの画像をタイル状に並べたタイルマップを編集する画面です。

サウンドエディタ:

サウンドを編集する画面です。

ミュージックエディタ:

サウンドを再生順に並べたミュージックを編集する画面です。

その他のリソース作成方法

Pyxel用の画像やタイルマップは以下の方法で作成することもできます。

• Image.setやTilemap.set関数で文字列のリストから作成する
• Image.load関数でPyxel向け配色のpngファイルを読み込む

Pyxel用のサウンドやミュージックは以下の方法で作成することもできます。

• Sound.setやMusic.set関数で文字列から作成する

各関数の使い方はAPIリファレンスを参照してください。

単体実行ファイルの作成方法

付属するPyxel Packagerを使用することで、Pythonがインストールされていない環境でも動作する、単体実行ファイルを作成することができます。

単体実行ファイルを作成するには、PyInstallerがインストール済みの環境で、次のようにpyxelpackagerコマンドでアプリケーションの起動に使用するPythonファイルを指定します。

pyxelpackager python_file

処理に成功すると、distフォルダに単体実行可能なファイルが作成されます。

.pyxresファイルや.pngファイル等のリソースも同梱する必要がある場合は、assetsフォルダ以下に置くと取り込まれます。

-i icon_fileオプションでアイコンファイルを設定することも可能です。

APIリファレンス

システム

• width, height
  画面の幅と高さ

• frame_count
  経過フレーム数

• init(width, height, [caption], [scale], [palette], [fps], [quit_key], [fullscreen])
  Pyxelアプリを画面サイズ (width, height) で初期化する。画面の最大の幅と高さは255
  また、captionでウィンドウタイトル、scaleで表示倍率、paletteでパレット色、fpsで動作フレームレート、quit_keyでアプリケーション終了キー、fullscreenでフルスクリーンでの起動を指定できる。paletteは24ビットカラーの16要素のリストで指定する
  例：pyxel.init(160, 120, caption="Pyxel with PICO-8 palette", palette=[0x000000, 0x1D2B53, 0x7E2553, 0x008751, 0xAB5236, 0x5F574F, 0xC2C3C7, 0xFFF1E8, 0xFF004D, 0xFFA300, 0xFFEC27, 0x00E436, 0x29ADFF, 0x83769C, 0xFF77A8, 0xFFCCAA], quit_key=pyxel.KEY_NONE, fullscreen=True)

• run(update, draw)
  Pyxelアプリを開始し、フレーム更新時にupdate関数、描画時にdraw関数を呼ぶ

• run_with_profiler(update, draw)
  プロファイラ付きでPyxelアプリを開始し、フレーム更新時にupdate関数、描画時にdraw関数を呼ぶ。アプリ終了時に各関数の処理時間を出力する

• quit()
  現在フレーム終了時にPyxelアプリを終了する

• flip()
  強制的に画面を描画する (通常のアプリケーションでは使用しない)

• show()
  画面を描画して待ち続ける (通常のアプリケーションでは使用しない)

リソース

• save(filename)
  実行スクリプトのディレクトリにリソースファイル (.pyxres) を保存する

• load(filename, [image], [tilemap], [sound], [music])
  実行スクリプトのディレクトリからリソースファイル (.pyxres) を読み込む。リソースタイプ(イメージ/タイルマップ/サウンド/ミュージック)にFalseを指定すると、そのリソースは読み込まれない

入力

• mouse_x, mouse_y
  現在のマウスカーソル座標

• mouse_wheel
  現在のマウスホイールの値

• btn(key)
keyが押されていたらTrue、押されていなければFalseを返す (キー定義一覧)

• btnp(key, [hold], [period])
  そのフレームにkeyが押されたらTrue、押されなければFalseを返す。holdとperiodを指定すると、holdフレーム以上ボタンを押し続けた際にperiodフレーム間隔でTrueが返る

• btnr(key)
  そのフレームにkeyが離されたらTrue、離されなければFalseを返す

• mouse(visible)
visibleがTrueならマウスカーソルを表示し、Falseなら非表示にする。マウスカーソルが非表示でも座標は更新される

グラフィックス

• image(img, [system])
  イメージバンクimg(0-2) を操作する (イメージクラスを参照のこと)。systemにTrueを指定すると、システム用のイメージバンクにアクセスできる。3がフォント、リソースエディタ用。4が表示スクリーン用
  例：pyxel.image(0).load(0, 0, "title.png")

• tilemap(tm)
  タイルマップtm(0-7)を操作する (タイルマップクラスを参照のこと)

• clip(x, y, w, h)
  画面の描画領域を (x, y) から幅w、高さhに設定する。clip()で描画領域を全画面にリセットする

• pal(col1, col2)
  描画時に色col1をcol2に置き換える。pal()で初期状態にリセットする

• cls(col)
  画面を色colでクリアする

• pget(x, y)
  (x, y) のピクセルの色を取得する

• pset(x, y, col)
  (x, y) に色colのピクセルを描画する

• line(x1, y1, x2, y2, col)
  色colの直線を (x1, y1)-(x2, y2) に描画する

• rect(x, y, w, h, col)
  幅w、高さh、色colの矩形を (x, y) に描画する

• rectb(x, y, w, h, col)
  幅w、高さh、色colの矩形の輪郭線を (x, y) に描画する

• circ(x, y, r, col)
  半径r、色colの円を (x, y) に描画する

• circb(x, y, r, col)
  半径r、色colの円の輪郭線を (x, y) に描画する

• tri(x1, y1, x2, y2, x3, y3, col)
  頂点が (x1, y1)、(x2, y2)、(x3, y3)、色colの三角形を描画する

• trib(x1, y1, x2, y2, x3, y3, col)
  頂点が (x1, y1)、(x2, y2)、(x3, y3)、色colの三角形の輪郭線を描画する

• blt(x, y, img, u, v, w, h, [colkey])
  イメージバンクimg(0-2) の (u, v) からサイズ (w, h) の領域を (x, y) にコピーする。w、hそれぞれに負の値を設定すると水平、垂直方向に反転する。colkeyに色を指定すると透明色として扱われる

• bltm(x, y, tm, u, v, w, h, [colkey])
  タイルマップtm(0-7) を (u, v) からサイズ (w, h) のタイル情報に従って (x, y) に描画する。colkeyに色を指定すると透明色として扱われる。タイルマップは1タイルが8x8のサイズで描画され、タイル番号が0ならイメージバンクの (0, 0)-(7, 7) の領域、1なら (8, 0)-(15, 0) の領域を表す

• text(x, y, s, col)
  色colの文字列sを (x, y) に描画する

オーディオ

• sound(snd, [system])
  サウンドsnd(0-63) を操作する (サウンドクラスを参照のこと)。systemにTrueを指定すると、システム用のサウンド64にアクセスできる
  例：pyxel.sound(0).speed = 60

• music(msc)
  ミュージックmsc(0-7) を操作する (ミュージッククラスを参照のこと)

• play_pos(ch)
  チャンネルch(0-3) のサウンド再生位置を取得する。100と1000の位はサウンド番号、1と10の位はノート番号。再生停止時は-1を返す

• play(ch, snd, loop=False)
  チャンネルch(0-3) でサウンドsnd(0-63) を再生する。sndがリストの場合順に再生する

• playm(msc, loop=False)
  ミュージックmsc(0-7) を再生する

• stop([ch])
  全チャンネルのサウンドの再生を停止する。ch(0-3) を指定すると該当チャンネルのみを停止する

イメージクラス

• width, height
  イメージの幅と高さ

• data
  イメージのデータ (256x256の二次元リスト)

• get(x, y)
  イメージの (x,y) のデータを取得する

• set(x, y, data)
  (x, y) に値または文字列のリストでイメージのデータを設定する
  例：pyxel.image(0).set(10, 10, ["1234", "5678", "9abc", "defg"])

• load(x, y, filename)
  (x, y) に実行スクリプトのディレクトリからpngファイルを読み込む

• copy(x, y, img, u, v, w, h)
  イメージバンクimg(0-2) の (u, v) からサイズ (w, h) の領域を (x, y) にコピーする

タイルマップクラス

• width, height
  タイルマップの幅と高さ

• data
  タイルマップのデータ (256x256の二次元リスト)

• refimg
  タイルマップが参照するイメージバンク

• get(x, y)
  タイルマップの (x,y) のデータを取得する

• set(x, y, data)
  (x, y) に値または文字列のリストでタイルマップのデータを設定する。
  e.g. pyxel.tilemap(0).set(0, 0, ["000102", "202122", "a0a1a2", "b0b1b2"])

• copy(x, y, tm, u, v, w, h)
  タイルマップtm(0-7) の (u, v) からサイズ (w, h) の領域を (x, y) にコピーする

サウンドクラス

• note
  音程 (0-127) のリスト (33 = 'A2' = 440Hz)

• tone
  音色 (0:Triangle / 1:Square / 2:Pulse / 3:Noise) のリスト

• volume
  音量 (0-7) のリスト

• effect
  エフェクト (0:None / 1:Slide / 2:Vibrato / 3:FadeOut) のリスト

• speed
  1音の長さ (120 = 1音1秒)

• set(note, tone, volume, effect, speed)
  文字列で音程、音色、音量、エフェクトを設定する。音色、音量、エフェクトの長さが音程より短い場合は、先頭から繰り返される

• set_note(note)
  'CDEFGAB'+'#-'+'0123'または'R'の文字列で音程を設定する。大文字と小文字を区別せず、空白は無視される
  例：pyxel.sound(0).set_note("G2B-2D3R RF3F3F3")

• set_tone(tone)
  'TSPN'の文字列で音色を設定する。大文字と小文字を区別せず、空白は無視される
  例：pyxel.sound(0).set_tone("TTSS PPPN")

• set_volume(volume)
  '01234567'の文字列で音量を設定する。大文字と小文字を区別せず、空白は無視される
  例：pyxel.sound(0).set_volume("7777 7531")

• set_effect(effect)
  'NSVF'の文字列でエフェクトを設定する。大文字と小文字を区別せず、空白は無視される
  例：pyxel.sound(0).set_effect("NFNF NVVS")

ミュージッククラス

• ch0
  チャンネル0で再生するサウンド (0-63) のリスト。空リストを指定すると再生にそのチャンネルを使用しない

• ch1
  チャンネル1で再生するサウンド (0-63) のリスト。空リストを指定すると再生にそのチャンネルを使用しない

• ch2
  チャンネル2で再生するサウンド (0-63) のリスト。空リストを指定すると再生にそのチャンネルを使用しない

• ch3
  チャンネル3で再生するサウンド (0-63) のリスト。空リストを指定すると再生にそのチャンネルを使用しない

• set(ch0, ch1, ch2, ch3)
  全チャンネルのサウンド (0-63) のリストを設定する。空リストを指定すると再生にそのチャンネルを使用しない
  例：pyxel.music(0).set([0, 1], [2, 3], [4], [])

• set_ch0(data)
  チャンネル0のサウンド (0-63) のリストを設定する

• set_ch1(data)
  チャンネル1のサウンド (0-63) のリストを設定する

• set_ch2(data)
  チャンネル2のサウンド (0-63) のリストを設定する

• set_ch3(data)
  チャンネル3のサウンド (0-63) のリストを設定する

コントリビューション方法

問題の報告

不具合の報告や機能の要望はIssue Trackerで受け付けています。 新しいレポートを作成する前に、同じ内容のものがないか確認をお願いします。

新しいレポートを作成する際は、こちらのリンクから内容に適したテンプレートを選択してください。

動作確認

動作確認を行い、Issue Trackerで不具合の報告や改善の提案をしてくれる方は大歓迎です！

プルリクエスト

パッチや修正はプルリクエスト(PR)として受け付けています。提出の前に問題がすでに解決済みでないかIssue Trackerで確認をお願いします。

提出されたプルリクエストはMITライセンスで公開することに同意したものを見なされます。

その他の情報

• Wiki
• Subreddit
• Discord server (English)
• Discord server (Japanese - 日本語版)

ライセンス

PyxelはMITライセンスです。ソースコードやライセンス表示用のファイル等で、著作権とライセンス全文の表示を行えば、自由に販売や配布をすることができます。

Pyxelは以下のソフトウェアを使用しています。

• SDL2
• miniz-cpp
• Gifsicle