map.h File Reference

Scrolling tilemap engine for Mode 1 backgrounds. More...

#include <snes/types.h>

Go to the source code of this file.

Macros
#define	ACT_BURN   0x8000
#define	ACT_CLIMB   0x2000
#define	ACT_DIE   0x4000
#define	ACT_FALL   0x0004
#define	ACT_JUMP   0x0002
#define	ACT_STAND   0x0000
#define	ACT_WALK   0x0001
#define	MAP_OPT_1WAY   0x01
	Only allow scrolling to the right (no left scroll)
#define	MAP_OPT_BG2   0x02
	Scroll BG2 instead of BG1 (VRAM address is still $6800)
#define	T_EMPTY   0x0000
	Empty tile (object will fall through)
#define	T_FIRES   0x0002
	Fire tile (object burns)
#define	T_LADDER   0x0001
	Ladder tile (object can climb)
#define	T_PLATE   0x0008
	Platform tile (can jump through from below, land on top)
#define	T_SLOPED1   0x0021
	Slope 1x1 descending right (floor drops left-to-right)
#define	T_SLOPELD2   0x0023
	Slope 2x1 lower half descending right.
#define	T_SLOPELU2   0x0022
	Slope 2x1 lower half ascending right.
#define	T_SLOPEU1   0x0020
	Slope 1x1 ascending right (floor rises left-to-right)
#define	T_SLOPEUD2   0x0025
	Slope 2x1 upper half descending right.
#define	T_SLOPEUU2   0x0024
	Slope 2x1 upper half ascending right.
#define	T_SOLID   0xFF00
	Solid tile (blocks movement)
#define	T_SPIKE   0x0004
	Spike tile (object dies)

Functions
u16	mapGetMetaTile (u16 xpos, u16 ypos)
	Get metatile index at map coordinates.
u16	mapGetMetaTilesProp (u16 xpos, u16 ypos)
	Get tile collision property at map coordinates.
void	mapLoad (u8 *layer1map, u8 *layertiles, u8 *tilesprop)
	Load map data into the engine and flush to VRAM.
void	mapSetMapOptions (u8 optmap)
	Set map engine options.
void	mapUpdate (void)
	Update map scroll buffers based on camera position.
void	mapUpdateCamera (u16 xpos, u16 ypos)
	Update camera position to follow an object.
void	mapVblank (void)
	Transfer map updates to VRAM.

Variables
u16	x_pos
	Current camera X position in pixels.
u16	y_pos
	Current camera Y position in pixels.

Detailed Description

Scrolling tilemap engine for Mode 1 backgrounds.

Provides hardware-efficient tilemap streaming using metatiles (8x8 pixel blocks). Supports horizontal and vertical scrolling with incremental VRAM updates during VBlank.

Usage

#include <snes.h>
#include <snes/map.h>
 
extern u8 mapmario, tilesetdef, tilesetatt;
 
// Background tileset must be loaded at VRAM $2000 (tiles) and $6800 (tilemap)
bgInitTileSet(0, &tileset, &tilesetpal, 0, size, 16*2, BG_16COLORS, 0x2000);
bgSetMapPtr(0, 0x6800, SC_64x32);
 
// Load map data (flushes VRAM internally — screen must be off)
mapLoad(&mapmario, &tilesetdef, &tilesetatt);
 
setScreenOn();  // VRAM is ready
 
// In main loop:
while (1) {
    mapUpdate();                   // Update scroll buffers
    mapUpdateCamera(playerx, playery);
    WaitForVBlank();
    mapVblank();                   // DMA updates to VRAM
}

Note

Map engine uses VRAM address $6800 for the tilemap by default.

Attribution

Based on: PVSnesLib map engine by Alekmaul Original: undisbeliever's castle_platformer License: zlib (compatible with MIT)

Macro Definition Documentation

ACT_BURN

#define ACT_BURN   0x8000

Burning (bit 15 — flag, combinable with state)

ACT_CLIMB

#define ACT_CLIMB   0x2000

Climbing ladder (bit 13 — flag, combinable with state)

ACT_DIE

#define ACT_DIE   0x4000

Dying (bit 14 — flag, combinable with state)

ACT_FALL

#define ACT_FALL   0x0004

Falling

ACT_JUMP

#define ACT_JUMP   0x0002

Jumping

ACT_STAND

#define ACT_STAND   0x0000

Standing still

ACT_WALK

#define ACT_WALK   0x0001

Walking

MAP_OPT_1WAY

#define MAP_OPT_1WAY   0x01

Only allow scrolling to the right (no left scroll)

MAP_OPT_BG2

#define MAP_OPT_BG2   0x02

Scroll BG2 instead of BG1 (VRAM address is still $6800)

T_EMPTY

#define T_EMPTY   0x0000

Empty tile (object will fall through)

T_FIRES

#define T_FIRES   0x0002

Fire tile (object burns)

T_LADDER

#define T_LADDER   0x0001

Ladder tile (object can climb)

T_PLATE

#define T_PLATE   0x0008

Platform tile (can jump through from below, land on top)

T_SLOPED1

#define T_SLOPED1   0x0021

Slope 1x1 descending right (floor drops left-to-right)

T_SLOPELD2

#define T_SLOPELD2   0x0023

Slope 2x1 lower half descending right.

T_SLOPELU2

#define T_SLOPELU2   0x0022

Slope 2x1 lower half ascending right.

T_SLOPEU1

#define T_SLOPEU1   0x0020

Slope 1x1 ascending right (floor rises left-to-right)

T_SLOPEUD2

#define T_SLOPEUD2   0x0025

Slope 2x1 upper half descending right.

T_SLOPEUU2

#define T_SLOPEUU2   0x0024

Slope 2x1 upper half ascending right.

T_SOLID

#define T_SOLID   0xFF00

Solid tile (blocks movement)

T_SPIKE

#define T_SPIKE   0x0004

Spike tile (object dies)

Function Documentation

mapGetMetaTile()

u16 mapGetMetaTile	(	u16	xpos,
		u16	ypos
	)

Get metatile index at map coordinates.

Parameters

xpos	X coordinate in map pixels
ypos	Y coordinate in map pixels

Returns

Metatile index (0-511)

mapGetMetaTilesProp()

u16 mapGetMetaTilesProp	(	u16	xpos,
		u16	ypos
	)

Get tile collision property at map coordinates.

Parameters

xpos	X coordinate in map pixels
ypos	Y coordinate in map pixels

Returns

Tile property value (T_EMPTY, T_SOLID, T_LADDER, etc.)

mapLoad()

void mapLoad	(	u8 *	layer1map,
		u8 *	layertiles,
		u8 *	tilesprop
	)

Load map data into the engine and flush to VRAM.

Initializes metatile definitions, tile properties, and the row lookup table. Performs a full-screen tilemap refresh and DMAs it directly to VRAM. After this call, the tilemap is ready — no separate mapVblank() needed before setScreenOn().

Parameters

layer1map	Address of map data (format: u16 width, u16 height, u16 pad, then tile indices)
layertiles	Address of metatile definitions (4 tiles per metatile, max 512 metatiles)
tilesprop	Address of tile property data (collision types)

Note

Must be called during forced blank (screen off). The function writes directly to VRAM via DMA.

mapSetMapOptions()

void mapSetMapOptions

(

u8

optmap

)

Set map engine options.

Parameters

optmap

Options bitmask (MAP_OPT_1WAY, MAP_OPT_BG2)

mapUpdate()

void mapUpdate

(

void

)

Update map scroll buffers based on camera position.

Call once per frame in the main loop. Builds horizontal/vertical update buffers when the camera crosses tile boundaries.

mapUpdateCamera()

void mapUpdateCamera	(	u16	xpos,
		u16	ypos
	)

Update camera position to follow an object.

Centers the camera on the given coordinates with boundary clamping. Scroll trigger distances: X=128px from edges, Y=80px from edges.

Parameters

xpos	X coordinate to focus on (in map pixels)
ypos	Y coordinate to focus on (in map pixels)

mapVblank()

void mapVblank

(

void

)

Transfer map updates to VRAM.

Performs DMA transfers of scroll update buffers during VBlank. Also updates BG scroll registers.

Note

Must be called during VBlank (after WaitForVBlank).

Variable Documentation

x_pos

u16 x_pos

extern

Current camera X position in pixels.

y_pos

u16 y_pos

extern

Current camera Y position in pixels.