collision.h File Reference

SNES Collision Detection. More...

#include <snes/types.h>

Go to the source code of this file.

Classes
struct	Rect
	Axis-aligned bounding box (rectangle). More...

Functions
u8	collidePoint (s16 x, s16 y, const Rect *r)
	Check point vs rectangle collision.
u8	collideRect (const Rect *a, const Rect *b)
	Check rectangle vs rectangle collision (AABB).
u8	collideRectEx (const Rect *a, const Rect *b, s16 *overlapX, s16 *overlapY)
	Check if two rectangles overlap and return overlap amount.
u8	collideRectTile (const Rect *r, const u8 *tilemap, u16 mapWidth)
	Check collision between rectangle and tilemap.
u8	collideTile (s16 px, s16 py, const u8 *tilemap, u16 mapWidth)
	Check collision with tile at pixel coordinates.
u8	collideTileEx (s16 px, s16 py, const u8 *tilemap, u16 mapWidth, u8 tileSize)
	Check collision with tile using custom tile size.
u8	rectContains (const Rect *inner, const Rect *outer)
	Check if rectangle is completely inside another.
void	rectGetCenter (const Rect *r, s16 *cx, s16 *cy)
	Get rectangle center point.
void	rectInit (Rect *r, s16 x, s16 y, u16 w, u16 h)
	Initialize a rectangle.
void	rectSetPos (Rect *r, s16 x, s16 y)
	Set rectangle position.

Detailed Description

SNES Collision Detection.

Simple collision detection routines for game objects.

Overview

This module provides:

• Rectangle vs rectangle (AABB) collision
• Point vs rectangle collision
• Tile-based collision for platformers
• Bounding box helpers

Usage Example

// Define collision boxes for player and enemy
Rect playerBox = { player_x, player_y, 16, 16 };
Rect enemyBox = { enemy_x, enemy_y, 16, 16 };
 
// Check collision
if (collideRect(&playerBox, &enemyBox)) {
    // Handle collision
    player_hit();
}
 
// Tile-based collision (for platformers)
if (collideTile(player_x + 8, player_y + 16, tilemap, 32)) {
    // Player is standing on solid ground
    on_ground = 1;
}

Author

OpenSNES Team

Copyright

MIT License

Function Documentation

collidePoint()

u8 collidePoint	(	s16	x,
		s16	y,
		const Rect *	r )

Check point vs rectangle collision.

Tests if a point is inside a rectangle.

Parameters

x	Point X coordinate
y	Point Y coordinate
r	Rectangle to test against

Returns

1 if point is inside rectangle, 0 otherwise

// Check if bullet hits target
if (collidePoint(bullet_x, bullet_y, &target)) {
    target_hit();
}

collideRect()

u8 collideRect	(	const Rect *	a,
		const Rect *	b )

Check rectangle vs rectangle collision (AABB).

Tests if two axis-aligned bounding boxes overlap.

Parameters

a	First rectangle
b	Second rectangle

Returns

1 if rectangles overlap, 0 otherwise

Rect player = { px, py, 16, 16 };
Rect enemy = { ex, ey, 16, 16 };
if (collideRect(&player, &enemy)) {
    // Collision detected
}

Note

Read-only rectangles are const Rect * since 2026-09-20 — in this module that is correctness, not style. A static const Rect lives in an asset bank, and only a const-qualified read is a far read: through the old Rect * parameter (with the cast it forced on the caller) the fields were read from bank $00. Callers passing a plain Rect * are unaffected.

collideRectEx()

u8 collideRectEx	(	const Rect *	a,
		const Rect *	b,
		s16 *	overlapX,
		s16 *	overlapY )

Check if two rectangles overlap and return overlap amount.

Tests collision and returns the overlap distance for each axis. Useful for collision response (pushing objects apart).

Parameters

a	First rectangle
b	Second rectangle
overlapX	Receives the X displacement that moves a OUT of b (negative = move a left, positive = move a right)
overlapY	Receives the Y displacement (negative = up, positive = down)

Returns

1 if rectangles overlap, 0 otherwise

The values are displacements to ADD to a. Both axes are always filled; applying both moves the object diagonally, so resolve the smaller one. (This example subtracted them until 2026-09-20, which pushes the player deeper into the wall: for a = {10,10,16,16}, b = {20,20,16,16} the function returns dx = -6, and a must move LEFT.)

s16 dx, dy;
if (collideRectEx(&player, &wall, &dx, &dy)) {
    // Push player out of wall along the axis of least penetration
    if ((dx < 0 ? -dx : dx) < (dy < 0 ? -dy : dy)) player_x += dx;
    else                                           player_y += dy;
}

collideRectTile()

u8 collideRectTile	(	const Rect *	r,
		const u8 *	tilemap,
		u16	mapWidth )

Check collision between rectangle and tilemap.

Tests if any corner of the rectangle touches a solid tile. Useful for checking if a moving object would collide with the world.

Parameters

r	Rectangle to test
tilemap	Pointer to collision tilemap
mapWidth	Width of tilemap in tiles

Returns

1 if any corner touches solid tile, 0 otherwise. A corner off the map to the left, the top or the right counts as solid (collideTile()).

Note

The function does not know the map's height, so a rectangle whose bottom row lies past the last map row reads whatever follows the tilemap in ROM — usually a non-zero byte, so it reads as a wall, but nothing guarantees it. Keep r->y + r->height - 1 inside the map, or add a solid last row to the collision map.

Rect playerBox = { player_x, player_y, 16, 16 };
if (collideRectTile(&playerBox, collision_map, 32)) {
    // Player hit solid tiles
}

collideTile()

u8 collideTile	(	s16	px,
		s16	py,
		const u8 *	tilemap,
		u16	mapWidth )

Check collision with tile at pixel coordinates.

Looks up the tile at a given pixel position and returns whether it's solid. Tiles are assumed to be 8x8 pixels.

Parameters

px	Pixel X coordinate
py	Pixel Y coordinate
tilemap	Pointer to collision tilemap (1 byte per tile, 0=empty, nonzero=solid)
mapWidth	Width of tilemap in tiles

Returns

Tile value at position; 0 if empty. Off the map to the left, the top or the right (px < 0, py < 0, px >= mapWidth * 8) the function returns 1, "off the map is a wall" (since the v1 fix that let sprites slip past the left wall; this line said 0 until 2026-10-04). The bottom edge is not bounded: it does not know the map's height, so keep py inside the map.

Note

tilemap is const ON PURPOSE: const-qualified loads compile to bank-honouring far reads (#121), so the collision map may live in ANY bank — typically a multi-KB .incbin in a SUPERFREE section. With a non-const pointer the dereference is bank-$00-hardcoded and a map outside bank $00 reads garbage SILENTLY, which forced callers to waste RAM on their map.

// Check if player would hit ground
if (collideTile(player_x + 8, player_y + 16, collision_map, 32)) {
    player_vy = 0;  // Stop falling
    on_ground = 1;
}

collideTileEx()

u8 collideTileEx	(	s16	px,
		s16	py,
		const u8 *	tilemap,
		u16	mapWidth,
		u8	tileSize )

Check collision with tile using custom tile size.

Like collideTile() but allows custom tile sizes (8, 16, etc).

Parameters

px	Pixel X coordinate
py	Pixel Y coordinate
tilemap	Pointer to collision tilemap
mapWidth	Width of tilemap in tiles
tileSize	Size of tiles in pixels (must be power of 2: 8, 16, 32; anything else is treated as 8)

Returns

Tile value at position; 0 if empty. Off the map to the left, the top or the right the function returns 1, like collideTile() (this line said 0 until 2026-10-05; the code has said 1 since the v1 fix). The bottom edge is not bounded.

rectContains()

u8 rectContains	(	const Rect *	inner,
		const Rect *	outer )

Check if rectangle is completely inside another.

Parameters

inner	Inner rectangle (potentially contained)
outer	Outer rectangle (container)

Returns

1 if inner is completely inside outer, 0 otherwise

rectGetCenter()

void rectGetCenter	(	const Rect *	r,
		s16 *	cx,
		s16 *	cy )

Get rectangle center point.

Parameters

r	Rectangle
cx	Pointer to store center X
cy	Pointer to store center Y

rectInit()

void rectInit	(	Rect *	r,
		s16	x,
		s16	y,
		u16	w,
		u16	h )

Initialize a rectangle.

Parameters

r	Rectangle to initialize
x	Left edge X
y	Top edge Y
w	Width
h	Height

rectSetPos()

void rectSetPos	(	Rect *	r,
		s16	x,
		s16	y )

Set rectangle position.

Parameters

r	Rectangle to modify
x	New X position
y	New Y position