`pyxen.Sprite`

Entityにアタッチされる描画可能な画像を表します。

スプライトは不変オブジェクトです。エンティティの表示を変更するには、スプライトを置き換えます。

レンダリングのコンセプトについてはスプライト＆レンダリングを参照してください。

コンストラクタ

Sprite(
    image,
    *,
    tile=None,
    pivot=None,
    animation=None,
    loop=True
)

imageは位置引数またはキーワード引数として渡せますが、両方は不可です。

パラメータ

パラメータ	型	説明
`image`	`str`	画像アセットの名前
`tile`	`(x, y, w, h)`	画像のサブ矩形
`pivot`	`(x, y)`	ピクセル単位のピボットポイント
`animation`	`str`	再生するスプライトアニメーションの名前
`loop`	`bool`	アニメーションをループするかどうか（デフォルト`True`）

`image`（必須）

Sprite("hero")

画像が存在しない場合：

ValueError: Failed to load image 'hero'

`tile`（オプション）

テクスチャのサブ矩形を定義します。

Sprite(
    "tileset",
    tile=(0, 0, 16, 16)
)

指定しない場合、画像全体が使用されます。

`pivot`（オプション）

スプライトの原点を定義します。

Sprite(
    "hero",
    pivot=(8, 8)
)

指定しない場合：(0, 0)（左上隅）。

`animation`（オプション）

スプライトエディタのアニメーションタイムラインで定義された名前付きアニメーションを再生します。エンジンは画像のメタデータからアニメーションデータ（フレームシーケンス、FPS）を読み取り、フレームを自動的に進めます。

Sprite("hero", animation="walk")

tileと組み合わせることはできません — どちらか一方を使用してください。

アニメーションはエンティティに割り当てられるとすぐに再生を開始します。デフォルトではループします。ワンショットアニメーションにはloop=Falseを使用します：

Sprite("hero", animation="death", loop=False)

アニメーションの状態を確認するには、エンティティのe.animationコンポーネントを使用します。

`loop`（オプション）

アニメーションを繰り返すかどうかを制御します。animationと一緒に使用する場合のみ有効です。デフォルト：True。

Sprite("hero", animation="jump", loop=False)

例

hero_sprite = Sprite(
    image="hero",
    tile=(0, 0, 16, 16),
    pivot=(8, 8)
)

アニメーション付きスプライト：

hero_sprite = Sprite(
    image="hero",
    animation="walk",
    pivot=(8, 8)
)

スプライトの割り当て

生成時に割り当て：

player = world.spawn(
    sprite=Sprite("hero"),
    x=32,
    y=32
)

または後から：

player.sprite = Sprite("hero_idle")

スプライトの不変性

スプライトは不変です — 作成後にスプライトを変更することはできません。

代わりにエンティティのスプライトを置き換えます：

player.sprite = Sprite("hero_jump")

カラー

エンティティはスプライトを置き換えずにティンティングするカラープロパティを公開します：

entity.color = (r, g, b, a)

例：

player.color = (1.0, 0.5, 0.5, 1.0)

デフォルトカラー：(1.0, 1.0, 1.0, 1.0)

カラーを読み取るとColorオブジェクトが返されます：

c = player.color
print(c.r, c.g, c.b, c.a)

アニメーション

スプライトアニメーションの推奨方法はanimationパラメータです。スプライトエディタで名前付きアニメーションを定義し、名前で再生します：

player.sprite = Sprite("hero", animation="walk")

新しいスプライトを割り当ててアニメーションを切り替えます：

player.sprite = Sprite("hero", animation="idle")

ワンショットアニメーションの場合、エンティティのanimationコンポーネントで完了を確認します：

player.sprite = Sprite("hero", animation="attack", loop=False)

def update():
    if player.animation and player.animation.finished:
        player.sprite = Sprite("hero", animation="idle")

手動アニメーション

フレームごとにスプライトのタイルを置き換えて手動でアニメーションすることもできます：

player.sprite = Sprite(
    "atlas",
    tile=(frame * 16, 0, 16, 16)
)

よくあるエラー

画像の指定なし

Sprite()

ValueError: Sprite must have an image

画像引数の重複

Sprite("hero", image="hero")

TypeError: image specified both positionally and as keyword

タイルとアニメーションの競合

Sprite("hero", tile=(0, 0, 16, 16), animation="walk")

TypeError: cannot specify both tile and animation

アニメーションが見つからない

Sprite("hero", animation="fly")

ValueError: Animation 'fly' not found in 'hero'

pyxen.Sprite