PICO-8

Imagery has support to export sprites and tilemap levels to PICO-8 cartridges. Furthermore, get more screens, levels and rooms than would normally be supported using strings and metatiles.

What is PICO-8?

PICO-8 is a wonderful fantasy console for creating, sharing, and playing tiny games. It comes with built-in tools for writing code, drawing sprites, designing maps, and creating sound and music, so you can make a complete game without leaving its cosy development environment.

It is deliberately built around constraints. Its 128×128 display, limited colour palette, cartridge size, code limits, and restricted graphics and map memory are designed to make things simpler, encourage creativity, and give PICO-8 games their distinctive character.

PICO-8 - the constraints

A PICO-8 cartridge can have 128 sprites and 16 map screens worth of data in dedicated memory.

Either sprites or maps can make use of a shared area in its last two banks, to give up to another 128 sprites or another 16 maps.

You can mix and match how you use the shared space but in simple terms it means the extremes are either-

256 sprites and 16 map screens, or
128 sprites and 32 map screens

You may want to create a larger game world and push beyond PICO-8's built-in limitations. PICO-8 developers have found many inventive ways to work around these constraints, and Imagery gives you an easy way to do the same.

A map screen in PICO-8 (a room in Imagery) is 16x16 sprite tiles

Can have 8 x 2 rooms - 16 in total, or 32 if using the shared space

In Imagery a screen in a tilemap is called a room. You can make as many rooms as you like and of any size. However, if we design for PICO-8 we'd typically want to target a room that is 16x16 tiles, where tiles are 8x8 pixels in size.

In this exercise we'll import sprites from an existing PICO-8 cartridge, make some rooms, convert to metatiles and export back to the PICO-8 cartridge.

Word of warning: Imagery can insert sprites and maps into your cartridges without disturbing your code or other elements. That said, it would be wise to back up any carts you work with in Imagery just in case anything goes wrong.

Importing from your PICO-8 cartridge

Go to File -> Import -> PICO-8 Cartridge... and pick your cartridge file.

There are a number of options, you can import a map also, but here I'm just importing the sprites and I've chosen The whole sheet as one frame. This gives one large 128 x 128 image containing all the sprites. The other way to import would create separate frames, and that is ok also.

You can optionally reduce the sprite canvas to 128 x 64 pixels (Anchor at top) if you wish to using Bank -> Canvas Size...

I've removed the 'x' that PICO-8 puts in sprite 0 otherwise that will be displayed in the empty spaes and I've drawn more sprites.

We're now ready to build a map (room).

Creating the rooms

Let's create the rooms, click Bank -> New Tilemap Bank...

The sprite bank we imported has been picked up and shown in the Cells from control. It has also detected that the cells are all on one picture rather than separate frames, with a tile size of 8x8.

Set the Room size to 16 x 16 tiles, enough to fill the screen.

We're going to match PICO-8's map size of 8 x 2 rooms (128 x 32 tiles).

Ready to go, click OK.

Construct your rooms

In the tilemap bank you can construct your first room. Use the tools such as pencil, fill, selections, rectangles and ovals.

Zooming in and panning work the same way as for sprites.

The list of tiles are shown on the right, select a tile to draw with.

Tip: While over the tile list, hold the Ctrl key and use the scroll wheel to change the size of the tiles in this view if they are too small.

Tile 0 is the transparent background tile.

You can optionally give your room a background colour such as black using Bank -> Tilemap Properties... which is also on the Tilemaps toolbar. However, we need to make one change here which is to set the tile index size to byte which is needed for PICO-8 maps.

At the bottom you can get to all your rooms. You can view and manage your rooms using Bank -> Room Layout... which is also where you can expand them.

Export type 1: standard PICO-8 map

You can export your rooms in several ways. Let's look at the simplest first which is a standard PICO-8 map. Click File -> Export to PICO-8... to get started.

You can export either the sprites or the map or both.

We need to export the Map, and I've opted to export the sprites too as I have added a some new ones.

As I'm exporting sprites I can choose what sprite number to export to, I've left at the default of 0 here.

Then for the Map I've chosen to Open in the cartridge's map.

Open the cartridge in PICO-8 and go to the map editor to see the map in place.

Export type 2: store map in a string

To get more maps into your PICO-8 game you want to use something other than the built in map editor. This is where Imagery can really help. Once again, click File -> Export to PICO-8... to get started.

For the map, this time chose As strings, in the cartidge's code.

This works differently, instead of using PICO-8's map system, the data is stored in strings.

Advantages of strings

Each string only takes 1 token no matter how long the string is
While strings still contribute to memory used in the cart, as it is in the source code they are compressed automatically by PICO-8

On the export screen click the Write button to create or update the cartridge. Open this on PICO-8 and examine the code editor.

At the top of the file is some code to support the format and define the rooms. Note the string with a mix of characters in it. This is our room definition.

Don't change anything in this section if you plan to update the cart from Imagery again.

Further down are example _Init(), _Update() and _Draw() blocks to demonstrate how to use the map drawing routine, with code to move through the rooms. You can safely change from here onwards and Imagery won't overwrite it.

That said, remember to work on a copy of your cart (not the original) when you are exporting from Imagery, in case anything goes wrong!

Go large to go small - Metatiles

What are metatiles? They are essentially tiny tilemaps where you can define a pattern using normal sprites to make a larger tile. You then use these metatiles in your rooms instead of sprites.

Sprite Bank -> Metatiles Bank -> Tilemap Bank

We can create a Metatile Bank from the Bank Menu, but there is an easier way. We can generate the metatiles from our regular tilemap.

Click Bank -> Generate Metatiles... on the menu, or go to the Bank tab and right click the tilemap bank and choose Generate Metatiles... to start the process.

The process of generating metatiles will create two new banks - a metatile bank and a new tilemap bank that is set up to use the metatiles.

Sprite Bank -> Tilemap Bank -> ( Metatiles Bank -> Metatile Tilemap )

But first we must configure how we want our metatiles to be generated.

You are asked the size you wish to use for your metatiles. The default is 2x2 tiles but you can go for larger patterns.

Generally, when making the original tilemap you would want to have the size of your metatiles in mind.

We can help optimise our metatiles by correcting our original tilemap and generated again, or by directly editing the generated metatile bank. More on this later.

For now, I'm going to stick with the default of 2x2 and click Make Them.

We now have four banks in our project.

PICO Sprites Bank -> Map 2 Bank -> ( Map 2 Metatiles Bank -> Map 2 Metatiled )

Map 2 Metatiles contains the 2x2 metatiles generated. Double click to open this up, you will see every combination of metatiles needed to construct your final map.

And Map 2 Metatiled contains the new meta-tile-map.

The original Map 2 tilemap now has a link to the banks it generated. You can examine this from the Tilemap Properties... for the Map 2 bank.

The section titled Generated metatiles contain the configuration and the banks where the new metatiles and tilemap have been created.

When you generate metatiles again from Map 2, they will update these banks. Note: this will replace the destination banks and if you had made any changes in those they will be lost.

Examining the new tilemap

At this point we can go directly to export to PICO-8 and start using it, but wait...there is more!

If you open the Map 2 Metatile bank that was generated you will see a series of the mini tilemaps. You can change these here, and they will update on the new Map 2 Metatiled bank where ever they are used.

Let's take a closer look at the Map 2 Metatiled tilemap. Find it on the Banks panel and double click its icon to go to its tilemaps tab.

On the Tilemap's toolbar you will hind a heat map button. Click this to identify metatiles (it also works for normal tiles) that are used infrequently...

Tiles coloured green are used frequently, amber less frequently and red coloured tiles are used only once.

The red coloured tiles means this metatile is used only one time across all the rooms, and might be a good candidate to change. While the heatmap is still switched on you can click on the tile to go to the metatile definition.

However, as we've automatically generated our metatiles we can go back to the original tilemap called Map 2 to make changes there, then choose Generate Metatiles... once again, which will update the existing metatiles and tilemap from it.

For example, if we remove the little character so it becomes a corridor, regenerating the metatiles will no longer include that one single variation.

Export type 3: Metatiles

Now we have metatiles, the room data stored in strings will be smaller. The meta tile definitions will use up space but overall the savings are immediate. For our example metatiles of size 2x2 are 1/4 the size of a normal tilemap.

Click File -> Export to PICO-8... to get started.

For the export options, this time the tiles and sprites are all together so configure these options:

Untick Sprites and tick Metatile sprites
Tick Map and chose As metatiles, in the cartridge's code
Click the Write button and open the cart in PICO-8:

The token count is the same, as broadly the code is almost identical. What differs is how the data is stored, and here we see the char count is much smaller. The compressed code is also 1% smaller. Compression might be the deciding factor to using metatiles or not. PICO-8 does a great job at compressing the code, so often just exporting a normal map is enough.

What else for Metatiles?

In this example I have used PICO-8's normal sprite size of 8x8 for my sprites and tiles. If you want to push more out of metatiles, you can also create 4x4 pixels sized sprite tiles, where four of these smaller tiles are packed into a single sprite. When used with metatiles of size 2x2, 3x3 or 4x4 you can get some very detailed maps created using the small string metatile footprint.

Page updated

Google Sites

Report abuse