Colliders.lua

From PGE Wiki
Jump to: navigation, search

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 into the LuaScriptsLib folder.

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

How to use

To enable the Colliders library for a specific level, add this line to luna.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(npcs()) 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:

Colliders img 1.png

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.