The PICO-8 is a fantasy console with limited space for programs and data, programmed in a flavor of Lua with a very small standard library. This repository is meant to serve as a collection of useful functions and tables built, curated, and optimized by the pico8 developer community.
The focus of this repository is on game-agnostic code and functions. Most of the code you will find here is applicable to any type of game or game engine, and represents code you might generally expect to find in the lua standard library (string, table, math, etc) or in a more comprehensive console I/O library (drawing, memory access, etc).
What you will not find here is code related to gameplay implementation, such as actor and component frameworks, rendering engines, or game rule logic. I would like to add this sort of content in the future, but it will require significant additional organization and documentation efforts above and beyond those requires for the current contents of the repo.
class- Create object oriented classes with inheritancefunctions- Function manipulation, creation, and helpersgraphics- Drawing and sprite manipulationjson- JSON(ish) parserlog- Write timestamped and leveled logs to STDOUTmath- Mathematical operations, mostly on numbersmemory- Reading, writing, and manipulating memorynumber- Non-mathematical manipulation of numbersphysics- Collision functions, etcstrings- String manipulation and creationtables- Table manipulation and creation
vector- Vectors (points and directions)rational- Rational Numbers (Fractions)test- Unit testinguint32- Unsigned 32-bit Integers
snippets- Inline snippets to mix with your own codeboilerplate- Mostly empty pico8 cart with profiling and comments
Some usage examples can be found in examples/ and tests/
Code is not minified for character count; that is a job for a minifier if desired or necessary. I try to aim for 3-5 character identifiers in moderate to complex functions, 1-3 characters in simple functions.
Functions and variables are local where possible, for performance reasons. Thanks to zep for giving it to us as a free token!
Some functions are provided in multiple variations, optimized for tokens, size, speed, and/or functionality. Every function should have at least a token-optimized version. Some functions have lines or blocks commented with variations.
-- inline[t,c] marks code that could be inlined to save t tokens and c characters, usually at the cost of cpu or memory.
-- remove[t,c] marks code that can be removed, usually at the cost of reduced functionality or code safety.
#include lines are commented out because nested includes are a syntax error in pico8. You will need to put all required includes in your own top level script file. e.g. if you want to do #include json.lua then you need to #include strings.lua earlier in the same file.
Thanks to mindfilleter we can use test to perform unit tests on this repo.
Individual tests are in tests/, and can run with a command like pico8 -x tests/test_test.p8.
tests/template.p8 contains a template for new tests, which can be used in this repo or on your own project that uses the test library.
PRs are welcome! I am looking to collect a variety of best-of-breed examples of common library functions. Additional tests would also be helpful.
The best place to chat with other PICO-8 developers is on the PICO-8 Discord.