Editing Tools

Editing Tools

Press ESC to toggle between console and editor.
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)

keys	description
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

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:

keys	description
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.

Code Tabs

Click the [+] button at the top to add a new tab. Navigate tabs by left-clicking, or with CTRL-TAB, HIFT-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.

Code Limits

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.

Draw Tool

Click and drag on the sprite to plot pixels, or use RMB to select the colour under the cursor. All perations apply only to the visible area, or the section if there is one. Hold CTRL to search and replace colour.

Stamp Tool

Click to stamp whatever is in the copy buffer. Hold CTRL to treat colour 0 (black) as transparent.

Select Tool (shortcut: SHIFT or S)

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)

Pan Tool (shortcut: SPACE)

Click and drag to move around the sprite sheet.

Fill Tool

Fill with the current colour. This applies only to the current selection, or the visible area if there is no selection.

Shape Tools

Click the tool button to cycle through: oval, rectangle, line options.
Hold CTRL to get a filled oval or rectangle.
Hold SHIFT to snap to circle, square, or low-integer-ratio line.

Extra keys

keys	description
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	totoggle black grid lines when zoomed in

Operations on selected area or selected sprites

keys	description
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

Sprite Flags

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.

Loading .png files into the sprite sheet

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 isshown in the editor as a reference to a sprite (0..255), but you can of course use the data torepresent whatever you like.

WARNING: The second half of the sprite sheet (banks 2 and 3), and the bottom half of the mapshare 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)

To move sprites in the sprite sheet without breaking references to them in the map:

1. 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
2. Select the sprites you would like to move (while still in map view), and press Ctrl-X
3. 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:

thing	value
A frequency	(C0..C5)
An instrument	(0..7)
A volume	(0..7)
An effect	(0..7)

Each SFX also has these properties:

property	description
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.

Pitch Mode

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.

Tracker Mode

• 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:

keys	description
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

Controls for both modes

keys	description
- +	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.

Effects

value	effect	description
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

Filters

Each SFX has 5 filter switches that can be accessed while in tracker mode:

filter	description
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.

Flow control

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 ero. This will show up in the sfx editor as "LEN" (for "Length") instead of "LOOP".

Copying and Pasting Music

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.

SFX Instruments

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.