-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathpico-8_manual.txt
4189 lines (3034 loc) · 185 KB
/
pico-8_manual.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
====================================================================================================
PICO-8 User Manual
====================================================================================================
PICO-8 v0.2.4c
https://www.pico-8.com
(c) Copyright 2014-2022 Lexaloffle Games LLP
Author: Joseph White // hey@lexaloffle.com
PICO-8 is built with:
SDL2 http://www.libsdl.org
Lua 5.2 http://www.lua.org // see license.txt
ws281x by jgarff // see license.txt
GIFLIB http://giflib.sourceforge.net/
WiringPi http://wiringpi.com/
libb64 by Chris Venter
miniz by Rich Geldreich
Latest version of this manual (as html, txt) and other resources:
https://www.lexaloffle.com/pico-8.php?page=resources
:: Welcome to PICO-8!
PICO-8 is a fantasy console for making, sharing and playing tiny games and other computer
programs. When you turn it on, the machine greets you with a shell for typing in Lua programs
and provides simple built-in tools for creating sprites, maps and sound.
The harsh limitations of PICO-8 are carefully chosen to be fun to work with, encourage small
but expressive designs and hopefully to give PICO-8 cartridges their own particular look and
feel.
:: Specifications
Display: 128x128, fixed 16 colour palette
Input: 6-button controllers
Carts: 32k data encoded as png files
Sound: 4 channel, 64 definable chip blerps
Code: Lua (max 8192 tokens of code)
Sprites: Single bank of 128 8x8 sprites (+128 shared)
Map: 128x32 8-bit cells (+128x32 shared)
====================================================================================================
Getting Started
====================================================================================================
----------------------------------------------------------------------------------------------------
Keys
----------------------------------------------------------------------------------------------------
ALT+ENTER: Toggle Fullscreen
ALT+F4: Fast Quit (Windows)
CTRL-Q: Fast Quit (Mac, Linux)
CTRL-R: Reload / Run / Restart cartridge
CTRL-S: Quick-Save working cartridge
CTRL-M: Mute / Unmute Sound
ENTER / P: Pause Menu (while running cart)
Player 1 default keys: Cursors + ZX / NM / CV
Player 2 default keys: SDFE + tab,Q / shift A
To change the default keys use the KEYCONFIG utility from inside PICO-8:
> KEYCONFIG
----------------------------------------------------------------------------------------------------
Hello World
----------------------------------------------------------------------------------------------------
After PICO-8 boots, try typing some of these commands followed by enter:
> PRINT("HELLO WORLD")
> RECTFILL(80,80,120,100,12)
> CIRCFILL(70,90,20,14)
> FOR I=1,4 DO PRINT(I) END
(Note: PICO-8 only displays upper-case characters -- just type normally without capslock!)
You can build up an interactive program by using commands like this in the code editing mode
along with two special callback functions @_UPDATE and @_DRAW. For example, the following
program allows you to move a circle around with the cursor keys. Press Esc to switch to the
code editor and type or copy & paste the following code:
X = 64 Y = 64
FUNCTION _UPDATE()
IF (BTN(0)) THEN X=X-1 END
IF (BTN(1)) THEN X=X+1 END
IF (BTN(2)) THEN Y=Y-1 END
IF (BTN(3)) THEN Y=Y+1 END
END
FUNCTION _DRAW()
CLS(5)
CIRCFILL(X,Y,7,14)
END
Now press Esc to return to the console and type RUN (or press CTRL-R) to see it in action.
Please refer to the demo cartridges for more complex programs (type INSTALL_DEMOS).
If you want to store your program for later, use the SAVE command:
> SAVE PINKCIRC
And to load it again:
> LOAD PINKCIRC
----------------------------------------------------------------------------------------------------
Example Cartridges
----------------------------------------------------------------------------------------------------
These cartridges are included with PICO-8 and can be installed by typing:
> INSTALL_DEMOS
> CD DEMOS
> LS
HELLO Greetings from PICO-8
API Demonstrates most PICO-8 functions
JELPI Platform game demo w/ 2p support
CAST 2.5D Raycaster demo
DRIPPY Draw a drippy squiggle
WANDER Simple walking simulator
COLLIDE Example wall and actor collisions
To run a cartridge, open PICO-8 and type:
> LOAD JELPI
> RUN
Press escape to stop the program, and once more to enter editing mode.
A small collection of BBS carts can also be installed to /GAMES with:
> INSTALL_GAMES
----------------------------------------------------------------------------------------------------
File System
----------------------------------------------------------------------------------------------------
These commands can be used to manage files and directories (folders):
LS list the current directory
CD BLAH change directory
CD .. go up a directory
CD / change back to top directory (on PICO-8's virtual drive)
MKDIR BLAH make a directory
FOLDER open the current directory in the host operating system's file browser
LOAD BLAH load a cart from the current directory SAVE BLAH save a cart to the current
directory
If you want to move files around, duplicate them or delete them, use the FOLDER command and do
it in the host operating system.
The default location for PICO-8's drive is:
Windows: C:/Users/Yourname/AppData/Roaming/pico-8/carts
OSX: /Users/Yourname/Library/Application Support/pico-8/carts
Linux: ~/.lexaloffle/pico-8/carts
You can change this and other settings in pico-8/config.txt
Tip: The drive directory can be mapped to a cloud drive (provided by Dropbox, Google Drive or
similar) in order to create a single disk shared between PICO-8 machines spread across
different host machines.
----------------------------------------------------------------------------------------------------
Loading and Saving
----------------------------------------------------------------------------------------------------
When using LOAD and SAVE, the .P8 extension can be omitted and is added automatically.
> SAVE FOO
SAVED FOO.P8
Cartridge files can also be dragged and dropped into PICO-8's window to load them.
Using .p8.png filename extension will write the cartridge in a special image format that looks
like a cartridge. Using .p8.rom" writes in a raw 32k binary format.
Use a filename of "@clip" to load or save to the clipboard.
Use a filename of "@url" to save to clipboard as a pico-8-edu.com url if it can be encoded in
2040 characters (code and gfx only).
Once a cartridge has been loaded or saved, it can also be quick-saved with CTRL-S
:: Saving .p8.png carts with a text label and preview image
To generate a label image saved with the cart, run the program first and press CTRL-7 to
grab whatever is on the screen. The first two lines of the program starting with '--' are
also drawn to the cart's label.
-- OCEAN DIVER LEGENDS
-- BY LOOPY
:: Code size restrictions for .p8.png / .p8.rom formats
When saving in .png or .rom format, the compressed size of the code must be less than 15360
bytes so that the total data is <= 32k.
To find out the current size of your code, use the INFO command. The compressed size limit
is not enforced for saving in .p8 format.
----------------------------------------------------------------------------------------------------
Using an External Text Editor
----------------------------------------------------------------------------------------------------
It is possible to edit .p8 files directly with a separate text editor. Using CTRL-R to run a
cartridge will automatically re-load the file if:
1. There are no unsaved changes in the PICO-8 editors, AND<br> 2. The file differs in
content from the last loaded version.
If there are changes to both the cart on disk and in the editor, a notification is displayed:
DIDN'T RELOAD; UNSAVED CHANGES
Alternatively, .lua text files can be modified in a separate editor and then included into the
cartridge's code each time it is run using @{#INCLUDE} (in the desired code location):
#INCLUDE YOURFILE.LUA
----------------------------------------------------------------------------------------------------
Backups
----------------------------------------------------------------------------------------------------
When quitting without saving changes, or overwriting an existing file, a backup of the
cartridge is saved to {appdata}/pico-8/backup. An extra copy of the current cartridge can also
be saved to the same folder by typing BACKUP.
To open the backups folder in the host operating system's file browser, use:
> FOLDER BACKUPS
It is then possible to drag and drop files into the PICO-8 window to load them.
From 0.2.4c, periodic backups are also saved every 20 minutes when not idle in the editor,
which means the backups folder will grow by about 1MB every 5 hours. This can be disabled or
adjusted in config.txt
----------------------------------------------------------------------------------------------------
Configuration
----------------------------------------------------------------------------------------------------
PICO-8 reads configuration settings from config.txt at the start of each session, and saves
it on exit (so you should edit config.txt when PICO-8 is not running).
The location of the config.txt file depends on the host operating system:
Windows: C:/Users/Yourname/AppData/Roaming/pico-8/config.txt
OSX: /Users/Yourname/Library/Application Support/pico-8/config.txt
Linux: ~/.lexaloffle/pico-8/config.txt
Use the -home switch (below) to use a different path to store config.txt and other data.
Some settings can be changed while running PICO-8 by typing CONFIG SETTING VALUE. (type
CONFIG by itself for a list)
:: Commandline parameters
// note: these override settings found in config.txt
pico8 [switches] [filename.p8]
-width n set the window width
-height n set the window height
-windowed n set windowed mode off (0) or on (1)
-volume n set audio volume 0..256
-joystick n joystick controls starts at player n (0..7)
-pixel_perfect n 1 for unfiltered screen stretching at integer scales (on by default)
-preblit_scale n scale the display by n before blitting to screen (useful with -pixel_perfect 0)
-draw_rect x,y,w,h absolute window coordinates and size to draw pico-8's screen
-run filename load and run a cartridge
-x filename execute a PICO-8 cart headless and then quit (experimental!)
-export param_str run EXPORT command in headless mode and exit (see notes under export)
-p param_str pass a parameter string to the specified cartridge
-splore boot in splore mode
-home path set the path to store config.txt and other user data files
-root_path path set the path to store cartridge files
-desktop path set a location for screenshots and gifs to be saved
-screenshot_scale n scale of screenshots. default: 3 (368x368 pixels)
-gif_scale n scale of gif captures. default: 2 (256x256 pixels)
-gif_len n set the maximum gif length in seconds (1..120)
-gui_theme n use 1 for a higher contrast editor colour scheme
-timeout n how many seconds to wait before downloads timeout (default: 30)
-software_blit n use software blitting mode off (0) or on (1)
-foreground_sleep_ms n how many milliseconds to sleep between frames.
-background_sleep_ms n how many milliseconds to sleep between frames when running in background
-accept_future n 1 to allow loading cartridges made with future versions of PICO-8
-global_api n 1 to leave api functions in global scope (useful for debugging)
:: Controller Setup
PICO-8 uses the SDL2 controller configuration scheme. It will detect common controllers on
startup and also looks for custom mappings in sdl_controllers.txt in the same directory as
config.txt. sdl_controllers.txt has one mapping per line.
To generate a custom mapping string for your controller, use either the controllermap program
that comes with SDL2, or try http://www.generalarcade.com/gamepadtool/
To find out the id of your controller as it is detected by SDL2, search for "joysticks" or
"Mapping" in log.txt after running PICO-8. This id may vary under different operating systems.
See: https://www.lexaloffle.com/bbs/?tid=32130
To set up which keyboard keys trigger joystick buttons presses, use KEYCONFIG.
----------------------------------------------------------------------------------------------------
Screenshots and GIFS
----------------------------------------------------------------------------------------------------
While a cartridge is running use:
CTRL-6 Save a screenshot to desktop
CTRL-7 Capture cartridge label image
CTRL-8 Start recording a video
CTRL-9 Save GIF video to desktop (8 seconds by default)
You can save a video at any time (it is always recording); CTRL-8 simply resets the video
starting point. To record more than 8 seconds, use the CONFIG command (maximum: 120)
CONFIG GIF_LEN 60
If you would like the recording to reset every time (to create a non-overlapping sequence),
use:
CONFIG GIF_RESET_MODE 1
The gif format can not match 30fps exactly, so PICO-8 instead uses the closest match: 33.3fps.
If you have trouble saving to the desktop, try configuring an alternative desktop path in
config.txt
----------------------------------------------------------------------------------------------------
Sharing Cartridges
----------------------------------------------------------------------------------------------------
There are three ways to share carts made in PICO-8:
1. Share the .p8 or .p8.png file directly with other PICO-8 users
Type FOLDER to open the current folder in your host operating system.
2. Post the cart on the Lexaloffe BBS to get a web-playable version
http://www.lexaloffle.com/pico-8.php?page=submit
3. Export the cartridge to a stand-alone html/js or native binary player (see the exporters
section for details)
----------------------------------------------------------------------------------------------------
SPLORE
----------------------------------------------------------------------------------------------------
SPLORE is a built-in utility for browsing and organising both local and bbs (online)
cartridges. Type SPLORE [enter] to launch it, or launch PICO-8 with -splore.
It is possible to control SPLORE entirely with a joystick:
LEFT and RIGHT to navigate lists of cartridges
UP AND DOWN to select items in each list
X,O or MENU to launch the cartridge
While inside a cart, press MENU to favourite a cartridge or exit to splore. If you're using a
keyboard, it's also possible to press F to favourite an item while it is selected in the
cartridge list view.
When viewing a list of BBS carts, use the top list item to re-download a list of cartridges. If
you are offline, the last downloaded list is displayed, and it is still possible to play any
cartridges you have downloaded.
If you have installed PICO-8 on a machine with no internet access, you can also use
INSTALL_GAMES to add a small selection of pre-installed BBS carts to /games
====================================================================================================
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
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.
:: Code Tabs
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.
:: 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 operations apply only to the visible area, or the section if there is one.
Hold CTRL to search and replace a 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.<br> Hold SHIFT to snap to circle, square, or
low-integer-ratio line.
:: Extra keys
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
:: Operations on selected area or selected sprites
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 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)
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:
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.
:: 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:
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
- + 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
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:
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 zero. 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.
====================================================================================================
Exporters / Importers
====================================================================================================
The EXPORT command can be used to generate png, wav files and stand-alone html and native binary
cartridge applications. The output format is inferred from the filename extension (e.g. .png).
You are free to distribute and use exported cartridges and data as you please, provided that you
have permission from the cartridge author and contributors.
:: Sprite Sheet / Label (.png)
> IMPORT BLAH.PNG -- EXPECTS 128X128 PNG AND COLOUR-FITS TO THE PICO-8 PALETTE
> EXPORT BLAH.PNG -- USE THE "FOLDER" COMMAND TO LOCATE THE EXPORTED PNG
When importing, -x and -y switches can be used to specify the target location in pixels: -s can
be used to shrink the image (3 means scale from 384x384 -> 128x128)
> IMPORT BLAH.PNG -X 16 -Y 16 -S 3
Use the -l switch with IMPORT and EXPORT to instead read and write from the cartridge's label:
> IMPORT -L BLAH.PNG
When importing spritesheets or labels, the palette is colour-fitted to the current draw state
palette.
:: SFX and Music (.wav)
To export music from the current pattern (when editor mode is MUSIC), or the current SFX:
> EXPORT FOO.WAV
To export all SFXs as foo0.wav, foo1.wav .. foo63.wav:
> EXPORT FOO%D.WAV
:: MAP and CODE
A cartridges map or source code can be exported as a single image named .map.png or .lua.png:
> EXPORT FOO.MAP.PNG
> EXPORT FOO.LUA.PNG
Map images are 1024x512 (128x32 8x8 sprites). Lua images are sized to fit, but each line is
fixed (and cropped) at 192 pixels wide.
:: Cartridges (.p8, .p8.png, .p8.rom)
Using EXPORT to save a cartridge is the same as using SAVE, but without changing the current
working cartridge. This can be useful for example, to save a copy in .p8.png format for
distribution without accidentally continuing to make changes to that file instead of the
original .p8 file.
EXPORT can also be used to perform cartridge file format conversions from commandline. For
example, from a Linux shell:
> pico8 foo.p8 -export foo.p8.png
----------------------------------------------------------------------------------------------------
Web Applications (.html)
----------------------------------------------------------------------------------------------------
To generate a stand-alone html player (mygame.html, mygame.js):
> EXPORT MYGAME.HTML
Or just the .js file:
> EXPORT MYGAME.JS
Use -f to write the files to a folder called mygame_html, using index.html instead of
mygame.html
> EXPORT -F MYGAME.HTML
Optionally provide a custom html template with the -p switch:
> EXPORT MYGAME.HTML -P ONE_BUTTON
This will use the file {application data}/pico-8/plates/one_button.html as the html shell,
replacing a special string "##js_file##" (without quotes), with the .js filename, and
optionally replacing the string "##label_file##" with the cart's label image as a data url.
Use -w to export as .wasm + .js:
> EXPORT -W MYGAME.HTML
When exported as .wasm, the page needs to be served by a webserver, rather than just opening it
directly from the local file system in a browser. For most purposes, the default .js export is
fine, but .wasm is slightly smaller and faster.
----------------------------------------------------------------------------------------------------
Binary Applications (.bin)
----------------------------------------------------------------------------------------------------
To generate stand-alone executables for Windows, Linux (64-bit), Mac and Raspberry Pi:
> EXPORT MYGAME.BIN
By default, the cartridge label is used as an icon with no transparency. To specify an icon
from the sprite sheet, use -i and optionally -s and/or -c to control the size and
transparency.
-I N Icon index N with a default transparent colour of 0 (black).
-S N Size NxN sprites. Size 3 would be produce a 24x24 icon.
-C N Treat colour N as transparent. Use 16 for no transparency.
For example, to use a 2x2 sprite starting at index 32 in the sprite sheet, using colour 12 as
transparent:
> EXPORT -I 32 -S 2 -C 12 MYGAME.BIN
To include an extra file in the output folders and archives, use the -E switch:
> EXPORT -E README.TXT MYGAME.BIN
Windows file systems do not support the file metadata needed to create a Linux or Mac
executable. PICO-8 works around this by exporting zip files in a way that preserves the file
attributes. It is therefore recommended that you distribute the outputted zip files as-is to
ensure users on other operating systems can run them. Otherwise, a Linux user who then
downloads the binaries may need to "chmod +x mygame" the file to run it, and Mac user would
need to "chmod +x mygame.app/Contents/MacOS/mygame"
----------------------------------------------------------------------------------------------------
Uploading to itch.io
----------------------------------------------------------------------------------------------------
If you would like to upload your exported cartridge to itch.io as playable html:
1. From inside PICO-8: EXPORT -F MYGAME.HTML
2. Create a new project from your itch dashboard.
3. Zip up the folder and upload it (set "This file will be played in the browser")
4. Embed in page, with a size of 750px x 680px.
5. Set "Mobile Friendly" on (default orientation) and "Automatically start on page load" on.
// no need for the fullscreen button as the default PICO-8 template has its own.
6. Set the background (BG2) to something dark (e.g. #232323) and the text to something light (#cccccc)
----------------------------------------------------------------------------------------------------
Exporting Multiple Cartridges
----------------------------------------------------------------------------------------------------
Up to 16 cartridges can be bundled together by passing them to EXPORT, when generating
stand-alone html or native binary players.
> EXPORT MYGAME.HTML DAT1.P8 DAT2.P8 GAME2.P8
During runtime, the extra carts can be accessed as if they were local files:
RELOAD(0,0,0X2000, "DAT1.P8") -- LOAD SPRITESHEET FROM DAT1.P8
LOAD("GAME2.P8") -- LOAD AND RUN ANOTHER CART
Exported cartridges are unable to load and run BBS cartridges e.g. via LOAD("#FOO")
----------------------------------------------------------------------------------------------------
Running EXPORT from the host operating system
----------------------------------------------------------------------------------------------------
Use the -export switch when launching PICO-8 to run the exporter in headless mode. File paths
are relative to the current directory rather than the PICO-8 file system.
Parameters to the EXPORT command are passed along as a single (lowercase) string:
pico8 mygame.p8 -export "-i 32 -s 2 -c 12 mygame.bin dat0.p8 dat1.p8"
====================================================================================================
Lua Syntax Primer
====================================================================================================
PICO-8 programs are written using Lua syntax, but do not use the standard Lua library. The
following is a brief summary of essential Lua syntax.
For more details, or to find out about proper Lua, see www.lua.org.
:: Comments
-- USE TWO DASHES LIKE THIS TO WRITE A COMMENT
--[[ MULTI-LINE
COMMENTS ]]
:: Types and assignment
Types in Lua are numbers, strings, booleans and tables:
NUM = 12/100
S = "THIS IS A STRING"
B = FALSE
T = {1,2,3}
Numbers in PICO-8 are all 16:16 fixed point. They range from -32768.0 to 32767.99999
Hexadecimal notation with optional fractional parts can be used:
?0x11 -- 17
?0x11.4000 -- 17.25
Numbers written in decimal are rounded to the closest fixed point value. To see the 32-bit
hexadecimal representation, use PRINT(TOSTR(VAL,TRUE)):
?TOSTR(-32768,TRUE) -- 0x8000.0000
?TOSTR(32767.99999,TRUE) -- 0X7FFF.FFFF
Dividing by zero evaluates to 0x7fff.ffff if positive, or -0x7fff.ffff if negative.
:: Conditionals
IF NOT B THEN
PRINT("B IS FALSE")
ELSE
PRINT("B IS NOT FALSE")
END
-- with ELSEIF
IF X == 0 THEN
PRINT("X IS 0")
ELSEIF X < 0 THEN
PRINT("X IS NEGATIVE")
ELSE
PRINT("X IS POSITIVE")
END
IF (4 == 4) THEN PRINT("EQUAL") END
IF (4 ~= 3) THEN PRINT("NOT EQUAL") END
IF (4 <= 4) THEN PRINT("LESS THAN OR EQUAL") END
IF (4 > 3) THEN PRINT("MORE THAN") END
:: Loops
Loop ranges are inclusive:
FOR X=1,5 DO
PRINT(X)
END
-- PRINTS 1,2,3,4,5
X = 1
WHILE(X <= 5) DO
PRINT(X)
X = X + 1
END
FOR X=1,10,3 DO PRINT(X) END -- 1,4,7,10
FOR X=5,1,-2 DO PRINT(X) END -- 5,3,1
:: Functions and Local Variables
Variables declared as LOCAL are scoped to their containing block of code (for example, inside a
FUNCTION, a FOR loop, or IF THEN END statement).
Y=0
FUNCTION PLUSONE(X)
LOCAL Y = X+1
RETURN Y
END
PRINT(PLUSONE(2)) -- 3
PRINT(Y) -- 0
:: Tables
In Lua, tables are a collection of key-value pairs where the key and value types can both be
mixed. They can be used as arrays by indexing them with integers.
A={} -- CREATE AN EMPTY TABLE
A[1] = "BLAH"
A[2] = 42
A["FOO"] = {1,2,3}
Arrays use 1-based indexing by default:
> A = {11,12,13,14}
> PRINT(A[2]) -- 12
But if you prefer 0-based arrays, just write something the zeroth slot:
> A = {[0]=10,11,12,13,14}
Tables with 1-based integer indexes are special though. The length of such an array can be
found with the # operator, and PICO-8 uses such arrays to implement ADD, DEL, DELI, ALL and
FOREACH functions.
> PRINT(#A) -- 4
> ADD(A, 15)
> PRINT(#A) -- 5
Indexes that are strings can be written using dot notation
PLAYER = {}
PLAYER.X = 2 -- is equivalent to PLAYER["X"]
PLAYER.Y = 3
See the @{Table_Functions} section for more details.
:: PICO-8 Shorthand
PICO-8 also allows several non-standard, shorter ways to write common patterns.
1. IF THEN END statements, and WHILE THEN END can be written on a single line with:
IF (NOT B) I=1 J=2