API Map

Map

The PICO-8 map is a 128x32 grid of 8-bit cells, or 128x64 when using the shared memory. When using the map editor, the meaning of each cell is taken to be an index into the sprite sheet (0…255). However, it can instead be used as a general block of data.

MGET(X, Y)

MSET(X, Y, VAL)

Get or set map value (VAL) at X, Y
When X, Y is outside the map range, MSET returns 0.

MAP([CELL_X], CELL_Y, [SX, SY], [CELL_W, CELL_H], [LAYERS])

Draw section of map (starting from CELL_X, CELL_Y) at screen position SX, SY (pixels).

To draw a 4x2 blocks of cells starting from 0,0 in the map, to the screen at 20,20:

MAP(0, 0, 20, 20, 4, 2) 

CELL_W and CELL_H default to 128,32 (the top half of the map). To draw the whole map, including the bottom half shared with the sprite sheet, use:

MAP(0, 0, 0, 0, 128, 64)

MAP() is often used in conjunction with CAMERA(). To draw the map so that a player object (at PL.X in PL.Y in pixels) is centered:

CAMERA(PL.X - 64, PL.Y - 64)
MAP()

LAYERS is a bitfield. When given, only sprites with matching sprite flags are drawn. For example, when LAYERS is 0x5, only sprites with flag 0 and 2 are drawn.

Sprite 0 is taken to mean "empty" and is not drawn. To disable this behaviour, use:

POKE(0x5F36, 0x8)

TLINE(X0, Y0, X1, Y1, MX, MY, [MDX, MDY], [LAYERS])

Draw a textured line from (X0,Y0) to (X1,Y1), sampling colour values from the map. When LAYERS is specified, only sprites with matching flags are drawn (similar to MAP())

MX, MY are map coordinates to sample from, given in tiles. Colour values are sampled from the 8x8 sprite present at each map tile. For example:

2.0, 1.0  means the top left corner of the sprite at position 2,1 on the map
2.5, 1.5  means pixel (4,4) of the same sprite

MDX, MDY are deltas added to mx, my after each pixel is drawn. (Defaults to 0.125, 0)

The map coordinates (MX, MY) are masked by values calculated by subtracting 0x0.0001 from the values at address 0x5F38 and 0x5F39. In simpler terms, this means you can loop a section of the map by poking the width and height you want to loop within, as long as they are powers of 2 (2,4,8,16..)

For example, to loop every 8 tiles horizontally, and every 4 tiles vertically:

POKE(0x5F38, 8)
POKE(0x5F39, 4)
TLINE(...)

The default values (0,0) gives a masks of 0xff.ffff, which means that the samples will loop every 256 tiles.

An offset to sample from (also in tiles) can also be specified at addresses 0x5f3a, 0x5f3b:

POKE(0x5F3A, OFFSET_X)
POKE(0x5F3B, OFFSET_Y)

Sprite 0 is taken to mean "empty" and not drawn. To disable this behaviour, use:

POKE(0x5F36, 0x8)