- 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).
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. The map can be edited with the PICO-8 map editor. Call the map()
function to draw a region of the map (a subsection of the grid cells) onto the screen.
The map can be used 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. This can be used, along with using transparent color(s) 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. The bottom half of sprite data and the bottom half of map data share the same 4 KiB block of memory. If this shared memory is used, for sprites numbered >= 128, drawing from map coordinates that correspond to that memory (where cely >= 32) will result in interpreting the sprite data as map data. Likewise, if the map utilizes this shared memory for its bottom 32 rows of tiles, accessing sprites >= 128 will interpret map data as sprite 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 (often simplified as platformer). 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
The layer argument in map()
is useful when multiple layers are needed, such as a foreground or a wall in a top-down game. Here is an example _draw()
function including the use of the layer argument.
-- rendering the player and the tiles that will appear under and over the player
function _draw()
cls()
-- render the tiles that will be under the player
-- 0x40 is the equivalent of flag 6 on a tile
-- any tile with flag 6 will be rendered before the player
map(celx, cely, sx, sy, celw, celh, 0x40)
-- renders sprite/player
spr(pspr, px, py, pw, ph, pfaceleft)
-- render the tiles that will be over the player
-- 0x80 is the equivalent of flag 7 on a tile
-- any tile with flag 7 will be rendered after the player
map(celx, cely, sx, sy, celw, celh, 0x80)
-- flag 0 = 0x01, flag 1 = 0x02, flag 2 = 0x04, flag 3 = 0x08
-- flag 4 = 0x10, flag 5 = 0x20, flag 6 = 0x40, flag 7 = 0x80
end
Jelpi, a game included with PICO-8, uses map()
. Jelpi draws 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()
.