project name: p8
project url: https://github.com/p3r7/p8
author: eigen
description: run PICO-8 tweetcarts on norns
discussion url: https://llllllll.co/t/37947
documentation url: https://norns.community/authors/eigen/p8
tags: art


Compatibility layer to run PICO-8 scripts on the monome norns.

This is not suitable for running full-fledged carts (with sprites, sound…), targeting instead tweetcarts (code fitting in a tweet).

norns.community page (wiki)

lines page (forum)

blog post


Both platform share similar goals: build a community around sharing small apps written in Lua.

PICO-8 is centered around games, norns around music-making apps.

The PICO-8 community provided some pretty crazy examples of what can be done with basic functions and I thought that one community could benefit from the efforts of the other.

The aim is not to have it embedded systematically in a norns app but instead to quickly steal animation ideas from tweetcart and see how they get rendered on the norns display.


By defining PICO-8 API functions from norns-compatible Lua code (code).

To compare them:

Their display APIs are pretty close to one another.

On the contrary, PICO-8’s trigonometric functions behave quite differently from the standard Lua math lib.


ghosts.lua (original tweetcart by @Alexis_Lessard).


confetti.lua (original tweetcart by @von_rostock).


manga_effect.lua (original tweetcart by @kadoyan).


tree.lua (original tweetcart by @Alexis_Lessard).


pumpkin.lua (original tweetcart by @von_rostock).


cube.lua (original code by @neauoire of 100 rabbits).




Most PICO-8 tweetcarts are not defined using the game loop but a combination of goto and flip instead.

To be executed on norns, they need to be slightly adapted:

See the Examples for concrete use-cases.


PICO-8’s print allows printing on the screen.

norns is not happy with having the standard print function redefined.

That’s why PICO-8’s version got renamed p8print.

Special PICO-8 Lua syntax

PICO-8’s Lua differs a bit from standard Lua.

It notably provides additional constructs such as a short form if/else ternary syntax and compound assignment operators (e.g. +=). These instructions should be converted for norns to interpret them.

Refer to this page for more detailed porting instructions.

-- valid PICO-8 Lua
t += 1
if (not b) then i=1 j=2 end
j != 0

-- equivalent Lua
t = t + 1
if (not b) then i=1 else j=2 end
j ~= 0

There is also the @<address> shorthand for peek that would need to be converted to an explicit peek call.


Not all of PICO-8 APIs will get implemented.

The following are not yet here but are the next one on the list:

These are interesting but seem difficult to implement fully with current norns APIs:

These might get implemented in a very loose way:

Current implementation of print (p8print) does not handle \n and screen scroll on end of framebuffer.

Current implementation of peek and poke only support interacting with the current color and current text cursor position.

Current implementation of pal doesn’t honor the p parameter.

Implementation details

Table manipulation API functions (foreach, all, add, del) stolen from the picolove project (BBS thread).

atan2 implementation taken from @benjamin_soule’s PAT Shooter with some improvements.