Skip to main content

FusionUtil

A collection of utility functions for Fusion.

DO NOT ACCESS THIS IN MULTIPLE VMs. Studio freaks out when fusion is loaded in multiple VMs for some unknown reason.

Functions​

promiseStateChange​

</>
FusionUtil.promiseStateChange(
state: State<any>,--

The state to observe

callback: ((value: any) → boolean)?--

An optional condition to check before resolving the promise

) → Promise--

The promise that will resolve when the state changes

Creates a promise that resolves when the given state changes. If a callback is given then the callback must return true for the promise to resolve. 

local a = Value(10)
FusionUtil.promiseStateChange(a, function(value)
	return value > 10
end):andThen(function(value)
	print("Value is now greater than 10")
end)

a:set(5) -- Promise does not resolve
a:set(15) -- Promise resolves

defaultProps​

</>
FusionUtil.defaultProps(
explicitProps: Props,--

The props to use

defaultProps: Props--

The default props that to fill in the gaps of explicit

) → table--

The reconciled props

Similar to a shallow reconcile, but also moves any children at numeric indices

ensureIsState​

</>
FusionUtil.ensureIsState(
data: CanBeState<T>?,--

The potential state object

defaultValue: T?,--

The default value to use if the data is nil

datatype: (string | {string})?--

The type or types of the data expected in the state

) → StateObject<T>--

The existing or newly created state object

Ensures a passed data is a StateObject. If it is not, it will be converted to one.

ensureIsValue​

</>
FusionUtil.ensureIsValue(
data: T | Value<T>,--

The potential value

defaultValue: T?,--

The default value to use if the data is nil or an invalid type

datatype: (string | {string})?--

The type or types of the data expected in the value

) → Value<T>--

The existing or newly created value

Ensures the given data is a settable Value. Allows for passing of a default value and a datatype to check against.

syncValues​

</>
FusionUtil.syncValues(
stateToWatch: State<any>,--

The state to watch for changes

valueToSet: Value<any>--

The value to set when the state changes

) → () → ()--

A function that will disconnect the observer

Syncronizes a StateObject to a Value. The Value will be set to the StateObject's value any time it changes.

local a = Value(123)
local b = Value(0)
local disconnect = FusionUtil.syncValues(a, b)

print( peek(b) ) -- 123
a:set(456)
print( peek(b) ) -- 456

disconnect()

ensureAssetId​

</>
FusionUtil.ensureAssetId(
id: CanBeState<string | number>,--

The AssetId to ensure

default: (string | number)?--

The default AssetId to use if the id is nil

) → CanBeState<string>--

The State that is synced with the AssetId

Takes an AssetId and ensures it to a valid State.

local assetId = FusionUtil.ensureAssetId("rbxassetid://1234567890")
print( peek(assetId) ) -- "rbxassetid://1234567890"

local assetId = FusionUtil.ensureAssetId(1234567890)
print( peek(assetId) ) -- "rbxassetid://1234567890"

ratio​

</>
FusionUtil.ratio(
numerator: CanBeState<number>,--

The numerator of the ratio

denominator: CanBeState<number>,--

The denominator of the ratio

mutator: (CanBeState<T> | (
ratio: number,
use: Use
) → T)?--

An optional State to scale by or a function to mutate the ratio

) → State<T>--

The ratio (Potentially mutated)

Generates a computed that calculates the ratio of two numbers as a State.

local numerator = Value(100)
local denominator = Value(200)

local ratio = FusionUtil.ratio(numerator, denominator)
print( peek(ratio) ) -- 0.5

ratioUDim2​

</>
FusionUtil.ratioUDim2(
numerator: CanBeState<number>,--

The numerator of the ratio

denominator: CanBeState<number>,--

The denominator of the ratio

v: CanBeState<UDim2>--

The UDim2 to scale

) → State<UDim2>--

The scaled UDim2

Wraps FusionUtil.ratio with a handler for UDim2s

local numerator = Value(100)
local denominator = Value(200)
local size = Value(UDim2.new(0.2, 100, 0.2, 100))
local sizeAdjusted = FusionUtil.ratioUDim2(numerator, denominator, size)
print( peek(sizeAdjusted) ) -- UDim2.new(0.1, 50, 0.1, 50)

screenRatio​

This item only works when running on the client. Client
</>
FusionUtil.screenRatio(
mutator: (CanBeState<T> | (
ratio: number,
use: Use
) → T)?,--

An optional State to scale by or a function to mutate the ratio

ratioFn: any--

An optional function to use for the ratio, defaults to FusionUtil.ratio, but could be given something like FusionUtil.ratioUDim2

) → ()

This wraps FusionUtil.ratio with a handler for scaling states/functions with the Screen Height.

local paddingOffset = Value(10)

local paddingAdjusted = FusionUtil.screenRatio(paddingOffset)

local size = Value(UDim2.new(0, 100, 0, 100))

local sizeAdjusted = FusionUtil.screenRatio(size, FusionUtil.ratioUDim2)

local x = Value(10)
local y = Value(20)
local z = FusionUtil.screenRatio(function(ratio, use)
	return (use(x) + use(y)) * ratio
end)

lerpNumber​

</>
FusionUtil.lerpNumber(
n1: CanBeState<number>,--

The first number state

n2: CanBeState<number>,--

The second number state

alpha: CanBeState<number>,--

The alpha state

_use: ((any) → (any))?--

An optional function to use to get the values of the states

) → State<number> | number--

The resultant lerped number state

Lerps between two number states. If no use function is given then it returns a state

local a = Value(10)
local b = Value(20)
local alpha = Value(0.5)
local z = FusionUtil.lerpNumber(a, b, alpha)
print( peek(z) ) -- 15

ifThenElse​

</>
FusionUtil.ifThenElse(
stateToCheck: State<boolean>,--

The condition to check

trueOutcome: CanBeState<X>,--

The value to return if the condition is true

falseOutcome: CanBeState<Y>--

The value to return if the condition is false

) → State<X | Y>--

The value that was returned

A simple swap function that returns the first value if the condition is true, otherwise returns the second value. Helps with simplifying lots of bulky computeds. 

local a = Value(10)
local b = Value(20)

local y = Value(false)
local z = FusionUtil.ifThenElse(y, a, b)

print( peek(z) ) -- 20
y:set(true)
print( peek(z) ) -- 10

eq​

</>
FusionUtil.eq(
stateToCheck1: CanBeState<any>,--

The first potential state to check

stateToCheck2: CanBeState<any>--

The second potential state to check

) → State<boolean>--

A state resolving to the equality of the two given arguments

A simple equality function that returns true if the two states are equal.

local a = Value(10)
local b = Value(10)
local c = FusionUtil.eq(a, b)
print( peek(c) ) -- true
a:set(20)
print( peek(c) ) -- false

ifExists​

</>
FusionUtil.ifExists(
value: any?,--

Value to check existance.

fn: (T...) → U...,--

Callback to run if 'value' exists.

...: any--

Args to be passed to the callback.

) → U...?--

The returned value of the callback if 'value' exists.

Checks if a given value exists, if it does then this returns the returned value of the passed function.

ifIsState​

</>
FusionUtil.ifIsState(
state: any?,--

State to check existence.

fn: (T...) → U...,--

Callback to run if 'value' is a state.

...: any--

Args to be passed to the callback.

) → U...?--

The returned value of the callback if 'value' exists.

Checks if a given value is a state, if it does then this returns the returned value of the passed function.

observeState​

</>
FusionUtil.observeState(
fusionState: State<any>,--

The state object to observe

callback: (stateValue: any) → ()--

The callback to call when the fusionState is updated

) → () → ()--

A function that will disconnect the observer

Calls the provided callback immediately with the initial state and again anytime the state updates.

watchAttribute​

deprecated in v1.0.0
</>
This was deprecated in v1.0.0

Use Fusion's Attribute System instead

FusionUtil.watchAttribute(
parent: Instance,--

The parent instance to watch for attribute changes

attribute: string,--

The name of the attribute to watch

defaultValue: any?--

The default value to use if the attribute is nil

) → (
State,--

The state object that is synced with the value

() → ()--

A function that will disconnect the observer

)

Syncronizes an instances attribute to a Value. The value will be set to the attribute's value any time it changes. This is superceded by Fusion's Attribute System and should no longer be used.

Show raw api
{
    "functions": [
        {
            "name": "promiseStateChange",
            "desc": "Creates a promise that resolves when the given state changes.\nIf a callback is given then the callback must return true for the promise to resolve.\n\n\n```lua\nlocal a = Value(10)\nFusionUtil.promiseStateChange(a, function(value)\n\treturn value > 10\nend):andThen(function(value)\n\tprint(\"Value is now greater than 10\")\nend)\n\na:set(5) -- Promise does not resolve\na:set(15) -- Promise resolves\n```",
            "params": [
                {
                    "name": "state",
                    "desc": "The state to observe",
                    "lua_type": "State<any>"
                },
                {
                    "name": "callback",
                    "desc": "An optional condition to check before resolving the promise",
                    "lua_type": "((value: any) -> boolean)?"
                }
            ],
            "returns": [
                {
                    "desc": "The promise that will resolve when the state changes",
                    "lua_type": "Promise"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 81,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        },
        {
            "name": "defaultProps",
            "desc": "Similar to a shallow reconcile, but also moves any children at numeric indices",
            "params": [
                {
                    "name": "explicitProps",
                    "desc": "The props to use",
                    "lua_type": "Props"
                },
                {
                    "name": "defaultProps",
                    "desc": "The default props that to fill in the gaps of explicit",
                    "lua_type": "Props"
                }
            ],
            "returns": [
                {
                    "desc": "The reconciled props",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 103,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        },
        {
            "name": "ensureIsState",
            "desc": "Ensures a passed data is a StateObject. If it is not, it will be converted to one.",
            "params": [
                {
                    "name": "data",
                    "desc": "The potential state object",
                    "lua_type": "CanBeState<T>?"
                },
                {
                    "name": "defaultValue",
                    "desc": "The default value to use if the data is nil",
                    "lua_type": "T?"
                },
                {
                    "name": "datatype",
                    "desc": "The type or types of the data expected in the state",
                    "lua_type": "(string | { string })?"
                }
            ],
            "returns": [
                {
                    "desc": "The existing or newly created state object",
                    "lua_type": "StateObject<T>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 126,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        },
        {
            "name": "ensureIsValue",
            "desc": "Ensures the given data is a settable Value. Allows for passing of a default value and a datatype to check against.",
            "params": [
                {
                    "name": "data",
                    "desc": "The potential value",
                    "lua_type": "T | Value<T>"
                },
                {
                    "name": "defaultValue",
                    "desc": "The default value to use if the data is nil or an invalid type",
                    "lua_type": "T?"
                },
                {
                    "name": "datatype",
                    "desc": "The type or types of the data expected in the value",
                    "lua_type": "(string | { string })?"
                }
            ],
            "returns": [
                {
                    "desc": "The existing or newly created value",
                    "lua_type": "Value<T>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 163,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        },
        {
            "name": "syncValues",
            "desc": "Syncronizes a StateObject to a Value. The Value will be set to the StateObject's value any time it changes.\n\n\n```lua\nlocal a = Value(123)\nlocal b = Value(0)\nlocal disconnect = FusionUtil.syncValues(a, b)\n\nprint( peek(b) ) -- 123\na:set(456)\nprint( peek(b) ) -- 456\n\ndisconnect()\n```",
            "params": [
                {
                    "name": "stateToWatch",
                    "desc": "The state to watch for changes",
                    "lua_type": "State<any>"
                },
                {
                    "name": "valueToSet",
                    "desc": "The value to set when the state changes",
                    "lua_type": "Value<any>"
                }
            ],
            "returns": [
                {
                    "desc": "A function that will disconnect the observer",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 214,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        },
        {
            "name": "ensureAssetId",
            "desc": "Takes an AssetId and ensures it to a valid State<string>.\n\n\n```lua\nlocal assetId = FusionUtil.ensureAssetId(\"rbxassetid://1234567890\")\nprint( peek(assetId) ) -- \"rbxassetid://1234567890\"\n```\n```lua\nlocal assetId = FusionUtil.ensureAssetId(1234567890)\nprint( peek(assetId) ) -- \"rbxassetid://1234567890\"\n```",
            "params": [
                {
                    "name": "id",
                    "desc": "The AssetId to ensure",
                    "lua_type": "CanBeState<string | number>"
                },
                {
                    "name": "default",
                    "desc": "The default AssetId to use if the id is nil",
                    "lua_type": "(string | number)?"
                }
            ],
            "returns": [
                {
                    "desc": "The State<string> that is synced with the AssetId",
                    "lua_type": "CanBeState<string>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 239,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        },
        {
            "name": "ratio",
            "desc": "Generates a computed that calculates the ratio of two numbers as a State<number>.\n\n\n```lua\nlocal numerator = Value(100)\nlocal denominator = Value(200)\n\nlocal ratio = FusionUtil.ratio(numerator, denominator)\nprint( peek(ratio) ) -- 0.5\n```",
            "params": [
                {
                    "name": "numerator",
                    "desc": "The numerator of the ratio",
                    "lua_type": "CanBeState<number>"
                },
                {
                    "name": "denominator",
                    "desc": "The denominator of the ratio",
                    "lua_type": "CanBeState<number>"
                },
                {
                    "name": "mutator",
                    "desc": "An optional State to scale by or a function to mutate the ratio",
                    "lua_type": "(CanBeState<T> | (ratio: number, use: Use) -> T)?\n"
                }
            ],
            "returns": [
                {
                    "desc": "The ratio (Potentially mutated)",
                    "lua_type": "State<T>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 271,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        },
        {
            "name": "ratioUDim2",
            "desc": "Wraps FusionUtil.ratio with a handler for UDim2s\n\n\n```lua\nlocal numerator = Value(100)\nlocal denominator = Value(200)\nlocal size = Value(UDim2.new(0.2, 100, 0.2, 100))\nlocal sizeAdjusted = FusionUtil.ratioUDim2(numerator, denominator, size)\nprint( peek(sizeAdjusted) ) -- UDim2.new(0.1, 50, 0.1, 50)\n```",
            "params": [
                {
                    "name": "numerator",
                    "desc": "The numerator of the ratio",
                    "lua_type": "CanBeState<number>"
                },
                {
                    "name": "denominator",
                    "desc": "The denominator of the ratio",
                    "lua_type": "CanBeState<number>"
                },
                {
                    "name": "v",
                    "desc": "The UDim2 to scale",
                    "lua_type": "CanBeState<UDim2>\n"
                }
            ],
            "returns": [
                {
                    "desc": "The scaled UDim2",
                    "lua_type": "State<UDim2>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 309,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        },
        {
            "name": "screenRatio",
            "desc": "This wraps FusionUtil.ratio with a handler for scaling states/functions with the Screen Height.\n\n\n```lua\nlocal paddingOffset = Value(10)\n\nlocal paddingAdjusted = FusionUtil.screenRatio(paddingOffset)\n```\n```lua\nlocal size = Value(UDim2.new(0, 100, 0, 100))\n\nlocal sizeAdjusted = FusionUtil.screenRatio(size, FusionUtil.ratioUDim2)\n```\n```lua\nlocal x = Value(10)\nlocal y = Value(20)\nlocal z = FusionUtil.screenRatio(function(ratio, use)\n\treturn (use(x) + use(y)) * ratio\nend)\n```",
            "params": [
                {
                    "name": "mutator",
                    "desc": "An optional State to scale by or a function to mutate the ratio",
                    "lua_type": "(CanBeState<T> | (ratio: number, use: Use) -> T)?"
                },
                {
                    "name": "ratioFn",
                    "desc": "An optional function to use for the ratio, defaults to FusionUtil.ratio, but could be given something like FusionUtil.ratioUDim2",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "static",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 347,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        },
        {
            "name": "lerpNumber",
            "desc": "Lerps between two number states. If no use function is given then it returns a state\n\n\n```lua\nlocal a = Value(10)\nlocal b = Value(20)\nlocal alpha = Value(0.5)\nlocal z = FusionUtil.lerpNumber(a, b, alpha)\nprint( peek(z) ) -- 15\n```",
            "params": [
                {
                    "name": "n1",
                    "desc": "The first number state",
                    "lua_type": "CanBeState<number>"
                },
                {
                    "name": "n2",
                    "desc": "The second number state",
                    "lua_type": "CanBeState<number>"
                },
                {
                    "name": "alpha",
                    "desc": "The alpha state",
                    "lua_type": "CanBeState<number>"
                },
                {
                    "name": "_use",
                    "desc": "An optional function to use to get the values of the states",
                    "lua_type": "((any) -> (any))?"
                }
            ],
            "returns": [
                {
                    "desc": "The resultant lerped number state",
                    "lua_type": "State<number> | number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 372,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        },
        {
            "name": "ifThenElse",
            "desc": "A simple swap function that returns the first value if the condition is true, otherwise returns the second value.\nHelps with simplifying lots of bulky computeds.\n\n\n```lua\nlocal a = Value(10)\nlocal b = Value(20)\n\nlocal y = Value(false)\nlocal z = FusionUtil.ifThenElse(y, a, b)\n\nprint( peek(z) ) -- 20\ny:set(true)\nprint( peek(z) ) -- 10\n```",
            "params": [
                {
                    "name": "stateToCheck",
                    "desc": "The condition to check",
                    "lua_type": "State<boolean>"
                },
                {
                    "name": "trueOutcome",
                    "desc": "The value to return if the condition is true",
                    "lua_type": "CanBeState<X>"
                },
                {
                    "name": "falseOutcome",
                    "desc": "The value to return if the condition is false",
                    "lua_type": "CanBeState<Y>"
                }
            ],
            "returns": [
                {
                    "desc": "The value that was returned",
                    "lua_type": "State<X|Y>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 404,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        },
        {
            "name": "eq",
            "desc": "A simple equality function that returns true if the two states are equal.\n\t\n\n```lua\nlocal a = Value(10)\nlocal b = Value(10)\nlocal c = FusionUtil.eq(a, b)\nprint( peek(c) ) -- true\na:set(20)\nprint( peek(c) ) -- false\n```",
            "params": [
                {
                    "name": "stateToCheck1",
                    "desc": "The first potential state to check",
                    "lua_type": "CanBeState<any>"
                },
                {
                    "name": "stateToCheck2",
                    "desc": "The second potential state to check",
                    "lua_type": "CanBeState<any>"
                }
            ],
            "returns": [
                {
                    "desc": "A state resolving to the equality of the two given arguments",
                    "lua_type": "State<boolean>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 428,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        },
        {
            "name": "ifExists",
            "desc": "Checks if a given value exists, if it does then this returns the returned value of the passed function.",
            "params": [
                {
                    "name": "value",
                    "desc": "Value to check existance.",
                    "lua_type": "any?"
                },
                {
                    "name": "fn",
                    "desc": "Callback to run if 'value' exists.",
                    "lua_type": "(T...) -> U..."
                },
                {
                    "name": "...",
                    "desc": "Args to be passed to the callback.",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "The returned value of the callback if 'value' exists.",
                    "lua_type": "U...?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 444,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        },
        {
            "name": "ifIsState",
            "desc": "Checks if a given value is a state, if it does then this returns the returned value of the passed function.",
            "params": [
                {
                    "name": "state",
                    "desc": "State to check existence.",
                    "lua_type": "any?"
                },
                {
                    "name": "fn",
                    "desc": "Callback to run if 'value' is a state.",
                    "lua_type": "(T...) -> U..."
                },
                {
                    "name": "...",
                    "desc": "Args to be passed to the callback.",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "The returned value of the callback if 'value' exists.",
                    "lua_type": "U...?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 458,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        },
        {
            "name": "observeState",
            "desc": "Calls the provided callback immediately with the initial state and again anytime the state updates.",
            "params": [
                {
                    "name": "fusionState",
                    "desc": "The state object to observe",
                    "lua_type": "State<any>"
                },
                {
                    "name": "callback",
                    "desc": "The callback to call when the fusionState is updated",
                    "lua_type": "(stateValue: any) -> ()"
                }
            ],
            "returns": [
                {
                    "desc": "A function that will disconnect the observer",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 471,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        },
        {
            "name": "watchAttribute",
            "desc": "Syncronizes an instances attribute to a Value. The value will be set to the attribute's value any time it changes.\nThis is superceded by Fusion's Attribute System and should no longer be used.",
            "params": [
                {
                    "name": "parent",
                    "desc": "The parent instance to watch for attribute changes",
                    "lua_type": "Instance"
                },
                {
                    "name": "attribute",
                    "desc": "The name of the attribute to watch",
                    "lua_type": "string"
                },
                {
                    "name": "defaultValue",
                    "desc": "The default value to use if the attribute is nil",
                    "lua_type": "any?"
                }
            ],
            "returns": [
                {
                    "desc": "The state object that is synced with the value",
                    "lua_type": "State"
                },
                {
                    "desc": "A function that will disconnect the observer",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "static",
            "deprecated": {
                "version": "v1.0.0",
                "desc": "Use Fusion's Attribute System instead"
            },
            "source": {
                "line": 493,
                "path": "src/railutils/src/RailUtil/FusionUtil.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "FusionUtil",
    "desc": "A collection of utility functions for Fusion.\n\nDO NOT ACCESS THIS IN MULTIPLE VMs. Studio freaks out when\nfusion is loaded in multiple VMs for some unknown reason.",
    "source": {
        "line": 12,
        "path": "src/railutils/src/RailUtil/FusionUtil.lua"
    }
}