MLib

MLib is a math and shape-intersection detection library written in Lua. It's aim is to be robust and easy to use.

NOTE:

• I am (slowly) working on completely rewriting this in order to be easier to use and less bug-prone. You can check out the progress here.
• I am currently slowing development of MLib while moving over to helping with CPML. To discuss this, please comment here.

If you are looking for a library that handles updating/collision responses for you, take a look at hxdx. It uses MLib functions as well as Box2d to handle physics calculations.

Downloading

You can download the latest stable version of MLib by downloading the latest release. You can download the latest working version of MLib by downloading the latest commit. Documentation will only be updated upon releases, not upon commits.

Implementing

To use MLib, simply place mlib.lua inside the desired folder in your project. Then use the require 'path.to.mlib' to use any of the functions.

Examples

If you don't have LÖVE installed, you can download the .zip of the demo from the Executables folder and extract and run the .exe that way. You can see some examples of the code in action here. All examples are done using the awesome engine of LÖVE. To run them properly, download the .love file and install LÖVE to your computer. After that, make sure you set .love files to open with "love.exe". For more, see here.

When should I use MLib?

• If you need to know exactly where two objects intersect.
• If you need general mathematical equations to be done.
• If you need very precise details about point intersections.

When should I not use MLib?

• All of the objects in a platformer, or other game, for instance, should not be registered with MLib. Only ones that need very specific information.
• When you don't need precise information/odd shapes.

Specs

Alternatively, you can find the tests here. Keep in mind that you may need to change certain semantics to suit your OS. You can run them via Telescope and type the following command in the command-line of the root folder:

tsc -f specs.lua

If that does not work, you made need to put a link to Lua inside of the folder for telescope and run the following command:

lua tsc -f specs.lua

If you encounter further errors, try to run the command line as an administrator (usually located in C:\Windows\System32\), then right-click on cmd.exe and select Run as administrator, then do

cd C:\Path\to\telescope\

And then run one of the above commands. If none of those work, just take my word for it that all the tests pass and look at this picture. 

Functions

• mlib.line
  • mlib.line.checkPoint
  • mlib.line.getClosestPoint
  • mlib.line.getYIntercept
  • mlib.line.getIntersection
  • mlib.line.getLength
  • mlib.line.getMidpoint
  • mlib.line.getPerpendicularSlope
  • mlib.line.getSegmentIntersection
  • mlib.line.getSlope
• mlib.segment
  • mlib.segment.checkPoint
  • mlib.segment.getPerpendicularBisector
  • mlib.segment.getIntersection
• mlib.polygon
  • mlib.polygon.checkPoint
  • mlib.polygon.getCentroid
  • mlib.polygon.getCircleIntersection
  • mlib.polygon.getLineIntersection
  • mlib.polygon.getPolygonArea
  • mlib.polygon.getPolygonIntersection
  • mlib.polygon.getSegmentIntersection
  • mlib.polygon.getSignedPolygonArea
  • mlib.polygon.getTriangleHeight
  • mlib.polygon.isCircleInside
  • mlib.polygon.isCircleCompletelyInside
  • mlib.polygon.isPolygonInside
  • mlib.polygon.isPolygonCompletelyInside
  • mlib.polygon.isSegmentInside
  • mlib.polygon.isSegmentCompletelyInside
• mlib.circle
  • mlib.circle.checkPoint
  • mlib.circle.getArea
  • mlib.circle.getCircleIntersection
  • mlib.circle.getCircumference
  • mlib.circle.getLineIntersection
  • mlib.circle.getSegmentIntersection
  • mlib.circle.isCircleCompletelyInside
  • mlib.circle.isCircleCompletelyInsidePolygon
  • mlib.circle.isPointOnCircle
  • mlib.circle.isPolygonCompletelyInside
• mlib.statistics
  • mlib.statistics.getCentralTendency
  • mlib.statistics.getDispersion
  • mlib.statistics.getMean
  • mlib.statistics.getMedian
  • mlib.statistics.getMode
  • mlib.statistics.getRange
  • mlib.statistics.getStandardDeviation
  • mlib.statistics.getVariance
  • mlib.statistics.getVariationRatio
• mlib.math
  • mlib.math.getAngle
  • mlib.math.getPercentage
  • mlib.math.getPercentOfChange
  • mlib.math.getQuadraticRoots
  • mlib.math.getRoot
  • mlib.math.getSummation
  • mlib.math.isPrime
  • mlib.math.round
• Aliases

mlib.line

• Deals with linear aspects, such as slope and length.

mlib.line.checkPoint

• Checks if a point lies on a line.
• Synopsis:
  • onPoint = mlib.line.checkPoint( px, px, x1, y1, x2, y2 )
• Arguments:
  • px, py: Numbers. The x and y coordinates of the point being tested.
  • x1, y1, x2, y2: Numbers. Two x and y coordinates of the line being tested.
• Returns:
  • onPoint: Boolean.
    • true if the point is on the line.
    • false if it does not.
• Notes:
  • You cannot use the format mlib.line.checkPoint( px, px, slope, intercept ) because this would lead to errors on vertical lines.

mlib.line.getClosestPoint

• Gives the closest point to a line.
• Synopses:
  • cx, cy = mlib.line.getClosestPoint( px, py, x1, y1, x2, y2 )
  • cx, cy = mlib.line.getClosestPoint( px, py, slope, intercept )
• Arguments:
  • x, y: Numbers. The x and y coordinates of the point.
  • x1, y1, x2, y2: Numbers. Two x and y coordinates on the line.
  • slope, intercept:
    • Numbers. The slope and y-intercept of the line.
    • Booleans (false). The slope and y-intercept of a vertical line.
• Returns:
  • cx, cy: Numbers. The closest points that lie on the line to the point.

mlib.line.getYIntercept

• Gives y-intercept of the line.
• Synopses:
  • intercept, isVertical = mlib.line.getYIntercept( x1, y1, x2, y2 )
  • intercept, isVertical = mlib.line.getYIntercept( x1, y1, slope )
• Arguments:
  • x1, y1, x2, y2: Numbers. Two x and y coordinates that lie on the line.
  • slope:
    • Number. The slope of the line.
• Returns:
  • intercept:
    • Number. The y-intercept of the line.
    • Number. The x1 coordinate of the line if the line is vertical.
  • isVertical:
    • Boolean. true if the line is vertical, false if the line is not vertical.

mlib.line.getIntersection

• Gives the intersection of two lines.
• Synopses:
  • x, y = mlib.line.getIntersection( x1, y1, x2, y2, x3, y3, x4, y4 )
  • x, y = mlib.line.getIntersection( slope1, intercept1, x3, y3, x4, y4 )
  • x, y = mlib.line.getIntersection( slope1, intercept1, slope2, intercept2 )
• Arguments:
  • x1, y1, x2, y2: Numbers. Two x and y coordinates that lie on the first line.
  • x3, y3, x4, y4: Numbers. Two x and y coordinates that lie on the second line.
  • slope1, intercept1:
    • Numbers. The slope and y-intercept of the first line.
    • Booleans (false). The slope and y-intercept of the first line (if the first line is vertical).
  • slope2, intercept2:
    • Numbers. The slope and y-intercept of the second line.
    • Booleans (false). The slope and y-intercept of the second line (if the second line is vertical).
• Returns:
  • x, y:
    • Numbers. The x and y coordinate where the lines intersect.
    • Boolean:
      • true, nil: The lines are collinear.
      • false, nil: The lines are parallel and not collinear.

mlib.line.getLength

• Gives the distance between two points.
• Synopsis:
  • `length = mlib.line.getLength( x1, y1, x2, y2 )
• Arguments:
  • x1, y1, x2, y2: Numbers. Two x and y coordinates.
• Returns:
  • length: Number. The distance between the two points.

mlib.line.getMidpoint

• Gives the midpoint of two poi