精灵与渲染

Pyxen 使用基于 Metal 的 2D 渲染器来渲染你的游戏。屏幕上所有可见的内容都是拥有 Sprite 组件的实体。

精灵

精灵告诉引擎为实体绘制什么。你通过引用项目中的图片来创建一个:

player = world.spawn(sprite=Sprite("hero"))

字符串 "hero" 引用项目素材中名为 hero 的图片。

图块表

大多数游戏使用图块表——一张包含许多帧或图块的单一图片,按网格排列。你使用 tile 参数选择图片的一个区域:

Sprite("characters", tile=(0, 0, 16, 16))    # first tile
Sprite("characters", tile=(16, 0, 16, 16))   # second tile
Sprite("characters", tile=(0, 16, 16, 16))   # tile on second row

四个值是 (x, y, width, height),以像素为单位,从图片左上角开始测量。

精灵动画

如果你在精灵编辑器中创建了命名动画,可以直接播放它们:

player = world.spawn(
    sprite=Sprite("hero", animation="walk"),
    x=100, y=50
)

引擎从精灵的元数据中读取动画的帧序列和 FPS,并自动推进帧。要切换动画,赋值一个新的精灵:

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

对于一次性动画(如攻击或死亡),设置 loop=False 并检查动画是否结束:

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

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

e.animation 组件提供对当前状态的只读访问:.name、.frame、.playing、.finished。详情请参见 Entity 参考文档。

你也可以通过每帧改变图块来手动制作动画:

def update():
    frame = time.frame % 4
    player.sprite = Sprite("hero", tile=(frame * 16, 0, 16, 16))

锚点

默认情况下,精灵从其左上角开始绘制。你可以更改锚点来控制精灵的锚定位置:

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

这将精灵居中于实体的位置。锚点使用相对于图块的像素坐标。将锚点设置到图块中心是最常见的选择——它让旋转和缩放的行为更直觉。

颜色着色

你可以通过设置颜色来为任何实体的精灵着色:

player.color = (1.0, 0.5, 0.5, 1.0)  # reddish tint

颜色是 RGBA 元组,值从 0.0 到 1.0。白色 (1, 1, 1, 1) 表示无着色。你可以使用 alpha 通道来实现透明:

ghost.color = (1, 1, 1, 0.5)  # 50% transparent

你也可以使用 tweens 平滑地动画化颜色和透明度:

ghost.tween("alpha", to=0, duration=0.5, ease="out_quad")  # 淡出

对于脉动或闪烁这类持续的效果,使用 animations:

ghost.animate("alpha", by=0.3, center=0.7, speed=4.0)  # 闪烁

摄像机

摄像机控制世界的哪个部分可见。通过生成一个带有 Camera 组件的实体来创建摄像机:

cam = world.spawn(camera=Camera(), x=160, y=90)

移动摄像机跟随玩家:

def update():
    cam.x = player.x
    cam.y = player.y

摄像机支持缩放:

cam.camera.zoom = 2.0  # zoom in 2x

你可以使用 tween 平滑地动画化缩放:

cam.tween("zoom", to=2.0, duration=0.5, ease="out_quad")

分辨率

Pyxen 游戏以默认分辨率 320x180 像素运行。这是一个有意的选择——低分辨率让像素美术看起来清晰,并保持渲染高效。引擎会缩放输出以填满屏幕。

文本

Text 组件渲染位图文本。这样创建一个文本实体:

label = world.spawn(text=Text("Hello, world!"))

文本默认使用内置的像素字体。要使用在字体编辑器中创建的字体:

title = world.spawn(text=Text("Game Over", font="myfont"))

运行时修改 text 属性即可更新文本:

def update():
    score_label.text = Text(f"Score: {score}")

完整的 API 请参阅 Text 参考。

绘制顺序

实体按以下顺序绘制:

  1. 图层 — 较低的图层先绘制(图层 0 在图层 1 后面)
  2. 深度 — 在同一图层内,由场景图位置决定
  3. 没有精灵的实体不会被绘制,但仍然存在于世界中

参见场景图了解更多关于图层和深度的内容。

完整 Sprite API 参见 Sprite 和 Camera。