Editing Tools
Press ESC to toggle between console and editor.<br> Click editing mode tabs at top right to
switch or press ALT+LEFT/RIGHT.
Code Editor
Hold shift to select (or click and drag with mouse)
CTRL-X, C, V to cut copy or paste selected
CTRL-Z, Y to undo, redo
CTRL-F to search for text in the current tab
CTRL-G to repeat the last search again
CTRL-L to jump to a line number
CTRL-UP, DOWN to jump to start or end
ALT-UP, DOWN to navigate to the previous, next function
CTRL-LEFT, RIGHT to jump by word
CTRL-W,E to jump to start or end of current line
CTRL-D to duplicate current line
TAB to indent a selection (shift to un-indent)
CTRL-B to comment / uncomment selected block
CTRL-U to get help on the keyword under the cursor
To enter special characters that represent buttons (and other glyphs), use SHIFT-L,R,U,D,O,X
There are 3 additional font entry modes that can be toggled:
CTRL_J Hiragana // type romaji equivalents (ka, ki, ku..)
CTRL-K Katakana // + shift-0..9 for extra symbols
CTRL-P Puny font // hold shift for the standard font
By default, puny font characters are encoded as unicode replacements when copying/pasting,
and both upper and lower case ASCII characters are pasted as regular PICO-8 characters. To
copy/paste puny characters as uppercase ASCII, make sure puny mode (CTRL-P) is on.
Click the [+] button at the top to add a new tab. Navigate tabs by left-clicking, or with
CTRL-TAB, SHIFT-CTRL-TAB. To remove the last tab, delete any contents and then moving off
it (CTRL-A, DEL, CTRL-TAB)
When running a cart, a single program is generated by concatenating all tabs in order.
The number of code tokens is shown at the bottom right. One program can have a maximum of
8192 tokens. Each token is a word (e.g. variable name) or operator. Pairs of brackets, and
strings each count as 1 token. commas, periods, LOCALs, semi-colons, ENDs, and comments are
not counted.
Right click to toggle through other stats (character count, compressed size). If a limit is
reached, a warning light will flash. This can be disabled by right-clicking.
Sprite Editor
The sprite editor is designed to be used both for sprite-wise editing and for freeform
pixel-level editing. The sprite navigator at the bottom of the screen provides an 8x8
sprite-wise view into the sprite sheet, but it is possible to use freeform tools (pan, select)
when dealing with larger or oddly sized areas.
Click and drag on the sprite to plot pixels, or use RMB to select the colour under the
cursor.
All operations apply only to the visible area, or the section if there is one.
Hold CTRL to search and replace a colour.
Click to stamp whatever is in the copy buffer. Hold CTRL to treat colour 0 (black) as
transparent.
Click and drag to create a rectangular selection. To remove the selection, press ENTER or
click anywhere.
If a pixel-wise selection is not present, many operations are instead applied to a
sprite-wise selection, or the visible view. To select sprites, shift-drag in the sprite
navigator. To select the sprite sheet press CTRL-A (repeat to toggle off the bottom half
shared with map data)
Click and drag to move around the sprite sheet.
Fill with the current colour. This applies only to the current selection, or the visible
area if there is no selection.
Click the tool button to cycle through: oval, rectangle, line options.
Hold CTRL to get a filled oval or rectangle.<br> Hold SHIFT to snap to circle, square, or
low-integer-ratio line.
CTRL-Z: Undo
CTRL-C/X: Copy/Cut selected area or selected sprites
CTRL-V: Paste to current sprite location
Q/A,W/Z: Switch to previous/next sprite
1,2: Switch to previous/next colour
TAB: Toggle fullscreen view
Mousewheel or < and > to zoom (centered in fullscreen)
CTRL-H to toggle hex view (shows sprite index in hexadecimal)
CTRL-G to toggle black grid lines when zoomed in
F: Flip sprite horizontally
V: Flip sprite vertically
R: Rotate (requires a square selection)
Cursor keys to shift (loops if sprite selection)
DEL/BACKSPACE to clear selected area
The 8 coloured circles are sprite flags for the current sprite. These have no particular
meaning, but can be accessed using the @FGET() / @FSET() functions. They are indexed from 0
starting from the left.
See @FSET() for more information.
To load a png file of any size into the sprite sheet, first select the sprite that should
be the top-left corner destination, and then either type "IMPORT IMAGE_FILE.PNG" or drag
and drop the image file into the PICO-8 window. In both cases, the image is colour-fitted
to the current display palette.
Map Editor
The PICO-8 map is a 128x32 (or 128x64 using shared space) block of 8-bit values. Each value is
shown in the editor as a reference to a sprite (0..255), but you can of course use the data to
represent whatever you like.
WARNING: The second half of the sprite sheet (banks 2 and 3), and the bottom half of the map
share the same cartridge space. It's up to you how you use the data, but be aware that drawing
on the second half of the sprite sheet could clobber data on the map and vice versa.
The tools are similar to the ones used in sprite editing mode. Select a sprite and click and
drag to paint values into the map.
To draw multiple sprites, select from sprite navigator with shift+drag To copy a block of
values, use the selection tool and then stamp tool to paste To pan around the map, use the pan
tool or hold space Q,W to switch to previous/next sprite Mousewheel or < and > to zoom
(centered in fullscreen) CTRL-H to toggle hex view (shows tile values and sprite index in
hexadecimal)
Moving sprites in the sprite sheet without breaking reference to them in the map is a little
tricky, but possible:
1. Press ENTER to clear any map selection
2. Select the sprites you would like to move (while still in map view), and press Ctrl-X
3. Select the area of the map you would like to alter (defaults to the top half of the map)
// press ctrl-A twice to select the full map including shared memory
4. Select the destination sprite (also while still in map view) and press Ctrl-V
// Note: this operation modifies the undo history for both the map and sprite editors, but
// PICO-8 will try to keep them in sync where possible. Otherwise, changes caused by moving
// map sprites can be reverted by also manually undoing in the sprite editor.
SFX Editor
There are 64 SFX ("sound effects") in a cartridge, used for both sound and music.
Each SFX has 32 notes, and each note has:
A frequency (C0..C5)
An instrument (0..7)
A volume (0..7)
An effect (0..7)
Each SFX also has these properties:
A play speed (SPD) : the number of 'ticks' to play each note for.
// This means that 1 is fastest, 3 is 3x as slow, etc.
Loop start and end : this is the note index to loop back and to
// Looping is turned off when the start index >= end index
When only the first of the 2 numbers is used (and the second one is 0), it is taken to mean
the number of notes to be played. This is normally not needed for sound effects (you can
just leave the remaining notes empty), but is useful for controlling music playback.
There are 2 modes for editing/viewing a SFX: Pitch mode (more suitable for sound effects) and
tracker mode (more suitable for music). The mode can be changed using the top-left buttons, or
toggled with TAB.
Click and drag on the pitch area to set the frequency for each note, using the currently
selected instrument (indicated by colour).
Hold shift to apply only the selected instrument.
Hold CTRL to snap entered notes to the C minor pentatonic scale.
Right click to grab the instrument of that note.
Each note shows: frequency octave instrument volume effect
To enter a note, use q2w3er5t6y7ui zsxdcvgbhnjm (piano-like layout)
Hold shift when entering a note to transpose -1 octave .. +1 octave
New notes are given the selected instrument/effect values
To delete a note, use backspace or set the volume to 0
Click and then shift-click to select a range that can be copied (CTRL-C) and pasted
(CTRL-V). Note that only the selected attributes are copied. Double-click to select all
attributes of a single note.
Navigation:
PAGEUP/DOWN or CTRL-UP/DOWN to skip up or down 4 notes
HOME/END to jump to the first or last note
CTRL-LEFT/RIGHT to jump across columns
- + to navigate the current SFX
SPACE to play/stop
SHIFT-SPACE to play from the current SFX quarter (group of 8 notes)
A to release a looping sample
Left click or right click to increase / decrease the SPD or LOOP values
// Hold shift when clicking to increase / decrease by 4
// Alternatively, click and drag left/right or up/down
Shift-click an instrument, effect, or volume to apply to all notes.
0 none
1 slide // Slide to the next note and volume
2 vibrato // Rapidly vary the pitch within one quarter-tone
3 drop // Rapidly drop the frequency to very low values
4 fade in // Ramp the volume up from 0
5 fade out // Ramp the volume down to 0
6 arpeggio fast // Iterate over groups of 4 notes at speed of 4
7 arpeggio slow // Iterate over groups of 4 notes at speed of 8
If the SFX speed is <= 8, arpeggio speeds are halved to 2, 4
Each SFX has 5 filter switches that can be accessed while in tracker mode:
NOIZ: Generate pure white noise (applies only to instrument 6)
BUZZ: Various alterations to the waveform to make it sound more buzzy
DETUNE-1: Detunes a second voice to create a flange-like effect
DETUNE-2: Various second voice tunings, mostly up or down an octave
REVERB: Apply an echo with a delay of 2 or 4 ticks
DAMPEN: Low pass filter at 2 different levels
When BUZZ is used with instrument 6, and NOIZ is off, pure brown noise is generated.
Music Editor
Music in PICO-8 is controlled by a sequence of 'patterns'. Each pattern is a list of 4 numbers
indicating which SFX will be played on that channel.
Playback flow can be controlled using the 3 buttons at the top right.
When a pattern has finished playing, the next pattern is played unless:
- there is no data left to play (music stops)
- a STOP command is set on that pattern (the third button)
- a LOOP BACK command is set (the 2nd button), in which case the music player searches
back for a pattern with the LOOP START command set (the first button) or returns to
pattern 0 if none is found.
When a pattern has SFXes with different speeds, the pattern finishes playing when the left-most
non-looping channel has finished playing. This can be used to set up double-time drum beats or
unusual polyrhythms.
For time signatures like 3/4 where less than 32 rows should be played before jumping to the
next pattern, the length of a SFX can be set by adjusting only the first loop position and
leaving the second one as zero. This will show up in the sfx editor as "LEN" (for "Length")
instead of "LOOP".
To select a range of patterns: click once on the first pattern in the pattern navigator, then
shift-click on the last pattern. Selected patterns can be copied and pasted with CTRL-C and
CTRL-V. When pasting into another cartridge, the SFX that each pattern points to will also be
pasted (possibly with a different index) if it does not already exist.
In addition to the 8 built-in instruments, custom instruments can be defined using the first 8
SFX. Use the toggle button to the right of the instruments to select an index, which will show
up in the instrument channel as green instead of pink.
When an SFX instrument note is played, it essentially triggers that SFX, but alters the note's
attributes:
Pitch is added relative to C2
Volume is multiplied
Effects are applied on top of the SFX instrument's effects
Any filters that are on in the SFX instrument are enabled for that note
For example, a simple tremolo effect could be implemented by defining an instrument in SFX 0
that rapidly alternates between volume 5 and 2. When using this instrument to play a note, the
volume can further be altered as usual (via the volume channel or using the fade in/out
effects). In this way, SFX instruments can be used to control combinations of detailed changes
in volume, pitch and texture.
SFX instruments are only retriggered when the pitch changes, or the previous note has zero
volume. This is useful for instruments that change more slowly over time. For example: a bell
that gradually fades out. To invert this behaviour, effect 3 (normally 'drop') can be used when
triggering the note. All other effect values have their usual meaning when triggering SFX
instruments.
Waveform instruments function the same way as SFX instruments, but consist of a custom 64-byte
looping waveform. Click on the waveform toggle button in the SFX editor to use SFX 0..7 as a
waveform instrument. In this mode, samples can be drawn with the mouse.
When drawing notes in pitch mode, hold CTRL to snap to the currently defined scale. This is the
C minor pentatonic scale by default, but can be customised using the scale editor mode. There
is a little keyboard icon on the bottom right to toggle this. There are 2 tranpose buttons, 1
invert button, and 3 scale preset buttons:
Dim Diminished 7th scale // invert to get a whole-half scale
Maj Major scale // invert to get pentatonic
Who Whole tone scale // invert to get.. the other whole tone scale
Changing the scale does not alter the current SFX, it is only when drawing new notes with CTRL
held down that the scale is applied.