Fusion Documentation

Fusion is a portable Luau companion library designed to enable simpler, more descriptive, and predictable code. It allows developers to assemble straightforward logic chains that are easy to debug and make strong guarantees about code behavior.

Key features include:

• Portability: Works with any Luau environment.
• Roblox Support: Provides batteries-included configuration specifically for Roblox.
• Extensibility: Designed for deep integration and custom API building in any Luau-based universe.

The Fusion API Reference provides technical documentation for the library's core modules. The API is organized into several functional areas:

• General: Error handling and contextual/safe execution patterns.
• Memory: Management of Scope, innerScope, doCleanup, and scoped operations.
• Graph: Reactive graph management, specifically the Observer.
• State: Reactive state primitives including UsedAs, Computed, peek, and Value.
• Animation: Motion primitives like Spring and Tween.
• Roblox: Integration utilities for Roblox-specific objects, such as Child, Children, Hydrate, and New.

For beginners, it is recommended to start with the tutorials before diving into the technical API reference.

A StateObject<T> is a reactive graph object that stores a value of type T which can change over time. It inherits from GraphObject, meaning it can broadcast updates to the reactive graph whenever its value changes.

Important Note for End-Users: This type is primarily an internal implementation detail of Fusion. You should not use StateObject directly in your application logic. Instead, you should use the UsedAs<T> type for your own code to interact with reactive values.

export type StateObject<T> = GraphObject & {
	type: "State",
	kind: string,
	_EXTREMELY_DANGEROUS_usedAsValue: T
}

The Animatable type defines a set of data types that Fusion can decompose into a tuple of parameters for smooth interpolation during animations. If you use a type not included in this list with Tween or Spring objects, the value will not animate; instead, it will immediately snap to its goal value.

-- Supported Animatable types:
export type Animatable =
	number |
	CFrame |
	Color3 |
	ColorSequenceKeypoint |
	DateTime |
	NumberRange |
	NumberSequenceKeypoint |
	PhysicalProperties |
	Ray |
	Rect |
	Region3 |
	Region3int16 |
	UDim |
	UDim2 |
	Vector2 |
	Vector2int16 |
	Vector3 |
	Vector3int16

In Fusion, components are implemented as standard Luau functions. To create a component, define a function that accepts a scope as its first parameter and a props table as its second. The function should return Fusion content (like an instance created via scope:New).

By placing scope first, you enable users to use the scoped() syntax, allowing them to call your component as a method of the scope (e.g., scope:ComponentName).

local function Button(
	scope: Fusion.Scope,
	props: {
		ButtonText: UsedAs<string>
	}
) 
    return scope:New "TextButton" {
        Text = props.ButtonText
    }
end

-- Usage via bare function call:
local btn = Button(scope, { ButtonText = "Hello" })

-- Usage via scoped() syntax:
local scope = scoped(Fusion, { Button = Button })
local btn = scope:Button { ButtonText = "Hello" }

A Value is Fusion's simplest state object. It stores a single piece of data that can be updated and read.

• Creation: Use scope:Value(initialValue) to create a new value object within a scope.
• Reading: Use the global peek(valueObject) function to retrieve the current value stored in the object.
• Updating: Use the valueObject:set(newValue) method to update the stored value. Note that :set() returns the value passed to it, allowing it to be used within expressions.

local Fusion = require(ReplicatedStorage.Fusion)
local peek = Fusion.peek
local scope = Fusion.scoped(Fusion)

-- Create a value
local health = scope:Value(100)

-- Read the value
print(peek(health)) --> 100

-- Update the value
health:set(25)
print(peek(health)) --> 25

If the input to ForValues is a state object, the output will automatically update whenever the input table changes. Additionally, you can use use() within the processor function to depend on other state objects; if those dependencies change, the ForValues output will also update.

local numbers = scope:Value({1, 2, 3, 4, 5})
local factor = scope:Value(2)

local multiplied = scope:ForValues(numbers, function(use, scope, num)
	return num * use(factor)
end)

print(peek(multiplied)) --> {2, 4, 6, 8, 10}

-- Updating the input table triggers an update
numbers:set({5, 15, 25})
print(peek(multiplied)) --> {10, 30, 50}

-- Updating a dependency via use() also triggers an update
factor:set(10)
print(peek(multiplied)) --> {50, 150, 250}