Colliders.lua

Attention: This page contains dead links!

Download Latest Version

Previous Version (2.0.1)

Colliders is a library that helps manage custom collisions in LunaLua, making custom behaviour much easier!

It supports native collisions between players, NPCs and animations, as well as custom Box and Circle colliders to be constructed.

As of version 2.1.0, this library requires VectR.lua (included in the download).

As of version 2.1.6, this library also requires expandedDefines.lua which is only included in SMBX2.

Installation

Place the file colliders.lua in either your level's custom graphics folder for use in a level, along with a lunadll.lua file, or in the same directory as your .wld file along with a lunaworld.lua file for use throughout an entire episode.

If you do not already have vectR.lua, also place that file into the same directory.

How to use

To enable the Colliders library for a specific level, add this line to lunadll.lua:

local colliders = API.load("colliders");

This will load the Colliders API.

Example

local colliders = API.load("colliders");
    
function onLoop()
    for k,v in pairs(NPC.get()) do
        if (colliders.collide(player, v)) then
            v:kill();
        end
    end
end

This will kill any NPC that touches the player (but may not stop them from killing the player too!)

The following is an example of creation of every kind of primitive collider:

local colliders = API.load("colliders");
    
local point = colliders.Point(-199824, -200208);
point:Debug(true);

local box = colliders.Box(-199740, -200224, 32, 32);
box:Debug(true);

local circle = colliders.Circle(-199624, -200208, 16);
circle:Debug(true);

local tri = colliders.Tri(-199524, -200208, {-16,16}, {0,-16}, {16, 16});
tri:Debug(true);

local poly = colliders.Poly(-199424, -200208, {-16,16}, {0,-16}, {16, 16}, {0,0});
poly:Debug(true);

This will create and draw 5 collider objects inside the level, and should look like this:

Documentation

Values

These are variables you can access

BLOCK_SOLID	A list of Block IDs for solid blocks. Includes blocks such as spikes, but does not include lava. Can be concatenated with other BLOCK_XXX lists.
BLOCK_SEMISOLID	A list of Block IDs for blocks that can be passed through, but can still be stood on (such as clouds). Can be concatenated with other BLOCK_XXX lists.
BLOCK_NONSOLID	A list of Block IDs for blocks that do not collide with the player. Can be concatenated with other BLOCK_XXX lists.
BLOCK_LAVA	A list of Block IDs for blocks that are lava. Can be concatenated with other BLOCK_XXX lists.
BLOCK_HURT	A list of Block IDs for blocks that harm the player (such as spikes or Jelectro). Can be concatenated with other BLOCK_XXX lists.
BLOCK_PLAYER	A list of Block IDs for blocks that are disabled when the player is a certain character. Can be concatenated with other BLOCK_XXX lists.

Classes

These are classes contained within this library

Vector (REMOVED AS OF 2.1.0. USE VECTR.LUA INSTEAD)

Values

Vector.x	The x value of the vector
Vector.y	The y value of the vector
Vector.magnitude	The magnitude value of the vector

Functions

Vector.dot		vector1	vector2
Calculates the dot product between two vectors	number	Vector The first vector.	Vector The second vector.
Vector:dot		vector
Calculates the dot product between the vector and another vector	number	Vector The other vector.
Vector:normalise
Calculates the normalised vector (can also be spelled "normalize")
Vector.add		vector1	vector2
Adds two vectors together (can also use the notation "a + b")	Vector	Vector The first vector.	Vector The second vector.
Vector:add		vector
Adds the vector to another vector	Vector	Vector The other vector.
Vector.subtract		vector1	vector2
Subtracts one vector from another vector (can also use the notation "a - b")	Vector	Vector The first vector.	Vector The second vector.
Vector:subtract		vector
Subtracts another vector from the vector	Vector	Vector The other vector.
Vector.mul		vector	scalar
Multiplies the vector by a constant (can also use the notation "v * c")	Vector	Vector The vector.	number The scalar.
Vector:mul		scalar
Multiplies the vector by a scalar	Vector	number The scalar.

Point

Values

Point.x	The x value of the point collider
Point.y	The y value of the point collider

Functions

Point:Draw		colour
Draws the collider to the screen with the specified RGBA colour. If no colour is supplied, the default will be used.	nil	number A 4-byte hexadecimal code supplying the colour to draw with. The default is 0x0099FF99.
Point:Debug		boolean
Tags the collider for debug drawing.	nil	boolean Tag or untag the collider.

Box

Values

Box.x	The x value of the top left of the box collider
Box.y	The y value of the top left of the box collider
Box.width	The width of the box collider
Box.height	The height of the box collider

Functions

Box:Draw		colour
Draws the collider to the screen with the specified RGBA colour. If no colour is supplied, the default will be used.	nil	number A 4-byte hexadecimal code supplying the colour to draw with. The default is 0xFF000099.
Box:Debug		boolean
Tags the collider for debug drawing.	nil	boolean Tag or untag the collider.

Circle

Values

Circle.x	The x value of the centre of the circle collider
Circle.y	The y value of the centre of the circle collider
Circle.radius	The radius of the circle collider

Functions

Circle:Draw		colour
Draws the collider to the screen with the specified RGBA colour. If no colour is supplied, the default will be used.	nil	number A 4-byte hexadecimal code supplying the colour to draw with. The default is 0xFF00FF99.
Circle:Debug		boolean
Tags the collider for debug drawing.	nil	boolean Tag or untag the collider.

Tri

Values

Tri.x	The x value of the triangle collider
Tri.y	The y value of the triangle collider
Tri.v	The vertex list of the triangle collider

Functions

Tri:Draw		colour
Draws the collider to the screen with the specified RGBA colour. If no colour is supplied, the default will be used.	nil	number A 4-byte hexadecimal code supplying the colour to draw with. The default is 0x00FF0099.
Tri:Debug		boolean
Tags the collider for debug drawing.	nil	boolean Tag or untag the collider.
Tri:Rotate		angle
Rotates the collider clockwise by the specified number of degrees.	nil	number Angle to rotate in degrees.
Tri:Translate		x	y
Translates the collider by the specified amount with respect to its position. This will change the origin of the triangle for scaling and rotating.	nil	number X coordinate to translate by.	number Y coordinate to translate by.
Tri:Scale		factor
Scales the collider by the specified scale factor.	nil	number Scale factor to resize the collider by.

Poly

Values

Poly.x	The x value of the polygon collider
Poly.y	The y value of the polygon collider
Poly.tris	The triangle list of the polygon collider, generated from a vertex list

Functions

Poly:Draw		colour
Draws the collider to the screen with the specified RGBA colour. If no colour is supplied, the default will be used.	nil	number A 4-byte hexadecimal code supplying the colour to draw with. The default is 0x0000FF99.
Poly:Debug		boolean
Tags the collider for debug drawing.	nil	boolean Tag or untag the collider.
Poly:Rotate		angle
Rotates the collider clockwise by the specified number of degrees.	nil	number Angle to rotate in degrees.
Poly:Translate		x	y
Translates the collider by the specified amount with respect to its position. This will change the origin of the polygon for scaling and rotating.	nil	number X coordinate to translate by.	number Y coordinate to translate by.
Poly:Scale		factor
Scales the collider by the specified scale factor.	nil	number Scale factor to resize the collider by.

External Use Functions

These are functions you will need to use the library

Point		x	y
Creates a Point collider.	Point	number The X coordinate of the collider.	number The Y coordinate of the collider.
Box		x	y	width	height
Creates a Box collider.	Box	number The X coordinate of the top-left corner of the collider.	number The Y coordinate of the top-left corner of the collider.	number The width of the collider.	number The height of the collider.
Circle		x	y	radius
Creates a Circle collider.	Circle	number The X coordinate of the centre of the collider.	number The Y coordinate of the centre of the collider.	number The radius of the collider.
Tri		x	y	point1	point2	point3
Creates a Triangle collider.	Tri	number The X coordinate of the collider.	number The Y coordinate of the collider.	pair(number) The coordinate of the first vertex.	pair(number) The coordinate of the second vertex.	pair(number) The coordinate of the third vertex.
Poly		x	y	...
Creates a Polygon collider. Will throw an error if two edges cross over each other.	Poly	number The X coordinate of the collider.	number The Y coordinate of the collider.	some pair(number)s A variable number of arguments, used to define the vertices of the polygon.
getAABB		aabb
Gets the Box collider defining the Axis-Aligned Bounding Box for the given object.	Box	NPC/Player/Animation/Point/Box/Circle/Tri/Poly The object to get the collider for. Box objects will return themselves.
getHitbox		object
Gets the primitive collider associated with the given object.	Point/Box/Circle/Tri/Poly	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly The object to get the collider for. Primitive colliders will return themselves.
getSpeedHitbox		object
Gets the Box or Circle collider associated with the given object, taking into account its movement speed.	Point/Box/Circle/Tri/Poly	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly The object to get the collider for. Box and Circle objects will return themselves with no speed modifier.
collide		object1	object2
Determines if two objects are touching.	boolean	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly The first object to test against.	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly The second object to test against.
speedCollide		object1	object2
Determines if two objects are touching, taking into account their movement speed.	boolean	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly The first object to test against. Box and Circle objects will not use a speed modifier.	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly The second object to test against. Box and Circle objects will not use a speed modifier.
bounce		object1	object2
Determines if the first object has just bounced on the second object. The second return value will be true if the first object is a spinjumping player. Box and Circle colliders cannot be used as the first object.	boolean,boolean	NPC/Player/Animation/Block The first object to test against.	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly The second object to test against.
bounceResponse		object	height
Causes the object to "bounce" upwards as if they had just jumped on an enemy.	nil	NPC/Player/Animation/Block The object to bounce	number:optional An optional bounce height modifier. By default, this will be the value of the jumpheightBounce() function.
slash		player	object
Determines if the given player has performed a sword slash and hit the object. Will return false if the player is not Lunk.	boolean	Player The player to test the slash.	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly The object to test against.
downSlash		player	object
Determines if the given player has performed a downward sword slash and hit the object. Will return false if the player is not Lunk.	boolean	Player The player to test the downward slash.	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly The object to test against.
tail		player	object
Determines if the given player has performed a tanooki tail spin and hit the object. Will return false if the player is not wearing a tanooki or racoon suit.	boolean	Player The player to test the tail spin.	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly The object to test against.
tongue		player	object
Determines if the given player has performed a Stupid horse tongue attack and hit the object. Will return false if the player is not riding a Stupid horse.	boolean	Player The player to test the tongue.	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly The object to test against.
collideNPC		object1	object2	section
Determines if two objects are colliding. Numbers can be substituted for objects, which will test against all NPCs with the given ID. Either ID can be given as a table of IDs to test multiple objects at once. Returns the number of detected collisions as a second object. Also returns a table containing pairs of colliding objects, or, if a specific collider was given as an argument, a table containing all objects that collide with that object. The table will be empty if both arguments are specific colliders.	boolean,number,table	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly/number/table of number The object or NPC ID to test with.	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly/number/table of number The object or NPC ID to test against.	number:optional Restrict the collision test to a specified section.
collideBlock		object1	object2	section
Determines if two objects are colliding. Numbers can be substituted for objects, which will test against all Blocks with the given ID. Either ID can be given as a table of IDs to test multiple objects at once. Returns the number of detected collisions as a second object. Also returns a table containing pairs of colliding objects, or, if a specific collider was given as an argument, a table containing all objects that collide with that object. The table will be empty if both arguments are specific colliders. Block IDs can also be supplied by using the BLOCK_XXX lists. Use the concatenation operator (..) to combine lists of Block IDs.	boolean,number,table	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly/number/table of number The object or Block ID to test with.	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly/number/table of number The object or Block ID to test against.	number:optional Restrict the collision test to a specified section.
collideNPCBlock		object1	object2	section
Determines if two objects are colliding. Numbers can be substituted for objects, which will test against all NPCs with the given ID for the first argument, or all Blocks with the given ID for the second argument. Either ID can be given as a table of IDs to test multiple objects at once. Returns the number of detected collisions as a second object. Also returns a table containing pairs of colliding objects, or, if a specific collider was given as an argument, a table containing all objects that collide with that object. The table will be empty if both arguments are specific colliders. Block IDs can also be supplied by using the BLOCK_XXX lists. Use the concatenation operator (..) to combine lists of Block IDs.	boolean,number,table	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly/number/table of number The object or NPC ID to test with.	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly/number/table of number The object or Block ID to test against.	number:optional Restrict the collision test to a specified section.
raycast		startpoint	direction	colliders
Creates a line starting from startpoint with the direction and length of direction, and determines whether any of the specified colliders intersect it, the point of the earliest intersection, the normal to the collider at that collision point, and the collider that it first intersected.	boolean,Vector2,Vector2,NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly	table of number/Point/Vector2 The starting point of the raycast.	table of number/Point/Vector2 The direction and length of the raycast.	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly/table of (NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly) List of colliders to test against.
linecast		startpoint	endpoint	colliders
Similar to raycast. This creates a line between startpoint and endpoint and performs the same tests. Determines whether any of the specified colliders intersect it, the point of the earliest intersection, the normal to the collider at that collision point, and the collider that it first intersected.	boolean,Vector2,Vector2,NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly	table of number/Point/Vector2 The starting point of the linecast.	table of number/Point/Vector2 The ending point of the linecast.	NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly/table of (NPC/Player/Animation/Block/Point/Box/Circle/Tri/Poly) List of colliders to test against.