[ English | 中文 | Deutsch | Español | Français | Italiano | 日本語 | 한국어 | Português | Русский | Türkçe | Українська ]
Pyxel (ピクセル) は Python 向けのレトロゲームエンジンです。
使える色は 16 色のみ、同時に再生できる音は 4 音までなど、レトロゲーム機を意識したシンプルな仕様で、Python でドット絵スタイルのゲームづくりが気軽に楽しめます。
Pyxel 開発のモチベーションはユーザーの皆さんからのフィードバックです。GitHub で Pyxel へのスター登録をよろしくお願いします!
Pyxel の仕様や API は、PICO-8やTIC-80を参考にしています。
Pyxel はオープンソースで、無料で自由に使えます。Pyxel でレトロゲームづくりを始めましょう!
- Windows、Mac、Linux、Web で動作
- Python によるプログラミング
- 16 色パレット
- 256x256 サイズ、3 画像バンク
- 256x256 サイズ、8 タイルマップ
- 4 音同時再生、定義可能な 64 サウンド
- 任意のサウンドを組み合わせ可能な 8 ミュージック
- キーボード、マウス、ゲームパッド
- 画像・サウンド編集ツール
Python3 (バージョン 3.8 以上) をインストールした後に、次のコマンドを実行します。
pip install -U pyxel
公式のインストーラーで Python をインストールする場合は、pyxel
コマンドを有効にするために、Add Python 3.x to PATH
にチェックをつけて Python のインストールを行なってください。
Homebrew をインストールした後に、次のコマンドを実行します。
brew install pipx
pipx ensurepath
pipx install pyxel
Pyxel インストール後にバージョンを更新する場合は、pipx upgrade pyxel
を実行してください。
SDL2 パッケージ (Ubuntu の場合はlibsdl2-dev
)、Python3 (バージョン 3.8 以上)、python3-pip
をインストールした後に、次のコマンドを実行します。
sudo pip3 install -U pyxel
上記で動作しない場合は、Makefileに記載されている手順に従ってセルフビルドを試してみてください。
Web 版の Pyxel は、Python や Pyxel のインストールを必要とせず、PC だけではなく、対応する Web ブラウザーを持つスマートフォンやタブレット端末でも動作します。
具体的な使い方については、こちらのページを参照してください。
Pyxel のインストール後に、次のコマンドでカレントディレクトリに Pyxel のサンプルコードがコピーされます。
pyxel copy_examples
コピーされるサンプルは以下の通りです。
01_hello_pyxel.py | シンプルなアプリケーション | Demo | Code |
02_jump_game.py | Pyxel リソースファイルを使ったジャンプゲーム | Demo | Code |
03_draw_api.py | 描画 API のデモ | Demo | Code |
04_sound_api.py | サウンド API のデモ | Demo | Code |
05_color_palette.py | カラーパレット一覧 | Demo | Code |
06_click_game.py | マウスクリックゲーム | Demo | Code |
07_snake.py | BGM 付きスネークゲーム | Demo | Code |
08_triangle_api.py | 三角形描画 API のデモ | Demo | Code |
09_shooter.py | 画面遷移のあるシューティングゲーム | Demo | Code |
10_platformer.py | マップのある横スクロールアクションゲーム | Demo | Code |
11_offscreen.py | Image クラスによるオフスクリーン描画 | Demo | Code |
12_perlin_noise.py | パーリンノイズアニメーション | Demo | Code |
13_bitmap_font.py | ビットマップフォント描画 | Demo | Code |
14_synthesizer.py | オーディオ拡張機によるシンセサイザー | Demo | Code |
15_tiled_map_file.py | タイルマップファイル (.tmx) の読み込みと描画 | Demo | Code |
16_transform.py | 画像の回転と拡大縮小 | Demo | Code |
99_flip_animation.py | flip 関数によるアニメーション (非 Web 環境のみ) | Demo | Code |
30SecondsOfDaylight.pyxapp | 第 1 回 Pyxel Jam 優勝ゲーム (Adam制作) | Demo | Code |
megaball.pyxapp | アーケードボール物理ゲーム (Adam制作) | Demo | Code |
8bit-bgm-gen.pyxapp | BGM自動作成ツール (frenchbread制作) | Demo | Code |
サンプルは以下のコマンドで実行できます。
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()
アニメーションのないシンプルなグラフィックスを作成する場合は、show
関数を使用してコードをより簡潔に記述することも可能です。
import pyxel
pyxel.init(120, 120)
pyxel.cls(1)
pyxel.circb(60, 60, 40, 7)
pyxel.show()
作成した Python スクリプトはpython
コマンドで実行できます。
python Pythonスクリプトファイル
pyxel run
コマンドで実行することも可能です。
pyxel run Pythonスクリプトファイル
また、pyxel watch
コマンドで、指定したディレクトリ内の変更を監視して、変化があったら自動的にプログラムを再実行することができます。
pyxel watch WATCH_DIR Pythonスクリプトファイル
ディレクトリの監視はCtrl(Command)+C
で終了します。
Pyxel アプリケーション実行中に、以下の特殊操作を行うことができます。
Esc
アプリケーションを終了するAlt(Option)+1
スクリーンショットをデスクトップに保存するAlt(Option)+2
画面キャプチャ動画の録画開始時刻をリセットするAlt(Option)+3
画面キャプチャ動画をデスクトップに保存する (最大 10 秒)Alt(Option)+9
画面モード (Crisp/Smooth/Retro) を切り替えるAlt(Option)+0
パフォーマンスモニタ (fps、update 時間、draw 時間) の表示を切り替えるAlt(Option)+Enter
フルスクリーン表示を切り替えるShift+Alt(Option)+1/2/3
対応するイメージバンクをデスクトップに保存するShift+Alt(Option)+0
現在のカラーパレットをデスクトップに保存する
Pyxel Editor を使って、Pyxel アプリケーションで使用する画像やサウンドを作成することができます。
Pyxel Editor は次のコマンドで起動します。
pyxel edit Pyxelリソースファイル
指定した Pyxel リソースファイル (.pyxres) が存在する場合は読み込み、存在しない場合は指定した名前で新規にファイルを作成します。リソースファイルを省略した場合はmy_resource.pyxres
がファイル名になります。
Pyxel Editor の起動後に、別のリソースファイルをドラッグ&ドロップすることでファイルを切り替えることができます。
作成したリソースファイルは Pyxel アプリケーションからload
関数で読み込めます。
Pyxel Editor には以下の編集モードがあります。
イメージエディタ
イメージバンクの画像を編集する画面です。
![](/kitao/pyxel/raw/main/docs/images/image_editor.gif)
イメージエディタに画像ファイル (PNG/GIF/JPEG) をドラッグ&ドロップすると、選択中のイメージバンクに画像を読み込むことができます。
タイルマップエディタ
イメージバンクの画像をタイル状に並べたタイルマップを編集する画面です。
![](/kitao/pyxel/raw/main/docs/images/tilemap_editor.gif)
タイルマップエディタに TMX ファイル (Tiled Map File) をドラッグ&ドロップすると、選択中のタイルマップ番号に対応した描画順のレイヤーを読み込むことができます。
サウンドエディタ
サウンドを編集する画面です。
![](/kitao/pyxel/raw/main/docs/images/sound_editor.gif)
ミュージックエディタ
サウンドを再生順に並べたミュージックを編集する画面です。
![](/kitao/pyxel/raw/main/docs/images/music_editor.gif)
Pyxel 用の画像やタイルマップは以下の方法で作成することもできます。
Image.set
やTilemap.set
関数で文字列のリストから作成するImage.load
関数で Pyxel 向け配色の画像ファイル (PNG/GIF/JPEG) を読み込む
Pyxel 用のサウンドやミュージックは以下の方法で作成することもできます。
Sound.set
やMusic.set
関数で文字列から作成する
各関数の使い方は API リファレンスを参照してください。
Pyxel ではプラットフォームによらず動作する、専用のアプリケーション配布ファイル形式 (Pyxel アプリケーションファイル) をサポートしています。
Pyxel アプリケーションファイル (.pyxapp) はpyxel package
コマンドで作成します。
pyxel package アプリケーションのディレクトリ 起動スクリプトファイル
リソースや追加モジュールを同梱する場合は、アプリケーションのディレクトリ内に配置してください。
作成したアプリケーションファイルはpyxel play
コマンドで実行します。
pyxel play Pyxelアプリケーションファイル
Pyxel アプリケーションファイルは、pyxel app2exe
コマンドやpyxel app2html
コマンドで、実行可能ファイルや HTML ファイルに変換することもできます。
-
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
キーが押されるまで待機します。 -
flip()
画面を 1 フレーム更新します。ESC
を押すとアプリケーションは終了します。この関数は Web 版では動作しません。 -
quit()
Pyxel アプリケーションを終了します。
load(filename, [excl_images], [excl_tilemaps], [excl_sounds], [excl_musics])
リソースファイル (.pyxres) を読み込みます。オプションにTrue
を指定すると、そのリソースは読み込まれません。また、同名のパレットファイル (.pyxpal) がリソースファイルと同じ場所に存在する場合は、パレットの表示色も変更されます。パレットファイルは表示色を改行区切りの 16 進数 (例:1100FF
) で入力します。パレットファイルを使うことで Pyxel Editor の表示色も変更可能です。
-
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
を使用してください。
例:old_colors = pyxel.colors.to_list(); pyxel.colors.from_list([0x111111, 0x222222, 0x333333]); pyxel.colors[15] = 0x112233
-
images
イメージバンク (0-2) のリスト。(イメージクラスを参照のこと)
例:pyxel.images[0].load(0, 0, "title.png")
-
tilemaps
タイルマップ (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()
で初期状態にリセットします。 -
dither(alpha)
描画時にディザリング (擬似半透明) を適用します。alpha
は 0.0-1.0 の範囲で設定し、0.0 が透明、1.0 が不透明になります。 -
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], [rotate], [scale])
イメージバンクimg
(0-2) の (u
,v
) からサイズ (w
,h
) の領域を (x
,y
) にコピーします。w
、h
それぞれに負の値を設定すると水平、垂直方向に反転します。colkey
に色を指定すると透明色として扱われます。rotate
(度:Degree)、scale
(1.0=100%)、またはその両方を指定すると対応する変換が適用されます。
bltm(x, y, tm, u, v, w, h, [colkey], [rotate], [scale])
タイルマップtm
(0-7) の (u
,v
) からサイズ (w
,h
) の領域を (x
,y
) にコピーします。w
、h
それぞれに負の値を設定すると水平、垂直方向に反転します。colkey
に色を指定すると透明色として扱われます。rotate
(度:Degree)、scale
(1.0=100%)、またはその両方を指定すると対応する変換が適用されます。1 タイルのサイズは 8x8 ピクセルで、(tile_x, tile_y)
のタプルとしてタイルマップに格納されています。
text(x, y, s, col)
色col
の文字列s
を (x
,y
) に描画します。
-
sounds
サウンド (0-63) のリスト。(サウンドクラスを参照のこと)
例:pyxel.sounds[0].speed = 60
-
musics
ミュージック (0-7) のリスト。(ミュージッククラスを参照のこと) -
play(ch, snd, [tick], [loop], [resume])
チャンネルch
(0-3) でサウンドsnd
(0-63) を再生します。snd
がリストの場合順に再生されます。再生開始位置はtick
(1 tick = 1/120 秒) で指定できます。loop
にTrue
を指定するとループ再生します。再生終了後に以前の音に復帰させるにはresume
にTrue
を指定します。 -
playm(msc, [tick], [loop])
ミュージックmsc
(0-7) を再生します。再生開始位置はtick
(1 tick = 1/120 秒) で指定できます。loop
にTrue
を指定するとループ再生します。 -
stop([ch])
指定したチャンネルch
(0-3) の再生を停止します。stop()
で全チャンネルの再生を停止します。 -
play_pos(ch)
チャンネルch
(0-3) のサウンド再生位置を(サウンド番号, ノート番号)
のタプルとして取得します。再生停止時はNone
を返します。
-
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)
乱数生成器のシードを設定します。 -
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.images[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
タイルマップの幅と高さ -
imgsrc
タイルマップが参照するイメージバンク (0-2) -
set(x, y, data)
(x
,y
) に文字列のリストでタイルマップを設定します。
例:pyxel.tilemap(0).set(0, 0, ["0000 0100 a0b0", "0001 0101 a1b1"])
-
load(x, y, filename, layer)
(x
,y
) に TMX ファイル (Tiled Map File) から描画順がlayer
(0-) のレイヤーを読み込みます。 -
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 / 4:Half-FadeOut / 5:Quarter-FadeOut) のリスト -
speed
再生速度。1 が一番速く、数値が大きいほど再生速度は遅くなります。120 で 1 音の長さが 1 秒になります。 -
set(notes, tones, volumes, effects, speed)
文字列で音程、音色、音量、エフェクトを設定します。音色、音量、エフェクトの長さが音程より短い場合は、先頭から繰り返されます。 -
set_notes(notes)
'CDEFGAB'+'#-'+'01234'または'R'の文字列で音程を設定します。大文字と小文字は区別されず、空白は無視されます。
例:pyxel.sounds[0].set_notes("G2B-2D3R RF3F3F3")
-
set_tones(tones)
'TSPN'の文字列で音色を設定します。大文字と小文字は区別されず、空白は無視されます。
例:pyxel.sounds[0].set_tones("TTSS PPPN")
-
set_volumes(volumes)
'01234567'の文字列で音量を設定します。大文字と小文字は区別されず、空白は無視されます。
例:pyxel.sounds[0].set_volumes("7777 7531")
-
set_effects(effects)
'NSVFHQ'の文字列でエフェクトを設定します。大文字と小文字は区別されず、空白は無視されます。
例:pyxel.sounds[0].set_effects("NFNF NVVS")
-
seqs
サウンド (0-63) のリストをチャンネル数分連ねた 2 次元リスト -
set(seq0, seq1, seq2, ...)
チャンネルのサウンド (0-63) のリストを設定します。空リストを指定するとそのチャンネルは再生に使用しません。
例:pyxel.musics[0].set([0, 1], [], [3])
Pyxel には「ユーザーを混乱させる可能性がある」「使うために専門の知識が必要」などの理由から、このリファレンスには記載していない「上級者向け API」があります。
腕に覚えのある方は、こちらを手がかりにして、あっと驚くような作品づくりに挑戦してみてください!
不具合の報告や機能の要望はIssue Trackerで受け付けています。新しいレポートを作成する前に、同じ内容のものがないか確認をお願いします。
動作確認を行い、Issue Trackerで不具合の報告や改善の提案をしてくれる方は大歓迎です!
パッチや修正はプルリクエスト (PR) として受け付けています。提出の前に問題がすでに解決済みでないかIssue Trackerで確認をお願いします。
提出されたプルリクエストはMIT ライセンスで公開することに同意したものと見なされます。
Pyxel はMIT ライセンスです。ソースコードやライセンス表示用のファイル等で、著作権とライセンス全文の表示を行えば、自由に販売や配布をすることができます。
Pyxel は GitHub Sponsors でスポンサーを募っています。Pyxel のメンテナンスと機能追加の継続のためにスポンサーになることをご検討ください。スポンサーは特典として Pyxel についての相談をすることができます。詳細はこちらをご覧ください。