- 游戏开发
【免费下载链接】pyxel
A retro game engine for Python
Pyxel Editor 是 Pyxel（A retro game engine for Python）内置的资源编辑工具，覆盖精灵图、瓦片地图、音效与 BGM 的完整制作流程。本文以 docs/editor-manual.md 官方手册为主体，结合仓库内 CLI 入口、编辑器实现与 Rust 核心常量，系统讲解pyxel edit的启动方式、四个编辑器的全部规格与快捷键，并补充源码级的运行原理，帮助你直接上手制作可被pyxel.load()加载的.pyxres资源文件。
概览：一个工具，四种编辑器
Pyxel Editor 是一个内置的图形化资源编辑工具，由四个独立编辑器组成，可通过屏幕顶部的编辑器切换按钮随时切换：
- 图像编辑器（Image Editor）：编辑用于精灵与瓦片贴图的图像库（image bank）
- 瓦片地图编辑器（Tilemap Editor）：将图像库中的图像作为瓦片排列，拼出地图
- 声音编辑器（Sound Editor）：编辑用于音效与旋律的声音（sound）
- 音乐编辑器（Music Editor）：按播放顺序排列声音，编曲成 BGM 等音乐（music）
从源码结构看，这四种编辑器分别由 python/pyxel/editor/image_editor.py、python/pyxel/editor/tilemap_editor.py、python/pyxel/editor/sound_editor.py 与 python/pyxel/editor/music_editor.py 实现，并在 python/pyxel/editor/app.py 中以_editors列表统一注册、按索引切换，编辑器窗口尺寸固定为 240×180（见 python/pyxel/editor/settings.py）。
快速上手：启动 Pyxel Editor
在终端中执行以下命令即可启动编辑器：
pyxel edit [PYXEL_RESOURCE_FILE]行为规则如下：
- 若指定的 Pyxel 资源文件（
.pyxres）已存在，则加载该文件内容； - 若不存在，则以指定名称创建新文件；
- 若省略文件名，则创建默认文件
my_resource.pyxres。
命令行入口的实现在 python/pyxel/cli.py：未提供文件名时自动补全为my_resource，并通过_complete_extension自动追加.pyxres扩展名，最终调用pyxel.editor.App(resource_file, starting_editor)启动编辑器；编辑器默认以图像编辑器（starting_editor="image"）打开。随后 python/pyxel/editor/app.py 会初始化 240×180 的 Pyxel 窗口、开启鼠标支持，并在资源文件存在时调用pyxel.load()，否则调用pyxel.load_pal()建立默认调色板。
通用操作
以下操作在所有编辑器中通用。
菜单栏
屏幕顶部的菜单栏包含四个编辑器切换按钮、撤销/重做按钮与保存按钮。右侧的帮助消息区域会根据光标位置显示上下文相关的操作提示（例如悬停撤销按钮时提示UNDO:CTRL+Z，对应实现见 python/pyxel/editor/app.py）。
| 按钮 | 功能 | 快捷键 |
|---|---|---|
| 图像编辑器 | 切换到图像编辑器 | — |
| 瓦片地图编辑器 | 切换到瓦片地图编辑器 | — |
| 声音编辑器 | 切换到声音编辑器 | — |
| 音乐编辑器 | 切换到音乐编辑器 | — |
| 撤销 | 撤销上一步操作 | Ctrl(Cmd)+Z |
| 重做 | 重做被撤销的操作 | Ctrl(Cmd)+Y |
| 保存 | 保存资源文件 | Ctrl(Cmd)+S |
其他快捷键
| 快捷键 | 作用 |
|---|---|
| Alt(Option)+Left/Right | 切换编辑器类型 |
| Shift+Ctrl(Cmd)+C | 复制整个编辑目标 |
| Shift+Ctrl(Cmd)+X | 剪切整个编辑目标（复制并清空） |
| Shift+Ctrl(Cmd)+V | 粘贴复制的目标 |
| Shift+点击（[+]/[-] 按钮） | 数值按 ±10 的增量变化 |
在程序中使用编辑器产物
创建好的资源文件在 Pyxel 应用中通过pyxel.load()加载使用：
import pyxel pyxel.init(256, 256) pyxel.load("my_resource.pyxres") # 加载编辑器保存的资源 pyxel.run(...)pyxel.load()的完整签名见 python/pyxel/init.pyi，可通过exclude_images、exclude_tilemaps、exclude_sounds、exclude_musics四个开关按需排除部分资源；若同目录存在同名.pyxpal调色板文件，也会一并更新显示颜色。保存则使用pyxel.save()（python/pyxel/init.pyi），两者在 Rust 侧的底层实现位于 crates/pyxel-binding/src/resource_wrapper.rs。
切换资源文件
编辑器运行期间，可拖拽另一个.pyxres文件到窗口以加载其内容。注意：该操作会覆盖当前所有编辑内容，若有未保存的修改请提前保存。
图像编辑器（Image Editor）
图像编辑器用于编辑每个图像库中的图像，是制作像素精灵与瓦片贴图的核心模块。
规格
- 图像库（Image Banks）：0–2，共 3 个
- 尺寸：每个 256×256 像素
- 坐标系：原点 (0,0) 位于左上角，X 轴向右、Y 轴向下
上述数值与 Rust 核心常量一一对应：NUM_IMAGES=3、IMAGE_SIZE=256（见 crates/pyxel-core/src/settings.rs），这意味着一个图像库恰好可容纳 32×32 个 8×8 瓦片，是设计瓦片素材时的重要参照。
界面布局
图像画布（Image Canvas）
显示图像库视图中选中区域的放大视图，鼠标点击并拖拽即可绘制像素。
| 操作 | 作用 |
|---|---|
| 右键点击 | 取色（拾取光标位置的像素颜色） |
| 右键拖拽 | 平移视图 |
图像库视图（Image Bank View）
整个图像库的缩略图，白色边框标示当前编辑区域。
| 操作 | 作用 |
|---|---|
| 方向键 | 移动编辑区域（白色边框） |
| 点击 | 将编辑区域移动到点击位置 |
| 右键拖拽 | 平移视图 |
工具按钮
选择绘制工具，各工具的默认快捷键如下：
| 工具 | 快捷键 | 说明 |
|---|---|---|
| 选区（Select） | S | 选择矩形区域 |
| 铅笔（Pencil） | P | 自由绘制；按住 Shift 绘制直线 |
| 空心矩形（Rect Outline） | R | 绘制矩形边框；按住 Shift 绘制正方形 |
| 实心矩形（Rect Filled） | Shift+R | 绘制实心矩形；按住 Shift 绘制正方形 |
| 空心椭圆（Ellipse Outline） | C | 绘制椭圆边框；按住 Shift 绘制圆形 |
| 实心椭圆（Ellipse Filled） | Shift+C | 绘制实心椭圆；按住 Shift 绘制圆形 |
| 油漆桶（Bucket） | B | 填充同色连通区域 |
选区工具快捷键
在使用选区工具时，以下快捷键可用：
| 快捷键 | 作用 |
|---|---|
| Ctrl(Cmd)+A | 全选整个画布 |
| Ctrl(Cmd)+C | 复制选区 |
| Ctrl(Cmd)+X | 剪切选区（复制并清空） |
| Ctrl(Cmd)+V | 粘贴复制的区域 |
| H | 水平翻转选区 |
| V | 垂直翻转选区 |
调色板
从 16 色调色板中选择绘制颜色。
| 快捷键 | 作用 |
|---|---|
| 1–8 | 选择颜色 0–7 |
| Shift+1–8 | 选择颜色 8–15 |
这 16 色的默认色值定义在 crates/pyxel-core/src/settings.rs 的DEFAULT_COLORS中，从索引 0 的黑色（0x000000）到索引 15 的桃色（0xedc7b0），并对应COLOR_NAVY、COLOR_PURPLE等命名常量（crates/pyxel-core/src/settings.rs）。
图像库编号（Bank Number）
切换目标图像库（0–2）。
加载外部图片
将 PNG、JPG 等图片文件拖拽到图像编辑器，即可在编辑区域位置加载该图片。原图颜色会自动转换为 Pyxel 调色板中的颜色，超出图像库边界的部分会被裁剪。
瓦片地图编辑器（Tilemap Editor）
瓦片地图编辑器用于将图像库中的图像作为瓦片图案排列，并编辑瓦片地图。
规格
- 瓦片地图（Tilemaps）：0–7，共 8 个
- 尺寸：每个 256×256 瓦片
- 瓦片图像：图像库中的 8×8 像素区域
- 引用图像库：每个瓦片地图引用一个图像库
对应核心常量：NUM_TILEMAPS=8、TILEMAP_SIZE=256、TILE_SIZE=8（crates/pyxel-core/src/settings.rs）。256×256 的瓦片地图配合 8×8 瓦片，意味着单张地图最多可编排 1024×1024 像素的内容。
界面布局
瓦片地图画布（Tilemap Canvas）
显示瓦片地图视图中选中区域的放大视图，在此放置瓦片图像视图中选中的瓦片。绘制工具与选区快捷键与图像编辑器共用。注意：所有格子默认填充瓦片 (0,0)，因此建议保持图像库 (0,0) 位置为空，以免地图初始状态出现意外内容。
| 操作 | 作用 |
|---|---|
| 右键点击 | 拾取光标位置的瓦片 |
| 右键拖拽 | 平移视图 |
瓦片地图视图（Tilemap View）
整个瓦片地图的缩略图，白色边框标示当前编辑区域。
| 操作 | 作用 |
|---|---|
| 方向键 | 移动编辑区域（白色边框） |
| 点击/拖拽 | 将编辑区域移动到点击位置 |
瓦片图像视图（Tile Image View）
显示被引用的图像库，通过白色边框选择瓦片图像。
| 操作 | 作用 |
|---|---|
| Shift+方向键 | 移动选区 |
| 拖拽 | 矩形框选多个瓦片 |
| 右键拖拽 | 平移视图 |
瓦片地图编号
切换目标瓦片地图（0–7）。
引用图像库编号（Ref. Image Bank Number）
切换用于瓦片图像的图像库（0–2）。
工具按钮
与图像编辑器相同的七种工具（选区 S / 铅笔 P / 空心矩形 R / 实心矩形 Shift+R / 空心椭圆 C / 实心椭圆 Shift+C / 油漆桶 B），用于在瓦片地图上绘制。
放置多个瓦片
在瓦片图像视图中拖拽选中多个瓦片后绘制时，选中的瓦片会作为循环图案被放置。例如纵向选中两个瓦片后用铅笔绘制，两个瓦片会交替循环出现；横向与纵向同时多选时同理。绘制起始位置对应所选区域的左上角。
加载 TMX 文件
将 Tiled Map Editor 创建的TMX 文件拖拽到瓦片地图编辑器，即可在编辑区域位置加载第 0 层（layer 0）的内容。仓库中的示例资源 python/pyxel/examples/assets/urban_rpg.tmx 搭配 python/pyxel/examples/15_tiled_map_file.py 演示了 TMX 的典型用法。
声音编辑器（Sound Editor）
声音编辑器用于编辑旋律与音效（sound），是 Pyxel 复古音频系统的核心入口。
规格
- 声音（Sounds）：0–63，共 64 个
- 音高范围：C0–B4
- 最大长度：48 个音符
- 复音数：单音（一个音符或休止符）
- 每个音符的设置：音色（Tone）、音量（Volume）、效果（Effect）
数值对应关系：NUM_SOUNDS=64（crates/pyxel-core/src/settings.rs）；最大 48 个音符定义于编辑器常量MAX_SOUND_LENGTH=48（python/pyxel/editor/settings.py）。
界面布局
声音编号（Sound Number）
切换目标声音（0–63），实现为NumberPicker，范围取自pyxel.NUM_SOUNDS - 1（python/pyxel/editor/sound_editor.py）。
播放速度（Playback Speed）
设置每个音符的播放时长，对全部音符统一生效，取值范围1–99。数值越小播放越快：1 个速度单位 = 1/120 秒，例如速度 60 表示每音符 0.5 秒。音效通常用 1–9，旋律建议 10 及以上。该换算依据核心常量SOUND_TICKS_PER_SECOND=120（crates/pyxel-core/src/settings.rs），速度值即音符占用的 tick 数。
播放 / 停止 / 循环
| 按钮 | 快捷键 | 作用 |
|---|---|---|
| 播放 | Space | 播放声音 |
| 停止 | Space | 播放中再次按 Space 停止 |
| 循环 | L | 切换循环播放 |
钢琴卷帘（Piano Roll）
点击即可输入音符音高。红色方块代表音符，蓝色方块代表休止符。钢琴卷帘编辑时显示蓝色光标，属性区编辑时显示另一种光标。音符从左到右依次播放，空位自动插入休止符；点击已有位置可覆盖改写；拖拽可连续输入音符并自动线性插值（滑音式过渡）。
| 操作 | 作用 |
|---|---|
| Up/Down | 在钢琴卷帘与属性区之间切换 |
| Left/Right | 移动光标 |
| Delete(fn+delete) | 删除当前位置的音符 |
| Backspace(delete) | 删除当前位置之前的音符 |
| Shift+Space | 从光标位置开始播放 |
| Ctrl(Cmd)+A | 全选整个范围 |
| Shift+Left/Right | 开始范围选择 |
范围选择
| 快捷键 | 作用 |
|---|---|
| Ctrl(Cmd)+C | 复制选区 |
| Ctrl(Cmd)+X | 剪切选区（复制并清空） |
| Ctrl(Cmd)+V | 粘贴复制的区域 |
| Ctrl(Cmd)+U | 将选区音高整体升高 1 |
| Ctrl(Cmd)+D | 将选区音高整体降低 1 |
八度栏（Octave Bar）
显示键盘输入的起始八度（0–3），键盘从所选八度起覆盖两个八度。
| 快捷键 | 作用 |
|---|---|
| PageUp(fn+Up) | 八度 +1 |
| PageDown(fn+Down) | 八度 -1 |
键盘输入
可使用 PC 键盘直接输入音符。上行（QWE 行 + 数字行）与下行（ZXC 行 + ASD 行）各对应一个八度的钢琴键，共覆盖两个八度；白键对应自然音，灰键对应升半音。用八度栏选择起始八度（0–3）。
上行八度（QWE 行 + 数字行）
| 音符 | 按键 |
|---|---|
| C | Q |
| C# | 2 |
| D | W |
| D# | 3 |
| E | E |
| F | R |
| F# | 5 |
| G | T |
| G# | 6 |
| A | Y |
| A# | 7 |
| B | U |
下行八度（ZXC 行 + ASD 行）
| 音符 | 按键 |
|---|---|
| C | Z |
| C# | S |
| D | X |
| D# | D |
| E | C |
| F | V |
| F# | G |
| G | B |
| G# | H |
| A | N |
| A# | J |
| B | M |
| 休止符 | A |
|---|
| 快捷键 | 作用 |
|---|---|
| 键盘按键 → Enter | 将按下的键盘音符输入到钢琴卷帘 |
| 1 | 循环切换键盘输入的预览音色（共 4 种） |
属性区（TON / VOL / EFX）
为每个音符设置音色（TON）、音量（VOL）与效果（EFX）。在钢琴卷帘编辑时按↓键或点击 TON 行即可进入属性区。光标移动、范围选择、复制粘贴等操作与钢琴卷帘共用。在对应行上按键即可输入该行的值，例如在 TON 行按P即设置 Pulse 音色。要中途改变某个属性，需从目标位置起为所有音符设置该值，VOL 与 EFX 同理。
音色（Tone）
光标位于 TON 行时，按以下键设置音色；未设置时默认 T（Triangle）。
| 按键 | 名称 | 说明 |
|---|---|---|
T | Triangle | 三角波，柔和温和的音色，类似长笛 |
S | Square | 方波，电子感清晰音色，类似单簧管或风琴 |
P | Pulse | 脉冲波，明亮华丽的音色，类似小号 |
N | Noise | 噪声，无音高，适合打击乐与爆炸音效 |
四种音色对应核心常量TONE_TRIANGLE（0）、TONE_SQUARE（1）、TONE_PULSE（2）、TONE_NOISE（3），其波形采样数据定义于 crates/pyxel-core/src/settings.rs 与DEFAULT_TONE_*系列常量（crates/pyxel-core/src/settings.rs），三角波采用 32 点 wavetable，方波与脉冲波为不同占空比的 wavetable，噪声则使用长周期噪声模式。
音量（Volume）
光标位于 VOL 行时，按数字键0–7设置音量（0 = 静音，7 = 最大）；默认值为 7。注意：多个声道同时使用最大音量可能导致整体响度过大。核心侧MAX_VOLUME=7与默认声道增益DEFAULT_CHANNEL_GAIN=0.125见 crates/pyxel-core/src/settings.rs。
效果（Effect）
光标位于 EFX 行时，按以下键设置效果；默认值为 N（None）。
| 按键 | 名称 | 说明 |
|---|---|---|
N | None | 无效果 |
S | Slide | 从前一音符平滑滑音到本音符 |
V | Vibrato | 周期性振荡音高（核心实现为 6Hz 周期、±25 音分深度，见VIBRATO_PERIOD_TICKS与VIBRATO_DEPTH_CENTS，crates/pyxel-core/src/settings.rs） |
F | FadeOut | 整个音符期间音量渐减；也用于区分同音高的连续音符 |
H | Half-FadeOut | 音符后半段音量渐减，比 F 更长的延音 |
Q | Quarter-FadeOut | 音符最后四分之一音量渐减，比 H 更长的延音 |
六种效果对应核心常量EFFECT_NONE（0）至EFFECT_QUARTER_FADEOUT（5），见 crates/pyxel-core/src/settings.rs。
音乐编辑器（Music Editor）
音乐编辑器用于按播放顺序排列声音，编曲成音乐轨道。
规格
- 音乐轨道（Music Tracks）：0–7，共 8 个
- 声道（Channels）：4
- 每声道最大声音数：32
对应核心常量NUM_MUSICS=8、NUM_CHANNELS=4（crates/pyxel-core/src/settings.rs），每声道最大 32 个声音槽由编辑器常量MAX_MUSIC_LENGTH=32定义（python/pyxel/editor/settings.py）。
界面布局
音乐编号（Music Number）
切换目标音乐轨道（0–7）。
播放 / 停止 / 循环
| 按钮 | 快捷键 | 作用 |
|---|---|---|
| 播放 | Space | 播放音乐 |
| 停止 | Space | 播放中再次按 Space 停止 |
| 循环 | L | 切换循环播放 |
序列编辑器（CH0–CH3）
在四个声道（CH0–CH3）中按播放顺序放置声音编号，支持跨声道复制粘贴。源码中四个声道由四个MusicField实例并排构成（python/pyxel/editor/music_editor.py），其底层数据为每个音乐轨道内的seqs序列列表。
| 快捷键 | 作用 |
|---|---|
| Up/Down | 切换编辑声道 |
| Left/Right | 移动编辑光标 |
| Delete(fn+delete) | 删除当前位置的声音 |
| Backspace(delete) | 删除当前位置之前的声音 |
| Shift+Space | 从光标位置开始播放 |
| Ctrl(Cmd)+A | 全选当前声道的整个范围 |
| Shift+方向键 | 在声道内选择范围 |
| Ctrl(Cmd)+C | 复制选区 |
| Ctrl(Cmd)+X | 剪切选区（复制并清空） |
| Ctrl(Cmd)+V | 粘贴选区（也支持跨声道） |
| Ctrl(Cmd)+U | 选区声音编号整体 +1 |
| Ctrl(Cmd)+D | 选区声音编号整体 -1 |
声音按钮（0–63）
用于插入声音编号（0–63）的按钮。点击按钮即把该声音编号插入到编辑光标位置。已创建的声音显示为蓝色，未创建的显示为灰色；鼠标悬停在按钮上可预览该声音。
测试与验证
仓库为编辑器提供了自动化测试保障： python/tests/test_editor.py 通过参数化用例逐帧截屏对比（compare_screenshots）验证图像、瓦片地图、声音、音乐各编辑器的渲染结果，参考图存放于 python/tests/references/editor（如editor_image_f1.png、editor_sound_fedit.png等），同时覆盖了按钮初始范围、数值钳制与自定义调色板映射等边界行为。这意味着本文介绍的全部快捷键与绘制行为均有可回归验证的实现支撑。
从编辑到运行：完整工作流
综合全文，一个典型的 Pyxel 资源制作与使用流程为：
- 运行
pyxel edit my_resource.pyxres打开编辑器（省略文件名则创建my_resource.pyxres）； - 在图像编辑器中绘制精灵与瓦片素材（16 色、256×256、3 个图像库）；
- 在瓦片地图编辑器中编排 8 个瓦片地图（每图 256×256 瓦片、引用一个图像库）；
- 在声音编辑器中创作最多 64 个声音（48 音符上限、T/S/P/N 四种音色、六种效果）；
- 在音乐编辑器中用 4 个声道编排最多 8 首音乐（每声道 32 个声音槽）；
- 按 Ctrl(Cmd)+S 保存，或在运行期间拖入新
.pyxres切换资源； - 在应用代码中调用
pyxel.load("my_resource.pyxres")加载，通过pyxel.images、pyxel.tilemaps、pyxel.sounds、pyxel.musics系列 API 在游戏中使用。
通过掌握上述规格与快捷键，你可以在不编写任何资源生成代码的情况下，纯可视化地完成 Pyxel 游戏所需的全部美术与音频资产。
- 游戏开发
【免费下载链接】pyxel
A retro game engine for Python
相关推荐
OpenSCAD 编辑器代码模板（Editor Templates）完全指南：原理、内置模板与自定义方法
OpenSCAD 编辑器代码模板（Editor Templates）完全指南：原理、内置模板与自定义方法 导读 OpenSCAD 是一款面向程序员的参数化 3D
图形学3D建模桌面应用ModelScope NLP 训练器模块深度解析：四大 Trainer 的实现原理与实战配置指南
ModelScope NLP 训练器模块深度解析：四大 Trainer 的实现原理与实战配置指南 ModelScope（Model as a Service）在
人工智能大模型微调模型评测预训练Automatisch Google Tasks 动作详解：四个内置任务操作的使用与实现原理
Automatisch Google Tasks 动作详解：四个内置任务操作的使用与实现原理 本文围绕 Automatisch 开源自动化平台内置的 Googl
工作流自动化后端前端低代码任务调度
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
