Skip to content

Latest commit

 

History

History
755 lines (541 loc) · 32.4 KB

README.ja.md

File metadata and controls

755 lines (541 loc) · 32.4 KB
Raw

Downloads GitHub Repo stars GitHub forks GitHub Sponsors

ko-fi

[ 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 はMIT ライセンスのオープンソースで、無料で自由に使えます。Pyxel でレトロゲームづくりを始めましょう！

仕様

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

カラーパレット

インストール方法

Windows

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

pip install -U pyxel

公式インストーラーで Python をインストールする場合は、pyxelコマンドを有効にするために、Add Python 3.x to PATHにチェックを入れて Python のインストールを行ってください。

Mac

Homebrew をインストールした後、次のコマンドを実行します。

brew install pipx
pipx ensurepath
pipx install pyxel

Pyxel をインストールした後にバージョンを更新する場合は、pipx upgrade pyxelを実行してください。

Linux

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

sudo pip3 install -U pyxel

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

Web

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

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

サンプルを実行する

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 パーリンノイズアニメーション デモ コード
13_bitmap_font.py ビットマップフォント描画 デモ コード
14_synthesizer.py オーディオ拡張機能によるシンセサイザー デモ コード
15_tiled_map_file.py タイルマップファイル (.tmx) の読み込みと描画 デモ コード
16_transform.py 画像の回転と拡大縮小 デモ コード
99_flip_animation.py flip 関数によるアニメーション (非 Web 環境のみ) デモ コード
30sec_of_daylight.pyxapp 第 1 回 Pyxel Jam 優勝ゲーム (Adam制作) デモ コード
megaball.pyxapp アーケードボール物理ゲーム (Adam制作) デモ コード
8bit-bgm-gen.pyxapp BGM自動作成ツール (frenchbread制作) デモ コード

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

cd pyxel_examples
pyxel run 01_hello_pyxel.py
pyxel play 30sec_of_daylight.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)+8またはゲームパッドでA+B+X+Y+DL
    画面の拡大方法を最大と整数倍で切り替える
  • Alt(Option)+9またはゲームパッドでA+B+X+Y+DR
    画面モード (Crisp/Smooth/Retro) を切り替える
  • Alt(Option)+0またはゲームパッドでA+B+X+Y+DU
    パフォーマンスモニタ (FPS/update時間/draw時間) の表示を切り替える
  • Alt(Option)+EnterまたはゲームパッドでA+B+X+Y+DD
    フルスクリーン表示を切り替える
  • Shift+Alt(Option)+1/2/3
    イメージバンク 0,1,2 をデスクトップに保存する
  • Shift+Alt(Option)+0
    現在のカラーパレットをデスクトップに保存する

リソースの作成方法

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

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

pyxel edit Pyxelリソースファイル

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

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

作成したリソースファイルは、load関数で読み込めます。

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

イメージエディタ

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

イメージエディタに画像ファイル (PNG/GIF/JPEG) をドラッグ＆ドロップすると、選択中のイメージバンクに画像を読み込みます。

タイルマップエディタ

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

タイルマップエディタに TMX ファイル (Tiled Map File) をドラッグ＆ドロップすると、選択中のタイルマップ番号に対応した描画順のレイヤーを読み込むことができます。

サウンドエディタ

メロディーや効果音に使用するサウンドを編集する画面です。

ミュージックエディタ

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

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

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 アプリケーションのディレクトリ 起動スクリプトファイル

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

起動スクリプトに次の形式でメタデータを記載すると、実行時に表示されます。title、author以外のフィールドは省略可能です。

# title: Pyxel Platformer
# author: Takashi Kitao
# desc: A Pyxel platformer example
# site: https://github.com/kitao/pyxel
# license: MIT
# version: 1.0

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

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

Pyxel アプリケーションファイルは、pyxel app2exeコマンドやpyxel app2htmlコマンドで、実行可能ファイルや HTML ファイルに変換できます。

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キーが押されるまで待機します。

  • flip()
    画面を 1 フレーム更新します。Escを押すとアプリケーションは終了します。この関数は Web 版では動作しません。

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

リソース

  • load(filename, [excl_images], [excl_tilemaps], [excl_sounds], [excl_musics])
    リソースファイル (.pyxres) を読み込みます。オプションにTrueを指定すると、そのリソースは読み込まれません。また、同名のパレットファイル (.pyxpal) がリソースファイルと同じ場所に存在する場合は、パレットの表示色も変更されます。パレットファイルは、表示色を改行区切りの 16 進数 (例：1100FF) で入力します。パレットファイルを使うことで Pyxel Editor の表示色も変更可能です。

  • user_data_dir(vendor_name, app_name)
    vendor_nameとapp_nameから生成されたユーザーデータ保存用ディレクトリを返します。該当ディレクトリが存在しない場合は自動で作成されます。ハイスコアやゲームの進行状況の保存先として使用します。
    例：print(pyxel.user_data_dir("Takashi Kitao", "Pyxel Shooter"))

入力

  • 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
    イメージバンク (Image クラスのインスタンス) のリスト (0-2)
    例：pyxel.images[0].load(0, 0, "title.png")

  • tilemaps
    タイルマップ (Tilemap クラスのインスタンス) のリスト (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 ピクセルで、(image_tx, image_ty)のタプルとしてタイルマップに格納されています。

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

オーディオ

  • sounds
    サウンド (Sound クラスのインスタンス) のリスト (0-63)
    例：pyxel.sounds[0].speed = 60

  • musics
    ミュージック (Music クラスのインスタンス) のリスト (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) のサウンド再生位置を(sound_no, note_no)のタプルとして取得します。再生停止時は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 ノイズ値を返します。

Image クラス

  • 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のピクセルを描画します。

Tilemap クラス

  • 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) のタイルを取得します。タイルは(image_tx, image_ty)のタプルです。

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

Sound クラス

  • 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")

Music クラス

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

  • set(seq0, seq1, seq2, ...)
    チャンネルのサウンド (0-63) のリストを設定します。空リストを指定すると、そのチャンネルは再生に使用されません。
    例：pyxel.musics[0].set([0, 1], [], [3])

上級者向け API

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

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

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

問題の報告

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

動作確認

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

プルリクエスト

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

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

その他の情報

ライセンス

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

スポンサー募集

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