[ English | 中文 | Deutsch | Español | Français | Italiano | 日本語 | 한국어 | Português | Русский | Türkçe | Українська ]
Pyxel 是一个针对 Python 的复古游戏引擎。
其规格受到复古游戏机的启发，例如仅支持 16 种颜色和 4 个音轨，同时可以轻松享受制作像素艺术风格游戏的乐趣。
Pyxel 的开发得益于用户的反馈。请在 GitHub 上给 Pyxel 评分！
Pyxel 的规格和 API 参考了 PICO-8 和 TIC-80。
Pyxel 在 MIT 许可证 下开源并免费使用。让我们开始使用 Pyxel 制作复古游戏吧！
- 支持 Windows、Mac、Linux 和 Web
- 使用 Python 编程
- 16 色调色板
- 3 个 256x256 尺寸图像库
- 8 个 256x256 尺寸瓦片地图
- 4 个通道，支持 64 种可定义声音
- 8 个音乐轨道可以组合任意声音
- 支持键盘、鼠标和游戏手柄输入
- 图像和声音编辑工具
- 用户可扩展的颜色、通道和库
在安装 Python3（版本 3.8 或更高）后，运行以下命令：
pip install -U pyxel在使用官方安装程序安装 Python 时，请确保勾选 Add Python 3.x to PATH 选项，以启用 pyxel 命令。
在安装 Homebrew 后，运行以下命令：
brew install pipx
pipx ensurepath
pipx install pyxel安装 Pyxel 后，要升级 Pyxel，请运行 pipx upgrade pyxel。
在安装 SDL2 包（对于 Ubuntu 为 libsdl2-dev）、Python3（版本 3.8 或更高）和 python3-pip 后，运行以下命令：
sudo pip3 install -U pyxel如果之前的命令失败，请按照 Makefile 中的说明考虑从源代码构建 Pyxel。
Pyxel 的 Web 版本不需要安装 Python 或 Pyxel，可以在支持的 Web 浏览器上运行于 PC、智能手机和平板电脑上。
有关详细说明，请参阅 此页面。
在安装 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 | 射击游戏与屏幕切换及MML | 演示 | 代码 |
| 10_platformer.py | 带有地图的横向卷轴平台游戏 | 演示 | 代码 |
| 11_offscreen.py | 使用 Image 类进行离屏渲染 | 演示 | 代码 |
| 12_perlin_noise.py | 柏林噪声动画 | 演示 | 代码 |
| 13_bitmap_font.py | 绘制位图字体 | 演示 | 代码 |
| 14_synthesizer.py | 使用音频扩展功能的合成器 | 演示 | 代码 |
| 15_tiled_map_file.py | 加载和绘制 Tiled Map File (.tmx) | 演示 | 代码 |
| 16_transform.py | 图像旋转和缩放 | 演示 | 代码 |
| 99_flip_animation.py | 使用翻转函数的动画（仅限非网页平台） | 演示 | 代码 |
| 30sec_of_daylight.pyxapp | 第 1 届 Pyxel Jam 获胜游戏由 Adam 制作 | 演示 | 代码 |
| megaball.pyxapp | 由 Adam 制作的街机球物理游戏 | 演示 | 代码 |
| 8bit-bgm-gen.pyxapp | 由 frenchbread 制作的背景音乐生成器 | 演示 | 代码 |
这些示例可以通过以下命令执行：
cd pyxel_examples
pyxel run 01_hello_pyxel.py
pyxel play 30sec_of_daylight.pyxapp在您的 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()创建的脚本可以使用 python 命令执行：
python PYTHON_SCRIPT_FILE它也可以使用 pyxel run 命令运行：
pyxel run PYTHON_SCRIPT_FILE此外，pyxel watch 命令监视指定目录中的更改，并在检测到更改时自动重新运行程序：
pyxel watch WATCH_DIR PYTHON_SCRIPT_FILE可以通过按 Ctrl(Command)+C 停止目录监视。
在运行 Pyxel 应用程序时，可以执行以下特殊键操作：
Esc
退出应用程序Alt(Option)+1
将屏幕截图保存到桌面Alt(Option)+2
重置屏幕录像视频的录制开始时间Alt(Option)+3
将屏幕录像视频保存到桌面（最多 10 秒）Alt(Option)+8或者在游戏手柄上按A+B+X+Y+DL
在最大和整数倍缩放之间切换屏幕缩放Alt(Option)+9或者在游戏手柄上按A+B+X+Y+DR
在屏幕模式 (Crisp/Smooth/Retro) 之间切换Alt(Option)+0或者在游戏手柄上按A+B+X+Y+DU
切换性能监视器 (FPS/update时间/draw时间)Alt(Option)+Enter或者在游戏手柄上按A+B+X+Y+DD
切换全屏Shift+Alt(Option)+1/2/3
将图像库 0、1 或 2 保存到桌面Shift+Alt(Option)+0
将当前的调色板保存到桌面
Pyxel Editor 可以创建用于 Pyxel 应用程序的图像和声音。
您可以使用以下命令启动 Pyxel Editor：
pyxel edit PYXEL_RESOURCE_FILE如果指定的 Pyxel 资源文件 (.pyxres) 存在，则会加载它。如果不存在，则会使用指定的名称创建一个新文件。如果省略资源文件，则会创建一个名为 my_resource.pyxres 的新文件。
启动 Pyxel Editor 后，您可以通过将另一个资源文件拖放到 Pyxel Editor 上来切换到该资源文件。
创建的资源文件可以使用 load 函数加载。
Pyxel Editor 有以下编辑模式。
图像编辑器
用于编辑每个图像库中图像的模式。
您可以将图像文件 (PNG/GIF/JPEG) 拖放到图像编辑器中，以将图像加载到当前选择的图像库中。
瓦片地图编辑器
用于编辑将图像库中的图像按瓦片模式排列的瓦片地图的模式。
将 TMX 文件（Tiled Map File）拖放到瓦片地图编辑器上，以将其第 0 层加载到当前选择的瓦片地图中。
声音编辑器
用于编辑用于旋律和音效的声音的模式。
音乐编辑器
用于编辑将声音按播放顺序排列的音乐的模式。
Pyxel 图像和瓦片地图还可以通过以下方法创建：
- 使用
Image.set函数或Tilemap.set函数从字符串列表创建图像 - 使用
Image.load函数加载带有 Pyxel 调色板的图像文件 (PNG/GIF/JPEG)
Pyxel 声音也可以通过以下方法创建：
- 使用
Sound.set函数或Music.set函数从字符串创建声音
有关这些函数的用法，请参阅 API 参考。
Pyxel 支持一种专用的跨平台应用程序分发文件格式（Pyxel 应用程序文件）。
使用 pyxel package 命令创建 Pyxel 应用程序文件 (.pyxapp)：
pyxel package APP_DIR STARTUP_SCRIPT_FILE如果您需要包括资源或其他模块，请将它们放在应用程序目录中。
通过在启动脚本中指定以下格式，可以在运行时显示元数据。除 title 和 author 外的字段都是可选的。
# title: Pyxel Platformer
# author: Takashi Kitao
# desc: A Pyxel platformer example
# site: https://github.com/kitao/pyxel
# license: MIT
# version: 1.0创建的应用程序文件可以使用 pyxel play 命令运行：
pyxel play PYXEL_APP_FILEPyxel 应用程序文件还可以使用 pyxel app2exe 或 pyxel app2html 命令转换为可执行文件或 HTML 文件。
-
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键时，应用程序退出。此功能在 Web 版中不可用。 -
quit()
退出 Pyxel 应用程序。
-
load(filename, [excl_images], [excl_tilemaps], [excl_sounds], [excl_musics])
加载资源文件 (.pyxres)。如果某个选项设置为True，相应的资源将被排除加载。如果资源文件所在位置存在同名的调色板文件 (.pyxpal)，调色板显示颜色也将更新。调色板文件包含 16 进制的显示颜色条目（例如1100ff），每行一个。调色板文件也可以用于更改 Pyxel Editor 中的显示颜色。 -
user_data_dir(vendor_name, app_name)
返回基于vendor_name和app_name创建的用户数据目录。如果目录不存在，它将自动创建。用于存储高分、游戏进度等数据。
例子：print(pyxel.user_data_dir("Takashi Kitao", "Pyxel Shooter"))
-
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，显示鼠标光标。如果visible为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
图像库的列表（Image 类的实例）(0-2)
例子：pyxel.images[0].load(0, 0, "title.png") -
tilemaps
瓦片地图的列表（Tilemap 类的实例）(0-7) -
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)
从 (x1,y1) 到 (x2,y2) 绘制颜色为col的线条。 -
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], [rotate], [scale])
将图像库img(0-2) 中从 (u,v) 开始的大小为 (w,h) 的区域复制到 (x,y)。如果w和/或h设置为负值，该区域将水平和/或垂直翻转。如果指定了colkey，则该颜色将被视为透明色。如果指定了rotate（以度为单位），scale（1.0 = 100%），或两者，应用相应的转换。
bltm(x, y, tm, u, v, w, h, [colkey], [rotate], [scale])
将瓦片地图tm(0-7) 中从 (u,v) 开始的大小为 (w,h) 的区域复制到 (x,y)。如果w和/或h设置为负值，该区域将水平和/或垂直翻转。如果指定了colkey，则该颜色将被视为透明色。如果指定了rotate（以度为单位），scale（1.0 = 100%），或两者，应用相应的转换。瓦片的大小为 8x8 像素，并以(image_tx, image_ty)元组存储在瓦片地图中。
text(x, y, s, col)
在 (x,y) 处以颜色col绘制字符串s。
-
sounds
声音的列表（Sound 类的实例）(0-63)
例子：pyxel.sounds[0].speed = 60 -
musics
音乐的列表（Music 类的实例）(0-7) -
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) 的声音播放位置，作为(sound_no, note_no)的元组返回。当播放停止时，返回None。
-
ceil(x)
返回大于或等于x的最小整数。 -
floor(x)
返回小于或等于x的最大整数。 -
sgn(x)
当x为正数时返回1，当x为0时返回0，当x为负数时返回-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)
设置 Perlin 噪声的种子。 -
noise(x, [y], [z])
返回指定坐标的 Perlin 噪声值。
-
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的像素。
-
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 Map File) 加载layer(0-) 的图层。 -
pget(x, y)
获取 (x,y) 处的瓦片。瓦片表示为(image_tx, image_ty)的元组。 -
pset(x, y, tile)
在 (x,y) 处绘制一个瓦片。瓦片表示为(image_tx, image_ty)的元组。
-
notes
音符 (0-127) 的列表。数值越大，音高越高。音符33对应 'A2'(440Hz)。休止符表示为-1。 -
tones
音色的列表 (0:Triangle / 1:Square / 2:Pulse / 3:Noise) -
volumes
音量的列表 (0-7) -
effects
效果的列表 (0:None / 1:Slide / 2:Vibrato / 3:FadeOut / 4:Half-FadeOut / 5:Quarter-FadeOut) -
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") -
mml(mml_str)
使用 Music Macro Language (MML) 设置相关参数。可用的命令有T(1-900),@(0-3),O(0-4),>,<,Q(1-8),V(0-7),X(0-7),L(1/2/4/8/16/32), 和CDEFGABR+#+-+.~&。有关指令的详细信息，请参阅此页面。
例子：pyxel.sounds[0].mml("t120 @1 o3 q6 l8 x0:12345 c4&c<g16r16>c.<g16 v4 >c.&d16 x0 e2~c2~") -
save(filename, count, [ffmpeg])
创建一个包含重复count次声音的 WAV 文件。如果已安装 FFmpeg 并将ffmpeg设置为True，还会创建一个 MP4 文件。
-
seqs
一个二维列表，包含多个通道的声音 (0-63) -
set(seq0, seq1, seq2, ...)
设置每个通道的声音 (0-63) 列表。如果指定了空列表，则该通道不会用于播放。
例子：pyxel.musics[0].set([0, 1], [], [3]) -
save(filename, count, [ffmpeg])
创建一个包含重复count次音乐的 WAV 文件。如果已安装 FFmpeg 并将ffmpeg设置为True，还会创建一个 MP4 文件。
Pyxel 包含一个“高级 API”，该 API 在本参考中未提及，因为它可能会让用户感到困惑或需要专业知识才能使用。
如果您对自己的技能充满信心，可以尝试使用这个作为指南，创造惊人的作品！
使用 问题跟踪器 提交 bug 报告和功能或增强请求。在提交新问题之前，请确保没有类似的开放问题。
任何手动测试代码并在 问题跟踪器 中报告 bug 或增强建议的人都非常欢迎！
补丁和修复以拉取请求 (PR) 的形式接受。请确保拉取请求所针对的问题在问题跟踪器中是开放的。
提交拉取请求意味着您同意根据 MIT 许可证 授权您的贡献。
Pyxel 采用 MIT 许可证。它可以在专有软件中重复使用，前提是所有软件或其重要部分的副本都包含 MIT 许可证条款和版权声明的副本。
Pyxel 在 GitHub Sponsors 上寻找赞助者。请考虑赞助 Pyxel，以支持其持续维护和功能开发。作为一种福利，赞助者可以直接咨询 Pyxel 开发者。有关更多详细信息，请访问 此页面。