Skip to content

Latest commit

 

History

History
755 lines (541 loc) · 27.2 KB

README.cn.md

File metadata and controls

755 lines (541 loc) · 27.2 KB
Raw

Downloads GitHub Repo stars GitHub forks GitHub Sponsors

ko-fi

[ 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 个音乐轨道可以组合任意声音
  • 支持键盘、鼠标和游戏手柄输入
  • 图像和声音编辑工具
  • 用户可扩展的颜色、通道和库

色彩调色板

如何安装

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 后，要升级 Pyxel，请运行 pipx upgrade pyxel。

Linux

在安装 SDL2 包（对于 Ubuntu 为 libsdl2-dev）、Python3（版本 3.8 或更高）和 python3-pip 后，运行以下命令：

sudo pip3 install -U pyxel

如果之前的命令失败，请按照 Makefile 中的说明考虑从源代码构建 Pyxel。

Web

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 射击游戏与屏幕切换 演示 代码
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）拖放到瓦片地图编辑器上，以加载其层次结构，绘制顺序与当前选择的瓦片地图编号相对应。

声音编辑器

用于编辑用于旋律和音效的声音的模式。

音乐编辑器

用于编辑将声音按播放顺序排列的音乐的模式。

其他资源创建方法

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_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 键时，应用程序退出。此功能在 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 像素，并以 (tile_x, tile_y) 元组存储在瓦片地图中。

  • 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 噪声值。

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 Map File) 加载绘制顺序为 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: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")

Music 类

  • seqs
    一个二维列表，包含多个通道的声音 (0-63)

  • set(seq0, seq1, seq2, ...)
    设置每个通道的声音 (0-63) 列表。如果指定了空列表，则该通道不会用于播放。
    例子：pyxel.musics[0].set([0, 1], [], [3])

高级 API

Pyxel 包含一个“高级 API”，该 API 在本参考中未提及，因为它可能会让用户感到困惑或需要专业知识才能使用。

如果您对自己的技能充满信心，可以尝试使用这个作为指南，创造惊人的作品！

如何贡献

提交问题

使用 问题跟踪器 提交 bug 报告和功能或增强请求。在提交新问题之前，请确保没有类似的开放问题。

功能测试

任何手动测试代码并在 问题跟踪器 中报告 bug 或增强建议的人都非常欢迎！

提交拉取请求

补丁和修复以拉取请求 (PR) 的形式接受。请确保拉取请求所针对的问题在问题跟踪器中是开放的。

提交拉取请求意味着您同意根据 MIT 许可证 授权您的贡献。

其他信息

许可证

Pyxel 采用 MIT 许可证。它可以在专有软件中重复使用，前提是所有软件或其重要部分的副本都包含 MIT 许可证条款和版权声明的副本。

征募赞助者

Pyxel 在 GitHub Sponsors 上寻找赞助者。请考虑赞助 Pyxel，以支持其持续维护和功能开发。作为一种福利，赞助者可以直接咨询 Pyxel 开发者。有关更多详细信息，请访问 此页面。