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.
TLDR :
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.
(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).
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! :)
Dunno if you've seen this, but I think @MBoffin created just what you're looking for a while back?
> PICO-8 Reference Cart
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
camera([x,y])
draw a circle
circ(x,y,r,[c])
draw a filled circle
circfill(x,y,r,[c])
set screen clipping region
clip([x,y,w,h])
clear screen c:color
cls([c])
set default color
color(c)
set cursor and cr/lf margin
position
cursor(x,y)
get sprite flag value
fget(n,[f])
flip screen back buffer
flip()
draw a line
line(x1,y1,x2,y2,[c])
switch color 0 with color 1,
p=0 draw palette, p=1 screen
palette
pal(c0,c1,[p]
set transparency for color c
to (t)rue/false
palt(c,t)
get color at x,y
pget(x,y)
print string
print(str,[x,y],[c])
set color of x,y
pset(x,y,c)
draw a rectangle
rect(x1,y1,x2,y2,[c])
draw a filled rectangle
rectfill(x1,y1,x2,y2,[c])
get spritesheet pixel color
sget(x,y)
draw sprite
spr(s,x,y,[w,h],[flip_x],
[flip_y])
set spritesheet pixel color
sset(x,y,[c])
draw texture from spritesheet
sspr(sx,sy,sw,sh,dx,dy,[dw,dh],
[flip_x],[flip_y])
\128\128 map \128\128\128\128\128\128\128\128\128\128
draw map, layer:flags, spr 0
is empty
mapdraw/map(map_x,map_y,scr_x,
scr_y,map_w,map_h,[layer])
get map value
mget(x,y)
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)
music(m,[fade_len],
[channel_mask])
play sound (s=-1 to stop, s=-2
to release loop in channel)
sfx(n,[channel],[offset])
\128\128 input \128\128\128\128\128\128\128\128\128
button i:0-5=l/r/u/d/a/b
p:player
btn(i,p)
button press
btnp(i,p)
\128\128 tables \128\128\128\128\128\128\128\128\128
add element v to table t
add(t,v)
used with "for v in all(t)"
loops
all(t)
number of elements in table t
count(t)
delete first instance of v
from t
del(t,v)
call function f for each v
in t
foreach(t,f)
used with "for k,v in
pairs(t)" loops
pairs(t)
initialize metatable
mt={}
set metatable mt to table t
setmetatable(t,mt)
\128\128 coroutines \128\128\128\128\128\128\128
returns a coroutine that
executes f
cocreate(f)
resume executing coroutine c
coresume(c)
returns coroutine status of
"dead" or "suspended"
costatus(c)
inside a coroutine, pause
execution until next
coresume(c)
yield()
\128\128 math \128\128\128\128\128\128\128\128\128\128
absolute value
abs(x)
convert (dx,dy) to
a 0..1 angle
atan2(dx,dy)
bitwise conjunction
band(x,y)
bitwise negation
bnot(x)
bitwise or
bor(x,y)
bitwise xor
bxor(x,y)
cosine of x (0..1)
cos(x)
round down
flr(x)
round up
-flr(-x)
pick greater of x/y
max(x,y)
pick middle value of x/y/z
mid(x,y,z)
pick less of x/y
min(x,y)
random value 0..x (exclusive)
rnd(x)
returns sign of x
sgn(x)
shift left
shl(x,y)
shift right
shr(x,y)
sine of x (0..1)
sin(x)
square root
sqr(x)
set random seed
srand(x)
\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::
goto label
inline if
if (<condition>) statement
if block
if <condition> then
statement[s]
elseif
statement[s]
else
statement[s]
end
while loop
while <condition> do
statement[s]
end
until loop
repeat
statement[s]
until <condition>
for loop (iterator)
for <var>=<first>,<last>,<step> do
statement[s]
end
for each in all
for <var> in all(<table>) do
statement[s]
end
for key/value pairs
for <key>,<value>
in pairs(<table>) do
statement[s]
end
\128\128 strings \128\128\128\128\128\128\128\128
string length
#s
string concatenation
"pico-"..8
substring
sub(str,from,[to])
cast string to number ("0xaf"
format for hex)
"123.45"+0
\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
cstore(dest_addr,src_addr,len,
[filename])
copy bytes
memcpy(dest_addr,src_addr,len)
set len bytes to val
memset(dest_addr,val,len)
read byte in ram address
peek(addr)
write val in ram address
poke(addr,val)
copy bytes from rom to ram
reload(dest_addr,src_addr,len,
[filename])
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
poke(0x5f2d,1)
mouse:read x coord
stat(32)
mouse:read y coord
stat(33)
mouse:read button bitmask;
1=primary 2=secondary 4=middle
stat(34)
extra graphics modes (m)
0:standard 128x128
1:horizontal stretch,64x128
2:vertical stretch,128x64
3:zoomed,64x64
4:standard,128x128
5:mirror left half
6:mirror top half
7:mirror top-left quarter
poke(0x5f2c,m)
\128\128 cart data \128\128\128\128\128\128\128
open cart data named id
(once per executed)
cartdata(id)
get number at index
dget(i)
set number at index to value
dset(i,v)
|
@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 ?
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 :)
| "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.)
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.
https://lifehacker.com/5750265/quickly-search-the-internet-from-windows-start-menu
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.
https://productforums.google.com/forum/#!msg/chrome/aunfa77WA4w/xiHtkrOwZWQJ
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.
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
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.
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!
[Please log in to post a comment]
