MotionFX

Preset and view names, grouped as Impact, Injury, View and Primitives. Typing MotionFX.Enum. autocompletes the groups and their names. Each entry is just its own string, so FX.Impact.Explosion == "Explosion". See Enum groups.

The driver library: Constant, Tween, Envelope, Noise, Spring, Bind, Cycle, Modulate, Sum, Sequence and Map. See Drive.

Ready-made tracks: Shake, Kick, Punch, Zoom, Edge, Flash, Blur, Tint, Overlay and Sound. Each returns an ordinary track with sensible defaults. See Ready-made tracks.

A frozen table of named, ready-to-use overlay sheets, used with Track.Overlay. Its names autocomplete. See Overlay presets.

Helpers for overlay sheets:

task.spawn(MotionFX.Overlay.Preload, MotionFX.Overlays.SnowOnScreen)

Not to be confused with MotionFX.Overlays, the table of ready-made sheets.

A frozen table of named sound asset ids used by the presets. Its names autocomplete. You can use them in your own Sound tracks too. See Sounds.

A live settings table for views and smoothing. Change a field and the change applies on the next frame. See View settings.

MotionFX.ViewSettings.ShoulderOffset = Vector3.new(-2.75, 0.5, 6.5) -- left shoulder

MotionFX:Create(name: string, definition: EffectDefinition, options: CreateOptions?): string

Registers a named effect so that Play(name) can run it, and returns name. The definition is validated right away. By default it errors if name is already taken, including by a built-in preset. Pass { Overwrite = true } to replace it.

MotionFX:Create("Stagger", {
	Duration = 1.2,
	FadeOut = 0.4,
	Retrigger = "Refresh",
	Tracks = {
		{ Primitive = "Rotation", Driver = Drive.Spring({ Kick = Vector3.new(0, 0, 6), Frequency = 2, Damping = 0.3 }) },
		{ Primitive = "Blur", Driver = Drive.Constant(6), Delay = 0.1 },
	},
})

MotionFX:Remove(name: string): ()

Unregisters a definition. Instances that are already running keep playing. Later Play(name) calls error.

MotionFX:Has(name: string): boolean

Returns true if an effect with that name is registered. Built-in presets count.

if not MotionFX:Has("Stagger") then
	MotionFX:Create("Stagger", definition)
end

MotionFX:Play(name: PresetName, options: PlayOptions?): Handle

Starts a registered effect and returns its Handle. What happens when the effect is already running depends on its Retrigger policy. Errors if no effect is registered under that name.

local handle = MotionFX:Play(FX.Impact.Earthquake, { Intensity = 0.5, Speed = 1.25 })
MotionFX:Play("Shake", { Params = { Sound = false } })

MotionFX:Stop(name: PresetName, fadeTime: number?): ()

Stops every running instance of name. With no fadeTime, each instance uses its own FadeOut.

MotionFX:StopAll(fadeTime: number?): ()

Stops every running effect, including those started with Apply. Views and smoothing are not affected.

MotionFX:GetActive(name: PresetName?): { Handle }

Returns the handles that haven't finished yet, including those in the "Stopping" state. Pass a name to only get that effect's handles.

local burning = #MotionFX:GetActive("Burning") > 0

MotionFX:Apply(primitive: PrimitiveName, driver: Driver<T>, options: PlayOptions?): Handle

Drives one primitive directly, without a named effect. Depending on the driver, the result is an instant set (Constant), an animation (Tween, Spring…) or a permanent binding (Bind). Every call is independent, with no retrigger rules. The overloads are typed so that each primitive only accepts its own value type. "Sound" can't be applied.

-- Zoom in 10 degrees over 0.25 s, hold, then release when the aim ends
local aim = MotionFX:Apply("FOV", Drive.Sequence(
	Drive.Tween(0, -10, 0.25),
	Drive.Constant(-10)
))
-- ...
aim:Stop(0.2)

MotionFX:SetView(view: ViewName, transitionTime: number?): ()

Switches to "Default", "FirstPerson", "ThirdPerson" or "BackView", blending over transitionTime (0.4 s by default, and 0 snaps). Errors on an unknown view name.

MotionFX:SetView(FX.View.ThirdPerson, 0.6)

MotionFX:ToggleView(view: ViewName, transitionTime: number?): ViewName

Switches to view. If view is already active, switches back to "Default". Returns the new view.

MotionFX:GetView(): ViewName

Returns the current view.

MotionFX:SetSmoothing(enabled: boolean, responsiveness: number?): ()

Makes the camera ease after the mouse instead of snapping to it, in any view. responsiveness (roughly 1 / seconds, default 12) must be greater than 0. It is stored in ViewSettings.Responsiveness.

MotionFX:SetSmoothing(true, 8) -- softer follow

MotionFX:IsSmoothing(): boolean

Returns whether smoothing is on.

handle:SetIntensity(value: number, fadeTime: number?): ()

Retargets the master intensity, either instantly or at a constant rate over fadeTime. Use it to drive an effect's strength from gameplay. It does nothing on a finished handle.

local damage = MotionFX:Play(FX.Injury.BrainDamage, { Duration = math.huge })
damage:SetIntensity(0.3, 1)   -- ease down to 30% over a second

handle:Stop(fadeTime: number?): ()

Fades the effect out over fadeTime seconds, or over its FadeOut if you pass nothing, and then finishes it. Sounds fade as well. A fade time of 0 finishes immediately. It only works while the handle is "Playing".

Fires once when the handle reaches "Finished", whether it ran out or was stopped. It supports Connect, Once and Wait. Callbacks run in new threads via task.spawn.

MotionFX:Play("Concussion").Finished:Once(function()
	print("back to normal")
end)