Map

map( celx, cely, sx, sy, celw, celh, [layer] )

Draws a portion of the map to the graphics buffer.

celx

The column location of the map cell in the upper left corner of the region to draw, where 0 is the leftmost column.

cely

The row location of the map cell in the upper left corner of the region to draw, where 0 is the topmost row.

sx

The x coordinate of the screen to place the upper left corner.

sy

The y coordinate of the screen to place the upper left corner.

celw

The number of map cells wide in the region to draw.

celh

The number of map cells tall in the region to draw.

layer

If specified, only draw sprites that have flags set for every bit in this value (a bitfield). The default is 0 (draw all sprites).

The map is a grid of sprites from the sprite sheet, where each cell in the grid is assigned a sprite number. You can edit the map using the Pico-8 map editor. You call the map() function to draw a region of the map (a subsection of the grid cells) onto the screen.

You can use the map to draw large pictures by reusing sprite tiles in multiple cells. This is more memory efficient than drawing large images in pixels with the sprite editor, and easier to use than storing tables of sprite numbers in code.

Any map cell set to sprite number 0 is not drawn, effectively making that cell transparent. You can use this along with using the transparent color for pixels in sprites to make regions of transparency in the image. A common technique is to layer multiple maps on top of one another, then animate the positions of these layers to produce effects such as parallax scrolling.

Another use for maps is to design interactive levels or areas of a game world. When doing this, it is often necessary to determine which sprite is at a given location on the map, such as to determine whether a location next to the player is an obstruction. See mget().

Note: The sprite data region and the map data region overlap in memory. If you are using this shared memory for sprite data and you specify map coordinates for that memory (cely > 31), map() will attempt to interpret the sprite data as map data. See Graphics and Memory.

Examples

-- fill the screen with the map region starting at row 0 column 16
map(16, 0, 0, 0, 16, 16)

map() works well in conjunction with camera() to pan over a large region, such as in a platform game. Here is a full-screen map viewer that demonstrates the use of camera() in this way. Use cursor keys to move the camera.

-- the coordinates of the upper left corner of the camera
cam_x = 0
cam_y = 0

function _update()
  if (btn(0) and cam_x > 0) cam_x -= 1
  if (btn(1) and cam_x < 895) cam_x += 1
  if (btn(2) and cam_y > 0) cam_y -= 1
  if (btn(3) and cam_y < 127) cam_y += 1
  -- (the camera stops with the bottom of
  -- the screen at row 32.)
end

function _draw()
  cls()
  -- set the camera to the current location
  camera(cam_x, cam_y)

  -- draw the entire map at (0, 0), allowing
  -- the camera and clipping region to decide
  -- what is shown
  map(0, 0, 0, 0, 128, 32)

  -- reset the camera then print the camera
  -- coordinates on screen
  camera()
  print('('..cam_x..', '..cam_y..')', 0, 0, 7)
end

Jelpi, a game included with Pico-8, uses map() to draw the background in multiple layers, and to define the level layout. A moving image of clouds is drawn behind the fixed image of a mountain, with both images defined in the map data by sprites. The cloud layer is animated by adjusting the sx value for map().

See also

• Graphics
• mget
• mset