Array Utilities

"Check" Utilities

• rm.doesArrayHave will check an array for a given element and return true if it is present.

rm.doesArrayHave([1, 2, 3], 3) // true

rm.doesArrayHave([1, 2, 3], 4) // false

"Find" Utilities

• rm.arrayFirstElement and rm.arrayLastElement will return the first and last elements of an array, respectively.

const myArray = [1, 2, 3, 4]

rm.arrayFirstElement(myArray) // 1
rm.arrayLastElement(myArray) // 4

"Generate" Utilities

• rm.generateArray lets you create a new array given a length and a function to generate each element.

rm.generateArray(3, (x) => x * 2) // [0, 2, 4]

• rm.fillArrayWithValues gives you a new array which contains all whole numbers between a minimum and maximum.

rm.fillArrayWithValues(3, 5) // [3, 4, 5]

"Mutate" Utilities

• rm.arrayRemove allows you to remove an element at an index of an array, updating it's contents and length.

const myArray = [1, 6, 4, 7]

rm.arrayRemove(myArray, 2)
// myArray: [1, 6, 7]

• rm.arrayAppend allows you to add the elements of one array to another, modifying it.

const arr1 = [1, 6]
const arr2 = [5, 9]

rm.arrayAppend(arr1, arr2)
// arr1: [1, 6, 5, 9]

"Operation" Utilities

• rm.arrayAdd, rm.arraySubtract, rm.arrayMultiply and rm.arrayDivide all take in some arrays A and B, where A and B have the same length. A new array which is the result of A <operation> B is then returned.

const arr1 = [1, 6]
const arr2 = [5, 9]

rm.arrayAdd(arr1, arr2) // [6, 15]
rm.arraySubtract(arr1, arr2) // [-4, -3]
rm.arrayMultiply(arr1, arr2) // [5, 54]
rm.arrayDivide(arr1, arr2) // [0.2, 0.666...]

• rm.arrayLerp takes in array A and B of the same length, as well as a "fraction" value between 0 and 1. It returns a new array which is the result of lerping each component with each other based on the fraction.

const arr1 = [1, 6]
const arr2 = [5, 9]

rm.arrayLerp(arr1, arr2, 0.5) // [3, 7.5]

"Split" Utilities

• rm.arraySplit takes in an array, as well as a condition to run on each element. Elements that pass the condition will be put into a success array, and elements that fail will be put into a fail array. Both the success and fail arrays are returned.

const myArray = [1, 3]

rm.arraySplit(myArray, (x) => x > 2) // { success: [ 3 ], fail: [ 1 ] }

• rm.arraySplit2 takes in an array, as well as a function to run on each element which will return a "key" for an array that the element will be placed into. All of the keys and their arrays with the elements that went into them will be returned.

const myArray = [1, 3]

rm.arraySplit2(myArray, (x) => x * 2) // { "2": [ 1 ], "6": [ 3 ] }

Defining Number Arrays With Exact Length

Let me give you an example of a common pitfall which may be confusing to new TypeScript users. Let's say you have a position that you want to use in multiple places, so you make a variable to store it:

const myPosition = [0, 0, 0]

rm.geometry(map, {
    position: myPosition
})

If you try to plug it in somewhere, you'll get a pretty horrifying and confusing error. It may not be clear what's wrong at first because if you ran this code, it would work fine. So what's wrong?

It comes down to that last statement about the array potentially having "fewer elements". Essentially, positions in ReMapper are typically typed as [number, number, number] while the myPosition variable you just wrote would be inferred as number[].

The issue is that number[] isn't concerned with how many elements it has, just that it's all numbers. While [number, number, number] is requesting specifically three numbers. The usual way to get around this is by giving TypeScript a hint that you want only 3 numbers in your variable:

const myPosition: [number, number, number] = [0, 0, 0]

// OR use ReMapper built-in "Vec3" type
const myPosition: rm.Vec3 = [0, 0, 0]

However, I have created a more elegant solution to this, the rm.vec function. It will always prefer the exact number of elements you have. Simply pass your elements as parameters to the function, and it will give you a type which corresponds to it's length.