Going from Lua 5.2 to PICO-8's Lua

readme.md

This information applies to the PICO-8 0.1.2 release.

This document is here to help folks with a proficiency in Lua understand the limitations and discrepencies between Lua and PICO-8's Lua.

You can always view the manual or yellowafterlife's extended manual.

General

• anything written in uppercase the PICO-8 editor or .p8 is made lowercase by the editor. → editing the .p8 file directly can work_
• multi line comments don't work correctly. → use single lines to get around this
• print(function() end) segfaults → wrapping it in a tostring() will fix it
• print takes three arguments (string,x,y) → use printh() instead
• PICO-8's Lua supports a few Compound assignment operators: +=,-=,*=,/=,%=
• PICO-8's Lua has single line shorthand for if then else operators. → Compare to ternary?: PICO-8 Lua: IF (NOT B) THEN I=1 J=2 END vs Lua: i,j = not b and 1,j or i,2.
• PICO-8's Lua has a different precision (16:16 fixed point) vs Lua's double-precision floating-point.
• PICO-8's Lua has additional Comparison operators/relational operators for "Not Equal To" (~=): !=
• ipairs does not have the proper indexing and will loop over the first element infinitely . → use pairs instead
• There is no io object. → There is technically "Cartride Data" that you can use for persistant information
• _VERSION exists, but can't be accessed via the editor. → It returns Lua 5.2.
• load has been overwritten with a PICO-8 function.
• PICO-8 introduces many other global functions (see manual).
• rawlen returns small fractions [incorrect value]
• [s|g]etmetatable needs to be tested.
• There are general rounding errors: print("-1"*1 == -1") -- false

Lua's String Library

• strings that use upper case pattern matching will not be able to be entered into the editor directly.
• string.byte returns a fraction [incorrect value]
• string.char operates differently:

• string.dump returns the characters va but offset I think? [incorrect value?]
• string.find returns small fractions [invalid indexes]
• string.gmatch does not return a working iterator [broken iterator index]
• string.gsub does not return the correct index [incorrect second value]
• string.len returns a rather small fraction [incorrect value] → use the # operator instead
• string.[upper|lower] while both of these functions technically work correctly, because the char table has had the upper case characters removed, it will not work as intended.

Lua's Table Library

• table.insert(t,o) does not insert the proper key. → use add(t,o) instead
• table.insert(t,p,o) does not insert the proper key. Attempting to insert beyond table initialization causes an position out of bounds error.
• table.remove(t,p) removes the correct value, but then assocates every following value with the key before it. → use del(t,o) instead

Lua's Math Library

• math.a[cos|sin|tan][2] does not work correctly. [Rounding errors?] → use atan2() instead of math.atan2(). Untested versions here
• math.[floor|ceil] returns input [incorrect value] → use flr() instead. For math.ceil(), use function ceil(x) return -flr(-x) end
• math.[cos|sin] return zero [incorrect value] → use cos() and sin(). Functions take 0..1 instead of 0..PI*2, and sin() is inverted.
• math.tan does not work correctly. [Rounding errors?] → use math instead:
• math.[cos|sin|tan]h does not work correctly. [Rounding errors?]
• math.[deg|rad] return zero [incorrect value] → _use math instead:
• math.[exp|log] does not work correctly [Rounding errors?]
• math.log10 is nil [does not exist]
• math.pow does not work correctly [returns -maxint] → use the ^ operator instead
• math.modf returns two zeros [incorrect value] → use the % operator instead
• math.sqrt does not work correctly [Rounding errors?] → use sqrt() instead
• math.random does not work correctly [returns zero] → use rnd() instead
• math.randomseed cannot be verified until math.random is fixed [dependency issue] → use srand() instead
• math.frexp does not return a value [incorrect return type] → but math.ldexp() works for some reason!
• math.huge is 0.5 [incorrect value and type]
• math.pi is 5.341e-05 [incorrect value] → use a fixed value instead, e.g.: 3.14159

Lua's OS library

• os.date works correctly, but due to a lack of upper case characters, it does not render correctly.
• os.time returns the incorrect value [rounding issues]
• os.getenv works correctly, but the editor cannot write upper case characters.
• os.difftime does not work correctly, but I think that this could be used to get os.time() to work correctly.
• os.re[name|move] this probably works, but operates where the binary for pico8 is located.
• os.clock doesn't work correctly, but could probably be scaled to the correct value. → pico8 is forced at 30fps; calculate time by incrementing a variable in _update() by 1/30.

Debug Library

this function has not been compared, but seems intact.

Undocumented PICO-8 functions

• bit32 table contains: extract,bnot,rrotate,arshift,btest,bxor,replace,band,lshift,rshift,lrotate,bor
• shutdown quits the pico8 binary.
• _update_buttons function. Has no arguments.
• _p8_program function. Causes out of memory error when called.
• ls function. Lists cache cart directory as root and colors output using print statement.
• decompress function. Not sure what it does.
• c variable may sometime be globally set. Seems to be a scope error for some other function.
• trace function. I'm guessing it's for the runtime errors.
• all function. Not sure what it does.
• _set_mainloop_exists function. Most likely toggles a variable in a local scope.
• stop function. Stops game at current point so you can debug things.

Just so you know, compress / decompress / all / shutdown are all documented. The last two are even in the manual.

trace() returns the current call stack.

reboot also reboots the pico8 binary

That's very helpful, thanks!

Cartridge is misspelled here:

There is no io object. → There is technically "Cartride Data" that you can use for persistant information - see cartdata()

@ryanpcmcquen thanks!

all t

Used in FOR loops to iterate over all items in a table (that have a 1-based integer index),
in the order they were added.

T = {11,12,13};
ADD(T,14)
ADD(T,"HI")
FOR V IN ALL(T) DO PRINT(V) END -- 11 12 13 14 HI
PRINT(#T) -- 5

https://www.lexaloffle.com/pico-8.php?page=manual

@ryanford-frontend I don't think all t needs to be ported, because ipairs and pairs is still in the Pico8 syntax. Perhaps I misunderstand?

Global functions and variables have been removed: ipairs

all function. Not sure what it does.

The equivalent of ipairs() in PICO-8 is all().
pairs() is still here, but ipairs() isn't.

This information applies to the PICO-8 0.1.6 release.

Has there been any other additions since?

@tapir - there has not, but you're welcome to offer changes!

Recent versions added chr, ord, ipairs, unpack!