Fusion

https://elttob.uk/Fusion/0.4
Admin
Fusion is a portable Luau companion library for simpler, more descriptive code, enabling developers...
Tokens:64,819
Snippets:593
Trust Score:5.4
Update:8 months ago
Show doc for...
Tokens:
Raw
### Lua: Configuring Instances with Events and Children

Source: https://elttob.uk/Fusion/0.4/Fusion/0

Demonstrates advanced instance creation using `scope:New`, including setting up event listeners and nesting child instances. This example creates a 'TextButton' with a 'UICorner' and an 'Activated' event handler.

```lua
-- This will create a rounded button.
-- When you click it, it’ll greet you.
local myButton = scope:New "TextButton" {
    Text = "Click me",

    [OnEvent "Activated"] = function()
        print("Hello! I’m a button.")
    end,

    [Children] = scope:New "UICorner" {
        CornerRadius = UDim.new(1, 0)
    }
}

```

--------------------------------

### Instantiate Spinner Component

Source: https://elttob.uk/Fusion/0.4/examples/cookbook/loading-spinner

This snippet shows how to create an instance of the `Spinner` component. It configures the layout properties such as position and anchor point, and passes the `currentTime` value to control the animation.

```lua
scope:Spinner {
    Layout = {
        Position = UDim2.fromScale(0.5, 0.5),
        AnchorPoint = Vector2.new(0.5, 0.5),
        Size = UDim2.fromOffset(50, 50)
    },
    CurrentTime = currentTime
}

```

--------------------------------

### Lua: Creating Instances with Fusion

Source: https://elttob.uk/Fusion/0.4/Fusion/0

Shows how to use Fusion's `scope:New` function to create Roblox instances with specified properties. This example demonstrates creating a red 'Part' in the workspace.

```lua
-- This will create a red part in the workspace.
local myPart = scope:New "Part" {
    Parent = workspace,
    BrickColor = BrickColor.Red()
}

```

--------------------------------

### Advanced Instance Creation with Fusion Events and Children (Luau)

Source: https://elttob.uk/Fusion/0.4/index

Demonstrates advanced instance creation using Fusion, including handling events like 'Activated' and nesting instances as children. This example creates a 'TextButton' with a 'UICorner' and prints a message when clicked.

```Luau
-- This will create a rounded button.
-- When you click it, it’ll greet you.
local myButton = scope:New "TextButton" {
    Text = "Click me",

    [OnEvent "Activated"] = function()
        print("Hello! I’m a button.")
    end,

    [Children] = scope:New "UICorner" {
        CornerRadius = UDim.new(1, 0)
    }
}
```

--------------------------------

### Creating Roblox Instances with Fusion (Luau)

Source: https://elttob.uk/Fusion/0.4/index

Shows how to use Fusion's 'scope:New' function to create Roblox instances with specified properties. This example demonstrates creating a red 'Part' in the 'workspace'.

```Luau
-- This will create a red part in the workspace.
local myPart = scope:New "Part" {
    Parent = workspace,
    BrickColor = BrickColor.Red()
}
```

--------------------------------

### ForKeys: Transform keys using a processor function (Lua)

Source: https://elttob.uk/Fusion/0.4/tutorials/tables/forkeys

Shows how to create a ForKeys object by providing an input table and a function that transforms each key. The example converts keys to uppercase.

```lua
local data = {red = "foo", blue = "bar"}
local renamed = scope:ForKeys(data, function(use, scope, key)
    return string.upper(key)
end)

print(peek(renamed)) --> {RED = "foo", BLUE = "bar"}
```

--------------------------------

### Fusion Error Message Example

Source: https://elttob.uk/Fusion/0.4/tutorials/get-started/getting-help

An example of a console error message generated by Fusion. It includes an ID and a link to a more detailed explanation of the error on the Fusion website. This helps users understand and resolve issues.

```text
[Fusion] The Frame class doesn't have a property called 'Activated'.
ID: cannotConnectChange
Learn more: https://elttob.uk/Fusion/0.3/api-reference/general/errors/#cannotconnectchange

```

--------------------------------

### Require Fusion with Vanilla Luau (Luau)

Source: https://elttob.uk/Fusion/0.4/tutorials/get-started/installing-fusion

This code snippet illustrates how to require the Fusion module in a vanilla Luau environment. It assumes Fusion is located in a 'shared/Fusion' directory with an 'init.luau' file.

```lua
-- vanilla Luau
local Fusion = require("../shared/Fusion/init.luau")
```

--------------------------------

### Insert into Scope (Lua)

Source: https://elttob.uk/Fusion/0.4/tutorials/fundamentals/scopes

Provides an example of using the 'insert' method on a scope to manually add destruction tasks, such as event connections or Roblox instances.

```lua
local conn, ins = scope:insert(
    RunService.Heartbeat:Connect(doUpdate),
    Instance.new("Part", workspace)
)

```

--------------------------------

### Configure Tween with TweenInfo

Source: https://elttob.uk/Fusion/0.4/tutorials/animation/tweens

Illustrates how to customize a tween's animation curve by providing a `TweenInfo` object. This example sets the duration and easing style for the tween.

```lua
local goal = scope:Value(0)
local style = TweenInfo.new(0.5, Enum.EasingStyle.Quad)
local animated = scope:Tween(goal, style)
```

--------------------------------

### Hydrate Instance Properties

Source: https://elttob.uk/Fusion/0.4/tutorials/roblox/hydration

Shows how to hydrate a Roblox instance with a table of properties. This example sets the color of a workspace part. The Hydrate function returns the instance, allowing for chained declarations.

```lua
local instance = workspace.Part

scope:Hydrate(instance)({
    Color = Color3.new(1, 0, 0)
})

```

```lua
local instance = workspace.Part

-- This only works when you're using curly braces {}!
scope:Hydrate(instance) {
    Color = Color3.new(1, 0, 0)
}

```

```lua
local instance = scope:Hydrate(workspace.Part) {
    Color = Color3.new(1, 0, 0)
}

```

--------------------------------

### Observe Table Changes with Fusion in Luau

Source: https://elttob.uk/Fusion/0.4/tutorials/best-practices/optimisation

Demonstrates how to use Fusion's `scope:Value` and `scope:Observer` to track changes in a table value. It shows how updates to the table trigger the observer callback, printing the name of the current theme. This example highlights Fusion's default behavior of not skipping updates for mutable tables.

```luau
local LIGHT_THEME = {
    name = "light",
    -- imagine theme colours in here
}
local DARK_THEME = {
    name = "dark",
    -- imagine theme colours in here
}
local currentTheme = scope:Value(LIGHT_THEME)
scope:Observer(currentTheme):onChange(function()
    print("-> currentTheme changed to " .. peek(currentTheme).name)
end)

print("Set to DARK_THEME")
currentTheme:set(DARK_THEME)
print("Set to DARK_THEME")
currentTheme:set(DARK_THEME)
print("Set to LIGHT_THEME")
currentTheme:set(LIGHT_THEME)
print("Set to LIGHT_THEME")
currentTheme:set(LIGHT_THEME)
```

--------------------------------

### Start Dragging an Item

Source: https://elttob.uk/Fusion/0.4/examples/cookbook/drag-and-drop

Initiates the dragging process for a to-do item when the mouse button is pressed. It captures the initial mouse offset relative to the item's position. This function relies on `peek` to access reactive state and `set` to update it.

```lua
if peek(currentlyDragging) == nil then
    local itemPos = peek(itemPosition) or Vector2.zero
    local mouseOffset = peek(mousePos) - itemPos
    currentlyDragging:set({
        id = item.id,
        mouseOffset = mouseOffset
    })
end
```

--------------------------------

### Create and Parent UI Elements

Source: https://elttob.uk/Fusion/0.4/examples/cookbook/drag-and-drop

Creates a `ScreenGui` and parents it to the player's `PlayerGui`. It then adds an overlay frame and task lists as children to this `ScreenGui`. This setup ensures the UI elements are visible to the player. Note that `TodoEntry` components manage their own parent and are not passed here.

```lua
local ui = scope:New "ScreenGui" {
    Parent = Players.LocalPlayer:FindFirstChildOfClass("PlayerGui"),

    [Children] = {
        overlayFrame,
        taskLists,
        -- Don't pass the generated `TodoEntry`s in here - they manage their own parent!
    }
}
```

--------------------------------

### Create a List of TodoItem Objects in Fusion

Source: https://elttob.uk/Fusion/0.4/examples/cookbook/drag-and-drop

This example demonstrates creating a list of 'TodoItem' objects. Each item has a unique ID, text, and a 'completed' status, which is represented as a 'Value' object to allow for dynamic updates. This structure is suitable for managing task lists where completion status changes.

```lua
local todoItems: {TodoItem} = {
    {
        id = newUniqueID(),
        text = "Wake up today",
        completed = scope:Value(true)
    },
    {
        id = newUniqueID(),
        text = "Read the Fusion docs",
        completed = scope:Value(true)
    },
    {
        id = newUniqueID(),
        text = "Take over the universe",
        completed = scope:Value(false)
    }
}


```

--------------------------------

### Create and Use an Observer with onBind()

Source: https://elttob.uk/Fusion/0.4/tutorials/fundamentals/observers

Illustrates creating an observer and using the :onBind() method. This method is similar to :onChange() but also executes the callback immediately when the observer is connected, in addition to running it when the state changes.

```Luau
local observer = scope:Observer(health)

print("...connecting...")
observer:onBind(function()
    print("Observed a change to: ", peek(health))
end)

print("...setting health to 25...")
health:set(25)
```

--------------------------------

### Require Fusion with Rojo (Luau)

Source: https://elttob.uk/Fusion/0.4/tutorials/get-started/installing-fusion

This code snippet shows how to require the Fusion module when using Rojo for synchronization. It assumes Fusion is located in ReplicatedStorage.

```lua
-- Rojo
local Fusion = require(ReplicatedStorage.Fusion)
```

--------------------------------

### Creating a Folder with Child Parts using [Children]

Source: https://elttob.uk/Fusion/0.4/tutorials/roblox/parenting

Demonstrates how to create a Folder instance and populate it with child Part instances using the [Children] key. This is a fundamental way to structure hierarchies in Fusion.

```lua
local folder = scope:New "Folder" {
    [Children] = {
        scope:New "Part" {
            Name = "Gregory",
            Color = Color3.new(1, 0, 0)
        },
        scope:New "Part" {
            Name = "Sammy",
            Material = "Glass"
        }
    }
}
```

--------------------------------

### Get Fusion Version

Source: https://elttob.uk/Fusion/0.4/api-reference/general/members/version

Retrieves the version string of the Fusion source code. The `isRelease` property indicates if the current version is from a formal release.

```fusion
Fusion.version: Version
```

--------------------------------

### Observe and Respond to Bio Loading State (Lua)

Source: https://elttob.uk/Fusion/0.4/examples/cookbook/fetch-data-from-server

This snippet sets up an observer to monitor changes in the user bio state. It prints a 'loading' message when the bio is nil and prints the loaded bio content when it becomes available, demonstrating how to handle both states.

```Lua
scope:Observer(currentUserBio):onBind(function()
    local bio = peek(currentUserBio)
    if bio == nil then
        print("User bio is loading...")
    else
        print("Loaded user bio:", bio)
    end
end)
```

--------------------------------

### Require Fusion in Roblox Studio (Luau)

Source: https://elttob.uk/Fusion/0.4/tutorials/get-started/installing-fusion

This code snippet demonstrates how to require the Fusion module after it has been imported as a Roblox model into ReplicatedStorage. It assumes Fusion is correctly placed and accessible.

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Fusion = require(ReplicatedStorage.Fusion)
```

--------------------------------

### Parenting an Existing Instance to a Folder using [Children]

Source: https://elttob.uk/Fusion/0.4/tutorials/roblox/parenting

Illustrates how to use the [Children] key to parent an already existing instance (e.g., workspace.Part) into a newly created Folder. This is useful for integrating existing objects into the Fusion-managed hierarchy.

```lua
local folder = scope:New "Folder" {
    -- The part will be moved inside of the folder
    [Children] = workspace.Part
}
```

--------------------------------

### Create and Use an Observer with onChange()

Source: https://elttob.uk/Fusion/0.4/tutorials/fundamentals/observers

Demonstrates creating an observer for a state object and attaching a callback function using the :onChange() method. The callback prints the new value when the state changes. It also shows how to disconnect the observer early.

```Luau
local observer = scope:Observer(health)
local disconnect = observer:onChange(function()
    print("The new value is: ", peek(health))
end)
task.wait(5)
disconnect()
```

```Luau
local observer = scope:Observer(health)

print("...connecting...")
observer:onChange(function()
    print("Observed a change to: ", peek(health))
end)

print("...setting health to 25...")
health:set(25)
```

```Luau
local disconnect = observer:onChange(function()
    print("The new value is: ", peek(health))
end)

-- disconnect the above handler after 5 seconds
task.wait(5)
disconnect()
```

--------------------------------

### Fusion.Out: Importing and Usage

Source: https://elttob.uk/Fusion/0.4/tutorials/roblox/outputs

Shows how to import the Out function from the Fusion library and use it to create a key for binding a Value object to an instance property.

```lua
local Out = Fusion.Out
local key = Out("Activated")
```

--------------------------------

### Require Fusion with darklua (Luau)

Source: https://elttob.uk/Fusion/0.4/tutorials/get-started/installing-fusion

This code snippet demonstrates how to require the Fusion module when using darklua for code transformation. It assumes Fusion is located in a 'shared' folder within the project structure.

```lua
-- darklua
local Fusion = require("../shared/Fusion")
```

--------------------------------

### Create and Hydrate Part Instance with Fusion (Optional Parentheses)

Source: https://elttob.uk/Fusion/0.4/tutorials/roblox/new-instances

Illustrates creating a new Part instance and setting its properties like Parent and Color. It shows the optional syntax for calling New when using curly braces for properties and quotes for the class type.

```lua
local instance = scope:New "Part" {
    Parent = workspace,
    Color = Color3.new(1, 0, 0)
}
```

--------------------------------

### Get Current Contextual Value (Luau)

Source: https://elttob.uk/Fusion/0.4/api-reference/general/types/contextual

The 'now' method of the Contextual type returns the current value of the contextual object. The returned value can differ based on the time and coroutine from which the function is invoked.

```Luau
function Contextual:now(): T
-- Returns the current value of this contextual.
end
```

--------------------------------

### Importing and Using Fusion's Children

Source: https://elttob.uk/Fusion/0.4/tutorials/roblox/parenting

Shows how to import the 'Children' key directly from the Fusion module for use in your code. This is necessary before utilizing it in instance creation.

```lua
local Children = Fusion.Children
```

--------------------------------

### Create ForPairs with Input Table and Processor Function

Source: https://elttob.uk/Fusion/0.4/tutorials/tables/forpairs

Illustrates the basic usage of ForPairs by creating an object that swaps keys and values from an input table. The processor function defines how each key-value pair is transformed.

```lua
local itemColours = { shoes = "red", socks = "blue" }
local swapped = scope:ForPairs(data, function(use, scope, item, colour)
    return colour, item
end)

print(peek(swapped)) --> { red = "shoes", blue = "socks" }
```

--------------------------------

### Create a Fusion Computed Object (Basic)

Source: https://elttob.uk/Fusion/0.4/tutorials/fundamentals/your-first-project

Creates a 'computed' Fusion object, which runs a provided function to determine its value. This example shows a computed object returning a static string. It requires a scope and can be peeked at.

```luau
local scope = Fusion:scoped()

local numCoins = scope:Value(50)

local message = scope:Computed(function()
    return "I am a message"
end)

print(Fusion.peek(message)) --> I am a message
```

--------------------------------

### Create and Use Fusion Value Object (Lua)

Source: https://elttob.uk/Fusion/0.4/tutorials/fundamentals/values

Demonstrates creating a Fusion Value object, setting its initial value, and reading it using `peek()` and `:set()` methods. Requires the Fusion module.

```lua
local Fusion = require(ReplicatedStorage.Fusion)
local doCleanup, scoped = Fusion.doCleanup, Fusion.scoped

local scope = scoped(Fusion)
local health = scope:Value(100)

print(peek(health)) --> 100
health:set(25)
print(peek(health)) --> 25
```

--------------------------------

### Create and Hydrate TextLabel Instance with Fusion

Source: https://elttob.uk/Fusion/0.4/tutorials/roblox/new-instances

Demonstrates creating a new TextLabel instance, setting its properties including text from a reactive value, and observing updates. It highlights the asynchronous nature of property updates.

```lua
local message = scope:Value("Hello there!")

local ui = scope:New "TextLabel" {
    Name = "Greeting",
    Parent = PlayerGui.ScreenGui,

    Text = message
}

print(ui.Name) --> Greeting
print(ui.Text) --> Hello there!

message:set("Goodbye friend!")
task.wait() -- important: changes are applied on the next frame!
print(ui.Text) --> Goodbye friend!
```

--------------------------------

### Spinner Component Definition

Source: https://elttob.uk/Fusion/0.4/examples/cookbook/loading-spinner

This snippet defines the core `Spinner` component in Fusion. It accepts layout properties and a `CurrentTime` value. The component renders an `ImageLabel` with its rotation dynamically calculated based on the provided `CurrentTime`.

```lua
local function Spinner(
    scope: Fusion.Scope,
    props: {
        Layout: {
            LayoutOrder: UsedAs<number>?,
            Position: UsedAs<UDim2>?,
            AnchorPoint: UsedAs<Vector2>?,
            ZIndex: UsedAs<number>?
        },
        CurrentTime: UsedAs<number>,
    }
): Fusion.Child
    return scope:New "ImageLabel" {
        Name = "Spinner",

        LayoutOrder = props.Layout.LayoutOrder,
        Position = props.Layout.Position,
        AnchorPoint = props.Layout.AnchorPoint,
        ZIndex = props.Layout.ZIndex,

        Size = UDim2.fromOffset(SPIN_SIZE, SPIN_SIZE),

        BackgroundTransparency = 1,
        Image = "rbxassetid://your-loading-spinner-image", -- replace this!

        Rotation = scope:Computed(function(use)
            return (use(props.CurrentTime) * SPIN_DEGREES_PER_SECOND) % 360
        end)
    }
end

```

--------------------------------

### Fusion.Out: Basic Instance Creation and Output

Source: https://elttob.uk/Fusion/0.4/tutorials/roblox/outputs

Demonstrates how to use Fusion.Out to create a new 'Part' instance and bind its 'Name' property to a Value object. Changes to the instance's 'Name' update the Value object, and changes to the Value object update the instance's 'Name' (two-way binding).

```lua
local name = scope:Value()

local thing = scope:New "Part" {
    Name = name -- When `name` changes, set `thing.Name`
    [Out "Name"] = name -- When `thing.Name` changes, set `name`
}

print(thing.Name, peek(name)) --> Part Part
name:set("NewName")
task.wait()
print(thing.Name, peek(name)) --> NewName NewName
```

--------------------------------

### Create and Hydrate Part Instance with Fusion (Required Parentheses)

Source: https://elttob.uk/Fusion/0.4/tutorials/roblox/new-instances

Demonstrates creating a new Part instance and setting its properties using the syntax where parentheses are required around the property table. This is an alternative to the syntax using curly braces directly.

```lua
local instance = scope:New("Part")({
    Parent = workspace,
    Color = Color3.new(1, 0, 0)
})
```

--------------------------------

### Update Current Time for Spinner Animation

Source: https://elttob.uk/Fusion/0.4/examples/cookbook/loading-spinner

This snippet demonstrates how to create a reactive value for the current time and update it every frame using `RunService.RenderStepped`. This `currentTime` value is then passed to the `Spinner` component to drive its animation.

```lua
local currentTime = scope:Value(os.clock())
table.insert(scope,
    RunService.RenderStepped:Connect(function()
        currentTime:set(os.clock())
    end)
)

```

--------------------------------

### Handling Errors with `pcall()` in Luau

Source: https://elttob.uk/Fusion/0.4/tutorials/best-practices/error-safety

Shows how to make an error non-fatal by wrapping it in a `pcall()` function. `pcall()` allows the program to continue running even if an error occurs within the protected call. This example demonstrates the output when an error is caught.

```Luau
print("before")
print("before")
print("before")

pcall(function()
    error("Kaboom!")
end)

print("after")
print("after")
print("after")

```

--------------------------------

### Instantiate a Button Component in Fusion (Luau)

Source: https://elttob.uk/Fusion/0.4/tutorials/best-practices/components

Demonstrates how to instantiate and use the 'Button' component created in Fusion. It shows two methods: direct function call with a scope, and using the `scoped()` syntax for a more concise component access.

```luau
local helloBtn = Button(scope, {
    ButtonText = "Hello",
    Size = UDim2.fromOffset(200, 50)
})

helloBtn.Parent = Players.LocalPlayer.PlayerGui.ScreenGui

```

```luau
local scope = scoped(Fusion, {
    Button = Button
})

local helloBtn = scope:Button {
    ButtonText = "Hello",
    Size = UDim2.fromOffset(200, 50)
}

helloBtn.Parent = Players.LocalPlayer.PlayerGui.ScreenGui

```

--------------------------------

### Create and Use a Basic Spring - Lua

Source: https://elttob.uk/Fusion/0.4/tutorials/animation/springs

Demonstrates how to create a basic spring object that follows a state object. It shows initialization and how to access the spring's current value.

```lua
local goal = scope:Value(0)
local animated = scope:Spring(goal)

print(peek(animated)) --> 0.26425...
```

--------------------------------

### Lua: Working with State Objects

Source: https://elttob.uk/Fusion/0.4/Fusion/0

Demonstrates the creation and usage of Fusion's state objects, which represent dynamic values. It shows how to peek at their current value and how they update over time.

```lua
-- For example, suppose this function returned a state object.
local currentTimeObj = getCurrentTimeStateObject()

-- State objects are objects...
print(typeof(currentTimeObj)) --> table

-- ...and you can peek at their value (or ‘state’) at any time.
print(peek(currentTimeObj)) --> 0.0
task.wait(5)
print(peek(currentTimeObj)) --> 5.0

```

--------------------------------

### Update Fusion Value and Observe Changes

Source: https://elttob.uk/Fusion/0.4/tutorials/fundamentals/your-first-project

Demonstrates updating the value of a Fusion 'value' object using its `:set()` method. When the value changes, any 'computed' objects that depend on it (using `use`) will automatically update. The example shows re-peeking the computed message after updating `numCoins`.

```luau
local scope = Fusion:scoped()

local numCoins = scope:Value(50)

local message = scope:Computed(function(use)
    return "The number of coins is " .. use(numCoins)
end)

print(Fusion.peek(message)) --> The number of coins is 50

numCoins:set(75)

print(Fusion.peek(message)) --> The number of coins is 75
```

--------------------------------

### Main File: PopUpMessageButton Component Structure

Source: https://elttob.uk/Fusion/0.4/tutorials/best-practices/components

This code snippet illustrates the main file structure for a 'PopUpMessageButton' component using Fusion. It demonstrates how to require Fusion, set up a scoped environment, and instantiate a UI with nested components.

```lua
local Fusion = require(game:GetService("ReplicatedStorage").Fusion)
local scoped, doCleanup = Fusion.scoped, Fusion.doCleanup

local scope = scoped(Fusion, {
    PopUp = require(script.Parent.PopUp)
})

local ui = scope:New "ScreenGui" {
    -- ...some properties...

    [Children] = scope:PopUp {
        Message = "Hello, world!",
        DismissText = "Close"
    }
}

```

--------------------------------

### Contextual Type Definition (Luau)

Source: https://elttob.uk/Fusion/0.4/api-reference/general/types/contextual

Defines the Contextual type, a generic type that holds a value accessible across different coroutines. It includes a 'type' field for runtime checking, a 'now' method to get the current value, and an 'is' method to temporarily set a value within a callback.

```Luau
export type Contextual<T> = {
    type: "Contextual",
    now: (self) -> T,
    is: (self, newValue: T) -> {
        during: <R, A...>(self, callback: (A...) -> R, A...) -> R
    }
}
```

--------------------------------

### Process Key-Value Pairs with ForPairs

Source: https://elttob.uk/Fusion/0.4/tutorials/tables/forpairs

Demonstrates how ForPairs processes key-value pairs from a table, allowing modification of both keys and values. It shows how changes to a state object used within the processing function affect the output.

```lua
local itemColours = { shoes = "red", socks = "blue" }
local owner = scope:Value("Janet")

local manipulated = scope:ForPairs(itemColours, function(use, scope, thing, colour)
    local newKey = colour
    local newValue = use(owner) .. "'s " .. thing
    return newKey, newValue
end)

print(peek(manipulated)) --> {red = "Janet's shoes", blue = "Janet's socks"}

owner:set("April")
print(peek(manipulated)) --> {red = "April's shoes", blue = "April's socks"}
```

--------------------------------

### Initiate Drag Operation with OnMouseDown in Fusion

Source: https://elttob.uk/Fusion/0.4/examples/cookbook/drag-and-drop

This 'OnMouseDown' function is responsible for starting a drag operation. It checks if another item is already being dragged. If not, it captures the mouse position relative to the item and updates the 'currentlyDragging' state with the item's ID and the calculated mouse offset.

```lua
            OnMouseDown = function()

```

--------------------------------

### Initializing Fusion Scope and Todo Items in Lua

Source: https://elttob.uk/Fusion/0.4/examples/cookbook/drag-and-drop

Sets up the main Fusion scope and initializes a list of `todoItems`. Each item has a unique ID, text, and a `completed` state managed by Fusion's `Value`. This demonstrates the initial state of the application.

```lua
-- Don't forget to pass this to `doCleanup` if you disable the script.
local scope = scoped(Fusion,{
    TodoEntry = TodoEntry
})

local todoItems: {TodoItem} = {
    {
        id = newUniqueID(),
        text = "Wake up today",
        completed = scope:Value(true)
    },
    {
        id = newUniqueID(),
        text = "Read the Fusion docs",
        completed = scope:Value(true)
    },
    {
        id = newUniqueID(),
        text = "Take over the universe",
        completed = scope:Value(false)
    }
}
```

--------------------------------

### ForKeys: Process keys with a prefix and update dynamically (Lua)

Source: https://elttob.uk/Fusion/0.4/tutorials/tables/forkeys

Demonstrates how to use ForKeys to prepend a prefix to keys from a data table. The prefix can be updated dynamically, and the ForKeys object automatically reflects these changes.

```lua
local data = {Red = "foo", Blue = "bar"}
local prefix = scope:Value("Key_")

local renamed = scope:ForKeys(data, function(use, scope, key)
    return use(prefix) .. key
end)

print(peek(renamed)) --> {Key_Red = "foo", Key_Blue = "bar"}

prefix:set("colour")
print(peek(renamed)) --> {colourRed = "foo", colourBlue = "bar"}
```

--------------------------------

### Manage Asynchronous Fetch Task State (Lua)

Source: https://elttob.uk/Fusion/0.4/examples/cookbook/fetch-data-from-server

This code manages the state of an ongoing asynchronous fetch operation. It ensures that only one fetch is active at a time by canceling any previous fetch tasks before starting a new one. It also updates a state object with the fetched data or resets it to nil during loading.

```Lua
local fetchInProgress = nil
local function performFetch()
    local userID = peek(currentUserID)
    currentUserBio:set(nil)
    if fetchInProgress ~= nil then
        task.cancel(fetchInProgress)
    end
    fetchInProgress = task.spawn(function()
        currentUserBio:set(fetchUserBio(userID))
        fetchInProgress = nil
    end)
end
```

--------------------------------

### Create a New Scope (Lua)

Source: https://elttob.uk/Fusion/0.4/tutorials/fundamentals/scopes

Demonstrates the creation of a new scope by initializing an empty Lua table. This scope will later hold objects to be managed.

```lua
local Fusion = require(ReplicatedStorage.Fusion)

local scope = {}

```

--------------------------------

### Fetch User Bio with Asynchronous Data Loading (Lua)

Source: https://elttob.uk/Fusion/0.4/examples/cookbook/fetch-data-from-server

This snippet demonstrates fetching user bio data asynchronously. It handles loading states by initially setting the bio to nil and updating it upon successful retrieval. It manages concurrent fetch requests by canceling previous ones before initiating a new fetch.

```Lua
local Fusion = -- initialise Fusion here however you please!
local scoped = Fusion.scoped
local peek = Fusion.peek

local function fetchUserBio(
    userID: number
): string
    -- pretend this calls out to a server somewhere, causing this code to yield
    task.wait(1)
    return "This is the bio for user " .. userID .. "!"
end

-- Don't forget to pass this to `doCleanup` if you disable the script.
local scope = scoped(Fusion)

-- This doesn't have to be a `Value` - any kind of state object works too.
local currentUserID = scope:Value(1670764)

-- While the bio is loading, this is `nil` instead of a string.
local currentUserBio: Fusion.Value<string?> = scope:Value(nil)

do
    local fetchInProgress = nil
    local function performFetch()
        local userID = peek(currentUserID)
        currentUserBio:set(nil)
        if fetchInProgress ~= nil then
            task.cancel(fetchInProgress)
        end
        fetchInProgress = task.spawn(function()
            currentUserBio:set(fetchUserBio(userID))
            fetchInProgress = nil
        end)
    end
    scope:Observer(currentUserID):onBind(performFetch)
end

scope:Observer(currentUserBio):onBind(function()
    local bio = peek(currentUserBio)
    if bio == nil then
        print("User bio is loading...")
    else
        print("Loaded user bio:", bio)
    end
end)
```

--------------------------------

### Implement Roblox Fusion Loading Spinner

Source: https://elttob.uk/Fusion/0.4/examples/cookbook/loading-spinner

This snippet shows the complete implementation of a loading spinner component using Roblox Fusion. It defines a `Spinner` component that takes a `CurrentTime` property to drive its rotation. The component is then instantiated and added to the player's GUI, with its rotation updated every frame using `RunService.RenderStepped`.

```lua
local RunService = game:GetService("RunService")
local Players = game:GetService("Players")

local Fusion = -- initialise Fusion here however you please!
local scoped = Fusion.scoped
local Children = Fusion.Children
type UsedAs<T> = Fusion.UsedAs<T>

local SPIN_DEGREES_PER_SECOND = 180
local SPIN_SIZE = 50

local function Spinner(
    scope: Fusion.Scope,
    props: {
        Layout: {
            LayoutOrder: UsedAs<number>?,
            Position: UsedAs<UDim2>?,
            AnchorPoint: UsedAs<Vector2>?,
            ZIndex: UsedAs<number>?
        },
        CurrentTime: UsedAs<number>,
    }
): Fusion.Child
    return scope:New "ImageLabel" {
        Name = "Spinner",

        LayoutOrder = props.Layout.LayoutOrder,
        Position = props.Layout.Position,
        AnchorPoint = props.Layout.AnchorPoint,
        ZIndex = props.Layout.ZIndex,

        Size = UDim2.fromOffset(SPIN_SIZE, SPIN_SIZE),

        BackgroundTransparency = 1,
        Image = "rbxassetid://your-loading-spinner-image", -- replace this!

        Rotation = scope:Computed(function(use)
            return (use(props.CurrentTime) * SPIN_DEGREES_PER_SECOND) % 360
        end)
    }
end

-- Don't forget to pass this to `doCleanup` if you disable the script.
local scope = scoped(Fusion, {
    Spinner = Spinner
})

local currentTime = scope:Value(os.clock())
table.insert(scope,
    RunService.RenderStepped:Connect(function()
        currentTime:set(os.clock())
    end)
)

local gui = scope:New "ScreenGui" {
    Name = "SpinnerGui",
    Parent = Players.LocalPlayer:WaitForChild("PlayerGui"),

    [Children] = scope:Spinner {
        Layout = {
            Position = UDim2.fromScale(0.5, 0.5),
            AnchorPoint = Vector2.new(0.5, 0.5),
            Size = UDim2.fromOffset(50, 50)
        },
        CurrentTime = currentTime
    }
}

```

--------------------------------

### Simulate Server Data Fetching (Lua)

Source: https://elttob.uk/Fusion/0.4/examples/cookbook/fetch-data-from-server

This function simulates fetching data from a server, including a delay to mimic network latency. It takes a user ID as input and returns a formatted string representing the user's bio.

```Lua
local function fetchUserBio(
    userID: number
): string
    -- pretend this calls out to a server somewhere, causing this code to yield
    task.wait(1)
    return "This is the bio for user " .. userID .. "!"
end
```

--------------------------------

### Nesting Instance Creation with [Children]

Source: https://elttob.uk/Fusion/0.4/tutorials/roblox/parenting

Demonstrates how to create nested instances, specifically a Folder containing a Part, by nesting the scope:New calls within the [Children] property. This allows for complex object structures to be defined concisely.

```lua
-- Makes a Folder, containing a part called Gregory
local folder = scope:New "Folder" {
    [Children] = scope:New "Part" {
        Name = "Gregory",
        Color = Color3.new(1, 0, 0)
    }
}
```

--------------------------------

### Luau Observer Example for Update Skipping

Source: https://elttob.uk/Fusion/0.4/tutorials/best-practices/optimisation

This Luau code demonstrates how Fusion's observer pattern skips updates when computed values are not meaningfully different. It sets up a computed value that checks if a number is even and an observer that logs changes. The observer only triggers when the 'isEven' value changes meaningfully, illustrating Fusion's optimization for non-changing results.

```Luau
local number = scope:Value(1)
local isEven = scope:Computed(function(use) 
    return use(number) % 2 == 0 
end)
scope:Observer(isEven):onChange(function()
    print("-> isEven has changed to " .. peek(isEven))
end)

print("Number becomes 2")
number:set(2)
print("Number becomes 3")
number:set(3)
print("Number becomes 13")
number:set(13)
print("Number becomes 14")
number:set(14)
print("Number becomes 24")
number:set(24)
```

--------------------------------

### Defining and Using Scopes in Fusion Components

Source: https://elttob.uk/Fusion/0.4/tutorials/best-practices/components

Demonstrates how to define and utilize scopes within Fusion components. It covers both barebones and scoped() syntax for component creation and type hinting for scopes to specify required methods.

```lua
-- barebones syntax
local thing = Component(scope, { 
    -- ... some properties here ...
})

-- scoped() syntax
local thing = scope:Component { 
    -- ... some properties here ...
}

```

```lua
scope: Fusion.Scope<YourMethodsHere>

```

```lua
local function Component(
    scope: Fusion.Scope,
    props: {}
)
    return scope:New "Thing" {
        -- ... rest of code here ...
    }
end

```

```lua
local function Component(
    scope: Fusion.Scope,
    props: {}
)
    local scope = scope:innerScope {
        SpecialThing1 = require(script.SpecialThing1),
        SpecialThing2 = require(script.SpecialThing2),
    }

    return scope:SpecialThing1 {
        -- ... rest of code here ...
    }
end

```

--------------------------------

### Animate UI Position with Fusion and Tween

Source: https://elttob.uk/Fusion/0.4/examples/cookbook/animated-computed

This snippet demonstrates animating a UI element's position using the Fusion library. It defines a reactive boolean value that controls the visibility of a UI element. A computed property translates this boolean into a target UDim2 position, and a tween animates the UI element towards this position based on a specified TweenInfo. The example includes setting up a ScreenGui, a Frame, and a loop to toggle the reactive value, causing the animation.

```lua
local Players = game:GetService("Players")

local Fusion = -- initialise Fusion here however you please!
local scoped = Fusion.scoped
local peek = Fusion.peek
local Children = Fusion.Children

TWEEN_INFO = TweenInfo.new(
    0.5,
    Enum.EasingStyle.Sine,
    Enum.EasingDirection.InOut
)

-- Don't forget to pass this to `doCleanup` if you disable the script.
local scope = scoped(Fusion)

-- You can set this at any time to indicate where The Thing should be.
local showTheThing = scope:Value(false)

local exampleUI = scope:New "ScreenGui" {
    Parent = Players.LocalPlayer:FindFirstChildOfClass("PlayerGui"),
    Name = "Example UI",

    [Children] = scope:New "Frame" {
        Name = "The Thing",
        Position = scope:Tween(
            scope:Computed(function(use) 
                local CENTRE = UDim2.fromScale(0.5, 0.5)
                local OFFSCREEN = UDim2.fromScale(-0.5, 0.5)
                return if use(showTheThing) then CENTRE else OFFSCREEN
            end),
            TWEEN_INFO
        ),
        Size = UDim2.fromOffset(200, 200)
    }
}

-- Without toggling the value, you won't see it animate.
task.defer(function()
    while true do
        task.wait(1)
        showTheThing:set(not peek(showTheThing))
    end
end)
```

--------------------------------

### ForPairs with State Object Input and Output Update

Source: https://elttob.uk/Fusion/0.4/tutorials/tables/forpairs

Shows how ForPairs reacts to changes when the input table is a state object. When the state object is updated, the ForPairs output is automatically recalculated and reflects the new data.

```lua
local itemColours = scope:Value({ shoes = "red", socks = "blue" })
local swapped = scope:ForPairs(data, function(use, scope, item, colour)
    return colour, item
end)

print(peek(swapped)) --> { red = "shoes", blue = "socks" }

itemColours:set({ sandals = "red", socks = "green" })
print(peek(swapped)) --> { red = "sandals", green = "socks" }
```

--------------------------------

### Referencing UI Elements with Value Objects in Fusion

Source: https://elttob.uk/Fusion/0.4/tutorials/best-practices/references

Illustrates using Fusion's value objects (Fusion.Value) to reference UI elements, especially when direct constants are impractical or cyclic references are needed. The `:set()` method allows referencing parts of the UI without disrupting the creation order, though the referenced value might be nil initially.

```lua
-- `selectionTarget` will show as `nil` to all code trying to use it, until the
-- `:set()` method is called later on.
local selectionTarget: Fusion.Value<Part?> = scope:Value(nil)

local ui = scope:New "Folder" {
    [Children] = {
        scope:New "SelectionBox" {
            Adornee = selectionTarget
        },
        selectionTarget:set(
            scope:New "Part" {
                Name = "Selection Target",
            }
        )
    }
}
```

```lua
local aliceRef: Fusion.Value<Instance?> = scope:Value(nil)
local bobRef: Fusion.Value<Instance?> = scope:Value(nil)

-- These two `ObjectValue` instances will refer to each other once the code has
-- finished running.
local alice = aliceRef:set(
    scope:New "ObjectValue" {
        Value = bobRef
    }
)
local bob = bobRef:set(
    scope:New "ObjectValue" {
        Value = aliceRef
    }
)
```

--------------------------------

### ForValues: Create with Input Table and Processor Function (Lua)

Source: https://elttob.uk/Fusion/0.4/tutorials/tables/forvalues

Illustrates the creation of a ForValues object by providing an input table and a processor function. The function takes 'use', 'scope', and the current table value as arguments.

```lua
local numbers = {1, 2, 3, 4, 5}
local doubled = scope:ForValues(numbers, function(use, scope, num) 
    return num * 2
end)
```

--------------------------------

### Lua: Observing State Object Changes with Observers

Source: https://elttob.uk/Fusion/0.4/Fusion/0

Explains how to use Fusion's Observer to monitor state objects for changes. It demonstrates setting up an observer to execute a callback function when a specific state object's value is updated.

```lua
-- This observer watches for when the greeting changes.
local myObserver = scope:Observer(myGreeting)

-- Let’s print out the greeting when there’s a new one.
local disconnect = myObserver:onChange(function()
    print(peek(myGreeting))
end)

-- This will run the code above!
myName:set("Danny")

```

--------------------------------

### Add Methods in Bulk with Fusion Scoped

Source: https://elttob.uk/Fusion/0.4/tutorials/fundamentals/scopes

Demonstrates how to pass the Fusion table directly to `scoped()` to access all its functions without manual import. This simplifies scope creation when all Fusion methods are needed. Conflicting names between tables passed to `scoped()` will result in an error.

```lua
local scope = scoped(Fusion)

-- all still works!
local thing1 = scope:Value("i am thing 1")
local thing2 = scope:Value("i am thing 2")
local thing3 = scope:Value("i am thing 3")

scope:doCleanup()

local scope = scoped(Fusion, {
    Foo = ..., 
    Bar = ...
})
```

--------------------------------

### Optimize Table Updates with `table.freeze` in Fusion (Luau)

Source: https://elttob.uk/Fusion/0.4/tutorials/best-practices/optimisation

Demonstrates how to use `table.freeze` to prevent table mutations and allow Fusion to skip redundant updates. By freezing `LIGHT_THEME` and `DARK_THEME`, Fusion can efficiently determine that no meaningful change has occurred when the same frozen table is set again, leading to fewer observer callbacks.

```luau
local LIGHT_THEME = table.freeze {
    name = "light",
    -- imagine theme colours in here
}
local DARK_THEME = table.freeze {
    name = "dark",
    -- imagine theme colours in here
}
local currentTheme = scope:Value(LIGHT_THEME)
scope:Observer(currentTheme):onChange(function()
    print("-> currentTheme changed to " .. peek(currentTheme).name)
end)

print("Set to DARK_THEME")
currentTheme:set(DARK_THEME)
print("Set to DARK_THEME")
currentTheme:set(DARK_THEME)
print("Set to LIGHT_THEME")
currentTheme:set(LIGHT_THEME)
print("Set to LIGHT_THEME")
currentTheme:set(LIGHT_THEME)
```

--------------------------------

### Lua: Creating and Using Value and Computed State Objects

Source: https://elttob.uk/Fusion/0.4/Fusion/0

Illustrates the creation of two fundamental state object types: 'Value' for manually settable states and 'Computed' for states derived from calculations. It also shows how to manage these objects within a scope and perform cleanup.

```lua
-- Start tracking some new objects.
local scope = Fusion:scoped()

-- This creates a state object that you can set manually.
-- You can change its value using myName:set().
local myName = scope:Value("Daniel")

-- This creates a state object from a calculation.
-- It determines its own value automatically.
local myGreeting = scope:Computed(function(use)
    return "Hello! My name is " .. use(myName)
end)

-- Discard all the objects.
scope:doCleanup()

```

--------------------------------

### Error Handling Comparison: pcall, xpcall, and Safe Expressions in Fusion

Source: https://elttob.uk/Fusion/0.4/tutorials/best-practices/error-safety

Compares three methods for safely executing code that might error: pcall, xpcall, and Fusion's Safe Expressions. Each snippet demonstrates how to handle a potential error when doubling a number, showing the increasing conciseness and readability.

```lua
local double = scope:Computed(function(use)
    local ok, result = pcall(function()
        local number = use(number)
        assert(number ~= 3, "I don't like the number 3")
        return number * 2
    end)
    if ok then
        return result
    else
        return "failed: " .. err
    end
end)

```

```lua
local double = scope:Computed(function(use)
    local _, result = xpcall(
        function()
            local number = use(number)
            assert(number ~= 3, "I don't like the number 3")
            return number * 2
        end,
        function(err)
            return "failed: " .. err
        end
    )
    return result
end)

```

```lua
local double = scope:Computed(function(use)
    return Safe {
        try = function()
            local number = use(number)
            assert(number ~= 3, "I don't like the number 3")
            return number * 2
        end,
        fallback = function(err)
            return "failed: " .. err
        end
    }
end)

```

--------------------------------

### Scoped with Initial Functions (Lua)

Source: https://elttob.uk/Fusion/0.4/tutorials/fundamentals/scopes

Shows how to initialize a scope with a table of functions using 'scoped()'. These functions can then be called as methods on the scope object.

```lua
local Fusion = require(ReplicatedStorage.Fusion)
local scoped = Fusion.scoped

local scope = scoped({
    Value = Fusion.Value,
    doCleanup = Fusion.doCleanup
})
local thing1 = Fusion.Value(scope, "i am thing 1")
local thing2 = Fusion.Value(scope, "i am thing 2")
local thing3 = Fusion.Value(scope, "i am thing 3")

Fusion.doCleanup(scope)

```
Tokens:
Raw