Difference between revisions of "PICO-8"

From SizeCoding
Jump to: navigation, search
m (sp.)
 
(19 intermediate revisions by 3 users not shown)
Line 45: Line 45:
 
RECTFILL(x,y,w,h,color)
 
RECTFILL(x,y,w,h,color)
 
LINE(x0,y0,x1,y1,color)
 
LINE(x0,y0,x1,y1,color)
−
PRINT(text,[x,y,color])
+
PRINT(text,[x,y,color]) / ?text,x,y,color
  
 
COLOR(color) - Set default color
 
COLOR(color) - Set default color
Line 96: Line 96:
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
 
POKE(12869+offset,value)SFX(1)
 
POKE(12869+offset,value)SFX(1)
 +
</syntaxhighlight>
 +
 +
More recently, the PICO-8's secret 5512Hz 8-bit digital audio out API at port 0x808 has been discovered.
 +
More information about this port can be found here: https://www.lexaloffle.com/bbs/?tid=41991
 +
 +
=== Optimisation Tricks ===
 +
Here are a few tricks you can use to optimize your PICO-8 code, using a plasma-effect as an example:
 +
 +
* Step 1: Use label/goto instead of the FUNCTION _DRAW
 +
<syntaxhighlight lang="lua">
 +
::F::
 +
FOR Y=0,127 DO FOR X=0,127 DO
 +
PSET(X,Y,SIN(X>>7)+SIN(Y>>7)+T())
 +
END END
 +
FLIP()GOTO F
 +
</syntaxhighlight>
 +
* Step 2: For pixel effects, you can skip the FLIP() command for Monte-Carlo style updating
 +
<syntaxhighlight lang="lua">
 +
::F::
 +
X=RND()Y=RND()
 +
PSET(X<<7,Y<<7,SIN(X)+SIN(Y)+T())
 +
GOTO F
 +
</syntaxhighlight>
 +
* Step 3: Use the PRINT/? command to draw characters instead of pixels to save a few characters
 +
<syntaxhighlight lang="lua">
 +
::F::
 +
X=RND()Y=RND()
 +
?0,X<<7,Y<<7,SIN(X)+SIN(Y)+T()
 +
GOTO F
 +
</syntaxhighlight>
 +
* Step 4: If it is possible to write the entire code on a single line, you can use the WHILE(1) code-construct, for example
 +
<syntaxhighlight lang="lua">
 +
WHILE(1)X=RND()Y=RND()?0,X<<7,Y<<7,SIN(X)+SIN(Y)+T()
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 101: Line 134:
 
If you are familiar with TIC-80 sizecoding, but less with PICO-8. This chapter will help you point out the main differences between the 2 platforms:
 
If you are familiar with TIC-80 sizecoding, but less with PICO-8. This chapter will help you point out the main differences between the 2 platforms:
  
−
* Performance on PICO-8 is more limited. The use of instructions/tokens (inside and outside loops) will have a performance/token penalty.
+
* Performance on PICO-8 is more limited. Every declaration, operator, and function call costs a certain number of cycles, charged against a limit of approximately 8 million (2^23) cycles/second. See https://pico-8.fandom.com/wiki/CPU for more details.
−
* Less code to work with (for a typical 256byte intro 229 characters vs 300-400 characters of LZ compressed code on the TIC-80)
 
 
* Code-editor = Escape (prepare to have your desktop filled with screenshots by accidentally pressing F1 ;-)
 
* Code-editor = Escape (prepare to have your desktop filled with screenshots by accidentally pressing F1 ;-)
 
* All alphabetic letters can be tugged against numeric chars (0..9) on PICO-8  
 
* All alphabetic letters can be tugged against numeric chars (0..9) on PICO-8  
Line 109: Line 141:
 
* The PICO-8 has custom characters available in the font (character numbers 128+).
 
* The PICO-8 has custom characters available in the font (character numbers 128+).
 
* The PICO-8 Lua variant supports x+=value / x-=value
 
* The PICO-8 Lua variant supports x+=value / x-=value
 +
* The PICO-8 Lua variant supports shorthand single-line IF/ELSE and WHILE statements, where the condition is wrapped in parens and the block continues to the end of the line.
 +
* The PICO-8 Lua variant has peek operators: @ (1 byte), % (2 bytes), $ (4 bytes).
 +
* Numbers are 16.16 fixed point.
 
* The XOR operator is ^^ instead of ~  
 
* The XOR operator is ^^ instead of ~  
 
* FUNCTION _DRAW() = FUNCTION TIC()
 
* FUNCTION _DRAW() = FUNCTION TIC()
Line 128: Line 163:
 
* Did you know that the T() shorthand version of the TIME() function is also available?
 
* Did you know that the T() shorthand version of the TIME() function is also available?
 
* Remember that ?"text",x,y is a shorthand for PRINT("text",x,y), however it does require its own newline (2x enter) to work
 
* Remember that ?"text",x,y is a shorthand for PRINT("text",x,y), however it does require its own newline (2x enter) to work
 +
* You can use [https://pico-8.fandom.com/wiki/P8SCII_Control_Codes P8SCII control codes] in PRINT (or ?) statements to do all kinds of things: clear the screen, invoke FLIP(), poke values into memory, etc.
 +
* A particularly useful P8SCII control code formula is ?"⁶1⁶c", which is essentially equivalent to FLIP() CLS(0).
 +
* 2darray's [https://www.lexaloffle.com/bbs/?tid=35462 Palette Maker cart] can help generate strings to set your desired palette. Just be sure you invoke tweetcart mode to get a shorthand print statement with ? instead of a PAL call, and consider replacing \^ with ⁶.
 +
* Many extended P8SCII characters have numeric values when referenced as variables. For example, █ is .5, and the expression ⌂-🐱 produces 0x6000, which is the base address of screen memory. Pancelor's [https://www.lexaloffle.com/bbs/?tid=44801 Constant Companion cart] can help identify shorthand ways to produce constants of interest.
 +
* When optimizing compressed P8.ROM size, carlc27843's [https://carlc27843.itch.io/pico-8-source-compression-visualizer PXAVIZ tool] can be helpful in finding additional compression opportunities.
  
−
When you are done, make sure that your raw Lua character count is around the target size minus 27 characters, as most demoparties will accept a loadable .P8 cartridge file as an intro, which adds a 27 byte header like so:
+
Before the introduction of the P8.ROM file format, the most common way to create tiny intros for Pico-8 was to use the raw .P8 format which contained the raw LUA code + a minimum header of 27 bytes:
  
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
Line 146: Line 186:
  
 
You can edit the cartridge with the above header in an external editor or find and strip them down from your internal PICO-8 cartridge folder (type FOLDER to jump directly to your cartridge folder and/or edit the PICO-8 config.txt to save your P8 cartridge files elsewhere).
 
You can edit the cartridge with the above header in an external editor or find and strip them down from your internal PICO-8 cartridge folder (type FOLDER to jump directly to your cartridge folder and/or edit the PICO-8 config.txt to save your P8 cartridge files elsewhere).
 +
 +
=== Tiny ROM Export ===
 +
With the release of PICO-8 0.2.4c it is now also possible to export the lua codeblock directly to .p8.rom PNG ARGB data, using the following export option:
 +
 +
<syntaxhighlight>
 +
EXPORT -T INTRO.P8.ROM
 +
</syntaxhighlight>
 +
 +
This results in a compressed P8.ROM file with 8 byte header that roughly matches the number of characters used in the LUA code, giving you slightly more space to work with.
 +
 +
Alternatively, you can use you RAW lua code and save/rename it to a P8.ROM file without header.
 +
 +
=== P8.ROM Packing ===
 +
You can use the shrinko8 tool at https://thisismypassport.github.io/shrinko8/ to help you minify and compress your code, which usually gives you a slightly better result than using
 +
the built-in rom export.
  
 
=== Additional Resources ===
 
=== Additional Resources ===

Latest revision as of 03:26, 4 September 2024

The PICO-8 is a fantasy computer for making, playing and sharing tiny games and demos.

There are built-in tools for development: code, sprites, maps, sound editors and the command line, which is enough to create a mini retro game. At the exit you will get a cartridge file, which can be stored and played on the website.

Also, the game can be packed into a player that works on all popular platforms and distribute as you wish. To make a retro styled game the whole process of creation takes place under some technical limitations: 128x128 pixels display, 16 color palette, 256 8x8 color sprites and 4 channel sound

Setting up

The PICO-8 fantasy computer is an all-in-one creation and execution platform.

Unfortunately, the PICO-8 is a commercial package and should be purchased before you can get started.

You can go to https://lexaloffle.itch.io/pico-8 to purchase and then download the package for your platform of choice (Windows, OSX and even Raspberry Pi).

Getting started

PICO-8 programs are coded using the Lua scripting language.

The main function used for updating the screen (and called either 30 or 60 times a second) is the _DRAW() function, so this function is also a requirement for doing anything with graphics.

Most animated effects will also need to use some kind of a timer, so you are likely to also use the built-in time() function or keep track of your time (t) yourself as well. So a minimal setup would look something like this: 

T=0 FUNCTION _DRAW()
-- your effect code
T=T+1
END

Here is a single-image PICO-8 Cheat sheet to get you started.

  • PICO-8 Cheat Sheet.png

Video display

The PICO-8 has a 128x128 pixel display with 16 colors which can be accessed via a wide range of graphics functions.

Built-in Draw functions

Here are a couple of built-in drawing functions you can use: 

CLS(color=0)
PSET(x,y,color) 
color=PGET(x,y)
CIRC(x,y,r,color)
CIRCFILL(x,y,r,color)
RECT(x,y,w,h,color)
RECTFILL(x,y,w,h,color)
LINE(x0,y0,x1,y1,color)
PRINT(text,[x,y,color]) / ?text,x,y,color

COLOR(color) - Set default color
PAL(destindex,sourceindex) - Replace dest colorindex with color from sourceindex
FILLP(mask) -- Set fill pattern for circ, circfill, rect, rectfill, pset, and line

Getting something on screen

Here is a bit of code to get you started: 

T=0FUNCTION _DRAW() 
FOR Y=0,128 DO FOR X=0,128 DO
PSET(X,Y,X~Y+T)
END END
T=T+1
END

Which will display an animated XOR pattern.

Color Palette

Unfortunately for us sizecoders, the PICO-8 comes with a fixed palette of 16 colors with size-unfriendly color indexing (https://lospec.com/palette-list/pico-8).

Luckily, the PICO-8 provides a PAL(source,dest) function that lets you swap the color index of each color, but these are quite costly at 8-10 bytes per colorswap call.

Colorindex table

One of the easier ways to get a nice color-ramp without using the PAL function is to use a color indextable like so: 

c={0,5,6,7}
pset(x,y,c[i])

This method gives you the most freedom in terms of building your custom ramp of colors.

Color index shuffling

Alternatively, you can shuffle your color indices a bit to get 'somewhat workable' colors.

A couple of examples for this are:

  • color+4 / pal(4,0) - Replaces color index 4 with 0(black) for a 4-shade Grayscale
  • color&7*2 - Black, purple, brown, white
  • (color&7)^2 - Black, blue, brown, yellow

But feel free to experiment yourself as well and let us know on Discord if you find something cool.

Sound

The PICO-8 does not allow you to poke the sound registers directly, but instead works with the SFX(effectindex) command to generate sounds. However we are allowed to poke the piece of memory that holds the sound effect data, like so: 

POKE(12869+offset,value)SFX(1)

More recently, the PICO-8's secret 5512Hz 8-bit digital audio out API at port 0x808 has been discovered. More information about this port can be found here: https://www.lexaloffle.com/bbs/?tid=41991

Optimisation Tricks

Here are a few tricks you can use to optimize your PICO-8 code, using a plasma-effect as an example:

  • Step 1: Use label/goto instead of the FUNCTION _DRAW 
::F::
FOR Y=0,127 DO FOR X=0,127 DO
PSET(X,Y,SIN(X>>7)+SIN(Y>>7)+T())
END END
FLIP()GOTO F
  • Step 2: For pixel effects, you can skip the FLIP() command for Monte-Carlo style updating
::F::
X=RND()Y=RND()
PSET(X<<7,Y<<7,SIN(X)+SIN(Y)+T())
GOTO F
  • Step 3: Use the PRINT/? command to draw characters instead of pixels to save a few characters
::F::
X=RND()Y=RND()
?0,X<<7,Y<<7,SIN(X)+SIN(Y)+T()
GOTO F
  • Step 4: If it is possible to write the entire code on a single line, you can use the WHILE(1) code-construct, for example
WHILE(1)X=RND()Y=RND()?0,X<<7,Y<<7,SIN(X)+SIN(Y)+T()

PICO-8 vs TIC-80 Sizecoding

If you are familiar with TIC-80 sizecoding, but less with PICO-8. This chapter will help you point out the main differences between the 2 platforms:

  • Performance on PICO-8 is more limited. Every declaration, operator, and function call costs a certain number of cycles, charged against a limit of approximately 8 million (2^23) cycles/second. See https://pico-8.fandom.com/wiki/CPU for more details.
  • Code-editor = Escape (prepare to have your desktop filled with screenshots by accidentally pressing F1 ;-)
  • All alphabetic letters can be tugged against numeric chars (0..9) on PICO-8
  • Math functions don't need the MATH. prefix (SIN, COS, ATAN2, SQRT, SGN, RND, etc.)
  • No integer divisions are needed anymore for logical operations
  • The PICO-8 has custom characters available in the font (character numbers 128+).
  • The PICO-8 Lua variant supports x+=value / x-=value
  • The PICO-8 Lua variant supports shorthand single-line IF/ELSE and WHILE statements, where the condition is wrapped in parens and the block continues to the end of the line.
  • The PICO-8 Lua variant has peek operators: @ (1 byte), % (2 bytes), $ (4 bytes).
  • Numbers are 16.16 fixed point.
  • The XOR operator is ^^ instead of ~
  • FUNCTION _DRAW() = FUNCTION TIC()
  • Warning: The POKE4 function pokes 4 bytes intro memory instead of a nibble. Nibble poke is not available.

Final optimisations and P8 Cartridge Release

When you are happy with your intro and want to get it ready for release, it becomes time to look at squeezing those last bytes.

Final optimisations can be done by stringing as much code together on single lines and removing any extra spaces and whitelines.

Here are a couple of other tips and tricks that help you squeeze those final bytes:

  • You can always directly stick a letter A..Z after a number 0..9 or a bracket.
  • Make sure to reorder variable assigments and code around to make use of optimal letter/number squeezing.
  • Unlike the TIC-80 , no integer divides (like //1) are usually necessary for doing logical operations.
  • Using a GOTO loop construction like ::L:: <yourcode> FLIP()GOTO L will save you 1 character over FUNCTION _DRAW() <yourcode> END
  • You can alias functions that you are going to use more frequently, e.g. S=SIN or R=RND
  • Using decimal values instead of hexadecimal will save 1 character (32768 vs 0x8000)
  • Did you know that the T() shorthand version of the TIME() function is also available?
  • Remember that ?"text",x,y is a shorthand for PRINT("text",x,y), however it does require its own newline (2x enter) to work
  • You can use P8SCII control codes in PRINT (or ?) statements to do all kinds of things: clear the screen, invoke FLIP(), poke values into memory, etc.
  • A particularly useful P8SCII control code formula is ?"⁶1⁶c", which is essentially equivalent to FLIP() CLS(0).
  • 2darray's Palette Maker cart can help generate strings to set your desired palette. Just be sure you invoke tweetcart mode to get a shorthand print statement with ? instead of a PAL call, and consider replacing \^ with ⁶.
  • Many extended P8SCII characters have numeric values when referenced as variables. For example, █ is .5, and the expression ⌂-🐱 produces 0x6000, which is the base address of screen memory. Pancelor's Constant Companion cart can help identify shorthand ways to produce constants of interest.
  • When optimizing compressed P8.ROM size, carlc27843's PXAVIZ tool can be helpful in finding additional compression opportunities.

Before the introduction of the P8.ROM file format, the most common way to create tiny intros for Pico-8 was to use the raw .P8 format which contained the raw LUA code + a minimum header of 27 bytes: 

pico-8 cartridge

__lua__

Followed by your raw Lua code, so this leaves:

  • 101 characters for a 128 byte intro.
  • 229 characters for a 256 byte intro.
  • 485 characters for a 512 byte intro.
  • 997 characters for a 1024 byte intro.

The number of used characters can be made visible in the bottom right of the PICO-8 code editor, so that you can keep track.

You can edit the cartridge with the above header in an external editor or find and strip them down from your internal PICO-8 cartridge folder (type FOLDER to jump directly to your cartridge folder and/or edit the PICO-8 config.txt to save your P8 cartridge files elsewhere).

Tiny ROM Export

With the release of PICO-8 0.2.4c it is now also possible to export the lua codeblock directly to .p8.rom PNG ARGB data, using the following export option: 

EXPORT -T INTRO.P8.ROM

This results in a compressed P8.ROM file with 8 byte header that roughly matches the number of characters used in the LUA code, giving you slightly more space to work with.

Alternatively, you can use you RAW lua code and save/rename it to a P8.ROM file without header.

P8.ROM Packing

You can use the shrinko8 tool at https://thisismypassport.github.io/shrinko8/ to help you minify and compress your code, which usually gives you a slightly better result than using the built-in rom export.

Additional Resources

Sizecoding on the PICO-8 is still in its infancy, but luckily there is already plenty of information to get you started!

Retrieved from "http://www.sizecoding.org/index.php?title=PICO-8&oldid=1615"