Log In  

Hello all -

I've been following Pico8 for a little while and finally have enough time on my hands to get into it. My background is in art but I do have some math knowledge from a past life. I have close to zero practical experience in proper programming, although I did use php/mysql a while back (I was using it to upload and organize pictures to my portfolio around the time blogs started to get popular). All that to say that I am very excited to dive into Pico8 because even though this is all new stuff for me, it is not as intimidating as it could be since I understand simple pseudo-code and basic programming concepts.

The example carts are fantastic, and the Pico8 Zine as well as the various other ressources I've found so far are all very well made. Great stuff !

However something bothers me. As far as I can tell there is no way to access the list of commands/API reference directly from the code editor. The boot screen mentions Pico8.txt, but I'd like to find a way to access the list of commands and their descriptions without having to leave the Pico8 environment, or at the very least, without having to reach for my mouse or a browser. Of course I can easily find answers to all my questions on http://pico-8.wikia.com/wiki/APIReference but there's something off about having to actively reach out to an external resource - it somehow breaks the flow of learning.

As a counter-example : I recently had to learn/use Construct2 in order to mockup the behaviour of a game UI to pass to a developer for proper implementation. Construct was fantastic in the sense that it was possible to figure out everything beyond the core initial concepts without having to leave the environment. So in short I am looking for a way to work similarly in Pico8 by always being able to reach the API documentation without having to reach for my mouse and/or use a browser.

Another counter-example is the way some console environments and CAD programs allow the user to merely start typing the name of a command, returning the properly type command name with a brief description of parameters.


I love the minimalist philosophy of Pico8, but as a beginner I am a bit hindered by the lack of discoverability of the commands. Even simply being able to launch a wiki search directly from Pico8 would be great. But I might be missing something - maybe there is a already a way to do that ? Or a way to directly access the help doc in cart form ? In which case I'd love to learn about it.

The best I've found so far is to use UltraEdit and launch google searches from it, which fires up a browser with Google search results for whatever is highlighted in UE - to which I just need to add "Pico8". But I'd love to find a more streamlined way to learn as it kind of defeats the purpose of working directly in the simple Pico8 environment.

I suppose that another path could rely on Autohotkey : highlight a command in Pico8 > copy > start a Autohotkey script performing a Google search on the term with "pico 8" appended. That's probably what I am going to attempt, but maybe there is a better way.

I hope this makes sense ! All suggestions are welcome.

P#44259 2017-09-17 02:46 ( Edited 2017-09-27 19:22)

:: P.O.

(I should also mention that yet another solution is to run one instance of Pico8 to work in, while also having a second one displaying api.p8 or any other cart to read code from).

P#44260 2017-09-17 03:27 ( Edited 2017-09-17 07:27)
:: Felice

Heads up that I've had trouble using AHK with Pico-8. I'm not sure exactly what the issue is, but getting keystrokes consistently recognized isn't easy. I think it polls key state instead of reading event messages, so it can miss a keypress between poll ticks. Increasing the key length/delay helps but it's still kinda janky and I'm really not sure why.

Edit: Anyone having better luck, please let us know your secrets! :)

P#44264 2017-09-17 04:52 ( Edited 2017-09-17 08:54)

Dunno if you've seen this, but I think @MBoffin created just what you're looking for a while back?
> PICO-8 Reference Cart

P#44267 2017-09-17 05:19 ( Edited 2017-09-17 09:19)
:: P.O.

Hey @Liquidream, that's fantastic !

I love this, it's so nice to be able to explore things directly like that. One could argue that it's not different from a regular reference page, but I love the idea of the presentation being 1:1 with the original look and feel of the program.

For what it's worth I just took the liberty to reformat things a little so that lines are not clipped and never go further than full width minus one character. Also uncommented the text so that color highlighting can do its thing.

--pico-8 reference cart
--credit: zep, neko250

\128 notes

--user notes go here

\128 graphics
\128 map
\128 audio
\128 input
\128 tables
\128 coroutines
\128 math
\128 operators
\128 flow control
\128 strings
\128 glyphs
\128 memory
\128 peek/poke
\128 cart data

\128\128 graphics \128\128\128\128\128\128\128\128

set camera position

draw a circle

draw a filled circle

set screen clipping region

clear screen c:color

set default color

set cursor and cr/lf margin

get sprite flag value

flip screen back buffer

draw a line

switch color 0 with color 1,
p=0 draw palette, p=1 screen

set transparency for color c
to (t)rue/false

get color at x,y

print string

set color of x,y

draw a rectangle

draw a filled rectangle

get spritesheet pixel color

draw sprite

set spritesheet pixel color

draw texture from spritesheet

\128\128 map  \128\128\128\128\128\128\128\128\128\128

draw map, layer:flags, spr 0
is empty

get map value

set map value
mset(x, y, v)

\128\128 audio  \128\128\128\128\128\128\128\128\128

play music (m=-1 to stop)

play sound (s=-1 to stop, s=-2
to release loop in channel)

\128\128 input  \128\128\128\128\128\128\128\128\128

button i:0-5=l/r/u/d/a/b

button press

\128\128 tables \128\128\128\128\128\128\128\128\128

add element v to table t

used with "for v in all(t)"

number of elements in table t

delete first instance of v
from t

call function f for each v
in t

used with "for k,v in
pairs(t)" loops

initialize metatable

set metatable mt to table t

\128\128 coroutines \128\128\128\128\128\128\128

returns a coroutine that
 executes f

resume executing coroutine c

returns coroutine status of
"dead" or "suspended"

inside a coroutine, pause
execution until next

\128\128 math \128\128\128\128\128\128\128\128\128\128

absolute value

convert (dx,dy) to
a 0..1 angle

bitwise conjunction

bitwise negation

bitwise or

bitwise xor

cosine of x (0..1)

round down

round up

pick greater of x/y

pick middle value of x/y/z

pick less of x/y

random value 0..x (exclusive)

returns sign of x

shift left

shift right

sine of x (0..1)

square root

set random seed

\128\128 operators  \128\128\128\128\128\128\128

a=b  assignment
a+b  addition
a-b  subtraction
a*b  multiplication
a/b  division
a%b  modulus
a^b  power

a+=b  add 
a-=b  subtract 
a*=b  multiply
a/=b  divide
a%=b  modulus
a^=b  power
a==b  equal
a!=b  not equal
a~=b  not equal

a>b   greater than
a<b   less than
a>=b  greather than or equal
a<=b  less than or equal

not a    boolean negation
a and b  boolean conjunction
a or b   boolean disjunction

(a)      operation delimiters

\128\128 flow control \128\128\128\128\128\128

goto label

inline if
if (<condition>) statement

if block
if <condition> then

while loop
while <condition> do

until loop
until <condition>

for loop (iterator)
for <var>=<first>,<last>,<step> do

for each in all
for <var> in all(<table>) do

for key/value pairs
for <key>,<value>
in pairs(<table>) do

\128\128 strings  \128\128\128\128\128\128\128\128

string length

string concatenation


cast string to number ("0xaf"
format for hex)

\128\128 glyphs \128\128\128\128\128\128\128\128\128

print codes, kb shortcuts:

"\128" \128 (shift-a)
"\129" \129 (shift-b)
"\130" \130 (shift-c)
"\131" \131 (shift-d)
"\132" \132 (shift-e)
"\133" \133 (shift-f)
"\134" \134 (shift-g)
"\135" \135 (shift-h)
"\136" \136 (shift-i)
"\137" \137 (shift-j)
"\138" \138 (shift-k)
"\139" \139 (shift-l)
"\140" \140 (shift-m)
"\141" \141 (shift-n)
"\142" \142 (shift-o)
"\143" \143 (shift-p)
"\144" \144 (shift-q)
"\145" \145 (shift-r)
"\146" \146 (shift-s)
"\147" \147 (shift-t)
"\148" \148 (shift-u)
"\149" \149 (shift-v)
"\150" \150 (shift-w)
"\151" \151 (shift-x)
"\152" \152 (shift-y)
"\153" \153 (shift-z)

\128\128 memory \128\128\128\128\128\128\128\128\128

copy bytes from ram to rom

copy bytes

set len bytes to val

read byte in ram address

write val in ram address

copy bytes from rom to ram

memory types
1. base ram (32kb)
2. cart rom
3. lua ram

ram layout
0x0    - gfx
0x1000 - gfx2/map2 (shared)
0x2000 - map
0x3000 - gfx_props
0x3100 - song
0x3200 - sfx
0x4300 - user data
0x5e00 - persistent cart data
(256 bytes)
0x5f00 - draw state
0x5f40 - hardware state
0x5f80 - gpio pins (128 bytes)
0x6000 - screen (8k)

\128\128 peek/poke  \128\128\128\128\128\128\128

mouse:initiate mouse listener

mouse:read x coord

mouse:read y coord

mouse:read button bitmask;
1=primary 2=secondary 4=middle

extra graphics modes (m)
0:standard 128x128
1:horizontal stretch,64x128
2:vertical stretch,128x64
5:mirror left half
6:mirror top half
7:mirror top-left quarter

\128\128 cart data  \128\128\128\128\128\128\128

open cart data named id
(once per executed)

get number at index

set number at index to value

@Felice : Good to know, I'll keep that in mind.

On a somewhat unrelated note : is there a way to make keyboard key repeat much faster ? The current is quite slow, making things somewhat tedious to navigate/select. It's been brought up here https://www.lexaloffle.com/bbs/?tid=29477 and as suggested in this thread, being able to use the system wide setting would be much better. Any ideas ?

P#44268 2017-09-17 05:56 ( Edited 2017-09-18 00:03)
:: sulai

I can understand why people want the reference in-game. It's what I liked when playing with QBasic back then, which had all the references inside. Even today when working with modern IDEs, the documentation is always at-hand, mostly using tool tips while doing auto-complete.

That being said, I think you don't want to write a full game in the Pico-8 code editor. Several reasons for that:

  • limited screen size, it's hard to read large chunks of code. Both horizontally and vertically.
  • missing code completion
  • missing inline documentation
  • missing lots of editor features like multi-caret
  • missing git integration and diff preview
  • missing static code analysis

That's why I prefer to edit plain Lua in Intellij Idea over using the Pico-8 code editor (I should write an article about how to set it up). However I still think the integrated code editor is very cool and I love to use it in these cases:

  • tweaking numbers to balance a game. It's very fast to loop using double escape, change a value, restart using ctrl-R.
  • set up map and sprites: this is similar, the are only a few lines to change and you quickly switch between Sprite editor, map editor and code editor.
  • similar work flow with music and sound fx

When working on a game, I'm using an external editor like 80 percent of the time. Depending on how complex the game logic and the algorithms are.

For beginners and for workshops in classes, I think an inline documentation would be brilliant. QBasic used a split screen approach: the upper half showed the documentation, the lower half showed your code editor. Just type "map" in the editor, press F1 and you'll get the map documentation. Nice :)

P#44410 2017-09-21 03:36 ( Edited 2017-09-21 07:56)

"That being said, I think you don't want to write a full game in the Pico-8 code editor."

Aww... But that's part of the fun!

You haven't lived until you've written a poker hand evaluator on a Pico-8 on a PocketCHIP.

Seriously, if you can't switch out to web browser for whatever reason, I recommend printing out something like this. Basically everything you need to know fits on that one page.
(Or this pdf but it's missing a few important things like the palette commands.)

P#44418 2017-09-21 09:40 ( Edited 2017-09-21 13:40)
:: P.O.

I totally see what both of you guys mean :) I ended up settling for a full-on UltraEdit for longer tasks, and direct Pico8 editing for small things. It works pretty well, especially across different machines with a /carts folder synced through Dropbox.

As for browser access : I of course have access to one, but I find that having to reach for a mouse to make searches was breaking the flow of learning. Fortunately I found out that it is possible to add web search directly to the windows Start button.


So I now I can do : Win key > pico8 [name of the command] > Down > Enter and it then launches the relevant web search. Searches can even be made faster by switching the default search engine from regular Google to "I am feeling lucky", hence landing directly on the relevant Wikia help page.


This effectively allows to make API searches without taking one's hands off the keyboard, which is great (and this of course applies to everything, not just Pico8).

All that being said even something as seemingly insignificant as the help .txt not being accessible directly from the application is a barrier to entry. Of course someone with enough dedication will take the time to browse for it or do their own research through one of the many pathways mentioned above. BUT, if one of the goals of Pico8 is to get people into programming then a case could be made for the help text and API references to be much more integrated into the program itself.

This could be as simple as having an optional extra panel (code/sprites/map/fx/track/help) enabled by default, with the possibility to turn it off in the settings file. Such a panel could have tabs covering various basic programming concepts, LUA/Pico8 syntax essentials, and so on. The idea being that of discoverability : being able to figure out basic concepts from scratch without even having to leave the application. In my opinion there is a lot of untapped potential there. And of course, being able to highlight something and F1 it for to get to the relevant documentation page sounds great too.

P#44424 2017-09-21 13:48 ( Edited 2017-09-21 19:52)
:: sulai

I often work split screen: to the right the editor, to the left pico 8 and a browser. I keep this tab open: http://pico-8.wikia.com/wiki/APIReference

P#44425 2017-09-21 15:32 ( Edited 2017-09-21 19:32)

For a portable version, i use a pocketchip with an Iphone synced to a dropbox folder containing offline (pdfed) copies of my favorite tutorials and the API of course.

Ideally, the pocketchip would easily alt-tab to a 'proper browser' but sadly it's nowhere near the crunching power of an iphone and having 2 screens is actually quite useful.

Oh well.

P#44453 2017-09-22 17:40 ( Edited 2017-09-22 21:40)

Hey another pocketchip coder!
I actually setup mine to act as a wireless router (easy to do) - using Textastic SFTP synchro feature, I can code on the iPhone AND test without an external 4g network.
In short:
Textastic - click synchro - switch to VNC/pico - load cart - run

I need to post a write-up of my setup!

P#44679 2017-09-27 15:22 ( Edited 2017-09-27 19:22)

[Please log in to post a comment]

Follow Lexaloffle:        
Generated 2021-05-07 19:28:50 | 0.057s | Q:28