Skip to main content

Presets

The registry of subject presets: named resolvers that produce a track's subject on the client at play time, for subjects that do not exist while the sequence is authored, such as the local player's character. The editor authors against a stand-in, and the runtime falls back to the stand-in if the preset fails to resolve.

A custom preset is a ModuleScript in Flow.CustomPresets that returns a Presets.PresetDefinition.

Types​

PresetDefinition​

</>
interface PresetDefinition {
Name: string--

Identifier-like; "Custom" is reserved

DisplayName: string
Description: string?
SubjectClass: string?
Resolve: (context: PresetContext) → PresetResult?--

Runs on the client before the clock starts, and may yield

CreateStandIn: (context: PresetContext) → Instance?--

Returns an unparented placeholder

}

PresetContext​

</>
interface PresetContext {
Sequence: SequenceData
Binding: BindingData--

The binding the preset is producing a subject for

Root: Instance--

The playback's root

Label: string
}

PresetResult​

</>
interface PresetResult {
Subject: Instance
Cleanup: (() → ())?--

Takes the subject down when playback ends; nil for a subject the preset does not own

}

Properties​

Changed​

</>
Presets.Changed: Signal

Fires when a preset is registered or unregistered.

Functions​

Validate​

</>
Presets.Validate(candidate: any) → (
boolean,--

Whether it conforms

{string}--

Every problem found, empty when it conforms

)

Checks a candidate module against the preset schema without registering it.

Register​

</>
Presets.Register(
definition: PresetDefinition,
source: Instance?
) → (
boolean,--

Whether it was registered

{string}--

Errors when it was not

)

Validates and registers a preset. Pass the source ModuleScript to mark it as custom; a custom preset cannot replace a built-in one.

Unregister​

</>
Presets.Unregister(name: string) → ()

Removes a custom preset. Built-in presets cannot be unregistered.

Get​

</>
Presets.Get(name: string) → PresetDefinition?

GetNames​

</>
Presets.GetNames() → {string}

Built-in names in registration order, then custom names alphabetically.

IsCustom​

</>
Presets.IsCustom(name: string) → boolean

GetSource​

</>
Presets.GetSource(name: string) → Instance?

The ModuleScript a custom preset was loaded from.

LoadFolder​

</>
Presets.LoadFolder(folder: Instance?) → LoadResult

Types

​

interface LoadResult {
Loaded: {string}--

Names registered

Errors: {[string]: {string}}--

Validation errors, by module name

}

Requires every ModuleScript in folder and registers the ones that conform. Custom presets whose module is no longer in the folder are unregistered.

GetSubjectParent​

</>
Presets.GetSubjectParent(root: Instance) → Instance

Where a preset subject lives so it renders: the root when it is or sits inside a WorldModel or ViewportFrame, and Workspace otherwise.

GetPlacement​

</>
Presets.GetPlacement(
root: Instance,
localPivot: CFrame?
) → CFrame

Where a preset subject stands before anything animates it: localPivot relative to the root's origin, or the origin itself when there is none.

PlaceSubject​

</>
Presets.PlaceSubject(
subject: Instance,
root: Instance,
localPivot: CFrame?
) → ()

Pivots a preset subject onto Presets.GetPlacement and parents it to Presets.GetSubjectParent. The runtime does this to every resolved subject and stand-in, so Resolve does not need to.

Show raw api
{
    "functions": [
        {
            "name": "Validate",
            "desc": "Checks a candidate module against the preset schema without registering it.",
            "params": [
                {
                    "name": "candidate",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "Whether it conforms",
                    "lua_type": "boolean"
                },
                {
                    "desc": "Every problem found, empty when it conforms",
                    "lua_type": "{ string }"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 112,
                "path": "runtime/Presets/init.luau"
            }
        },
        {
            "name": "Register",
            "desc": "Validates and registers a preset. Pass the `source` ModuleScript to mark it as custom; a custom preset\ncannot replace a built-in one.",
            "params": [
                {
                    "name": "definition",
                    "desc": "",
                    "lua_type": "PresetDefinition"
                },
                {
                    "name": "source",
                    "desc": "",
                    "lua_type": "Instance?"
                }
            ],
            "returns": [
                {
                    "desc": "Whether it was registered",
                    "lua_type": "boolean"
                },
                {
                    "desc": "Errors when it was not",
                    "lua_type": "{ string }"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 147,
                "path": "runtime/Presets/init.luau"
            }
        },
        {
            "name": "Unregister",
            "desc": "Removes a custom preset. Built-in presets cannot be unregistered.",
            "params": [
                {
                    "name": "name",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 170,
                "path": "runtime/Presets/init.luau"
            }
        },
        {
            "name": "Get",
            "desc": "",
            "params": [
                {
                    "name": "name",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PresetDefinition?\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 183,
                "path": "runtime/Presets/init.luau"
            }
        },
        {
            "name": "GetNames",
            "desc": "Built-in names in registration order, then custom names alphabetically.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ string }\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 191,
                "path": "runtime/Presets/init.luau"
            }
        },
        {
            "name": "IsCustom",
            "desc": "",
            "params": [
                {
                    "name": "name",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 207,
                "path": "runtime/Presets/init.luau"
            }
        },
        {
            "name": "GetSource",
            "desc": "The ModuleScript a custom preset was loaded from.",
            "params": [
                {
                    "name": "name",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Instance?\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 215,
                "path": "runtime/Presets/init.luau"
            }
        },
        {
            "name": "LoadFolder",
            "desc": "Requires every ModuleScript in `folder` and registers the ones that conform. Custom presets whose module is\nno longer in the folder are unregistered.",
            "params": [
                {
                    "name": "folder",
                    "desc": "",
                    "lua_type": "Instance?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "LoadResult\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 224,
                "path": "runtime/Presets/init.luau"
            }
        },
        {
            "name": "GetSubjectParent",
            "desc": "Where a preset subject lives so it renders: the root when it is or sits inside a WorldModel or\nViewportFrame, and Workspace otherwise.",
            "params": [
                {
                    "name": "root",
                    "desc": "",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Instance\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 261,
                "path": "runtime/Presets/init.luau"
            }
        },
        {
            "name": "GetPlacement",
            "desc": "Where a preset subject stands before anything animates it: `localPivot` relative to the root's origin, or\nthe origin itself when there is none.",
            "params": [
                {
                    "name": "root",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "localPivot",
                    "desc": "",
                    "lua_type": "CFrame?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "CFrame\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 273,
                "path": "runtime/Presets/init.luau"
            }
        },
        {
            "name": "PlaceSubject",
            "desc": "Pivots a preset subject onto [Presets.GetPlacement] and parents it to [Presets.GetSubjectParent]. The\nruntime does this to every resolved subject and stand-in, so `Resolve` does not need to.",
            "params": [
                {
                    "name": "subject",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "root",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "localPivot",
                    "desc": "",
                    "lua_type": "CFrame?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 282,
                "path": "runtime/Presets/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "Changed",
            "desc": "Fires when a preset is registered or unregistered.",
            "lua_type": "Signal",
            "source": {
                "line": 89,
                "path": "runtime/Presets/init.luau"
            }
        }
    ],
    "types": [
        {
            "name": "LoadResult",
            "desc": "",
            "fields": [
                {
                    "name": "Loaded",
                    "lua_type": "{ string }",
                    "desc": "Names registered"
                },
                {
                    "name": "Errors",
                    "lua_type": "{ [string]: { string } }",
                    "desc": "Validation errors, by module name"
                }
            ],
            "source": {
                "line": 29,
                "path": "runtime/Presets/init.luau"
            }
        },
        {
            "name": "PresetDefinition",
            "desc": "",
            "fields": [
                {
                    "name": "Name",
                    "lua_type": "string",
                    "desc": "Identifier-like; `\"Custom\"` is reserved"
                },
                {
                    "name": "DisplayName",
                    "lua_type": "string",
                    "desc": ""
                },
                {
                    "name": "Description",
                    "lua_type": "string?",
                    "desc": ""
                },
                {
                    "name": "SubjectClass",
                    "lua_type": "string?",
                    "desc": ""
                },
                {
                    "name": "Resolve",
                    "lua_type": "(context: PresetContext) -> PresetResult?",
                    "desc": "Runs on the client before the clock starts, and may yield"
                },
                {
                    "name": "CreateStandIn",
                    "lua_type": "(context: PresetContext) -> Instance?",
                    "desc": "Returns an unparented placeholder"
                }
            ],
            "source": {
                "line": 57,
                "path": "runtime/Presets/init.luau"
            }
        },
        {
            "name": "PresetContext",
            "desc": "",
            "fields": [
                {
                    "name": "Sequence",
                    "lua_type": "SequenceData",
                    "desc": ""
                },
                {
                    "name": "Binding",
                    "lua_type": "BindingData",
                    "desc": "The binding the preset is producing a subject for"
                },
                {
                    "name": "Root",
                    "lua_type": "Instance",
                    "desc": "The playback's root"
                },
                {
                    "name": "Label",
                    "lua_type": "string",
                    "desc": ""
                }
            ],
            "source": {
                "line": 66,
                "path": "runtime/Presets/init.luau"
            }
        },
        {
            "name": "PresetResult",
            "desc": "",
            "fields": [
                {
                    "name": "Subject",
                    "lua_type": "Instance",
                    "desc": ""
                },
                {
                    "name": "Cleanup",
                    "lua_type": "(() -> ())?",
                    "desc": "Takes the subject down when playback ends; nil for a subject the preset does not own"
                }
            ],
            "source": {
                "line": 73,
                "path": "runtime/Presets/init.luau"
            }
        }
    ],
    "name": "Presets",
    "desc": "The registry of subject presets: named resolvers that produce a track's subject on the client at play time,\nfor subjects that do not exist while the sequence is authored, such as the local player's character. The\neditor authors against a stand-in, and the runtime falls back to the stand-in if the preset fails to\nresolve.\n\nA custom preset is a ModuleScript in `Flow.CustomPresets` that returns a [Presets.PresetDefinition].",
    "source": {
        "line": 46,
        "path": "runtime/Presets/init.luau"
    }
}