README.ja.md

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

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

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

Pyxel の仕様や API は、PICO-8やTIC-80を参考にしています。

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

仕様

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

カラーパレット

インストール方法

Windows

Python3 (バージョン 3.7 以上) をインストールした後に、次のコマンドを実行します。

pip install -U pyxel

Mac

Python3 (バージョン 3.7 以上) をインストールした後に、次のコマンドを実行します。

pip3 install -U pyxel

Linux

SDL2 パッケージ (Ubuntu の場合はlibsdl2-dev)、Python3 (バージョン 3.7 以上)、python3-pipをインストールした後に、次のコマンドを実行します。

sudo pip3 install -U pyxel

上記で動作しない場合は、Makefileに記載されている手順に従ってセルフビルドを試してみてください。

Web

Pyxel Web Launcher または HTML 用のカスタムエレメントを使用することで、インストールの作業なしに Web ブラウザ上で Pyxel を動かすことができます。

具体的な使い方については、こちらのページを参照してください。

サンプルを実行する

Pyxel のインストール後に、次のコマンドでカレントディレクトリに Pyxel のサンプルコードがコピーされます。

pyxel copy_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 - 画面遷移のあるシューティングゲーム
• 10_platformer.py - マップのある横スクロールアクションゲーム
• 11_offscreen.py - Image クラスによるオフスクリーン描画
• 12_perlin_noise.py - パーリンノイズアニメーション
• 30SecondsOfDaylight.pyxapp - 第 1 回 Pyxel Jam 優勝ゲーム (Adam制作)
• megaball.pyxapp - アーケードボール物理ゲーム (Adam制作)

サンプルは以下のコマンドで実行できます。

cd pyxel_examples
pyxel run 01_hello_pyxel.py
pyxel play 30SecondsOfDaylight.pyxapp

使い方

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

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()

アプリケーションの実行方法

作成した Python スクリプトは次のコマンドで実行できます。

pyxel run Pythonスクリプトファイル

またパッケージ版であれば、通常の Python スクリプトと同様に実行することもできます。

python3 Pythonスクリプトファイル

(Windows の場合はpython3の代わりにpythonと入力してください)

特殊操作

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

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

リソースの作成方法

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

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

pyxel edit [Pyxelリソースファイル]

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

Pyxel Editor の起動後に、別のリソースファイルをドラッグ＆ドロップすることでファイルを切り替えることができます。

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

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

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

イメージエディタ:

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

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

タイルマップエディタ:

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

サウンドエディタ:

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

ミュージックエディタ:

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

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

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

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

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

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

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

アプリケーションの配布方法

Pyxel ではプラットフォームによらず動作する、専用のアプリケーション配布ファイル形式 (Pyxel アプリケーションファイル) をサポートしています。

Pyxel アプリケーションファイル (.pyxapp) は次のコマンドで作成します。

pyxel package アプリケーションのディレクトリ 起動スクリプトファイル

リソースや追加モジュールを同梱する場合は、アプリケーションのディレクトリ内に配置してください。

作成したアプリケーションファイルは以下のコマンドで実行します。

pyxel play Pyxelアプリケーションファイル

API リファレンス

システム

• width, height
  画面の幅と高さ

• frame_count
  経過フレーム数

• init(width, height, [title], [fps], [quit_key], [display_scale], [capture_scale], [capture_sec])
  Pyxel アプリケーションを画面サイズ (width, height) で初期化します。titleでウィンドウタイトル、fpsで動作フレームレート、quit_keyでアプリケーション終了キー、display_scaleで画面表示の倍率、capture_scaleで画面キャプチャの倍率、capture_secで画面キャプチャ動画の最大録画時間を指定します。
  例：pyxel.init(160, 120, title="My Pyxel App", fps=60, quit_key=pyxel.KEY_NONE, capture_scale=3, capture_sec=0)

• run(update, draw)
  Pyxel アプリケーションを開始し、フレーム更新時にupdate関数、描画時にdraw関数を呼びます。

• show()
  画面を表示してEscキーが押されるまで待機します。

• quit()
  Pyxel アプリケーションを終了します。

リソース

• load(filename, [image], [tilemap], [sound], [music])
  リソースファイル (.pyxres) を読み込みます。リソースタイプ (image/tilemap/sound/music) にFalseを指定すると、そのリソースは読み込まれません。

入力

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

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

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

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

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

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

グラフィックス

• colors
  パレットの表示色リスト。表示色は 24 ビット数値で指定します。Python リストを直接代入、取得する場合はcolors.from_listとcolors.to_listを使用してください。
  例：org_colors = pyxel.colors.to_list(); pyxel.colors[15] = 0x112233; pyxel.colors.from_list(org_colors)

• image(img)
  イメージバンクimg (0-2) を操作します。(イメージクラスを参照のこと)
  例：pyxel.image(0).load(0, 0, "title.png")

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

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

• camera(x, y)
  画面の左上隅の座標を (x, y) に変更します。camera()で左上隅の座標を (0, 0) にリセットします。

• 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) に描画します。

• elli(x, y, w, h, col)
  幅w、高さh、色colの楕円を (x, y) に描画します。

• ellib(x, y, w, h, col)
  幅w、高さh、色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の三角形の輪郭線を描画します。

• fill(x, y, col)
  (x, y) と同じ色でつながっている領域を色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) にコピーします。w、hそれぞれに負の値を設定すると水平、垂直方向に反転します。colkeyに色を指定すると透明色として扱われます。1 タイルのサイズは 8x8 ピクセルで、(tile_x, tile_y)のタプルとしてタイルマップに格納されています。

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

オーディオ

• sound(snd)
  サウンドsnd (0-63) を操作します。(サウンドクラスを参照のこと)
  例：pyxel.sound(0).speed = 60

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

• play_pos(ch)
  チャンネルch (0-3) のサウンド再生位置を(サウンド番号, ノート番号)のタプルとして取得します。再生停止時はNoneを返します。

• play(ch, snd, [tick], [loop])
  チャンネルch (0-3) でサウンドsnd (0-63) を再生します。sndがリストの場合順に再生されます。再生開始位置はtick (1 tick = 1/120 秒) で指定できます。loopにTrueを指定するとループ再生します。

• playm(msc, [tick], [loop])
  ミュージックmsc (0-7) を再生します。再生開始位置はtick (1 tick = 1/120 秒) で指定できます。loopにTrueを指定するとループ再生します。

• stop([ch])
  指定したチャンネルch (0-3) の再生を停止します。stop()で全チャンネルの再生を停止します。

数学

• ceil(x)
x以上の最小の整数を返します。

• floor(x)
x以下の最大の整数を返します。

• sgn(x)
xが正の時に 1、0 の時に 0、負の時に-1 を返します。

• sqrt(x)
xの平方根を返します。

• sin(deg)
deg度(Degree)の正弦を返します。

• cos(deg)
deg度(Degree)の余弦を返します。

• atan2(y, x)
y/xの逆正接を度(Degree)で返します。

• rseed(seed: int)
  乱数生成器のシードを設定します。

• rndi(a, b)
a以上b以下のランダムな整数を返します。

• rndf(a, b)
a以上b以下のランダムな小数を返します。

• nseed(seed)
  Perlin ノイズのシードを設定します。

• noise(x, [y], [z])
  指定された座標の Perlin ノイズ値を返します。

イメージクラス

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

• set(x, y, data)
  (x, y) に文字列のリストでイメージを設定します。
  例：pyxel.image(0).set(10, 10, ["0123", "4567", "89ab", "cdef"])

• load(x, y, filename)
  (x, y) に画像ファイル (png/gif/jpeg) を読み込みます。

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

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

タイルマップクラス

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

• refimg
  タイルマップが参照するイメージバンク (0-2)

• set(x, y, data)
  (x, y) に文字列のリストでタイルマップを設定します。
  例：pyxel.tilemap(0).set(0, 0, ["0000 0100 a0b0", "0001 0101 a1b1"])

• pget(x, y)
  (x, y) のタイルを取得します。タイルは(tile_x, tile_y)のタプルです。

• pset(x, y, tile)
  (x, y) にタイルを設定します。タイルは(tile_x, tile_y)のタプルです。

サウンドクラス

• notes
  音程 (0-127) のリスト。数値が大きいほど音程は高くなり、33 で'A2'(440Hz)になります。休符は-1 です。

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

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

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

• speed
  再生速度。1 が一番速く、数値が大きいほど再生速度は遅くなります。120 で 1 音の長さが 1 秒になります。

• set(notes, tones, volumes, effects, speed)
  文字列で音程、音色、音量、エフェクトを設定します。音色、音量、エフェクトの長さが音程より短い場合は、先頭から繰り返されます。

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

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

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

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

ミュージッククラス

• snds_list
  サウンド (0-63) のリストをチャンネル数分連ねた 2 次元リスト

• set(snds0, snds1, snds2, snds3)
  全チャンネルのサウンド (0-63) のリストを設定します。空リストを指定するとそのチャンネルは再生に使用しません。
  例：pyxel.music(0).set([0, 1], [2, 3], [4], [])

上級者向け API

Pyxel には「ユーザーを混乱させる可能性がある」「使うために専門の知識が必要」などの理由から、このリファレンスには記載していない「上級者向け API」があります。

腕に覚えのある方は、こちらを手がかりにして、あっと驚くような作品づくりに挑戦してみてください！

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

問題の報告

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

動作確認

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

プルリクエスト

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

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

その他の情報

• Q&A
• User Examples
• Discord Server (English)
• Discord Server (Japanese - 日本語版)

ライセンス

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

スポンサー募集

Pyxel は GitHub Sponsors でスポンサーを募っています。Pyxel のメンテナンスと機能追加の継続のためにスポンサーになることをご検討ください。スポンサーは特典として Pyxel についての相談をすることができます。詳細はこちらをご覧ください。