{"id":23100746,"url":"https://github.com/p3r7/p8","last_synced_at":"2025-08-16T14:31:58.343Z","repository":{"id":92559742,"uuid":"309128706","full_name":"p3r7/p8","owner":"p3r7","description":"🕹️ Compatibility layer to run PICO-8 scripts on the monome norns","archived":false,"fork":false,"pushed_at":"2022-01-12T21:04:55.000Z","size":82,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-08-16T03:51:09.528Z","etag":null,"topics":["monome-norns","norns","pico-8"],"latest_commit_sha":null,"homepage":"https://llllllll.co/t/37947","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/p3r7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-01T15:41:50.000Z","updated_at":"2025-07-06T10:00:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"588ef25b-b15e-4f7e-8795-796ef07733ae","html_url":"https://github.com/p3r7/p8","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/p3r7/p8","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p3r7%2Fp8","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p3r7%2Fp8/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p3r7%2Fp8/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p3r7%2Fp8/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/p3r7","download_url":"https://codeload.github.com/p3r7/p8/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p3r7%2Fp8/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270723212,"owners_count":24634339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["monome-norns","norns","pico-8"],"created_at":"2024-12-16T23:34:58.478Z","updated_at":"2025-08-16T14:31:58.315Z","avatar_url":"https://github.com/p3r7.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# p8\n\nCompatibility layer to run [_PICO-8_](https://www.lexaloffle.com/pico-8.php) scripts on the [_monome norns_](https://monome.org/docs/norns/).\n\nThis is not suitable for running full-fledged carts (with sprites, sound...), targeting instead [_tweetcarts_](https://twitter.com/hashtag/tweetcart?lang=en) (code fitting in a tweet).\n\n[_norns.community_ page (wiki)](https://norns.community/authors/eigen/p8)\n\n[_lines_ page (forum)](https://llllllll.co/t/p8-pico-8-wrapper-lib/37947)\n\n[blog post](https://www.eigenbahn.com/2021/05/10/norns-community)\n\n\n## Why?\n\nBoth platform share similar goals: build a community around sharing small apps written in Lua.\n\n_PICO-8_ is centered around games, _norns_ around music-making apps.\n\nThe _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.\n\nThe 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.\n\n\n## How?\n\nBy defining PICO-8 API functions from norns-compatible Lua code ([code](./lib/p8.lua)).\n\nTo compare them:\n- [_PICO-8_ API reference](https://pico-8.fandom.com/wiki/APIReference), [manual](https://www.lexaloffle.com/pico-8.php?page=manual) (most up to date), [cheatsheet](https://iiviigames.github.io/pico8-api/)\n- [_norns_ API reference](https://monome.org/docs/norns/api/) (look especially at the [screen](https://monome.org/docs/norns/api/classes/screen.html) API)\n\nTheir display APIs are pretty close to one another.\n\nOn the contrary, _PICO-8's_ trigonometric functions behave quite differently from the standard Lua `math` lib.\n\n\n## Examples\n\n[ghosts.lua](ghosts.lua) ([original tweetcart](https://twitter.com/user/status/1322164958008905728) by [@Alexis_Lessard](https://twitter.com/Alexis_Lessard)).\n\n![norns_p8_ghosts](https://www.eigenbahn.com/assets/gif/norns_p8_ghosts.gif)\n\n[confetti.lua](confetti.lua) ([original tweetcart](https://twitter.com/user/status/1324156597569048578) by [@von_rostock](https://twitter.com/von_rostock)).\n\n![norns_p8_confetti](https://www.eigenbahn.com/assets/gif/norns_p8_confetti.gif)\n\n[manga_effect.lua](manga_effect.lua) ([original tweetcart](https://twitter.com/user/status/1309354303933616131) by [@kadoyan](https://twitter.com/kadoyan)).\n\n![norns_p8_manga-effect](https://www.eigenbahn.com/assets/gif/norns_p8_manga-effect.gif)\n\n[tree.lua](tree.lua) ([original tweetcart](https://twitter.com/user/status/1319781601425952768) by [@Alexis_Lessard](https://twitter.com/Alexis_Lessard)).\n\n![norns_p8_tree](https://www.eigenbahn.com/assets/gif/norns_p8_tree.gif)\n\n[pumpkin.lua](tree.lua) ([original tweetcart](https://twitter.com/user/status/1322693583623884803) by [@von_rostock](https://twitter.com/von_rostock)).\n\n![norns_p8_pumpkin](https://www.eigenbahn.com/assets/gif/norns_p8_pumpkin.gif)\n\n[cube.lua](cube.lua) ([original code](https://gist.github.com/neauoire/200d97396805dda71154) by [@neauoire of 100 rabbits](https://twitter.com/hundredrabbits)).\n\n![norns_p8_cube](https://www.eigenbahn.com/assets/gif/norns_p8_cube.gif)\n\n\n## Usage\n\n#### General\n\nMost _PICO-8_ _tweetcarts_ are not defined using the [game loop](https://pico-8.fandom.com/wiki/GameLoop) but a combination of `goto` and `flip` instead.\n\nTo be executed on _norns_, they need to be slightly adapted:\n\n - the label / `goto` block needs to be moved to a function (typically `redraw`)\n - this function needs to be called from a `metro` object\n\nSee the [Examples](#examples) for concrete use-cases.\n\n\n#### print\n\n_PICO-8's_ `print` allows printing on the screen.\n\n_norns_ is not happy with having the standard `print` function redefined.\n\nThat's why _PICO-8's_ version got renamed `p8print`.\n\n\n#### Special _PICO-8_ Lua syntax\n\n_PICO-8's_ Lua differs a bit from standard Lua.\n\nIt 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.\n\nRefer to [this page](https://gist.github.com/josefnpat/bfe4aaa5bbb44f572cd0) for more detailed porting instructions.\n\n```lua\n-- valid PICO-8 Lua\nt += 1\nif (not b) then i=1 j=2 end\nj != 0\n\n-- equivalent Lua\nt = t + 1\nif (not b) then i=1 else j=2 end\nj ~= 0\n```\n\nThere is also the `@\u003caddress\u003e` shorthand for `peek` that would need to be converted to an explicit `peek` call.\n\n\n## Completeness\n\nNot all of [_PICO-8_ APIs](https://pico-8.fandom.com/wiki/APIReference) will get implemented.\n\nThe following are not yet here but are the next one on the list:\n- `fillp` (patterned fill)\n- `tline` (textured line)\n\nThese are interesting but seem difficult to implement fully with current _norns_ APIs:\n- `clip`\n- `camera`\n-  map APIs\n\nThese might get implemented in a very loose way:\n- `fset` / `fget`\n- sprite sheet fns: `sset` / `sget`, `spr`, `sspr`\n\nCurrent implementation of `print` (`p8print`) does not handle `\\n` and screen scroll on end of framebuffer.\n\nCurrent implementation of `peek` and `poke` only support interacting with the current color and current text cursor position.\n\nCurrent implementation of `pal` doesn't honor the `p` parameter.\n\n\n## Implementation details\n\nTable manipulation API functions (`foreach`, `all`, `add`, `del`) stolen from the [picolove](https://github.com/picolove/picolove) project ([BBS thread](https://www.lexaloffle.com/bbs/?tid=2444)).\n\n`atan2` implementation taken from [@benjamin_soule](https://www.lexaloffle.com/bbs/?uid=9308)'s [PAT Shooter](https://www.lexaloffle.com/bbs/?pid=10183) with some improvements.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp3r7%2Fp8","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fp3r7%2Fp8","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp3r7%2Fp8/lists"}