Fusion

https://elttob.uk/Fusion/0.3/api-reference
Admin
Fusion is a reactive UI library for Roblox that provides state management, animation, and instance...
Tokens:18,606
Snippets:262
Trust Score:5.4
Update:4 months ago
Show doc for...
Tokens:
Raw
### Get Fusion Version

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

Access the Fusion version information. The `isRelease` flag indicates if the current build is from a formal release.

```javascript
Fusion.version: Version

```

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

### Create a SpecialKey for Attribute Changes

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/members/attributechange

Use Fusion.AttributeChange to get a SpecialKey that listens for changes to a specific attribute. This key can then be used in property tables to connect callbacks to attribute change events.

```typescript
function Fusion.AttributeChange(
    attributeName: string
): SpecialKey
```

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

### Creating a SpecialKey for an Attribute

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/members/attribute

Use this function to get a special key that targets a specific attribute by name. This key can then be used in property tables to set the attribute's value.

```typescript
function Fusion.Attribute(
    attributeName: string
): SpecialKey
```

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

### use<T>(target: UsedAs<T>) -> T

Source: https://elttob.uk/Fusion/0.3/api-reference/state/types/use

Extracts a value of type `T` from a `UsedAs<T>` target. This function is the most generic way to get a value, and specific APIs like computeds can provide their own implementations for additional processing.

```APIDOC
## use<T>(target: UsedAs<T>) -> T

### Description
Extracts a value of type `T` from a `UsedAs<T>` target. This function is the most generic way to get a value, and specific APIs like computeds can provide their own implementations for additional processing.

### Parameters
#### Path Parameters
- **target** (UsedAs<T>) - Required - The representation of `T` to extract a value from.

### Returns -> T
The current value of `T`, derived from `target`.
```

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

### Get Current Contextual Value

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

Retrieves the current value of a Contextual object. The returned value may differ depending on the coroutine and the time of execution.

```luau
function Contextual:now(): T
```

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

### Using ForPairs as a Scope Method

Source: https://elttob.uk/Fusion/0.3/api-reference/state/members/forpairs

Demonstrates the idiomatic way to call ForPairs using method syntax on a scope object. This is the recommended approach for integrating ForPairs into your Fusion application.

```lua
local forObj = scope:ForPairs(inputTable, processor)
```

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

### Using ForValues via Scoped Method Syntax

Source: https://elttob.uk/Fusion/0.3/api-reference/state/members/forvalues

Demonstrates how to use the ForValues function as a method on a scope object. This is the recommended way to access the functionality.

```lua
local forObj = scope:ForValues(inputTable, processor)

```

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

### Cannot Create Class Instance Error

Source: https://elttob.uk/Fusion/0.3/api-reference/general/errors

This error indicates an attempt to instantiate a class type that Fusion is unable to create. Some instances may require specific Studio beta features to be enabled.

```text
Can't create a new instance of class 'EditableImage'.

```

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

### Using ForKeys via Scope Method

Source: https://elttob.uk/Fusion/0.3/api-reference/state/members/forkeys

Demonstrates the typical usage of the ForKeys function as a method on a scope object. This is the recommended way to access the functionality.

```lua
local forObj = scope:ForKeys(inputTable, processor)

```

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

### Fusion.New

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/members/new

Creates a component for constructing Roblox instances of a specified class. This component accepts a property table to customize the instance's properties, including state objects and special keys for advanced configuration.

```APIDOC
## Fusion.New

### Description
Given a class name, returns a component for constructing instances of that class. In the property table, string keys are assigned as properties on the instance. If the value is a state object, it is re-assigned every time the value of the state object changes. Any special keys present in the property table are applied to the instance after string keys are processed, in the order specified by their `stage`. A special exception is made for assigning `Parent`, which is only assigned after the `descendants` stage.

### Parameters
#### Path Parameters
* **className** (string) - Required - The kind of instance that should be constructed.

#### Request Body
* **props** (PropertyTable) - Required - A table where string keys are assigned as properties on the instance. State objects are re-assigned on change. Special keys are applied based on their `stage`.

### Returns
#### Success Response
* **Instance Component** (Instance) - A component that constructs instances of the specified type, accepting various properties to customize each instance uniquely.
```

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

### Accessing Spring as a Scope Method

Source: https://elttob.uk/Fusion/0.3/api-reference/animation/members/spring

Demonstrates how to use the Spring function as a method on a scope object. This is the intended way to construct a new spring state.

```lua
local spring = scope:Spring(goal, speed, damping)

```

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

### Registering Callback for Immediate and Future Updates

Source: https://elttob.uk/Fusion/0.3/api-reference/graph/types/observer

Executes a callback function immediately and also registers it to run on subsequent updates. Returns a function to unregister the callback.

```lua
function Observer:onBind(
    callback: () -> ()
): (() -> ())
```

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

### Observer:onBind

Source: https://elttob.uk/Fusion/0.3/api-reference/graph/types/observer

Executes a callback function immediately upon binding and also registers it to run whenever the Observer receives an update. The returned function can be used to unregister the callback.

```APIDOC
## Observer:onBind

### Description
Runs the callback immediately, and registers the callback to run when an update is received. The returned function will unregister the callback.

### Method
Observer.onBind

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **callback** (() -> ()) - The function to be executed immediately and on subsequent updates.

#### Response Example
None
```

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

### Tween<T> Method Syntax

Source: https://elttob.uk/Fusion/0.3/api-reference/animation/members/tween

This demonstrates the idiomatic way to access the Tween<T> functionality as a method on a scope object. It's used for creating tweens with a specified goal and optional info.

```lua
local tween = scope:Tween(goal, info)
```

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

### Cannot Connect to Non-existent Property Error

Source: https://elttob.uk/Fusion/0.3/api-reference/general/errors

This error occurs when trying to subscribe to a property change event for a property that does not exist on the specified instance.

```text
The Frame class doesn't have a property called 'Foo'.

```

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

### Cannot Connect to Non-existent Event Error

Source: https://elttob.uk/Fusion/0.3/api-reference/general/errors

This error is triggered when attempting to connect to an event on an instance that does not possess the specified event.

```text
The Frame class doesn't have an event called 'Foo'.

```

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

### Fusion.Safe<Success, Fail>

Source: https://elttob.uk/Fusion/0.3/api-reference/general/members/safe

Safely runs a function and returns the value it produces. If the function fails, the fallback function can handle the error and produce a fallback value. It acts like a version of xpcall that is easier to use in calculations and expressions.

```APIDOC
## Fusion.Safe<Success, Fail>

### Description
Safely executes a function (`try`) and returns its result. If an error occurs during the execution of `try`, the `fallback` function is called with the error, and its result is returned.

### Method
N/A (Function Call)

### Signature
```lua
function Fusion.Safe<Success, Fail>(
    callbacks: {
        try: () -> Success,
        fallback: (err: unknown) -> Fail
    }
): Success | Fail
```

### Parameters
#### Callbacks Object
- **try** (function) - Required - The function to execute. It takes no arguments and returns a value of type `Success`.
- **fallback** (function) - Required - The function to execute if `try` throws an error. It takes one argument, `err` (unknown type), which is the error that occurred, and returns a value of type `Fail`.

### Returns
- **Success | Fail** - The value produced by the `try` function if it executes successfully, or the value produced by the `fallback` function if an error occurs during the execution of `try`.
```

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

### SpecialKey Apply Method Signature

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/types/specialkey

Provides the signature for the apply method of a SpecialKey, detailing the parameters it accepts and its return type.

```lua
function SpecialKey:apply(
    self,
    scope: Scope<unknown>,
    value: unknown,
    applyTo: Instance
): ()

```

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

### Fusion.doCleanup

Source: https://elttob.uk/Fusion/0.3/api-reference/memory/members/docleanup

Attempts to destroy all arguments based on their runtime type. Any values passed into doCleanup should be treated as completely gone.

```APIDOC
## Fusion.doCleanup

### Description
Attempts to destroy all arguments based on their runtime type. This function acts as a black hole, ensuring that any values passed into it are permanently disposed of and all references are removed.

### Method Signature
```lua
function Fusion.doCleanup(
    task: Fusion.Task
): ()
```

### Parameters
#### task : Task
A value whose runtime type will be inspected to determine the appropriate cleanup action.

- If the value is a `function`, it will be called.
- If the value has a `destroy` method (e.g., `{destroy: (self) -> ()}`), `:destroy()` will be called.
- If the value has a `Destroy` method (e.g., `{Destroy: (self) -> ()}`), `:Destroy()` will be called.
- If the value is a table (e.g., `{any}`), `doCleanup` will be called recursively on all its members.

**Special handling for Roblox environment:**
- If the value is an `Instance`, `:Destroy()` will be called.
- If the value is an `RBXScriptConnection`, `:Disconnect()` will be called.

If none of these conditions match, the value is ignored.

### Learn More
- Scopes tutorial
```

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

### Registering Callback for Updates

Source: https://elttob.uk/Fusion/0.3/api-reference/graph/types/observer

Registers a callback function to be executed whenever the Observer receives an update. Returns a function to unregister the callback.

```lua
function Observer:onChange(
    callback: () -> ()
): (() -> ())
```

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

### Fusion.Observer Constructor

Source: https://elttob.uk/Fusion/0.3/api-reference/graph/members/observer

Constructs a new observer. This function is intended to be accessed as a method on a scope.

```lua
function Fusion.Observer(
    scope: Scope<unknown>,
    watching: unknown
) -> Observer
```

```lua
local observer = scope:Observer(watching)
```

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

### Fusion.Observer Constructor

Source: https://elttob.uk/Fusion/0.3/api-reference/graph/members/observer

Constructs and returns a new observer. This function is intended to be accessed as a method on a scope.

```APIDOC
## Fusion.Observer Constructor

### Description
Constructs and returns a new observer. This function is intended to be accessed as a method on a scope.

### Syntax
```lua
function Fusion.Observer(
    scope: Scope<unknown>,
    watching: unknown
) -> Observer
```

### Usage Example
```lua
local observer = scope:Observer(watching)
```

### Parameters
#### scope : Scope<unknown>
- **Description**: The scope which should be used to store destruction tasks for this object.

#### watching : unknown
- **Description**: The target that the observer should watch for changes. Works best with graph objects. While non-graph object values are accepted for compatibility, they won't be able to trigger updates.

### Returns -> Observer
- **Description**: A freshly constructed observer.
```

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

### Cleanup Method Renamed Error

Source: https://elttob.uk/Fusion/0.3/api-reference/general/errors

This error is a warning for using the deprecated `cleanup()` method, which has been renamed to `doCleanup()`. It will be a hard error in future versions.

```text
`Fusion.cleanup` was renamed to `Fusion.doCleanup`. This will be an error in
future versions of Fusion.

```

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

### Fusion.OnChange Function Signature

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/members/onchange

This snippet shows the function signature for Fusion.OnChange. It takes a property name as a string and returns a SpecialKey object.

```lua
function Fusion.OnChange(
    propertyName: string
): SpecialKey
```

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

### Fusion.ForPairs

Source: https://elttob.uk/Fusion/0.3/api-reference/state/members/forpairs

Constructs and returns a new For state object which processes keys and values in pairs. This function is intended to be accessed as a method on a scope.

```APIDOC
## Fusion.ForPairs<KI, KO, VI, VO, S>

### Description
Constructs and returns a new For state object which processes keys and values in pairs. This function is intended to be accessed as a method on a scope.

### Syntax
```lua
function Fusion.ForPairs<KI, KO, VI, VO, S>(
    scope: Scope<S>,
    inputTable: UsedAs<{[KI]: VI}>,
    processor: (Use, Scope<S>, key: KI, value: VI) -> (KO, VO)
) -> For<KO, VO>
```

### Method Syntax
```lua
local forObj = scope:ForPairs(inputTable, processor)
```

### Parameters
#### scope : Scope<S>
The scope which should be used to store destruction tasks for this object.

#### inputTable : UsedAs<{[KI]: VI}>
The table which will provide the input keys and input values for this object. If it is a state object, this object will respond to changes in that state.

#### processor : (Use, Scope<S>, key: KI, value: VI) -> (KO, VO)
Accepts a `KI` key and `VI` value pair from the input table, and returns the `KO` key and `VO` value pair that should appear in the output table. The processor is given a use function for including other objects in the computation, and a scope for queueing destruction tasks to run on re-computation. The given scope has the same methods as the scope used to create the whole object.

### Returns -> For<KO, VO>
A freshly constructed For state object.
```

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

### Fusion.OnChange

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/members/onchange

Returns a special key that can be used to listen for changes to a specific property. This key is typically used in conjunction with a callback function to execute code when the property's value is modified.

```APIDOC
## Fusion.OnChange

### Description
Given a property name, returns a special key which can listen to changes for properties of that name. When paired with a callback in a property table, the special key connects the callback to the property's change event.

### Method
```lua
function Fusion.OnChange(
    propertyName: string
): SpecialKey
```

### Parameters
#### Path Parameters
- **propertyName** (string) - Required - The name of the property that the special key should target.

### Returns
#### Success Response
- **SpecialKey** - A special key for listening to changes for properties of that name.

### Learn More
- Change Events tutorial
```

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

### Fusion.Spring<T> Function Signature

Source: https://elttob.uk/Fusion/0.3/api-reference/animation/members/spring

This is the function signature for Fusion.Spring<T>. It defines the parameters and return type for creating a spring state object.

```lua
function Fusion.Spring<T>(
    scope: Scope<unknown>,
    goal: UsedAs<T>,
    speed: UsedAs<number>?,
    damping: UsedAs<number>?
) -> Spring<T>

```

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

### Fusion.ForKeys<KI, KO, V, S>

Source: https://elttob.uk/Fusion/0.3/api-reference/state/members/forkeys

Constructs and returns a new For state object which processes keys and preserves values. This function is intended to be accessed as a method on a scope.

```APIDOC
## Fusion.ForKeys<KI, KO, V, S>

### Description
Constructs and returns a new For state object which processes keys and preserves values. Use scoped() method syntax. This function is intended to be accessed as a method on a scope.

### Method Signature
```lua
function Fusion.ForKeys<KI, KO, V, S>(
    scope: Scope<S>,
    inputTable: UsedAs<{[KI]: V}>,
    processor: (Use, Scope<S>, key: KI) -> KO
) -> For<KO, V>
```

### Usage Example
```lua
local forObj = scope:ForKeys(inputTable, processor)
```

### Parameters
#### scope : Scope<S>
The scope which should be used to store destruction tasks for this object.

#### inputTable : UsedAs<{[KI]: V}>
The table which will provide the input keys and input values for this object. If it is a state object, this object will respond to changes in that state.

#### processor : (Use, Scope<S>, key: KI) -> KO
Accepts a `KI` key from the input table, and returns the `KO` key that should appear in the output table. The processor is given a use function for including other objects in the computation, and a scope for queueing destruction tasks to run on re-computation. The given scope has the same methods as the scope used to create the whole object.

### Returns -> For<KO, V>
A freshly constructed For state object.
```

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

### setVelocity

Source: https://elttob.uk/Fusion/0.3/api-reference/animation/types/spring

Directly sets the spring's velocity without altering its current position.

```APIDOC
## setVelocity

### Description
Overwrites the spring's velocity without changing its position. The velocity must have the same `typeof()` as the goal state.

### Method Signature
```typescript
function Spring:setVelocity(
    newVelocity: T
): ()
```

### Parameters
#### Path Parameters
- **newVelocity** (T) - Required - The new velocity to set for the spring. Must be of the same type as the goal state.
```

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

### Using Computed as a Scope Method

Source: https://elttob.uk/Fusion/0.3/api-reference/state/members/computed

This demonstrates the intended usage of the Computed function as a method on a scope object. It simplifies the creation of computed states within a given scope.

```lua
local computed = scope:Computed(processor)

```

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

### Double Cleanup Attempt Error

Source: https://elttob.uk/Fusion/0.3/api-reference/general/errors

This error occurs when `doCleanup()` is called on an object or function that is already undergoing cleanup. This prevents infinite loops and ensures cleanup tasks run only once.

```text
`doCleanup()` was given something that it is already cleaning up. Unclear how to
proceed.

```

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

### Spring setPosition Method

Source: https://elttob.uk/Fusion/0.3/api-reference/animation/types/spring

Immediately sets the spring's position to a new value. The new position must match the type of the goal state.

```typescript
function Spring:setPosition(
    newPosition: T
): ()
```

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

### Fusion.Spring<T>

Source: https://elttob.uk/Fusion/0.3/api-reference/animation/members/spring

Constructs and returns a new spring state object. This function is intended to be accessed as a method on a scope.

```APIDOC
## Fusion.Spring<T>

### Description
Constructs and returns a new spring state object. Use scoped() method syntax.

### Method Signature
```lua
function Fusion.Spring<T>(
    scope: Scope<unknown>,
    goal: UsedAs<T>,
    speed: UsedAs<number>?,
    damping: UsedAs<number>?
) -> Spring<T>
```

### Usage Example
```lua
local spring = scope:Spring(goal, speed, damping)
```

### Parameters
#### Parameters
- **scope** (Scope<S>) - Required - The scope which should be used to store destruction tasks for this object.
- **goal** (UsedAs<T>) - Required - The goal that this object should follow. For best results, the goal should be animatable.
- **speed** (UsedAs<number>?) - Optional - Multiplies how fast the motion should occur; doubling the `speed` exactly halves the time it takes for the motion to complete.
- **damping** (UsedAs<number>?) - Optional - The amount of resistance the motion encounters. 0 represents no resistance, 1 is just enough resistance to prevent overshoot (critical damping), and larger values damp out inertia effects and straighten the motion.

### Returns
- **Spring<T>** - A freshly constructed spring state object.
```

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

### Contextual Type Definition

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

Defines the structure of the Contextual type, including its fields and methods. Note the non-standard 'self' syntax used for method representation.

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

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

### Fusion.Out

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/members/out

Given a property name, returns a special key which can output values from properties of that name. When paired with a value object in a property table, the special key sets the value when the property changes.

```APIDOC
## Fusion.Out

### Description
Returns a special key that targets a property by its name. This key can be used to output property values and update them dynamically when used with a value object.

### Signature
```lua
function Fusion.Out(propertyName: string): SpecialKey
```

### Parameters
#### propertyName
- **propertyName** (string) - Required - The name of the property to target for outputting values.

### Returns
- **SpecialKey** - A special key that enables outputting and updating property values.
```

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

### Fusion.doCleanup() Function Signature

Source: https://elttob.uk/Fusion/0.3/api-reference/memory/members/docleanup

This snippet shows the TypeScript signature for the doCleanup function, indicating it takes a Fusion.Task object and returns nothing.

```typescript
function Fusion.doCleanup(
    task: Fusion.Task
): ()
```

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

### Fusion.deriveScope

Source: https://elttob.uk/Fusion/0.3/api-reference/memory/members/derivescope

Creates a new scope with methods from an existing scope and optional additional methods. The new scope has an independent lifecycle from the original.

```APIDOC
## Fusion.deriveScope<Existing, AddMethods...>

### Description
Creates a new scope with methods from an existing scope and optional additional methods. The new scope has an independent lifecycle from the original.

### Method
```
function Fusion.deriveScope<Existing, AddMethods...>(
    existing: Scope<Existing>,
    ...: (AddMethods & {})...
): Scope<merge(Existing, AddMethods...)>
```

### Parameters
#### existing : Scope<T>
An existing scope, whose methods should be re-used for the new scope.

#### ... : AddMethods...
A series of tables, ideally including functions which take a scope as their first parameter. Those functions will turn into methods on the scope.

### Returns -> Scope<T>
A blank (non-inner) scope with the same methods as the existing scope, plus the extra methods provided.
```

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

### Task Type Definition

Source: https://elttob.uk/Fusion/0.3/api-reference/memory/types/task

Defines the possible structures for a Task, which are entities that `doCleanup` can process. This includes instances, RBXScriptConnections, functions, and objects with 'destroy' or 'Destroy' methods.

```typescript
export type Task =
    Instance
    | RBXScriptConnection
    | () -> ()
    | {destroy: (self) -> ()}
    | {Destroy: (self) -> ()}
    | {Task}
```

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

### Fusion.Out Function Signature

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/members/out

Defines the Fusion.Out function which takes a property name and returns a SpecialKey. This key can be used to output values from properties when they change.

```lua
function Fusion.Out(
    propertyName: string
): SpecialKey
```

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

### Contextual Type Definition

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

Defines the structure and methods of the Contextual type, including how to access its current value and how to temporarily set a new value for specific operations.

```APIDOC
## Type: Contextual<T>

### Description
An object representing a widely-accessible value, which can take on different values at different times in different coroutines.

### Fields
#### type : "Contextual"
- A type string which can be used for runtime type checking.

### Methods
#### now -> T
- **Description**: Returns the current value of this contextual. This varies based on when the function is called, and in what coroutine it was called.
- **Signature**: `function Contextual:now(): T`

#### is/during -> R
- **Description**: Runs a callback function with a temporary new value for the Contextual. The Contextual will appear to be `newValue` within the callback's scope.
- **Signature**: `function Contextual:is(newValue: T): { during: <R, A...>(self, callback: (A...) -> R, A...) -> R }`
- **Parameters**:
  - `newValue` (T): The temporary value to set for the Contextual within the callback.
  - `callback` ((A...) -> R): The function to execute with the temporary value active.
  - `A...`: Arguments to pass to the callback function.
- **Returns**: The return value of the `callback` function (R).
```

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

### Spring setVelocity Method

Source: https://elttob.uk/Fusion/0.3/api-reference/animation/types/spring

Overwrites the spring's velocity without altering its current position. The new velocity must match the type of the goal state.

```typescript
function Spring:setVelocity(
    newVelocity: T
): ()
```

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

### ForKeys Function Signature

Source: https://elttob.uk/Fusion/0.3/api-reference/state/members/forkeys

This is the function signature for ForKeys. It defines the types for input keys (KI), output keys (KO), values (V), and the scope (S).

```lua
function Fusion.ForKeys<KI, KO, V, S>(
    scope: Scope<S>,
    inputTable: UsedAs<{[KI]: V}>,
    processor: (Use, Scope<S>, key: KI) -> KO
) -> For<KO, V>


```

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

### setPosition

Source: https://elttob.uk/Fusion/0.3/api-reference/animation/types/spring

Immediately sets the spring to a new position, affecting the animation's target state.

```APIDOC
## setPosition

### Description
Immediately snaps the spring to the given position. The position must have the same `typeof()` as the goal state.

### Method Signature
```typescript
function Spring:setPosition(
    newPosition: T
): ()
```

### Parameters
#### Path Parameters
- **newPosition** (T) - Required - The new position to set the spring to. Must be of the same type as the goal state.
```

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

### set Method

Source: https://elttob.uk/Fusion/0.3/api-reference/state/types/value

Updates the value of this state object and notifies other objects of the change. The newValue is always returned.

```APIDOC
## Method: set -> T

Updates the value of this state object. Other objects using the value are notified of the change.

### Signature
```luau
function Value:set(
    newValue: T
): T
```

### Parameters
#### newValue (T) - Required
 The new value to set for the state object.

### Returns
- T: The `newValue` is always returned, so that `:set()` can be used to capture values inside of expressions.
```

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

### Spring addVelocity Method

Source: https://elttob.uk/Fusion/0.3/api-reference/animation/types/spring

Appends a velocity change to the spring's current velocity without altering its position. The delta velocity must match the type of the goal state.

```typescript
function Spring:addVelocity(
    deltaVelocity: T
): ()
```

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

### Fusion.ForPairs Function Signature

Source: https://elttob.uk/Fusion/0.3/api-reference/state/members/forpairs

This is the function signature for Fusion.ForPairs. It defines the types for keys, values, and the scope, and outlines the parameters and return type.

```typescript
function Fusion.ForPairs<KI, KO, VI, VO, S>(
    scope: Scope<S>,
    inputTable: UsedAs<{[KI]: VI}>,
    processor: (Use, Scope<S>, key: KI, value: VI) -> (KO, VO)
) -> For<KO, VO>
```

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

### Version Type Definition

Source: https://elttob.uk/Fusion/0.3/api-reference/general/types/version

Defines the structure for representing a version of Fusion's source code. Includes major and minor version numbers and a release status flag.

```typescript
export type Version = {
    major: number,
    minor: number,
    isRelease: boolean
}
```

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

### GraphObject _evaluate Method Signature

Source: https://elttob.uk/Fusion/0.3/api-reference/graph/types/graphobject

Shows the signature for the _evaluate method, which is called by Fusion during graph object evaluation. It returns a boolean indicating if a meaningful change occurred.

```lua
function GraphObject:_evaluate(): boolean


```

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

### Spring Type Definition

Source: https://elttob.uk/Fusion/0.3/api-reference/animation/types/spring

Defines the structure of a Spring, including its kind, and methods for controlling position and velocity.

```APIDOC
## Spring Type

### Description
A specialized state object for following a goal state smoothly over time, using physics to shape the motion. The methods on this type allow for direct control over the position and velocity of the motion.

### Type Definition
```typescript
export type Spring<T> = StateObject<T> & {
    kind: "Spring",
    setPosition: (self, newPosition: T) => (),
    setVelocity: (self, newVelocity: T) => (),
    addVelocity: (self, deltaVelocity: T) => ()
}
```

### Members
#### kind
- **kind** (string) - Required - A more specific type string which can be used for runtime type checking. This can be used to tell types of state object apart. Its value is always "Spring".
```

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

### Fusion.OnEvent

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/members/onevent

Returns a special key that can be used to listen for events of a specified name. This key is used to connect callbacks to events when provided in a property table.

```APIDOC
## Fusion.OnEvent

### Description
Given an event name, returns a special key which can listen for events of that name. When paired with a callback in a property table, the special key connects the callback to the event.

### Method
```
function Fusion.OnEvent(
    eventName: string
): SpecialKey
```

### Parameters
#### Path Parameters
- **eventName** (string) - Required - The name of the event that the special key should target.

### Returns
- **SpecialKey** - A special key for listening to events of that name.
```

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

### Value Type Definition

Source: https://elttob.uk/Fusion/0.3/api-reference/state/types/value

Defines the structure and properties of the Value type, including its kind and set method.

```APIDOC
## Type: Value<T>

A specialised state object which allows regular Luau code to control its value.

### Type Definition
```luau
export type Value<T> = StateObject<T> & {
    kind: "State",
    set: (self, newValue: T) -> (),
    timeliness: "lazy"
}
```

### Members
#### kind : "Value" 
 A more specific type string which can be used for runtime type checking. This can be used to tell types of state object apart.
```

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

### addVelocity

Source: https://elttob.uk/Fusion/0.3/api-reference/animation/types/spring

Applies a change to the spring's current velocity, modifying its motion.

```APIDOC
## addVelocity

### Description
Appends to the spring's velocity without changing its position. The velocity must have the same `typeof()` as the goal state.

### Method Signature
```typescript
function Spring:addVelocity(
    deltaVelocity: T
): ()
```

### Parameters
#### Path Parameters
- **deltaVelocity** (T) - Required - The velocity to add to the spring's current velocity. Must be of the same type as the goal state.
```

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

### Fusion.innerScope

Source: https://elttob.uk/Fusion/0.3/api-reference/memory/members/innerscope

Creates a new inner scope that inherits methods from an existing scope and can merge in additional methods. The returned scope is nested within the original scope and its lifecycle is tied to the original scope's cleanup.

```APIDOC
## Fusion.innerScope

### Description
Creates a new inner scope that inherits methods from an existing scope and can merge in additional methods. The returned scope is nested within the original scope and its lifecycle is tied to the original scope's cleanup.

### Method
```
function Fusion.innerScope<Existing, AddMethods...>(existing: Scope<Existing>, ...: (AddMethods & {})...): Scope<merge(Existing, AddMethods...)>
```

### Parameters
#### existing : Scope<T>
An existing scope, whose methods should be re-used for the new scope.

#### ... : AddMethods...
A series of tables, ideally including functions which take a scope as their first parameter. Those functions will turn into methods on the scope.

### Returns -> Scope<T>
A blank inner scope with the same methods as the existing scope, plus the extra methods provided.
```

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

### Fusion.peek<T>(target: UsedAs<T>): T

Source: https://elttob.uk/Fusion/0.3/api-reference/state/members/peek

Extracts a value of type T from its input target. This method is a general-purpose implementation of Use and does not perform additional processing beyond determining the returned value.

```APIDOC
## Fusion.peek<T>(target: UsedAs<T>): T

### Description
Extracts a value of type `T` from its input `target`. This is a general-purpose implementation of `Use` and does not perform any extra processing or book-keeping beyond what is required to determine the returned value.

### Method
```
function Fusion.peek<T>(
    target: UsedAs<T>
): T
```

### Parameters
#### target : UsedAs<T>
- **target** (UsedAs<T>) - Required - The abstract representation of `T` to extract a value from.

### Returns -> T
- The current value of `T`, derived from `target`.
```

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

### Observer:onChange

Source: https://elttob.uk/Fusion/0.3/api-reference/graph/types/observer

Registers a callback function to be executed whenever the Observer receives an update from the reactive graph. It returns a function that can be called to unregister the callback.

```APIDOC
## Observer:onChange

### Description
Registers the callback to run when an update is received. The returned function will unregister the callback.

### Method
Observer.onChange

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **callback** (() -> ()) - The function to be executed on update.

#### Response Example
None
```

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

### Fusion.AttributeOut

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/members/attributeout

Creates a special key that outputs values from attributes of a specified name. This is useful for dynamically updating values when an attribute changes.

```APIDOC
## Fusion.AttributeOut

### Description
Given an attribute name, returns a special key which can output values from attributes of that name. When paired with a value object in a property table, the special key sets the value when the attribute changes.

### Parameters
#### attributeName : string
The name of the attribute that the special key should target.

### Returns -> SpecialKey
A special key for outputting values from attributes of that name.
```

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

### SpecialKey Type Definition

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/types/specialkey

Defines the structure of the SpecialKey type, including its members and the apply method signature.

```APIDOC
## Type: SpecialKey

### Description
Represents a custom operation to be applied to a Roblox instance during its creation.

### Members
- **type**: string - A type string for runtime checking, always "SpecialKey".
- **kind**: string - A more specific type string for differentiating special keys.
- **stage**: "self" | "descendants" | "ancestor" | "observer" - Determines when the operation is applied relative to parenting.
  - `self`: Runs before parenting any instances.
  - `descendants`: Runs after descendants are parented, but before the instance is parented to its ancestor.
  - `ancestor`: Runs after all parenting operations are complete.
  - `observer`: Runs after all other operations to observe the final state.

### Methods
#### apply

- **Description**: Called to apply this operation to an instance. `value` is the value from the property table, and `applyTo` is the instance to apply the operation to.
- **Signature**: `function SpecialKey:apply(self, scope: Scope<unknown>, value: unknown, applyTo: Instance): ()
- **Scope**: The provided `scope` is cleaned up when the operation is unapplied or the instance is destroyed. Operations should use the scope for cleanup.
```

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

### Construct a Contextual Object

Source: https://elttob.uk/Fusion/0.3/api-reference/general/members/contextual

Use Fusion.Contextual to create a new contextual object. This object will return the provided defaultValue if no value is set using Contextual:is():during().

```typescript
function Fusion.Contextual<T>(
    defaultValue: T
): Contextual<T>


```

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

### Fusion.peek<T> Function Signature

Source: https://elttob.uk/Fusion/0.3/api-reference/state/members/peek

This is the general-purpose function signature for Fusion.peek<T>. It extracts a value of type T from a UsedAs<T> target.

```typescript
function Fusion.peek<T>(
    target: UsedAs<T>
): T
```

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

### Set Method for Value

Source: https://elttob.uk/Fusion/0.3/api-reference/state/types/value

Updates the value of a Value state object and returns the new value. Other objects using this value are notified of the change.

```luau
function Value:set(
    newValue: T
): T
```

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

### Constructing a Value<T> State Object

Source: https://elttob.uk/Fusion/0.3/api-reference/state/members/value

Use this function to create a new state object. It is intended to be accessed as a method on a scope object.

```typescript
function Fusion.Value<T>(
    scope: Scope<unknown>,
    initialValue: T
) -> Value<T>

```

```lua
local computed = scope:Computed(processor)

```

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

### Fusion.scoped Function Signature

Source: https://elttob.uk/Fusion/0.3/api-reference/memory/members/scoped

This is the function signature for Fusion.scoped. It accepts a variable number of method tables and returns a Scope object.

```Luau
function Fusion.scoped<
    Methods...
>(
    ...: (Methods & {})...
): Scope<merge(Methods)>
```

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

### Fusion.New Function Signature

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/members/new

Defines the signature for the Fusion.New function, which takes a class name and returns a component for creating instances with a property table.

```typescript
function Fusion.New(
    className: string
): (
    props: PropertyTable
) -> Instance

```

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

### Fusion.AttributeChange

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/members/attributechange

Given an attribute name, returns a special key which can listen to changes for attributes of that name. When paired with a callback in a property table, the special key connects the callback to the attribute's change event.

```APIDOC
## Fusion.AttributeChange

### Description
Returns a special key that listens for changes to attributes with the specified name. This key can be used to connect callbacks to attribute change events.

### Method
```
function Fusion.AttributeChange(
    attributeName: string
): SpecialKey
```

### Parameters
#### attributeName
- **attributeName** (string) - Required - The name of the attribute to listen for changes on.

### Returns
- **SpecialKey** - A special key for listening to changes for attributes of that name.
```

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

### Fusion.scoped

Source: https://elttob.uk/Fusion/0.3/api-reference/memory/members/scoped

Creates a new scope with merged methods. Functions within the provided tables that accept a scope as their first parameter will become methods on the returned scope.

```APIDOC
## Fusion.scoped

### Description
Creates a new scope by merging method tables. Functions within these tables that take a scope as their first argument are exposed as methods on the new scope.

### Method Signature
```lua
function Fusion.scoped<Methods...>(...: (Methods & {})...): Scope<merge(Methods)>
```

### Parameters
#### Methods
- **...** (Methods & {}): A series of tables containing functions. Functions designed to accept a scope as their first parameter will be converted into methods of the returned scope.

### Returns
- **Scope<T>** : A new, blank scope object with the merged methods.

### Learn More
- Scopes tutorial
```

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

### For Loop Key Collision Error

Source: https://elttob.uk/Fusion/0.3/api-reference/general/errors

This error is thrown when a `For` object returns the same key multiple times simultaneously, which is not permitted as keys must be unique within a table.

```text
The key '6' was returned multiple times simultaneously, which is not allowed in
`For` objects.

```

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

### Fusion.OnEvent Function Signature

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/members/onevent

This is the function signature for Fusion.OnEvent. It takes an eventName string and returns a SpecialKey object.

```lua
function Fusion.OnEvent(
    eventName: string
): SpecialKey

```

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

### Observer Type Definition

Source: https://elttob.uk/Fusion/0.3/api-reference/graph/types/observer

Defines the structure of an Observer object, including its type, timeliness, and callback registration methods.

```typescript
export type Observer = GraphObject & {
    type: "Observer",
    timeliness: "eager",
    onChange: (self, callback: () -> ()) -> (() -> ()),
    onBind: (self, callback: () -> ()) -> (() -> ())
}
```

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

### Dependency Cycle Error

Source: https://elttob.uk/Fusion/0.3/api-reference/general/errors

This error arises when attempting to establish a dependency between two graph objects where either the dependency set or the dependent set is frozen, or if the objects are not designed for such relationships.

```text
Observer can't depend on Observer.

```

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

### Derive a New Scope with Additional Methods

Source: https://elttob.uk/Fusion/0.3/api-reference/memory/members/derivescope

Creates a new scope that inherits methods from an existing scope and merges in additional methods. The returned scope has an independent lifecycle from the original.

```typescript
function Fusion.deriveScope<Existing, AddMethods...>(
    existing: Scope<Existing>,
    ...: (AddMethods & {})...
): Scope<merge(Existing, AddMethods...)>
```

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

### GraphObject._evaluate Method

Source: https://elttob.uk/Fusion/0.3/api-reference/graph/types/graphobject

The `_evaluate` method is called by the system during the graph object's evaluation process. It's used to implement computational updates and should return true if a 'meaningful change' occurred that could affect dependencies.

```APIDOC
## GraphObject._evaluate Method

### Description
This method is called by the system during the graph object's evaluation process. It's where logic for computational updates should be placed. The return value indicates whether a 'meaningful change' occurred that might affect dependencies.

### Method Signature
`function GraphObject:_evaluate(): boolean`

### Returns
- `boolean` - `true` if a 'meaningful change' occurred, `false` otherwise.

### Restrictions
This method must complete without spawning new processes, blocking the thread, or erroring.
```

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

### Fusion.Children: SpecialKey

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/members/children

This special key parents other instances into this instance. When paired with a `Child` in a property table, it explores the `Child` to find every `Instance` nested inside and parents them under the instance to which the special key was applied. It will recursively explore arrays and bind to any state objects.

```lua
Fusion.Children: SpecialKey
```

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

### Fusion.ForValues

Source: https://elttob.uk/Fusion/0.3/api-reference/state/members/forvalues

Constructs and returns a new For state object which processes values and preserves keys. This function is intended to be accessed as a method on a scope.

```APIDOC
## Fusion.ForValues<K, VI, VO, S>

### Description
Constructs and returns a new For state object which processes values and preserves keys. This function is intended to be accessed as a method on a scope.

### Method Signature
```lua
function Fusion.ForValues<K, VI, VO, S>(
    scope: Scope<S>,
    inputTable: UsedAs<{[K]: VI}>,
    processor: (Use, Scope<S>, value: VI) -> VO
) -> For<K, VO>
```

### Usage
```lua
local forObj = scope:ForValues(inputTable, processor)
```

### Parameters
#### scope : Scope<S>
The scope which should be used to store destruction tasks for this object.

#### inputTable : UsedAs<{[K]: VI}>
The table which will provide the input keys and input values for this object. If it is a state object, this object will respond to changes in that state.

#### processor : (Use, Scope<S>, value: VI) -> VO
Accepts a `VI` value from the input table, and returns the `VO` value that should appear in the output table. The processor is given a use function for including other objects in the computation, and a scope for queueing destruction tasks to run on re-computation. The given scope has the same methods as the scope used to create the whole object.

### Returns -> For<K, VO>
A freshly constructed For state object.
```

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

### Fusion.Hydrate

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/members/hydrate

Hydrates a Roblox Instance by binding extra functionality and properties. It returns a component that accepts properties to build up bindings and operations applied to the instance.

```APIDOC
## Fusion.Hydrate

### Description

Given an instance, returns a component for binding extra functionality to that instance. In the property table, string keys are assigned as properties on the instance. If the value is a state object, it is re-assigned every time the value of the state object changes. Any special keys present in the property table are applied to the instance after string keys are processed, in the order specified by their `stage`. A special exception is made for assigning `Parent`, which is only assigned after the `descendants` stage. Do not overwrite properties: If the instance was previously created with `New` or previously hydrated, do not assign to any properties that were previously specified in those prior calls. Duplicated assignments can interfere with each other in unpredictable ways.

### Parameters

#### target

* **target** (Instance) - The instance which should be modified.

### Returns

* **(PropertyTable) -> Instance** - A component that hydrates that instance, accepting various properties to build up bindings and operations applied to the instance.
```

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

### Fusion.Attribute

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/members/attribute

Creates a special key that targets a specific attribute name. This key can then be used in property tables to set the attribute to a desired value.

```APIDOC
## Fusion.Attribute

### Description
Given an attribute name, returns a special key which can modify attributes of that name. When paired with a value in a property table, the special key sets the attribute to that value.

### Parameters
#### attributeName : string
The name of the attribute that the special key should target.

### Returns -> SpecialKey
A special key for modifying attributes of that name.
```

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

### Fusion ForValues Function Signature

Source: https://elttob.uk/Fusion/0.3/api-reference/state/members/forvalues

This is the function signature for Fusion.ForValues. It defines the types for keys, input values, output values, and the scope.

```typescript
function Fusion.ForValues<K, VI, VO, S>(
    scope: Scope<S>,
    inputTable: UsedAs<{[K]: VI}>,
    processor: (Use, Scope<S>, value: VI) -> VO
) -> For<K, VO>

```

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

### Fusion.Value<T>

Source: https://elttob.uk/Fusion/0.3/api-reference/state/members/value

Constructs and returns a new value state object. This function is intended to be accessed as a method on a scope.

```APIDOC
## Fusion.Value<T>

### Description
Constructs and returns a new value state object. This function is intended to be accessed as a method on a scope.

### Signature
```lua
function Fusion.Value<T>(
    scope: Scope<unknown>,
    initialValue: T
) -> Value<T>
```

### Parameters
#### scope
- **scope** (Scope<S>) - Required - The scope which should be used to store destruction tasks for this object.
#### initialValue
- **initialValue** (T) - Required - The initial value that will be stored until the next value is `:set()`.

### Returns
- **Value<T>** - A freshly constructed value state object.
```

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

### Callback Function Error

Source: https://elttob.uk/Fusion/0.3/api-reference/general/errors

This error occurs when a callback function provided to Fusion encounters an issue, such as attempting arithmetic operations on incompatible types (e.g., number and string).

```text
Error in callback: attempt to perform arithmetic (add) on number and string

```

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

### Fusion.Safe Function Signature

Source: https://elttob.uk/Fusion/0.3/api-reference/general/members/safe

The signature for Fusion.Safe, detailing its generic types and the structure of the callbacks object it accepts. This function is used to run a 'try' function and provides a 'fallback' for error handling.

```typescript
function Fusion.Safe<Success, Fail>(
    callbacks: {
        try: () -> Success,
        fallback: (err: unknown) -> Fail
    }
): Success | Fail

```

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

### Fusion.Contextual<T>

Source: https://elttob.uk/Fusion/0.3/api-reference/general/members/contextual

Constructs and returns a new contextual object. This object can be used to manage a default value that can be overridden during specific operations.

```APIDOC
## Fusion.Contextual<T>

### Description
Constructs and returns a new contextual object. This object can be used to manage a default value that can be overridden during specific operations.

### Method
```
function Fusion.Contextual<T>(
    defaultValue: T
): Contextual<T>
```

### Parameters
#### defaultValue : T
The value which `Contextual:now()` should return if no value has been specified by `Contextual:is():during()`.

### Returns -> Contextual<T>
A freshly constructed contextual.

### Learn More
* Sharing Values tutorial
```

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

### Unassignable Property Error

Source: https://elttob.uk/Fusion/0.3/api-reference/general/errors

This error is thrown when attempting to set a property on an instance that cannot be assigned. This can happen if the property does not exist or is protected from modification by Roblox.

```text
The class type 'Foo' has no assignable property 'Bar'.

```

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

### Temporarily Override Contextual Value

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

Executes a callback function with a temporary override of the Contextual's value. The original value is restored after the callback completes. The callback's return value is propagated.

```luau
function Contextual:is(
    newValue: T
): {
    during: <R, A...>(
        self,
        callback: (A...) -> R,
        A...
    ) -> R
}
```

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

### SpecialKey Type Definition

Source: https://elttob.uk/Fusion/0.3/api-reference/roblox/types/specialkey

Defines the structure of a SpecialKey object, including its type, kind, stage, and the apply function.

```typescript
export type SpecialKey = {
    type: "SpecialKey",
    kind: string,
    stage: "self" | "descendants" | "ancestor" | "observer",
    apply: (
        self,
        scope: Scope<unknown>,
        value: unknown,
        applyTo: Instance
    ) -> ()
}

```
Tokens:
Raw