音声・画像を持ち込む ── メディアアセット

Pyxel の音楽エディタ(チップチューン)だけでは表現できない、録音した音声 や カメラで撮った写真、外部の画像編集ツールで描いたイラスト を、そのまま魔導書に取り込んで作品に使えます。

対応しているのは 4 種類:

  • 音声: .ogg(Ogg Vorbis)
  • 画像: .png
  • マップ: .tmx(Tiled Map Editor で作ったマップ)
  • 3D モデル: .glb(Blockbench の「glTF モデル」書き出し)

いずれも Pyxel の標準機能でそのまま読み込めます。

アップロードする

羽根筆のゆりかごのエディタで、ページタブの右にある 「+」ボタン を押すと、追加するページの種類を選ぶメニューが開きます。

その中の 「メディアをアップロード」 を選ぶと、アップロードダイアログが開きます:

  1. パソコンから .ogg / .png / .tmx / .glb のファイルを選ぶ
  2. プレビュー(画像のサムネイル・音声の再生ボタン)で中身を確認する(マップと 3D モデルは種類だけが表示されます)
  3. 魔導書内で使いたい 名前 を入力する(拡張子は自動で保たれます)
  4. 「アップロード」を押す

1 ファイルの上限は 3MB(3,145,728 バイト)です。中身が本当にその種類のファイルであるかも自動でチェックされるので、拡張子だけ変えたファイルはアップロードできません。

音声を鳴らす

アップロードした .ogg は、Pyxel の Sound.pcm() にファイル名を渡すだけで サウンド枠に読み込めます。あとはいつもの pyxel.play() で鳴らせます:

import pyxel


class App:
    def __init__(self):
        pyxel.init(160, 120)

        # 音声をサウンド枠 0 に読み込む
        pyxel.sounds[0].pcm("whale.ogg")

        # 音量(既定 0.125 → 少し大きく)
        pyxel.channels[0].gain = 0.8

        # チャンネル 0 でサウンド 0 をループ再生
        pyxel.play(0, 0, loop=True)

        pyxel.run(self.update, self.draw)

    def update(self):
        pass

    def draw(self):
        pyxel.cls(0)


App()

OGG 形式とは?

MP3 と同じく音声用のデータ圧縮方式で、オープンソース である点が特徴です。Pyxel の pcm() が直接扱えます。手元の MP3 は、たとえば下記のようにして OGG に変換できます:

ffmpeg -i in.mp3 -c:a libvorbis -q:a 5 out.ogg

再生時の音質ロスを避けるため、サンプルレートは 22.05 kHz への変換がおすすめです。

画像を表示する

アップロードした .png は、Pyxel の Image.from_image() に渡すだけで読み込めます。あとは pyxel.blt() で画面に描けます:

import pyxel


class App:
    def __init__(self):
        pyxel.init(160, 120)

        # パレットを最初に読み込む(下で説明します)
        pyxel.load_pal("palette.pyxpal")

        # 画像を読み込む
        self.bg = pyxel.Image.from_image("background.png")

        pyxel.run(self.update, self.draw)

    def update(self):
        pass

    def draw(self):
        pyxel.blt(0, 0, self.bg, 0, 0, self.bg.width, self.bg.height)


App()

画像とパレットの関係 ── 「共有パレット」の仕組み

Pyxel はゲーム全体で 1 枚のパレット の色を使って絵を描きます。画像を Image.from_image() で読み込むとき、そのときアクティブなパレットの中で一番近い色に、各ピクセルが変換されて 取り込まれます(Pyxel 公式の挙動)。

そのため、そのまま外の画像を持ち込むと 色が変わって見える ことがあります。写真の水色が、パレットに水色が無いために青紫になってしまう、といった具合です。

これを防ぐため、Code & Magic では 画像をアップロードするときに、その画像の色を魔導書共有のパレットにまとめて登録 できます。

アップロードダイアログには次のチェックボックスがあります(既定 ON):

🎨 画像の色をパレット(palette.pyxpal)にまとめる

チェックしたまま OK すると:

  • 魔導書に palette.pyxpal という 1 枚のパレットファイルが自動で作られます(既に存在すれば、そこに色が追記されます)
  • Pyxel 標準の 16 色は index 0〜15 にそのまま残し、その 後ろに画像の色が追加 されます
  • 画像を 2 枚 3 枚と足しても、同じ palette.pyxpal にまとまります(同じ色は共有されます)

コードの冒頭で pyxel.load_pal("palette.pyxpal") を 1 回だけ 呼んでおけば、あとから Image.from_image() で読み込んだどの画像も、追加した色そのままで表示されます。

マップを読み込む

Tiled Map Editor で作ったマップ(.tmx)は、Pyxel のタイルマップに読み込めます:

# タイルマップ 0 の左上(0, 0)に、マップの 0 番目のレイヤーを読み込む
pyxel.tilemaps[0].load(0, 0, "stage1.tmx", 0)

あとはいつもの pyxel.bltm() で画面に描けます。

3D モデルを動かす

Pyxel 3.0.0 の 3D の機能(pyxel.cube)を使うと、3D モデル(.glb)を画面に出して動かせます:

import pyxel
from pyxel.cube import Camera, Mat4, Mesh, Node, Vec3


class App:
    def __init__(self):
        pyxel.init(160, 120)

        # 3D モデルを読み込み、最初の動きを再生する
        mesh = Mesh.from_glb("actor.glb")
        self.model = Node.from_mesh(mesh)
        self.model.play_motion(mesh.motions[0])

        # カメラを置いて、モデルを場面に入れる
        self.scene = Node()
        self.scene.camera = Camera()
        self.scene.camera.transform = Mat4.look_at(Vec3(0, 1, 3), Vec3.ZERO)
        self.scene.add_child(self.model)

        pyxel.run(self.update, self.draw)

    def update(self):
        self.scene.update()

    def draw(self):
        pyxel.cls(1)
        self.scene.draw(0, 0, pyxel.width, pyxel.height)


App()

読み込めるのは、Blockbench の「glTF モデル」書き出し(Binary・テクスチャ埋め込み・armature なし)です。テクスチャを別ファイルにした .glb は読み込み時にエラーになります。

魔導書の中で見る

アップロードしたメディアは、.py や .pyxres と同じようにファイルタブに並びます。タブの左には ファイルの種類を示すアイコン が付いているので、コードなのか、リソースなのか、画像なのか、音声なのか、パレットなのか、一目で見分けられます。

アイコン拡張子意味
py.pyプログラム
pyxres.pyxresドット絵・効果音のリソースパック
ogg.ogg音声
png.png画像
pyxpal.pyxpalカラーパレット

タブを開くと:

  • 音声(.ogg) ── 再生ボタンで試聴できる。読み込み方のサンプルコードを添えて表示
  • 画像(.png) ── サムネイルと解像度(幅 × 高さ)を表示。読み込み方のサンプルコードを添えて表示
  • パレット(.pyxpal) ── 登録されている色のスウォッチ一覧と、load_pal のサンプルコードを表示
  • マップ(.tmx) ── マップの大きさ(マス数)とレイヤーの数を表示。読み込み方のサンプルコードを添えて表示
  • 3D モデル(.glb) ── 部品と動きの名前を表示。カメラの位置まで入った、そのまま動くサンプルコードを添えて表示

サンプルコードは コピペしてすぐ使える ようになっているので、コード側にファイル名をタイプミスなく書けます。

リミックス素材としての扱い

アップロードしたメディアアセットも、コードと同じように 他の冒険者にリミックスされる可能性 があります(デコード & リミックス)。

一方で、公開作品の魔導書からメディアアセットを 単独でダウンロードすることはできません(.py や .pyxres も同様)。作品の一部として遊びの中で楽しんでもらう、リミックスするならもう一度作品として作り込む ── その前提で組み込んでいます。

使い分けのヒント

  • 効果音や短い BGM: Pyxel の音楽エディタ(チップチューン)で作るのがおすすめ。軽くてループも滑らか
  • 鳥のさえずり・環境音・録音音声: チップチューンで再現できないので .ogg で持ち込む
  • ドット絵: .pyxres のイメージバンクで管理する
  • ドット絵にできない画像・大きな背景画像・写真: .png で持ち込み、共有パレットに色をまとめる
  • 大きなマップ: Tiled で作って .tmx で持ち込む
  • 立体のキャラクターや物: Blockbench で作って .glb で持ち込む

コードで動かせる範囲や、他に使えるライブラリは コードのルール を参照してください。