Utils

Methods

Utils.absClamp(value: number, min: number, max: number)

Limits the absolute value of a number between two positive numbers, then sets it to its original sign.

Arguments:

value: number	The value to limit.
min: number	The minimum bound. If the absolute value of the specified value is less than this number, it is set to it.
max: number	The maximum bound. If the absolute value of the specified value is greater than this number, it is set to it.

Returns:

result: number

The new limited number.

Utils.absMax(a: number, b: number)

Returns the number further from zero.

Arguments:

a: number	The first number to compare.
b: number	The second number to compare.

Returns:

result: number

The specified number that was further from zero than the other.

Utils.absMin(a: number, b: number)

Returns the number closer to zero.

Arguments:

a: number	The first number to compare.
b: number	The second number to compare.

Returns:

result: number

The specified number that was closer to zero than the other.

Utils.absoluteToLocalPath(target_dir: string, asset_path: string, source_dir: string)

Attempts to resolve a relative path from a Tiled export to a valid asset id, given it points to a path inside the target_dir of the current project.

Relative directories (..) of the asset path are resolved by starting from the source_dir, which should match the directory the Tiled data was exported to. Exporting to a different directory and copying/moving the exported data will likely cause this relative search to fail.

Arguments:

target_dir: string	The Kristal folder to get the path relative to.
asset_path: string	The asset path from a Tiled export to resolve.
source_dir: string	Parent directory of the Tiled export, which the `asset_path` should be relative to.

Returns:

asset_id: string?

The asset path relative the target_dir without its extension, or nil if the resolution failed.

Utils.all(tbl: [], func: (fun( <T)boolean)?)

Returns whether every value in a table is true, iterating numerically.

Arguments:

tbl: []	The table to iterate through.
func: (fun( <T)boolean)?	If provided, each value of the table will instead be passed into the function, whose returned value will be considered instead of the table value itself.

Returns:

result: boolean

Whether every value was true or not.

Utils.angle(x1: number, y1: number, x2: number, y2: number)

Returns the angle from one point to another, or from one object's position to another's.

Arguments:

x1: number	The horizontal position of the first point.
y1: number	The vertical position of the first point.
x2: number	The horizontal position of the second point.
y2: number	The vertical position of the second point.

Returns:

angle: number

The angle from the first point to the second point.

Utils.angleDiff(a: number, b: number)

Returns the distance between two angles, properly accounting for wrapping around.

Arguments:

a: number	The first angle to compare.
b: number	The second angle to compare.

Returns:

diff: number

The difference between the two angles.

Utils.any(tbl: [], func: (fun( <T)boolean)?)

Returns whether any individual value in a table is true, iterating numerically.

Arguments:

tbl: []	The table to iterate through.
func: (fun( <T)boolean)?	If provided, each value of the table will instead be passed into the function, whose returned value will be considered instead of the table value itself.

Returns:

result: boolean

Whether any value was true or not.

Utils.approach(val: number, target: number, amount: number)

Moves the specified value towards a target value by a specified amount, without exceeding the target.
If the target is less than the value, then the amount will be subtracted from the value instead to approach it.

Arguments:

val: number	The initial value.
target: number	The target value to approach.
amount: number	The amount the initial value should approach the target by.

Returns:

result: number

The new value. If the value would have passed the target value, it will instead be set to the target.

Utils.approachAngle(val: number, target: number, amount: number)

Moves the specified angle towards a target angle by a specified amount, properly accounting for wrapping around.
Will always approach in the direction with the shorter distance.

Arguments:

val: number	The initial angle.
target: number	The target angle to approach.
amount: number	The amount the initial angle should approach the target by.

Returns:

result: number

The new angle. If the angle would have passed the target angle, it will instead be set to the target.

Utils.between(val: number, a: number, b: number, include: boolean?)

Returns whether a value is between two numbers.

Arguments:

val: number	The value to compare.
a: number	The start value of the range.
b: number	The end value of the range.
include: boolean?	Determines whether the function should consider being equal to a range value to be "between". (Defaults to false)

Returns:

result: boolean

Whether the value was within the range.

Utils.ceil(value: number, to: number?)

Rounds the specified value up to the nearest integer.

Arguments:

value: number	The value to round.
to: number?	If specified, the value will instead be rounded up to the nearest multiple of this number.

Returns:

result: number

The rounded value.

Utils.clamp(val: number, min: number, max: number)

Limits the specified value to be between 2 bounds, setting it to be the respective bound if it exceeds it.

Arguments:

val: number	The value to limit.
min: number	The minimum bound. If the value is less than this number, it is set to it.
max: number	The maximum bound. If the value is greater than this number, it is set to it.

Returns:

result: number

The new limited number.

Utils.clampMap(val: number, min_a: number, max_a: number, min_b: number, max_b: number, mode: ("in-back"|"in-bounce"|"in-circ"|"in-cubic"|"in-elastic"...(+66))?)

Maps a value between a specified range to its equivalent position in a new range.

mode:
    | "linear"
    | "in-quad"
    | "in-cubic"
    | "in-quart"
    | "in-quint"
    | "in-sine"
    | "in-expo"
    | "in-circ"
    | "in-back"
    | "in-bounce"
    | "in-elastic"
    | "out-quad"
    | "out-cubic"
    | "out-quart"
    | "out-quint"
    | "out-sine"
    | "out-expo"
    | "out-circ"
    | "out-back"
    | "out-bounce"
    | "out-elastic"
    | "in-out-quad"
    | "in-out-cubic"
    | "in-out-quart"
    | "in-out-quint"
    | "in-out-sine"
    | "in-out-expo"
    | "in-out-circ"
    | "in-out-back"
    | "in-out-bounce"
    | "in-out-elastic"
    | "inQuad"
    | "outQuad"
    | "inOutQuad"
    | "outInQuad"
    | "inCubic"
    | "outCubic"
    | "inOutCubic"
    | "outInCubic"
    | "inQuart"
    | "outQuart"
    | "inOutQuart"
    | "outInQuart"
    | "inQuint"
    | "outQuint"
    | "inOutQuint"
    | "outInQuint"
    | "inSine"
    | "outSine"
    | "inOutSine"
    | "outInSine"
    | "inExpo"
    | "outExpo"
    | "inOutExpo"
    | "outInExpo"
    | "inCirc"
    | "outCirc"
    | "inOutCirc"
    | "outInCirc"
    | "inElastic"
    | "outElastic"
    | "inOutElastic"
    | "outInElastic"
    | "inBack"
    | "outBack"
    | "inOutBack"
    | "outInBack"
    | "inBounce"
    | "outBounce"
    | "inOutBounce"
    | "outInBounce"

Arguments:

val: number	The initial value in the initial range.
min_a: number	The start value of the initial range.
max_a: number	The end value of the initial range.
min_b: number	The start value of the new range.
max_b: number	The end value of the new range.
mode: ("in-back"\|"in-bounce"\|"in-circ"\|"in-cubic"\|"in-elastic"...(+66))?	If specified, the value's new position will be eased into the new range based on the percentage of its position in its initial range.

Returns:

result: number

The value within the new range.

Utils.clampWrap(val: number, min: number, max: number)

Limits the specified value to be between 2 bounds, wrapping around if it exceeds it.

Arguments:

val: number	The value to wrap.
min: number	The minimum bound. If not specified, defaults to `1` for array wrapping.
max: number	The maximum bound.

Returns:

result: number

The new wrapped number.

Utils.clear(tbl: table)

Empties a table of all defined values.

Arguments:

tbl: table

The table to clear.

Utils.colliderFromShape(parent: Object, data: table, x: number?, y: number?, properties: table?)

Creates a Collider based on a Tiled object shape.

Arguments:

parent: Object	The object that the new Collider should be parented to.
data: table	The Tiled shape data.
x: number?	An optional value defining the horizontal position of the collider.
y: number?	An optional value defining the vertical position of the collider.
properties: table?	A table defining additional properties for the collider.

Returns:

collider: Collider

The new Collider instance.

Utils.contains(str: string, filter: string)

Returns whether a string contains a given substring.

Arguments:

str: string	The string to check.
filter: string	The substring that the string may contain.

Returns:

result: boolean

Whether the string contained the specified substring.

Utils.containsValue(tbl: table, val: any)

Whether the table contains the specified value.

Arguments:

tbl: table	The table to check the value from.
val: any	The value to check.

Returns:

result: boolean

Whether the table contains the specified value.

Utils.copy(tbl: table?, deep: boolean?, seen: table?)

Makes a new copy of a table, giving it all of the same values.

Arguments:

tbl: table?	The table to copy.
deep: boolean?	Whether tables inside the specified table should be copied as well.
seen: table?	(Used internally) A table of values used to keep track of which objects have been cloned.

Returns:

new: table?

The new table.

Utils.copyInto(new_tbl: table, tbl: table, deep: boolean?, seen: table?)

Copies the values of one table into a different one.

Arguments:

new_tbl: table	The table receiving the copied values.
tbl: table	The table to copy values from.
deep: boolean?	Whether tables inside the specified table should be copied as well.
seen: table?	(Used internally) A table of values used to keep track of which objects have been cloned.

Returns:

1: nil

Utils.dist(x1: number, y1: number, x2: number, y2: number)

Returns the distance between two points.

Arguments:

x1: number	The horizontal position of the first point.
y1: number	The vertical position of the first point.
x2: number	The horizontal position of the second point.
y2: number	The vertical position of the second point.

Returns:

dist: number

The linear distance from the first point to the second point.

Utils.dump(o: any)

Returns a string converting a table value into readable text. Useful for debugging table values.

Arguments:

o: any

The value to convert to a string.

Returns:

result: string

The newly generated string.

Utils.ease(a: number, b: number, t: number, mode: "in-back"|"in-bounce"|"in-circ"|"in-cubic"|"in-elastic"...(+66))

Returns a value eased between two numbers, determined by a percentage from 0 to 1.

mode:
    | "linear"
    | "in-quad"
    | "in-cubic"
    | "in-quart"
    | "in-quint"
    | "in-sine"
    | "in-expo"
    | "in-circ"
    | "in-back"
    | "in-bounce"
    | "in-elastic"
    | "out-quad"
    | "out-cubic"
    | "out-quart"
    | "out-quint"
    | "out-sine"
    | "out-expo"
    | "out-circ"
    | "out-back"
    | "out-bounce"
    | "out-elastic"
    | "in-out-quad"
    | "in-out-cubic"
    | "in-out-quart"
    | "in-out-quint"
    | "in-out-sine"
    | "in-out-expo"
    | "in-out-circ"
    | "in-out-back"
    | "in-out-bounce"
    | "in-out-elastic"
    | "inQuad"
    | "outQuad"
    | "inOutQuad"
    | "outInQuad"
    | "inCubic"
    | "outCubic"
    | "inOutCubic"
    | "outInCubic"
    | "inQuart"
    | "outQuart"
    | "inOutQuart"
    | "outInQuart"
    | "inQuint"
    | "outQuint"
    | "inOutQuint"
    | "outInQuint"
    | "inSine"
    | "outSine"
    | "inOutSine"
    | "outInSine"
    | "inExpo"
    | "outExpo"
    | "inOutExpo"
    | "outInExpo"
    | "inCirc"
    | "outCirc"
    | "inOutCirc"
    | "outInCirc"
    | "inElastic"
    | "outElastic"
    | "inOutElastic"
    | "outInElastic"
    | "inBack"
    | "outBack"
    | "inOutBack"
    | "outInBack"
    | "inBounce"
    | "outBounce"
    | "inOutBounce"
    | "outInBounce"

Arguments:

a: number	The start value of the range.
b: number	The end value of the range.
t: number	The percentage (from 0 to 1) that determines the point on the specified range.
mode: "in-back"\|"in-bounce"\|"in-circ"\|"in-cubic"\|"in-elastic"...(+66)	The ease type to use between the two values. (Refer to https://easings.net/)

Returns:

1: number|unknown

Utils.endsWith(value: string|, suffix: string|)

Returns whether a string ends with the specified substring, or a table ends with the specified series of values.
The function will also return a second value, created by copying the initial value and removing the suffix.

Arguments:

value: string\|	The value to check the end of.
suffix: string\|	The prefix that should be checked.

Returns:

success: boolean	Whether the value ended with the specified suffix.
rest: string\|	A new value created by removing the suffix substring or values from the initial value. If the result was unsuccessful, this value will simply be the initial unedited value.

Utils.equal(a: any, b: any, deep: boolean?)

Returns whether two tables have an equivalent set of values.

Arguments:

a: any	The first table to compare.
b: any	The second table to compare.
deep: boolean?	Whether table values within these tables should also be compared using `Utils.equal()`.

Returns:

success: boolean

Whether the sets of values for the two tables were equivalent.

Utils.facingFromAngle(angle: number)

Returns a facing direction nearest to the specified angle.

direction:
    | "right"
    | "down"
    | "left"
    | "up"

Arguments:

angle: number

The angle to convert.

Returns:

direction: "down"|"left"|"right"|"up"

The facing direction the specified angle is closest to.

Utils.filter(tbl: [], filter: fun( <T)boolean)

Returns a new table containing only values that a function returns true for.

Arguments:

tbl: []	An array of values.
filter: fun( <T)boolean	A function that should return `true` for all values in the table to keep, and `false` for values to discard.

Returns:

result: []

A new array containing only approved values.

Utils.filterInPlace(tbl: [], filter: fun( <T)boolean)

Removes values from a table if a function does not return true for them.

Arguments:

tbl: []	An array of values.
filter: fun( <T)boolean	A function that should return `true` for all values in the table to keep, and `false` for values to discard.

Utils.findFiles(folder: any, base: any, path: any)

TODO: Merge with getFilesRecursive?

Arguments:

folder: any
base: any
path: any

Returns:

1: table

Utils.flatten(tbl: [][], deep: boolean?)

Merges a list of tables containing values into a single table containing each table's contents.

Arguments:

tbl: [][]	The array of tables to merge.
deep: boolean?	If true, tables contained inside listed tables will also be merged.

Returns:

result: []

The new table containing all values.

Utils.flipTable(tbl: table)

Flips the values of a 2-dimensional array, such that its columns become its rows, and vice versa.
As an example, the following table:

{
    {1, 2},
    {3, 4},
}

would result in this when passed into the function:

{
    {1, 3},
    {2, 4},
}

Arguments:

tbl: table

The table array to flip the values of.

Returns:

result: table

The new flipped array.

Utils.floor(value: number, to: number?)

Rounds the specified value down to the nearest integer.

Arguments:

value: number	The value to round.
to: number?	If specified, the value will instead be rounded down to the nearest multiple of this number.

Returns:

result: number

The rounded value.

Utils.format(str: string, tbl: table)

This function substitutes values from a table into a string using placeholders in the form of {key} or {}, where the latter indexes the table by number.

Arguments:

str: string	The string to substitute values into.
tbl: table	The table containing the values to substitute.

Returns:

result: string

The formatted string.

Utils.getAnyCase(t: , key: string)

Returns the value found for a string index, ignoring case-sensitivity.

Arguments:

t:	The table to get the value from.
key: string	The index to check within the table.

Returns:

value: ?

The value found at the specified index, or nil if no similar index was found.

Utils.getClassName(class: table, parent_check: boolean?)

Returns the name of a given class, using the name of the global variable for the class.
If it cannot find a global variable associated with the class, it will instead return the name of the class it extends, along with the class's ID.

Arguments:

class: table	The class instance to check.
parent_check: boolean?	Whether the function should only return the extended class, and not attach the class's ID, if the class does not have a global name.

Returns:

The name of the class, or nil if it cannot find one.

Utils.getCombinedText(text: string|table)

Concatenates exclusively string values within a table.

Arguments:

text: string|table

The table of values to combine.

Returns:

result: string

The concatenated string.

Utils.getDirname(path: string)

See: https ://stackoverflow.com/a/12191225

Arguments:

path: string

Returns:

dirname: string

Utils.getFacingVector(facing: "down"|"left"|"right"|"up")

Returns two numbers defining a vector based on the specified direction.

facing:
    | "right"
    | "down"
    | "left"
    | "up"

Arguments:

facing: "down"|"left"|"right"|"up"

The facing direction to get the vector of.

Returns:

x: number	The horizontal factor of the specified direction.
y: number	The vertical factor of the specified direction.

Utils.getFilesRecursive(dir: string, ext: string?)

Returns a table of file names within the specified directory, checking subfolders as well.

Arguments:

dir: string	The file path to check, relative to the LÖVE Kristal directory.
ext: string?	If specified, only files with the specified extension will be returned, and the extension will be stripped. (eg. `"png"` will only return .png files)

Returns:

result: string[]

The table of file names.

Utils.getIndex(t: [], value: )

Returns the position of a specified value found within an array.

Arguments:

t: []	The array to get the position from.
value:	The value to find the position of.

Returns:

position: number?

The position found for the specified value.

Utils.getKey(t: , value: )

Returns the non-numerical key of a specified value found within a table.

Arguments:

t:	The table to get the key from.
value:	The value to find the key of.

Returns:

key: ?

The key found for the specified value.

Utils.getKeys(t: )

Returns a list of every key in a table.

Arguments:

t:	The table to get the keys from.

Returns:

result: []

An array of each key in the table.

Utils.getLineIntersect(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, x4: number, y4: number, seg1: boolean?, seg2: boolean?)

Returns the point at which two lines intersect.

y:
    | "The lines are parallel."
    | "The lines don't intersect."
    | "The lines are the same."

Arguments:

x1: number	The horizontal position of the first point for the first line.
y1: number	The vertical position of the first point for the first line.
x2: number	The horizontal position of the second point for the first line.
y2: number	The vertical position of the second point for the first line.
x3: number	The horizontal position of the first point for the second line.
y3: number	The vertical position of the first point for the second line.
x4: number	The horizontal position of the second point for the second line.
y4: number	The vertical position of the second point for the second line.
seg1: boolean?	If true, the first line will be treated as a line segment instead of an infinite line.
seg2: boolean?	If true, the second line will be treated as a line segment instead of an infinite line.

Returns:

x: boolean\|number	If the lines intersected, this will be the horizontal position of the intersection; otherwise, this value will be `false`.
y: number\|"The lines are parallel."\|"The lines are the same."\|"The lines don't intersect."	If the lines intersected, this will be the vertical position of the intersection; otherwise, this will be a string describing why the lines did not intersect.

Utils.getPointOnPath(path: number, y, t: number)

Returns a point at a certain distance along a path.

Arguments:

path: number, y	An array of tables with X and Y values each, defining the coordinates of each point on the path.
t: number	The distance along the path that the point should be at.

Returns:

x: number	The horizontal position of the point found on the path.
y: number	The vertical position of the point found on the path.

Utils.getPolygonBounds(points: number[][])

Returns the bounds of a rectangle containing every point of a polygon.

Arguments:

points: number[][]

An array of tables with two number values each, defining the points of a polygon.

Returns:

x: number	The horizontal position of the bounds.
y: number	The vertical position of the bounds.
width: number	The width of the bounds.
height: number	The height of the bounds.

Utils.getPolygonEdges(points: number[][])

Returns a table of line segments based on a set of polygon points.

Arguments:

points: number[][]

An array of tables with two number values each, defining the points of a polygon.

Returns:

edges: number[], [2]

An array of tables containing four values each, defining line segments describing the edges of a polygon.

Utils.getPolygonOffset(points: number[][], dist: number)

Returns a new polygon with points offset outwards by a certain distance.

Arguments:

points: number[][]	An array of tables with two number values each, defining the points of a polygon.
dist: number	The distance to offset the points by. If this value is negative, the points will be offset inwards.

Returns:

A: number[][]

new polygon array.

Utils.group(tbl: [], count: number)

Creates a table grouping values of a table into a series of tables.

Arguments:

tbl: []	The table to group values from.
count: number	The amount of values that should belong in each group. If the table does not divide evenly, the final group of the returned table will be incomplete.

Returns:

result: [][]

The table containing the grouped values.

Utils.hexToRgb(hex: string, value: number?)

Converts a hex color string to an RGBA color table.

Arguments:

hex: string	The string to convert to RGB. The string must be formatted with a # at the start, eg. `"#ff00ff"`.
value: number?	An optional number specifying the alpha the returned table should have.

Returns:

rgba: number[]

The converted RGBA table.

Utils.hook(target: table, name: string, hook: fun( fun(...any), ...any), exact_func: boolean?)

Replaces a function within a class with a new function.
Also allows calling the original function, allowing you to add code to the beginning or end of existing functions.
Utils.hook() should always be called in Mod:init(). An example of how to hook a function is as follows:

-- this code will hook 'Object:setPosition(x, y)', and will be run whenever that function is called
-- all class functions receive the object instance as the first argument. in this function, i name that argument 'obj', and it refers to whichever object is calling 'setPosition()'
Utils.hook(Object, "setPosition", function(orig, obj, x, y)
    -- calls the original code (setting its position as normal)
    orig(obj, x, y)
    
    -- sets 'new_x' and 'new_y' variables for the object instance
    obj.new_x = x
    obj.new_y = y
end)

Arguments:

target: table	The class variable containing the function you want to hook.
name: string	The name of the function to hook.
hook: fun( fun(...any), ...any)	The function containing the new code to replace the old code with. Receives the original function as an argument, followed by the arguments the original function receives.
exact_func: boolean?	(Used internally) Whether the function should be replaced exactly, or whether it should be replaced with a function that calls the hook function. Should not be specified by users.

Utils.hookScript(include: (string|function||)?)

@param include — The class to extend from. If passed as a string, will be looked up from the current registry (e.g. scripts/data/actors if creating an actor) or the global namespace.

@return class — The new class, extended from include if provided.

@return super — Allows calling methods from the base class. self must be passed as the first argument to each method.

Arguments:

include: (string|function||)?

The class to extend from. If passed as a string, will be looked up from the current registry (e.g. scripts/data/actors if creating an actor) or the global namespace.

Returns:

class: function\|	The new class, extended from `include` if provided.
super: function\|\|function\|	Allows calling methods from the base class. `self` must be passed as the first argument to each method.

Utils.hslToRgb(h: number, s: number, l: number)

Converts HSL values to RGB values. Both HSL and RGB should be values between 0 and 1.

Arguments:

h: number	The hue value of the HSL color.
s: number	The saturation value of the HSL color.
l: number	The lightness value of the HSL color.

Returns:

r: number	The red value of the converted color.
g: number	The green value of the converted color.
b: number	The blue value of the converted color.

Utils.hsvToRgb(h: number, s: number, v: number)

Converts HSV values to RGB values. Both HSV and RGB should be values between 0 and 1.

Arguments:

h: number	The hue value of the HSV color.
s: number	The saturation value of the HSV color.
v: number	The 'value' value of the HSV color.

Returns:

r: number	The red value of the converted color.
g: number	The green value of the converted color.
b: number	The blue value of the converted color.

Utils.isArray(tbl: table)

Returns whether a table contains exclusively numerical indexes.

Arguments:

tbl: table

The table to check.

Returns:

result: boolean

Whether the table contains only numerical indexes or not.

Utils.isFacingAngle(facing: "down"|"left"|"right"|"up", angle: number)

Returns whether the specified angle is considered to be in the specified direction.

facing:
    | "right"
    | "down"
    | "left"
    | "up"

Arguments:

facing: "down"\|"left"\|"right"\|"up"	The facing direction to compare.
angle: number	The angle to compare.

Returns:

result: boolean

Whether the angle is closest to the specified facing direction.

Utils.isNaN(v: any)

Checks if the value is NaN (Not a Number)

Arguments:

v: any

Returns:

1: boolean

Utils.isPolygonClockwise(points: number[][])

Determines whether a polygon's points are clockwise or counterclockwise.

Arguments:

points: number[][]

An array of tables with two number values each, defining the points of a polygon.

Returns:

result: boolean

Whether the polygon is clockwise or not.

Utils.iterClass(class: table)

Iterates through the fields of a class (e.g. pairs) excluding special class variables and functions

Arguments:

Returns:

1: fun( table<K, V? <K)<K
2: table

Utils.len(input: string)

Returns the length of a string, while being UTF-8 aware.

Arguments:

input: string

The string to get the length of.

Returns:

length: integer

The length of the string.

Utils.lerp(a: number|, b: number|, t: number, oob: boolean?)

Returns a value between two numbers, determined by a percentage from 0 to 1.
If given a table, it will lerp between each value in the table.

Arguments:

a: number\|	The start value of the range.
b: number\|	The end value of the range.
t: number	The percentage (from 0 to 1) that determines the point on the specified range.
oob: boolean?	If true, then the percentage can be values beyond the range of 0 to 1.

Returns:

result: number|

The new value from the range.

Utils.lerpPoint(x1: number, y1: number, x2: number, y2: number, t: number, oob: boolean?)

Lerps between two coordinates.

Arguments:

x1: number	The horizontal position of the first point.
y1: number	The vertical position of the first point.
x2: number	The horizontal position of the second point.
y2: number	The vertical position of the second point.
t: number	The percentage (from 0 to 1) that determines the new point on the specified range between the specified points.
oob: boolean?	If true, then the percentage can be values beyond the range of 0 to 1.

Returns:

new_x: number	The horizontal position of the new point.
new_y: number	The vertical position of the new point.

Utils.merge(tbl: table, other: table, deep: boolean?)

Merges the values of one table into another one.

Arguments:

tbl: table	The table to merge values into.
other: table	The table to copy values from.
deep: boolean?	Whether shared table values between the two tables should also be merged.

Returns:

tbl: table

The initial table, now containing new values.

Utils.mergeColor(start_color: number[], end_color: number[], amount: number)

Merges two colors based on a percentage between 0 and 1.

Arguments:

start_color: number[]	The first table of RGBA values to merge.
end_color: number[]	The second table of RGBA values to merge.
amount: number	A percentage (from 0 to 1) that determines how much of the second color to merge into the first.

Returns:

result_color: number[]

A new table of RGBA values.

Utils.mergeMultiple(...: table)

Merges a list of tables into a new table.

Arguments:

...: table

The list of tables to merge values from.

Returns:

result: table

A new table containing the values of the series of tables provided.

Utils.orderedNext(table: , index: ?)

Equivalent of the next function, but returns the keys in the alphabetic order. We use a temporary ordered key table that is stored in the table being iterated. See: ~~http~~ ://lua-users.org/wiki/SortedIteration

Arguments:

table:
index: ?

Returns:

1: ?
2: ?

Utils.orderedPairs(t: )

Equivalent of the pairs() function on tables. Allows to iterate in order See: ~~http~~ ://lua-users.org/wiki/SortedIteration

Arguments:

t:	The table to iterate

Returns:

next: fun( table<K, V? <K)<K
t:
3: nil

Utils.override(old_func: function, new_func: fun( <T))

Returns a function that calls a new function, giving it an older function as an argument.
Essentially, it's a version of Utils.hook() that works with local functions.

Arguments:

old_func: function	The function to be passed into the new function.
new_func: fun( <T)	The new function that will be called by the result function.

Returns:

result_func: function

A function that will call the new function, providing the original function as an argument, followed by any other arguments that this function receives.

Utils.padString(str: string, len: number, beginning: boolean?, with: string?)

Returns a string with a specified length, filling it with empty spaces by default. Used to make strings consistent lengths for UI.
If the specified string has a length greater than the desired length, it will not be adjusted.

Arguments:

str: string	The string to extend.
len: number	The amount of characters the returned string should be.
beginning: boolean?	If true, the beginning of the string will be filled instead of the end.
with: string?	If specified, the string will be filled with this specified string, instead of with spaces.

Returns:

result: string

The new padded result.

Utils.parseColorProperty(property: string)

Converts a Tiled color property to an RGBA color table.

Arguments:

property: string

The property string to convert.

Returns:

rgba: number[]?

The converted RGBA table.

Utils.parseFlagProperties(flag: string?, inverted: string?, value: string?, default_value: any, properties: table)

Returns a series of values used to determine the behavior of a flag property for a Tiled event.

Arguments:

flag: string?	The name of the flag property.
inverted: string?	The name of the property used to determine if the flag should be inverted.
value: string?	The name of the property used to determine what the flag's value should be compared to.
default_value: any	If a property for the `value` name is not found, the value will be this instead.
properties: table	The properties table of a Tiled event's data.

Returns:

flag: string	The name of the flag to check.
inverted: boolean	Whether the result of the check should be inverted.
value: any	The value that the flag should be compared to.

Utils.parsePropertyList(id: string, properties: table)

Returns a table with values based on Tiled properties.
The function will check for a series of numbered properties starting with the specified id string, eg. "id1", followed by "id2", etc.

Arguments:

id: string	The name the series of properties should all start with.
properties: table	The properties table of a Tiled event's data.

Returns:

result: table

The list of property values found.

Utils.parsePropertyMultiList(id: string, properties: table)

Returns an array of tables with values based on Tiled properties.
The function will check for a series of layered numbered properties started with the specified id string, eg. "id1_1", followed by "id1_2", "id2_1", "id2_2", etc.

The returned table will contain a list of tables correlating to each individual list.
For example, the first table in the returned array will contain the values for "id1_1" and "id1_2", the second table will contain "id2_1" and "id2_2", etc.

Arguments:

id: string	The name the series of properties should all start with.
properties: table	The properties table of a Tiled event's data.

Returns:

result: table

The list of property values found.

Utils.parseTileGid(id: number)

Returns the actual GID and flip flags of a tile.

Arguments:

id: number

The GID of the tile.

Returns:

gid: integer	The GID of the tile without the flags.
flip_x: boolean	Whether the tile should be flipped horizontally.
flip_y: boolean	Whether the tile should be flipped vertically.
flip_diag: boolean	Whether the tile should be flipped diagonally.

Utils.pick(tbl: [], sort: (fun( <T)boolean)?, remove: boolean?)

Returns a random value from an array.

Arguments:

tbl: []	An array of values.
sort: (fun( <T)boolean)?	If specified, the table will be sorted via `Utils.filter(tbl, sort)` before selecting a value.
remove: boolean?	If true, the selected value will be removed from the given table.

Returns:

result:

The randomly selected value.

Utils.pickMultiple(tbl: [], amount: number, sort: (fun( <T)boolean)?, remove: any)

Returns multiple random values from an array, not selecting any value more than once.

Arguments:

tbl: []	An array of values.
amount: number	The amount of values to select from the table.
sort: (fun( <T)boolean)?	If specified, the table will be sorted via `Utils.filter(tbl, sort)` before selecting a value.
remove: any

Returns:

result:

A table containing the randomly selected values.

Utils.popPerformance()

Utils.printPerformance()

Utils.pushPerformance(name: any)

Arguments:

Utils.random(a: number?, b: number?, c: number?)

Returns a randomly generated decimal value.
If no arguments are provided, the value is between 0 and 1.
If a is provided, the value is between 0 and a.
If a and b are provided, the value is between a and b.
If c is provided, the value is between a and b, rounded to the nearest multiple of c.

Arguments:

a: number?	The first argument.
b: number?	The second argument.
c: number?	The third argument.

Returns:

rng: number

The new random value.

Utils.randomAxis()

Returns a table of 2 numbers, defining a vector in a random cardinal direction. (eg. {0, -1})

Returns:

vector: number[]

The vector table.

Utils.randomPointOnBorder(x: number, y: number, w: number, h: number)

Returns the coordinates a random point along the border of the specified rectangle.

Arguments:

x: number	The horizontal position of the topleft of the rectangle.
y: number	The vertical position of the topleft of the rectangle.
w: number	The width of the rectangle.
h: number	The height of the rectangle.

Returns:

x: number	The horizontal position of a random point on the rectangle border.
y: number	The vertical position of a random point on the rectangle border.

Utils.randomSign()

Returns either -1 or 1.

Returns:

sign: number

The new random sign.

Utils.removeDuplicates(tbl: table, deep: boolean?)

Remove duplicate elements from a table.

Arguments:

tbl: table	The table to remove duplicates from.
deep: boolean?	Whether tables inside the tbl will also have their duplicates removed.

Returns:

result: table

The new table that has its duplicates removed.

Utils.removeFromTable(tbl: table, val: )

Removes the specified value from the table.

Arguments:

tbl: table	The table to remove the value from.
val:	The value to be removed from the table.

Returns:

val: ?

The now removed value.

Utils.reverse(tbl: [], group: number?)

Returns a table containing the values of an array in reverse order.

Arguments:

tbl: []	An array of values.
group: number?	If defined, the values will be grouped into sets of the specified size, and those sets will be reversed.

Returns:

result: []

The new table containing the values of the specified array.

Utils.rgbToHex(rgb: number[])

Converts a table of RGB values to a hex color string.

Arguments:

rgb: number[]

The RGB table to convert. Values should be between 0 and 1.

Returns:

hex: string

The converted hex string. Formatted with a # at the start, eg. "#ff00ff".

Utils.rgbToHsl(r: number, g: number, b: number)

Converts RGB values to HSL values. Both RGB and HSL should be values between 0 and 1.

Arguments:

r: number	The red value of the RGB color.
g: number	The green value of the RGB color.
b: number	The blue value of the RGB color.

Returns:

h: number	The hue value of the converted color.
s: number	The saturation value of the converted color.
l: number	The lightness value of the converted color.

Utils.rotateTable(tbl: table, ccw: boolean?)

Rotates the values of a 2-dimensional array.
As an example, the following table:

{
    {1, 2},
    {3, 4},
}

would result in this when passed into the function, rotating it clockwise:

{
    {3, 1},
    {4, 2},
}

Arguments:

tbl: table	The table array to rotate the values of.
ccw: boolean?	Whether the rotation should be counterclockwise.

Returns:

result: table

The new rotated array.

Utils.roughEqual(a: number, b: number)

Returns whether two numbers are roughly equal (less than 0.01 away from each other).

Arguments:

a: number	The first value to compare.
b: number	The second value to compare.

Returns:

result: boolean

Whether the two values are roughly equal.

Utils.round(value: number, to: number?)

Rounds the specified value to the nearest integer.

Arguments:

value: number	The value to round.
to: number?	If specified, the value will instead be rounded to the nearest multiple of this number.

Returns:

result: number

The rounded value.

Utils.roundFromZero(value: number)

Rounds the specified value to the nearest integer away from zero.

Arguments:

value: number

The value to round.

Returns:

result: number

The rounded value.

Utils.roundToZero(value: number)

Rounds the specified value to the nearest integer towards zero.

Arguments:

value: number

The value to round.

Returns:

result: number

The rounded value.

Utils.shuffle(tbl: [])

Returns a table containing the values of another table, randomly rearranged.

Arguments:

tbl: []

An array of values.

Returns:

result: []

The new randomly shuffled array.

Utils.sign(num: number)

Returns the polarity of the specified value: -1 if it's negative, 1 if it's positive, and 0 otherwise.

Arguments:

num: number

The value to check.

Returns:

sign: number

The sign of the value.

Utils.split(input: string, separator: string, remove_empty: boolean?)

Splits a string into a new table of strings using a substring as a separator.
Less optimized than Utils.splitFast(), but allows separating with multiple characters, and is more likely to work for any string.

Arguments:

input: string	The string to separate.
separator: string	The substring used to split the main string.
remove_empty: boolean?	Whether strings containing no characters shouldn't be included in the result table.

Returns:

result: string[]

The table containing the new split strings.

Utils.splitFast(input: string, separator: string)

Splits a string into a new table of strings using a single character as a separator.
More optimized than Utils.split(), at the cost of lacking features.
Note: This function uses gmatch, so special characters must be escaped with a %.

Arguments:

input: string	The string to separate.
separator: string	The character used to split the main string.

Returns:

result: string[]

The table containing the new split strings.

Utils.squishAndTrunc(str: string, font: love.Font, max_width: number, def_scale: number?, min_scale: number?, trunc_affix: (string|false)?)

Finds and returns the scale required to print str with the font font, such that it's width does not exceed max_width.
If a min_scale is specified, strings that would have to be squished smaller than it will instead have their remaining part truncated.
Returns the input string (truncated if necessary), and the scale to print it at.

trunc_affix:
    | false

Arguments:

str: string	The string to squish and truncate.
font: love.Font	The font being used to print the string.
max_width: number	The maximum width the string should be able to take up.
def_scale: number?	The default scale used to print the string. Defaults to `1`.
min_scale: number?	The minimum scale that the string can be squished to before being truncated.
trunc_affix: (string\|false)?	The affix added to the string during truncation. If `false`, does not add an affix. Defaults to `...`.

Returns:

result: string	The truncated result. Returns the original string if it was not truncated.
scale: number	The scale the `result` string should be printed at to fit within the specified width.

Utils.startsWith(value: string|, prefix: string|)

Returns whether a string starts with the specified substring, or a table starts with the specified series of values.
The function will also return a second value, created by copying the initial value and removing the prefix.

Arguments:

value: string\|	The value to check the beginning of.
prefix: string\|	The prefix that should be checked.

Returns:

success: boolean	Whether the value started with the specified prefix.
rest: string\|	A new value created by removing the prefix substring or values from the initial value. If the result was unsuccessful, this value will simply be the initial unedited value.

Utils.stringInsert(str1: string, str2: string, pos: number)

Inserts a string into a different string at the specified position.

Arguments:

str1: string	The string to receive the substring.
str2: string	The substring to insert into the main string.
pos: number	The position at which to insert the string.

Returns:

result: string

The newly created string.

Utils.sub(input: string, from: integer?, to: integer?)

Returns a substring of the specified string, properly accounting for UTF-8.

Arguments:

input: string	The initial string to get a substring of.
from: integer?	The index that the substring should start at. (Defaults to 1, referring to the first character of the string)
to: integer?	The index that the substring should end at. (Defaults to -1, referring to the last character of the string)

Returns:

substring: string

The new substring.

Utils.tableLength(t: table)

Returns how many indexes a table has, including non-numerical indexes.

Arguments:

t: table

The table to check.

Returns:

result: number

The amount of indexes found.

Utils.titleCase(str: string)

Converts a string into a new string where the first letter of each "word" (determined by spaces between characters) will be capitalized.

Arguments:

str: string

The initial string to edit.

Returns:

result: string

The new string, in Title Case.

Utils.trim(str: string)

Strips a string of padding whitespace.

Arguments:

str: string

The initial string to edit.

Returns:

result: string

The new string, without padding whitespace.

Utils.unpack(t: [])

Returns every numerically indexed value of a table.
This fixes the issue with unpack() not returning nil values.

Arguments:

t: []

The table to unpack.

Returns:

...:	The values of the table.

Utils.unpackColor(color: number, [2]? })

Returns the values of an RGB table individually.

Arguments:

color: number, [2]? }

An RGB(A) table.

Returns:

r: number	The red value of the color.
g: number	The green value of the color.
b: number	The blue value of the color.
a: number	The alpha value of the color, or 1 if it was not specified.

Utils.unpackPolygon(points: number[][])

Converts a set of polygon points to a series of numbers.

Arguments:

points: number[][]

An array of tables with two number values each, defining the points of a polygon.

Returns:

...: number

A series of numbers describing the horizontal and vertical positions of each point in the polygon.

Utils.wave(val: number, min: number, max: number)

Returns a value between two numbers, sinusoidally positioned based on the specified value.

Arguments:

val: number	The number used to determine the sine position.
min: number	The start value of the range.
max: number	The end value of the range.

Returns:

result: number

The sine-based value within the range.

Utils.xor(...: any)

XOR (eXclusive OR) logic operation

Arguments:

...: any

[conditions]

Returns:

1: boolean

Kristal Wiki

Kristal Wiki

Methods

Utils.absClamp(value: number, min: number, max: number)

Utils.absMax(a: number, b: number)

Utils.absMin(a: number, b: number)

Utils.absoluteToLocalPath(target_dir: string, asset_path: string, source_dir: string)

Utils.all(tbl: [], func: (fun( <T)boolean)?)

Utils.angle(x1: number, y1: number, x2: number, y2: number)

Utils.angleDiff(a: number, b: number)

Utils.any(tbl: [], func: (fun( <T)boolean)?)

Utils.approach(val: number, target: number, amount: number)

Utils.approachAngle(val: number, target: number, amount: number)

Utils.between(val: number, a: number, b: number, include: boolean?)

Utils.ceil(value: number, to: number?)

Utils.clamp(val: number, min: number, max: number)

Utils.clampMap(val: number, min_a: number, max_a: number, min_b: number, max_b: number, mode: ("in-back"|"in-bounce"|"in-circ"|"in-cubic"|"in-elastic"...(+66))?)

Utils.clampWrap(val: number, min: number, max: number)

Utils.clear(tbl: table)

Utils.colliderFromShape(parent: Object, data: table, x: number?, y: number?, properties: table?)

Utils.contains(str: string, filter: string)

Utils.containsValue(tbl: table, val: any)

Utils.copy(tbl: table?, deep: boolean?, seen: table?)

Utils.copyInto(new_tbl: table, tbl: table, deep: boolean?, seen: table?)

Utils.dist(x1: number, y1: number, x2: number, y2: number)

Utils.dump(o: any)

Utils.ease(a: number, b: number, t: number, mode: "in-back"|"in-bounce"|"in-circ"|"in-cubic"|"in-elastic"...(+66))

Utils.endsWith(value: string|, suffix: string|)

Utils.equal(a: any, b: any, deep: boolean?)

Utils.facingFromAngle(angle: number)

Utils.filter(tbl: [], filter: fun( <T)boolean)

Utils.filterInPlace(tbl: [], filter: fun( <T)boolean)

Utils.findFiles(folder: any, base: any, path: any)

Utils.flatten(tbl: [][], deep: boolean?)

Utils.flipTable(tbl: table)

Utils.floor(value: number, to: number?)

Utils.format(str: string, tbl: table)

Utils.getAnyCase(t: , key: string)

Utils.getClassName(class: table, parent_check: boolean?)

Utils.getCombinedText(text: string|table)

Utils.getDirname(path: string)

Utils.getFacingVector(facing: "down"|"left"|"right"|"up")

Utils.getFilesRecursive(dir: string, ext: string?)

Utils.getIndex(t: [], value: )

Utils.getKey(t: , value: )

Utils.getKeys(t: )

Utils.getLineIntersect(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, x4: number, y4: number, seg1: boolean?, seg2: boolean?)

Utils.getPointOnPath(path: number, y, t: number)

Utils.getPolygonBounds(points: number[][])

Utils.getPolygonEdges(points: number[][])

Utils.getPolygonOffset(points: number[][], dist: number)

Utils.group(tbl: [], count: number)

Utils.hexToRgb(hex: string, value: number?)

Utils.hook(target: table, name: string, hook: fun( fun(...any), ...any), exact_func: boolean?)

Utils.hookScript(include: (string|function||)?)

Utils.hslToRgb(h: number, s: number, l: number)

Utils.hsvToRgb(h: number, s: number, v: number)

Utils.isArray(tbl: table)

Utils.isFacingAngle(facing: "down"|"left"|"right"|"up", angle: number)

Utils.isNaN(v: any)

Utils.isPolygonClockwise(points: number[][])

Utils.iterClass(class: table)

Utils.len(input: string)

Utils.lerp(a: number|, b: number|, t: number, oob: boolean?)

Utils.lerpPoint(x1: number, y1: number, x2: number, y2: number, t: number, oob: boolean?)

Utils.merge(tbl: table, other: table, deep: boolean?)

Utils.mergeColor(start_color: number[], end_color: number[], amount: number)

Utils.mergeMultiple(...: table)

Utils.orderedNext(table: , index: ?)

Utils.orderedPairs(t: )

Utils.override(old_func: function, new_func: fun( <T))

Utils.padString(str: string, len: number, beginning: boolean?, with: string?)

Utils.parseColorProperty(property: string)

Utils.parseFlagProperties(flag: string?, inverted: string?, value: string?, default_value: any, properties: table)

Utils.parsePropertyList(id: string, properties: table)

Utils.parsePropertyMultiList(id: string, properties: table)

Utils.parseTileGid(id: number)

Utils.pick(tbl: [], sort: (fun( <T)boolean)?, remove: boolean?)

Utils.pickMultiple(tbl: [], amount: number, sort: (fun( <T)boolean)?, remove: any)

Utils.popPerformance()