pyxel - Python复古游戏引擎打造像素风格作品

Pyxel是一个用于Python的复古游戏引擎。

由于其简单的规格受到复古游戏主机的启发，例如只能显示16种颜色，同时只能播放4种声音，您可以自由地享受制作像素艺术风格的游戏。

Pyxel开发的动力来自用户的反馈。请在GitHub上给Pyxel一个星标！

Pyxel的规格和API受到PICO-8和TIC-80的启发。

Pyxel是开源和免费使用的。让我们开始用Pyxel制作复古游戏吧！

规格

可在Windows、Mac、Linux和Web上运行
使用Python编程
16色调色板
3个256x256大小的图像库
8个256x256大小的瓦片地图
4个通道，64个可定义的声音
8个音乐，可组合任意声音
键盘、鼠标和游戏手柄输入
图像和声音编辑器

调色板

如何安装

Windows

安装Python3（3.8版本或更高）后，运行以下命令：

pip install -U pyxel

如果您使用官方安装程序安装Python，请勾选Add Python 3.x to PATH复选框以启用pyxel命令。

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

Pyxel的Web版本不需要安装Python或Pyxel，可在支持的Web浏览器上运行，包括PC以及智能手机和平板电脑。

具体说明请参考此页面。

尝试Pyxel示例

安装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	带背景音乐的贪吃蛇游戏	演示	代码
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)	演示	代码
99_flip_animation.py	使用翻转功能的动画（仅适用于非网页平台）	演示	代码
30SecondsOfDaylight.pyxapp	第一届Pyxel Jam获胜游戏，作者Adam	演示	代码
megaball.pyxapp	街机球物理游戏，作者Adam	演示	代码
8bit-bgm-gen.pyxapp	背景音乐生成器，作者frenchbread	演示	代码

可以使用以下命令执行示例:

cd pyxel_examples
pyxel run 01_hello_pyxel.py
pyxel play 30SecondsOfDaylight.pyxapp

如何使用

创建 Pyxel 应用程序

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

运行 Pyxel 应用程序

可以使用以下命令执行创建的 Python 脚本:

pyxel run PYTHON_SCRIPT_FILE

也可以像普通 Python 脚本一样执行:

python3 PYTHON_SCRIPT_FILE

特殊控制

在 Pyxel 应用程序运行时,可以执行以下特殊控制:

Esc
退出应用程序
Alt(Option)+1
将截图保存到桌面
Alt(Option)+2
重置屏幕捕获视频的录制开始时间
Alt(Option)+3
将屏幕捕获视频保存到桌面(最多 10 秒)
Alt(Option)+9
切换屏幕模式(清晰/平滑/复古)
Alt(Option)+0
切换性能监视器(fps、更新时间和绘制时间)
Alt(Option)+Enter
切换全屏
Shift+Alt(Option)+1/2/3
将对应的图像库保存到桌面
Shift+Alt(Option)+0
将当前调色板保存到桌面

如何创建资源

Pyxel Editor 可以创建 Pyxel 应用程序中使用的图像和声音。

使用以下命令启动:

pyxel edit PYXEL_RESOURCE_FILE

如果指定的 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 APP_DIR STARTUP_SCRIPT_FILE

如果应用程序应包含资源或额外模块,请将它们放在应用程序目录中。

可以使用以下命令执行创建的应用程序文件:

pyxel play PYXEL_APP_FILE

Pyxel 应用程序文件也可以使用 pyxel app2exe 或 pyxel app2html 命令转换为可执行文件或 HTML 文件。

API 参考

系统

width, height
屏幕的宽度和高度
frame_count
经过的帧数
init(width, height, [title], [fps], [quit_key], [display_scale], [capture_scale], [capture_sec])
使用屏幕大小(width, height)初始化 Pyxel 应用程序。可以指定以下选项:使用 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()
刷新一帧画面。当按下Esc键时应用程序退出。此功能在网页版中不可用。
quit()
退出Pyxel应用程序。

资源

load(filename, [excl_images], [excl_tilemaps], [excl_sounds], [excl_musics])
加载资源文件（.pyxres）。如果某个选项为True，则该资源不会被加载。如果在资源文件相同位置存在同名的调色板文件（.pyxpal），调色板显示颜色也会被更改。调色板文件是由换行符分隔的显示颜色的十六进制条目（例如1100FF）。调色板文件也可用于更改Pyxel编辑器中显示的颜色。

输入

mouse_x, mouse_y
鼠标光标的当前位置
mouse_wheel
鼠标滚轮的当前值
btn(key)
如果key被按下则返回True，否则返回False。（按键定义列表）
btnp(key, [hold], [repeat])
如果key在该帧被按下则返回True，否则返回False。当指定hold和repeat时，如果key被按住超过hold帧，则每隔repeat帧返回True。
btnr(key)
如果key在该帧被释放则返回True，否则返回False。
mouse(visible)
如果visible为True，显示鼠标光标。如果为False，隐藏鼠标光标。即使鼠标光标不显示，其位置也会更新。

图形

colors
调色板显示颜色列表。显示颜色由24位数值指定。使用colors.from_list和colors.to_list直接分配和检索Python列表。
例如：old_colors = pyxel.colors.to_list(); pyxel.colors.from_list([0x111111, 0x222222, 0x333333]); pyxel.colors[15] = 0x112233
images
图像库列表（0-2）。（参见Image类）
例如：pyxel.images[0].load(0, 0, "title.png")
tilemaps
图块地图列表（0-7）。（参见Tilemap类）
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)
从(x, y)开始绘制宽度为w，高度为h，颜色为col的矩形。
rectb(x, y, w, h, col)
从(x, y)开始绘制宽度为w，高度为h，颜色为col的矩形轮廓。
circ(x, y, r, col)
以(x, y)为中心绘制半径为r，颜色为col的圆。
circb(x, y, r, col)
以(x, y)为中心绘制半径为r，颜色为col的圆的轮廓。
elli(x, y, w, h, col)
从(x, y)开始绘制宽度为w，高度为h，颜色为col的椭圆。
ellib(x, y, w, h, col)
从(x, y)开始绘制宽度为w，高度为h，颜色为col的椭圆轮廓。
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)
用颜色col填充与(x, y)处相同颜色的连通区域。
blt(x, y, img, u, v, w, h, [colkey])
将图像库img(0-2)中从(u, v)开始的大小为(w, h)的区域复制到(x, y)。如果为w和/或h设置负值，则会水平和/或垂直翻转。如果指定了colkey，则将其视为透明色。

bltm(x, y, tm, u, v, w, h, [colkey])
将图块地图tm(0-7)中从(u, v)开始的大小为(w, h)的区域复制到(x, y)。如果为w和/或h设置负值，则会水平和/或垂直翻转。如果指定了colkey，则将其视为透明色。图块的大小为8x8像素，在图块地图中以(tile_x, tile_y)的元组形式存储。

- `text(x, y, s, col)`
在坐标 (x, y) 绘制颜色为 col 的字符串 s。

音频

sounds
音效列表（0-63）。（参见 Sound 类）
例如：pyxel.sounds[0].speed = 60
musics
音乐列表（0-7）。（参见 Music 类）
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）的音效播放位置，返回一个包含 (音效编号, 音符编号) 的元组。当播放停止时返回 None。

数学

ceil(x)
返回大于或等于 x 的最小整数。
floor(x)
返回小于或等于 x 的最大整数。
sgn(x)
当 x 为正数时返回 1，为零时返回 0，为负数时返回 -1。
sqrt(x)
返回 x 的平方根。
sin(deg)
返回 deg 度的正弦值。
cos(deg)
返回 deg 度的余弦值。
atan2(y, x)
返回 y/x 的反正切值（以度为单位）。
rseed(seed)
设置随机数生成器的种子。
rndi(a, b)
返回一个大于等于 a 且小于等于 b 的随机整数。
rndf(a, b)
返回一个大于等于 a 且小于等于 b 的随机小数。
nseed(seed)
设置柏林噪声的种子。
noise(x, [y], [z])
返回指定坐标的柏林噪声值。

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 地图文件）加载绘制顺序为 layer（0-）的图层。
pget(x, y)
获取坐标 (x, y) 的瓦片。瓦片是一个 (tile_x, tile_y) 元组。
pset(x, y, tile)
在坐标 (x, y) 绘制瓦片。瓦片是一个 (tile_x, tile_y) 元组。

Sound 类

notes
音符列表（0-127）。数字越大，音调越高，33 对应 'A2'（440Hz）。休止符为 -1。
tones
音色列表（0:三角波 / 1:方波 / 2:脉冲波 / 3:噪声）
volumes
音量列表（0-7）
effects
音效列表（0:无 / 1:滑音 / 2:颤音 / 3:淡出 / 4:半淡出 / 5:四分之一淡出）
speed
播放速度。1 最快，数字越大播放速度越慢。120 时一个音符的长度为 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")