`pyxen.Sprite`

表示分配给 Entity 的可渲染图像。

Sprite 是不可变对象。要更改实体显示的内容，请替换精灵。

有关渲染概念，请参见精灵与渲染。

构造函数

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

分配 Sprite

可以在生成时分配：

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

或稍后：

player.sprite = Sprite("hero_idle")

Sprite 不可变性

Sprite 是不可变的——创建后无法修改。

替换实体的精灵：

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

Tile 和 Animation 冲突

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