Skip to content

Utils

Jump to bottom
Syyrion edited this page Nov 6, 2022 · 7 revisions

List of all utility functions.

The file utils.lua contains a variety of general purpose functions and constants. It also contains the Discrete Class.

Constants

Dimension Constants

Name Value Derived From
FOCUS_RATIO 0.625
PLAYER_WIDTH_UNFOCUSED 23
PLAYER_WIDTH_FOCUSED 14.375 PLAYER_WIDTH_UNFOCUSED * FOCUS_RATIO
PLAYER_TIP_DISTANCE_OFFSET 7.3
PLAYER_BASE_DISTANCE_OFFSET -2.025
PIVOT_RADIUS_TO_PLAYER_DISTANCE_RATIO 0.75
PIVOT_BORDER_WIDTH 5

Time Constants

Name Value Derived From
FRAMES_PER_SECOND 60 FPS (from base utils.lua)
SECONDS_PER_FRAME 0.016666... 1 / FRAMES_PER_SECOND
TICKS_PER_FRAME 4
FRAMES_PER_TICK 0.25 1 / TICKS_PER_FRAME
TICKS_PER_SECOND 240 FRAMES_PER_SECOND * TICKS_PER_FRAME
SECONDS_PER_TICK 0.00416666... 1 / TICKS_PER_SECOND
FRAMES_PER_PLAYER_ROTATION * 38.095238095... 800 / 21
TICKS_PER_PLAYER_ROTATION * 152.38095238... FRAMES_PER_PLAYER_ROTATION * TICKS_PER_FRAME
SECONDS_PER_PLAYER_ROTATION * 0.63492063... FRAMES_PER_PLAYER_ROTATION * SECONDS_PER_FRAME

* These assume a player speed multiplier of 1

Other Constants

Name Value Derived From
THICKNESS 40

Filters

These functions return true if their condition is met, false otherwise.

Types

  • Filter.NIL(val)
  • Filter.NUMBER(val)
  • Filter.STRING(val)
  • Filter.BOOLEAN(val)
  • Filter.TABLE(val)
  • Filter.FUNCTION(val)
  • Filter.THREAD(val)
  • Filter.USERDATA(val)

Numeric

  • Filter.POSITIVE(val)
  • Filter.NON_NEGATIVE(val)
  • Filter.NEGATIVE(val)
  • Filter.NON_POSITIVE(val)
  • Filter.NON_ZERO(val)
  • Filter.INTEGER(val)
  • Filter.NON_ZERO_INTEGER(val)
  • Filter.WHOLE(val)
  • Filter.NATURAL(val)
  • Filter.SIDE_COUNT(val)

General Utility

  • __NOP(...)
    No operation function. Returns all values passed to it.

  • __NIL(...)
    Similar to __NOP but doesn't return anything.

  • __TRUE(...)
    A function that always returns true.

  • __FALSE(...)
    A funtion that always returns false.

  • string.split(str, pattern)
    Splits a string with a pattern. The pattern must not contain any captures. Returns an ordered list of strings. An add-on to the string library.

  • string.gsplit(str, pattern)
    Returns an iterator function which iterates over all split strings. An add-on to the string library.

    Usage:

    for str in string.gsplit('hello world', '[e%s]') do print(str) end

    Output:

    h
llo
world

  • errorf(level, label, message, ...)
    Formatted error.

    Example:

    errorf(1, 'Example', 'Formatting example: %d', 10)

    Message:

    [ExampleError] Formatting example: 10

  • tableContainsValue(val, table)
    Tests whether a table contains a specific value on any existing key

  • rotate2DPointAroundOrigin(R, x, y)
    Takes a coordinate (<x>, <y>), rotates it by <R> radians about the origin and outputs the new coordinates as a tuple.

  • forceSetHue(h)
    Sets hue to a specific value by setting its min an max to the same value.

  • forceSetPulse(p)
    Sets pulse to a specific value by setting its min an max to the same value.

  • mapValue(i, a, b, c, d)
    Takes a value <i> between <a> and <b> and proportionally maps it to a value between <c> and <d>.

  • fromHSV(h, s, v)
    Converts the HSV color space to the RGB color space.

  • createSolidPolygonConstructor(sides, fn)
    Creates a table that is used to construct solid regular polygons using the minimum amount of custom walls with sides <sides> using the custom wall creation function <fn> (defaults to cw_createNoCollision()).

    Table Structure:

    {
    [<cw_key>] = {
        [0] = <vertex_0_angle>,
        [1] = <vertex_1_angle>,
        [2] = <vertex_2_angle>,
        [3] = <vertex_3_angle>
    }
    [<cw_key>] = {
        ...
    }
    ...
}

Waves

  • Wave.square(x, d)
    A square wave function with period 1 and amplitude 1 at value <x> with duty cycle <d> ranging from 0 to 1.
    Legacy name: squareWave

  • Wave.triangle(x, d)
    An asymmetrical triangle wave function with period 1 and amplitude 1 at value <x> Asymmetry can be adjusted with <d> and ranges from 0 to 1. An asymmetry of 1 is equivalent to a sawtooth wave. An asymmetry of 0 is equivalent to a reversed sawtooth wave.
    Legacy name: triangleWave

  • Wave.sawtooth(x)
    A sawtooth wave function with period 1 and amplitude 1 at value <x>.
    Legacy name: sawtoothWave

Dimensions

  • getDistanceBetweenCenterAndPlayer()
    Returns the distance from the center to the player position.

  • getDistanceBetweenCenterAndPlayerTip()
    Returns the distance from the center to tip of the player arrow.

  • getDistanceBetweenCenterAndPlayerBase(mFocus)
    Returns the distance from the center to the base of the player arrow (depends on focus).

  • getPlayerHeight(mFocus)
    Returns the distance from the base to the tip of the player arrow (depends on focus).

  • getPlayerBaseWidth(mFocus)
    Returns the base width of the player arrow (depends on focus).

  • getPlayerHalfBaseWidth(mFocus)
    Returns one half of the base width of the player arrow (depends on focus).

  • getCapRadius()
    Returns the radius of a circle circumscribed around the center polygon cap.

  • getPivotRadius()
    Returns the radius of a circle circumscribed around the center polygon.

Thickness and Delay

  • thicknessToFrames(th)
    Returns the amount of frames it takes for a certain thickness of wall to travel one full length of itself.

  • thicknessToTicks(th)
    Returns the amount of ticks it takes for a certain thickness of wall to travel one full length of itself.

  • thicknessToSeconds(th)
    Returns the amount of seconds it takes for a certain thickness of wall to travel one full length of itself.

  • framesToThickness(frames)
    Inverse of thicknessToFrames(th)

  • ticksToThickness(ticks)
    Inverse of thicknessToTicks(th)

  • secondsToThickness(seconds)
    Inverse of thicknessToSeconds(th)

  • getFramesPerPlayerRotation()
    Returns the amount of time in frames for the player make one full revolution adjusted for the player speed multiplier.

  • getTicksPerPlayerRotation()
    Returns the amount of time in ticks for the player make one full revolution adjusted for the player speed multiplier.

  • getSecondsPerPlayerRotation()
    Returns the amount of time in seconds for the player make one full revolution adjusted for the player speed multiplier.

  • getIdealDelayInFrames(sides)
    Returns the amount of time in frames for the player travel across one side.

  • getIdealDelayInTicks(sides)
    Returns the amount of time in ticks for the player travel across one side.

  • getIdealDelayInSeconds(sides)
    Returns the amount of time in seconds for the player travel across one side.

  • getIdealThickness(sides)
    The composition of the functions ticksToThickness(th) and getIdealDelayInTicks(sides).

Classes

Cascade

This class is mainly used to streamline the process of adding parameters to classes. Takes care of setter and getter functions and default values. This class is allowed to copy itself and will create a hierarchy of default values with a cascading effect.

  • Cascade.new(filter, init, def)
    Initializes a new CascadeChain class. The <filter> is a function used to verify whether input values are correct. The parameter <init> is the CascadeChain's default value (should be consistent with the filter). The get function can be exchanged with a different function <def>. This function can take a self argument and must return one and only one value that is consitent with the filter.

CascadeChain

  • CascadeChain:new(init, def)
    Creates a new CascadeChain class with value <init>, definition function <def>.

  • CascadeChain:set(val)
    Sets the value of class to <val>. Setting <val> to nil or an invalid type will cause the class value to be cleared.

  • CascadeChain:get()
    Gets the class value. If the class has no value, the function will return the superclass value.

  • CascadeChain:rawget()
    Gets the raw class value. Ignores inheritance.

  • CascadeChain:define(fn)
    Defines a class's value to be a function. This function will be called every time the value needs to be assessed. (Function should be as described in previous section.)

  • CascadeChain:freeze()
    Sets the value of the class to be it's closest inherited value. This function is equivalent to running:

    CascadeChain:set(nil)
CascadeChain:set(CascadeChain:get())

Channel

The Channel class is a special cascading class designed to handle colors.

  • Channel:setcolor(r, g, b)
    Sets the red, green, and blue channels. The alpha channel is untouched.

  • Channel:sethsv(h, s, v)
    Sets the red, green, and blue channels using the HSV color space. The alpha channel is untouched.

  • Channel:setalpha(a)
    Sets the alpha channel.

  • Channel:set(r, g, b, a)
    Sets the red, green, blue, and alpha channels.

  • Channel:get()
    Returns the red, green, blue, and alpha channels in that order.

  • Channel:rawget()
    Same as above but ignores inheritance.

  • Channel:define(fn)
    Defines the color to a function. The function is allowed to take arguments which can be set when calling Cascade:get(). The function must return 4 numbers for red, green, blue, and alpha. Returning anything else is undefined behavior.

  • Channel:freeze()
    Sets the channel to its closest inherited values.

Incrementer

This class is used to increment values over time. A starting value, target value, and the number of steps to take to reach the target value are used to increment or decrement values.

  • Incrementer:new(start, target, steps)
    Creates a new Incrementer class with starting value <start>, target value <target> and steps <steps>.

  • Incrementer:restart()
    Resets the incrementer back to its initial state.

  • Incrementer:increment()
    Advances the class to the next value. Returns the new value. If the target has been reached, the value is not changed.

  • Incrementer:get()
    Gets the value.

The information presented in this wiki is not guaranteed to be accurate. The information presented may be a few versions old.

Clone this wiki locally