What is Ranlib?
Ranlib is a Random wrapper which includes new utilities for procedural generation. It serves to make randomness even more useful and convenient than ever before, grouping up many previously separate functionality from others, improving its design, as well as adding original ideas, making it distinct.
What can I use it for?
Ranlib allows generating more randomized complex objects, such as Enums, uniformly distributed points on a sphere, strings, etc. as well as providing commonly needed methods such as random selection and shuffling.
Documentation
Fields
Ranlib.Quantum
Quantum library for Ranlib.
Ranlib.Random
The Random object the wrapper is using.
Ranlib.State
The previous random output of the wrapper.
Ranlib.AntiRepetition = false
The previous random output of the wrapper.
Methods
Note: Arrays and Dictionaries are both tables, with the former having numerical indexes and the latter with non-numerical indexes.
Ranlib.new(seed: number): RanlibWrapper
Creates a new Random wrapper.
Ranlib.HashString(key: string || any): int32
Generates a hash using the given key. If the key is not a string, it will be converted into one using tostring().
Ranlib.OldHashString(key: string || any): int32
Generates a hash using the given key. If the key is not a string, it will be converted into one using tostring().
Ranlib.WorleyNoise2D(x: number, y: number, seed: number): number
Returns a worley noise value in 2D.
Ranlib.WorleyNoise3D(x: number, y: number, z: number, seed: number): number
Returns a worley noise value in 3D.
Ranlib:Clone(): RanlibWrapper
Creates a new Random wrapper with the same state.
Ranlib:SetSeed(newSeed: number): nil
Overwrite the seed of the wrapper
Ranlib:NextInteger(m: int?, n: int?): int
Gives the next integer using a and b as thresholds. if b is not specified, it will generate an integer between 0 and a. If both a and b are not specified, it will generate either a one or zero.
Ranlib:NextNumber(m: number?, n: number?): number
Gives the next number using a and b as thresholds. If b is not specified, it will generate a number between 0 and a. If both a and b are not specified, it will generate a number between one and zero.
Ranlib:NextTriangular(min: number, center: number, max: number): number
Gives the next random number in a triangular distribution using min and max as thresholds. The center is where the center of that distribution is located.
Ranlib:NextBoolean(): boolean
Gives the next boolean. Can either be true or false.
Ranlib:NextBiasedBoolean(percentTrue: number): boolean
Gives the next random boolean that is biased towards a certain outcome.
Ranlib:NextEnum(EnumTable: enum): Enum
Gives the next random Enum item inside an Enum.
Example:
local rand = Ranlib.new()
rand:NextEnum(Enum.KeyCode)
Returns a random key.
Ranlib:NextMaterial(): Enum.Material
Gives the next random Material.
Ranlib:NextColor(): Color3
Gives the next Color3.
Ranlib:NextBrickColor(): BrickColor
Gives the next BrickColor.
Ranlib:NextSphere(radius: number?, onlyUnit: boolean?): Vector3
Gives the next 3-D point on a sphere.
Ranlib:NextCircle(radius: number?, onlyUnit: boolean?): Vector2
Gives the next 2-D point on a circle.
Ranlib:NextBox(size: Vector3): Vector3
Gives the next 3-D point on a box.
Ranlib:NextAngle(): CFrame
Gives the next randomly rotated CFrame.
Ranlib:NextFlatAngle(): CFrame
Gives the next randomly rotated CFrame. The LookVector is parallel to the horizon.
Ranlib:NextAxis3D(flat: boolean): Vector3
Returns the next randomly chosen unit axial direction in 3 dimensions.
Ranlib:NextAxis2D(): Vector2
Returns the next randomly chosen unit axial direction in 2 dimensions.
Ranlib:NextSelect(array: array): any
Gives a random selection of an element in t.
Ranlib:NextKey(dictionary: dictionary, amount: int): any
Gives a random access key of a dictionary. The amount argument determines how many values (these are stored in an array; if this is not specified, it will return the key without being wrapped in an array) it returns.
Ranlib:NextShuffle(cards: table): table
Shuffles a copy of the table cards before returning the result.
Ranlib:NextChance(chanceDictionary: dictionary): any
Gives the next “chance” of a weighted table. For example, you could have a chance table that looks like this:
local chanceDictionary = {
Normal = 80,
Uncommon = 10,
Rare = 5,
Unique = 3,
Legendary = 2,
}
The method would then have an 80% chance to give a Normal, 10% a Uncommon, 5% a Rare, and etc.
Ranlib:LoadNextChanceState(chanceDictionary: dictionary): ChanceState
Returns a ChanceState object
ChanceState:NextChance(): any
Ranlib:GetPercentages(chanceDictionary: dictionary): dictionary
Gives the probability of a weighted table’s outcome. This is to help obey laws in the EU.
Ranlib:NextString(length: int): string
Gives the next string.
Ranlib:NextName(length: int, markovChain: table): string
Generates the next random name using a markov chain. The length argument determines how many terms are in the final string. Markov chains in this module are constructed like this:
local chain = {
a = {
a = 50,
b = 25,
c = 25
},
b = {
a = 25,
b = 50,
c = 25
},
c = {
a = 25,
b = 25,
c = 50
},
}
, where each term is listed in the dictionary, with chance tables for all future terms contained inside. If a markov chain is not specified, it will use the default one. The list of names the default chain can produce include but not limited to the following:
Anumizune
Ocolyaeses
Teb
Muso
Luretolyov
Lohas
Uxaumeiac
Azienal
Damememe
Results should be filtered before being shown to players.
Ranlib:LoadNextNameState(markovChain: table): NameState
Returns a NameState object
NameState:NextName(length: int): string
Quantum Library Methods
Ranlib.Quantum.NextNumber(min: number, max: number, requests: int): number | array | boolean, number
Requests the next quantum random numbers. Returns a random number and the time it took to request it. If requests is greater than 1, it will return an array of numbers instead.
Ranlib.Quantum.NextInteger(min: number, max: number, requests: int): number | array | boolean, number
Requests the next quantum random integers. Returns a random integer and the time it took to request it. If requests is greater than 1, it will return an array of integers instead.
Improvements
Roblox has announced that they are planning to adding a new method to their Random class called :NextUnitVector(), which I plan on incorporating into Ranlib’s current implementation.
Some methods could be further optimized by partially saving their local states, such as :NextEnum(), :NextName(), and :NextChance(), however, their current performance is adequate for release.
I am also considering adding more features such as more random variate generation, better anti-repetition abilities quasi-replacement capabilities, quantum/random.org true randomness, and smooth noise algorithms
