docs/editor-manual.md
This document was auto-generated from the Pyxel Editor Manual web page, which also offers multilingual support.
Pyxel Editor is a built-in resource editing tool for Pyxel. It consists of four editors, which can be switched using the editor buttons at the top of the screen.
Launch Pyxel Editor with the following command:
pyxel edit [PYXEL_RESOURCE_FILE]
If the specified Pyxel resource file (.pyxres) exists, it will be loaded. If it does not exist, a new file with the specified name will be created. If the filename is omitted, my_resource.pyxres will be created.
Operations common to all editors.
The menu bar at the top of the screen contains four editor switching buttons, Undo/Redo buttons, and a Save button. The help message area on the right displays context-sensitive information based on the cursor position.
| Shortcut | Action |
|---|---|
| Alt(Option)+Left/Right | Switch between editor types |
| Shift+Ctrl(Cmd)+C | Copy the entire editing target |
| Shift+Ctrl(Cmd)+X | Cut the entire editing target (copy and clear) |
| Shift+Ctrl(Cmd)+V | Paste the copied target |
| Shift+Click ([+]/[-] buttons) | Change number or value in increments of ±10 |
The created resource file can be loaded and used in a Pyxel application with the pyxel.load() function.
While the editor is running, you can drag and drop another .pyxres file onto the window to load its contents. This operation overwrites all current edits, so please be careful if you have unsaved changes.
A mode for editing images in each image bank. You can create pixel art for sprites and tiles.
The editing area selected in the image bank view is displayed magnified. Click and drag with the mouse to draw.
| Shortcut | Action |
|---|---|
| Right Click | Pick the color at the cursor position (color pick) |
| Right Drag | Pan the view |
A thumbnail view of the entire image bank. The white frame indicates the current editing area.
| Shortcut | Action |
|---|---|
| Arrow Keys | Move the editing area (white frame) |
| Click | Move the editing area to the clicked position |
| Right Drag | Pan the view |
Select a tool for drawing.
The following shortcut keys are available while using the selection tool.
| Shortcut | Action |
|---|---|
| Ctrl(Cmd)+A | Select the entire canvas |
| Ctrl(Cmd)+C | Copy the selection |
| Ctrl(Cmd)+X | Cut the selection (copy and clear) |
| Ctrl(Cmd)+V | Paste the copied area |
| H | Flip the selection horizontally |
| V | Flip the selection vertically |
Select a drawing color from the 16-color palette.
| Shortcut | Action |
|---|---|
| 1–8 | Select colors 0–7 |
| Shift+1–8 | Select colors 8–15 |
Switch the target image bank (0–2).
Drag and drop an image file such as PNG or JPG onto the Image Editor to load the image at the editing area position. The original image colors are automatically converted to Pyxel's color palette, and any parts exceeding the image bank boundaries are clipped.
A mode for arranging image bank images as tile patterns and editing tilemaps.
The editing area selected in the tilemap view is displayed magnified. Place tile images selected in the tile image view. Drawing tools and selection shortcuts are shared with the Image Editor. Note that all cells default to tile (0,0), so it is recommended to keep image bank position (0,0) empty.
| Shortcut | Action |
|---|---|
| Right Click | Pick the tile at the cursor position (tile pick) |
| Right Drag | Pan the view |
A thumbnail view of the entire tilemap. The white frame indicates the current editing area.
| Shortcut | Action |
|---|---|
| Arrow Keys | Move the editing area (white frame) |
| Click/Drag | Move the editing area to the clicked position |
Displays the referenced image bank. Select tile images with the white frame.
| Shortcut | Action |
|---|---|
| Shift+Arrow Keys | Move the selection |
| Drag | Select multiple tiles in a rectangle |
| Right Drag | Pan the view |
Switch the target tilemap (0–7).
Switch the image bank (0–2) referenced for tile images.
Select a tool for drawing.
When you draw with multiple tile images selected by dragging in the tile image view, the selected tiles are placed as a repeating pattern. For example, if you select two tiles vertically and draw with the pen, the two tiles are placed alternately in a repeating pattern. The same applies when selecting multiple tiles both horizontally and vertically. The drawing start position corresponds to the top-left of the selection.
Drag and drop a TMX file created with Tiled Map Editor (Tiled) onto the Tilemap Editor to load the contents of layer 0 at the editing area position.
A mode for editing sounds used for melodies and sound effects.
Switch the target sound (0–63).
Sets the playback duration per note. This is a common setting for all notes, specified in the range 1–99. Smaller values result in faster playback (1 speed unit = 1/120 second; e.g., speed 60 = 0.5 seconds per note). For sound effects, 1–9 is typical; for melodies, 10 or higher is recommended.
Click to input note pitch. Red squares represent notes, blue squares represent rests. During piano roll editing, a blue cursor is displayed; during property area editing, a different cursor shape appears. Notes are played from left to right, and rests are automatically inserted in empty positions. Clicking an already-filled position overwrites it. Dragging inputs notes continuously with linear interpolation.
| Shortcut | Action |
|---|---|
| Up/Down | Switch between piano roll and property area |
| Left/Right | Move the cursor |
| Delete(fn+delete) | Delete the note at the current position |
| Backspace(delete) | Delete the note before the current position |
| Shift+Space | Play from the cursor position |
| Ctrl(Cmd)+A | Select the entire range |
| Shift+Left/Right | Start range selection |
| Shortcut | Action |
|---|---|
| Ctrl(Cmd)+C | Copy the selection |
| Ctrl(Cmd)+X | Cut the selection (copy and clear) |
| Ctrl(Cmd)+V | Paste the copied area |
| Ctrl(Cmd)+U | Raise the pitch of the selection by 1 |
| Ctrl(Cmd)+D | Lower the pitch of the selection by 1 |
Displays the starting octave (0–3) for keyboard input. The keyboard covers two octaves from the selected octave.
| Shortcut | Action |
|---|---|
| PageUp(fn+Up) | Raise the octave by 1 |
| PageDown(fn+Down) | Lower the octave by 1 |
You can input notes using the PC keyboard. The upper row (QWE row + number row) and the lower row (ZXC row + ASD row) each correspond to one octave of piano keys, covering two octaves simultaneously. White keys are assigned to natural notes and gray keys to sharps. Select the starting octave (0–3) with the octave bar.
Upper Octave (QWE row + number row)
| Note | Key |
|---|---|
| C | Q |
| C# | 2 |
| D | W |
| D# | 3 |
| E | E |
| F | R |
| F# | 5 |
| G | T |
| G# | 6 |
| A | Y |
| A# | 7 |
| B | U |
Lower Octave (ZXC row + ASD row)
| Note | Key |
|---|---|
| C | Z |
| C# | S |
| D | X |
| D# | D |
| E | C |
| F | V |
| F# | G |
| G | B |
| G# | H |
| A | N |
| A# | J |
| B | M |
| Rest | A |
| Shortcut | Action |
|---|---|
| Keyboard Key → Enter | Input the pressed keyboard note into the piano roll |
| 1 | Cycle the preview tone for keyboard input (4 types) |
Set the tone (TON), volume (VOL), and effect (EFX) for each note. Press the ↓ key or click the TON row during piano roll editing to move to the property area. Cursor movement, range selection, copy & paste, and other operations are shared with the piano roll. Press a key on each row to input the corresponding value. For example, pressing P on the TON row sets Pulse. To change the tone partway through, set the value for all notes from the desired position onward. The same applies to VOL and EFX.
With the cursor on the TON row, press the following keys to set the tone. The default when not set is T (Triangle).
| Key | Name | Description |
|---|---|---|
T | Triangle | Triangle wave. Soft and gentle tone. Similar to a flute |
S | Square | Square wave. Electronic and clear tone. Similar to a clarinet or organ |
P | Pulse | Pulse wave. Bright and flashy tone. Similar to a trumpet |
N | Noise | Noise. Unpitched sound. Suitable for percussion and explosion effects |
With the cursor on the VOL row, press number keys 0–7 to set the volume (0 = silent, 7 = maximum). The default when not set is 7. Using maximum volume on multiple channels simultaneously may result in excessive loudness.
With the cursor on the EFX row, press the following keys to set the effect. The default when not set is N (None).
| Key | Name | Description |
|---|---|---|
N | None | No effect |
S | Slide | Smoothly glide the pitch from the previous note |
V | Vibrato | Periodically oscillate the pitch |
F | FadeOut | Gradually decrease the volume over the entire note. Also used to separate notes of the same pitch |
H | Half-FadeOut | Gradually decrease the volume in the second half of the note. Longer sustain than F |
Q | Quarter-FadeOut | Gradually decrease the volume in the last quarter of the note. Longer sustain than H |
A mode for arranging sounds in playback order to compose music tracks.
Switch the target music (0–7).
Place sound numbers in playback order across four channels (CH0–CH3). Copy and paste between channels is also supported.
| Shortcut | Action |
|---|---|
| Up/Down | Switch the editing channel |
| Left/Right | Move the editing cursor |
| Delete(fn+delete) | Delete the sound at the current position |
| Backspace(delete) | Delete the sound before the current position |
| Shift+Space | Play from the cursor position |
| Ctrl(Cmd)+A | Select the entire range of the current channel |
| Shift+Arrow Keys | Select a range within the channel |
| Ctrl(Cmd)+C | Copy the selection |
| Ctrl(Cmd)+X | Cut the selection (copy and clear) |
| Ctrl(Cmd)+V | Paste the selection (also across channels) |
| Ctrl(Cmd)+U | Increment the sound number of the selection by 1 |
| Ctrl(Cmd)+D | Decrement the sound number of the selection by 1 |
Buttons for inserting sound numbers (0–63). Pressing a button inserts the sound number at the editing cursor position. Created sounds are shown in blue, uncreated ones in gray. Hovering over a button previews the sound.