<img src="https://yellow-cdn.veclightyear.com/835a84d5/01d47b81-28e5-4063-b20c-cfb973579110.png">

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

要复制的示例如下：

<table> <tr> <td>01_hello_pyxel.py</td> <td>最简单的应用程序</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/01_hello_pyxel.html">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/01_hello_pyxel.py">代码</a></td> </tr> <tr> <td>02_jump_game.py</td> <td>使用Pyxel资源文件的跳跃游戏</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/02_jump_game.html">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/02_jump_game.py">代码</a></td> </tr> <tr> <td>03_draw_api.py</td> <td>绘图API演示</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/03_draw_api.html">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/03_draw_api.py">代码</a></td> </tr> <tr> <td>04_sound_api.py</td> <td>声音API演示</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/04_sound_api.html">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/04_sound_api.py">代码</a></td> </tr> <tr> <td>05_color_palette.py</td> <td>色彩调色板列表</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/05_color_palette.html">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/05_color_palette.py">代码</a></td> </tr> <tr> <td>06_click_game.py</td> <td>鼠标点击游戏</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/06_click_game.html">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/06_click_game.py">代码</a></td> </tr> <tr> <td>07_snake.py</td> <td>带背景音乐的贪吃蛇游戏</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/07_snake.html">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/07_snake.py">代码</a></td> </tr> <tr> <td>08_triangle_api.py</td> <td>三角形绘制API演示</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/08_triangle_api.html">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/08_triangle_api.py">代码</a></td> </tr> <tr> <td>09_shooter.py</td> <td>带屏幕过渡的射击游戏</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/09_shooter.html">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/09_shooter.py">代码</a></td> </tr> <tr> <td>10_platformer.py</td> <td>带地图的横向卷轴平台游戏</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/10_platformer.html">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/10_platformer.py">代码</a></td> </tr> <tr> <td>11_offscreen.py</td> <td>使用Image类的离屏渲染</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/11_offscreen.html">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/11_offscreen.py">代码</a></td> </tr> <tr> <td>12_perlin_noise.py</td> <td>柏林噪声动画</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/12_perlin_noise.html">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/12_perlin_noise.py">代码</a></td> </tr> <tr> <td>13_bitmap_font.py</td> <td>绘制位图字体</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/13_bitmap_font.html">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/13_bitmap_font.py">代码</a></td> </tr> <tr> <td>14_synthesizer.py</td> <td>利用音频扩展功能的合成器</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/14_synthesizer.html">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/14_synthesizer.py">代码</a></td> </tr> <tr> <td>15_tiled_map_file.py</td> <td>加载并绘制瓦片地图文件(.tmx)</td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/15_tiled_map_file.html">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/15_tiled_map_file.py">代码</a></td> </tr> <tr> <td>99_flip_animation.py</td> <td>使用翻转功能的动画（仅适用于非网页平台）</td> <td><a href="https://github.com/kitao/pyxel/blob/main/docs/images/99_flip_animation.gif">演示</a></td> <td><a href="https://github.com/kitao/pyxel/blob/main/python/pyxel/examples/99_flip_animation.py">代码</a></td> </tr> <tr> <td>30SecondsOfDaylight.pyxapp</td> <td>第一届Pyxel Jam获胜游戏，作者<a href="https://twitter.com/helpcomputer0">Adam</a></td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/30SecondsOfDaylight.html">演示</a></td> <td><a href="https://github.com/kitao/30SecondsOfDaylight">代码</a></td> </tr> <tr> <td>megaball.pyxapp</td> <td>街机球物理游戏，作者<a href="https://twitter.com/helpcomputer0">Adam</a></td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/megaball.html">演示</a></td> <td><a href="https://github.com/helpcomputer/megaball">代码</a></td> </tr> <tr> <td>8bit-bgm-gen.pyxapp</td> <td>背景音乐生成器，作者<a href="https://twitter.com/frenchbread1222">frenchbread</a></td> <td><a href="https://kitao.github.io/pyxel/wasm/examples/8bit-bgm-gen.html">演示</a></td> <td><a href="https://github.com/shiromofufactory/8bit-bgm-generator">代码</a></td> </tr> </table> 可以使用以下命令执行示例:

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)的元组形式存储。

<img src="https://yellow-cdn.veclightyear.com/835a84d5/f9884dae-3431-4771-8427-0fd417dbd8c0.png"> - `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")