Map

Map manipulation

functions

map(), mapdraw()

Draws a portion of the map to the graphics buffer.

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

Note: mapdraw() is the original name for this function, and may still be found in older carts. Its use is deprecated.

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

Copy
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

mget()

Gets the sprite number assigned to a cell on the map.

Copy
mget( celx, cely )

The mget() function returns the sprite number assigned to a cell on the map. If a cell was modified by a call to mset, mget() returns the updated value.

When using the map to store level designs, a common technique is to keep track of the player's effective cell position on the map, then use mget() to look for adjacent level features such as obstructions. This can be combined with sprite flags (read with fget()) to indicate which sprite tiles represent obstructions, so a general purpose test for obstructions only needs to read the flags.

mset()

Sets a cell on the map to a new sprite number.

Copy
mset( celx, cely, v )

The mset() function modifies the map data.

A simple use of mset() is to place or remove objects on the map, such as a treasure that the player can pick up. This allows for the level designer to set the initial locations of objects.

In a more sophisticated version of this technique, the program can scan the map for objects with mget(), store their locations in a table, then erase them from the map data and draw them separately. This may make the objects easier to animate or participate in physics simulation.

Advanced techniques that use mset() include generating levels procedurally, or storing very large maps as compressed data and decompressing it into the map region as needed. In both cases, once the maps are written to memory, the game engine can use map() to draw the level to the screen.

Setting values on the map changes the data in memory, but does not change the cartridge. A program can restore the original data from the cartridge with reload(), and can save the modified data to the cart with cstore(). See Memory for information about the memory addresses to use.