Skip to main content

StepUtils

Utility functions primarily used to bind animations into update loops of the Roblox engine.

Functions​

getAnimationStepSignal​

</>
StepUtils.getAnimationStepSignal() → RBXScriptSignal

Returns the signal animation should step on: RunService.RenderStepped on the client, RunService.Stepped (the physics pre-step) on a running server so that writes land before the physics step -- springs that drive CFrames stay in lockstep with constraints, characters, and replication. Heartbeat is only the fallback for a non-running DataModel (headless test runs, edit mode), where Stepped never fires.

Use this instead of hand-rolling the realm branch at call sites.

CAUTION

The argument shape is realm-dependent: RenderStepped fires (deltaTime) but Stepped fires (time, deltaTime). Shared code connecting directly to this signal must not assume the first argument is deltaTime.

getSteppedSignal​

</>
StepUtils.getSteppedSignal() → RBXScriptSignal

Returns the signal per-frame bookkeeping should run on: RunService.Stepped (the physics pre-step) on a running DataModel, falling back to RunService.Heartbeat on a non-running one (headless test runs, edit mode) where Stepped never fires.

Unlike StepUtils.getAnimationStepSignal this does not branch to RenderStepped on the client, so both realms step at the same point in the frame. Prefer it for work that is not driving visuals -- rescoring, polling, cache invalidation -- and that would otherwise silently stop running outside a live game.

CAUTION

Stepped fires (time, deltaTime) but Heartbeat fires (deltaTime). Do not assume the first argument is deltaTime when connecting directly to this signal.

bindToRenderStep​

</>
StepUtils.bindToRenderStep(
update: () → boolean--

should return true while it needs to update

) → (
(...) → (),--

Connect function

() → ()--

Disconnect function

)

Binds the given update function to StepUtils.getAnimationStepSignal.

local spring = Spring.new(0)
local maid = Maid.new()

local startAnimation, maid._stopAnimation = StepUtils.bindToRenderStep(function()
	local animating, position = SpringUtils.animating(spring)

	print(position)

	return animating
end)

spring.t = 1
startAnimation()
TIP

Be sure to call the disconnect function when cleaning up, otherwise you may memory leak.

deferWait​

</>
StepUtils.deferWait() → ()

Yields until the frame deferral is done

bindToStepped​

</>
StepUtils.bindToStepped(
update: () → boolean--

should return true while it needs to update

) → (
(...) → (),--

Connect function

() → ()--

Disconnect function

)

Binds the given update function to RunService.Stepped. See StepUtils.bindToRenderStep for details.

TIP

Be sure to call the disconnect function when cleaning up, otherwise you may memory leak.

bindToSignal​

</>
StepUtils.bindToSignal(
signal: Signal | RBXScriptSignal,
update: () → boolean--

should return true while it needs to update

) → (
(...) → (),--

Connect function

() → ()--

Disconnect function

)

Binds an update event to a signal until the update function stops returning a truthy value.

onceAtRenderPriority​

</>
StepUtils.onceAtRenderPriority(
priority: number,
func: function--

Function to call

) → function--

Call this function to cancel call

Calls the function once at the given priority level, unless the cancel callback is invoked.

onceAtStepped​

deprecated in 3.5.2
</>
This was deprecated in 3.5.2
This item is deprecated. Do not use it for new work.
StepUtils.onceAtStepped(
func: function--

Function to call

) → function--

Call this function to cancel call

Invokes the function once at stepped, unless the cancel callback is called.

-- Sometimes you need to defer the execution of code to make physics happy
maid:GiveTask(StepUtils.onceAtStepped(function()
	part.CFrame = CFrame.new(0, 0, )
end))
TIP

use RunService.Stepped:Once() instead

onceAtRenderStepped​

deprecated in 3.5.2
</>
This was deprecated in 3.5.2
This item is deprecated. Do not use it for new work.
StepUtils.onceAtRenderStepped(
func: function--

Function to call

) → function--

Call this function to cancel call

Invokes the function once at renderstepped, unless the cancel callback is called.

TIP

use RunService.RenderStepped:Once() instead

onceAtEvent​

deprecated in 3.5.2
</>
This was deprecated in 3.5.2
This item is deprecated. Do not use it for new work.
StepUtils.onceAtEvent(
func: function--

Function to call

) → function--

Call this function to cancel call

Invokes the function once at the given event, unless the cancel callback is called.

Show raw api
{
    "functions": [
        {
            "name": "getAnimationStepSignal",
            "desc": "Returns the signal animation should step on: [RunService.RenderStepped] on the client,\n[RunService.Stepped] (the physics pre-step) on a running server so that writes land before\nthe physics step -- springs that drive CFrames stay in lockstep with constraints, characters,\nand replication. Heartbeat is only the fallback for a non-running DataModel (headless test\nruns, edit mode), where Stepped never fires.\n\nUse this instead of hand-rolling the realm branch at call sites.\n\n:::caution\nThe argument shape is realm-dependent: RenderStepped fires `(deltaTime)` but Stepped fires\n`(time, deltaTime)`. Shared code connecting directly to this signal must not assume the\nfirst argument is deltaTime.\n:::",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "RBXScriptSignal"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 29,
                "path": "src/steputils/src/Shared/StepUtils.lua"
            }
        },
        {
            "name": "getSteppedSignal",
            "desc": "Returns the signal per-frame bookkeeping should run on: [RunService.Stepped] (the physics\npre-step) on a running DataModel, falling back to [RunService.Heartbeat] on a non-running one\n(headless test runs, edit mode) where Stepped never fires.\n\nUnlike [StepUtils.getAnimationStepSignal] this does not branch to RenderStepped on the client,\nso both realms step at the same point in the frame. Prefer it for work that is not driving\nvisuals -- rescoring, polling, cache invalidation -- and that would otherwise silently stop\nrunning outside a live game.\n\n:::caution\nStepped fires `(time, deltaTime)` but Heartbeat fires `(deltaTime)`. Do not assume the first\nargument is deltaTime when connecting directly to this signal.\n:::",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "RBXScriptSignal"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 56,
                "path": "src/steputils/src/Shared/StepUtils.lua"
            }
        },
        {
            "name": "bindToRenderStep",
            "desc": "Binds the given update function to [StepUtils.getAnimationStepSignal].\n\n```lua\nlocal spring = Spring.new(0)\nlocal maid = Maid.new()\n\nlocal startAnimation, maid._stopAnimation = StepUtils.bindToRenderStep(function()\n\tlocal animating, position = SpringUtils.animating(spring)\n\n\tprint(position)\n\n\treturn animating\nend)\n\nspring.t = 1\nstartAnimation()\n```\n\n:::tip\nBe sure to call the disconnect function when cleaning up, otherwise you may memory leak.\n:::",
            "params": [
                {
                    "name": "update",
                    "desc": "should return true while it needs to update",
                    "lua_type": "() -> boolean"
                }
            ],
            "returns": [
                {
                    "desc": "Connect function",
                    "lua_type": "(...) -> ()"
                },
                {
                    "desc": "Disconnect function",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 91,
                "path": "src/steputils/src/Shared/StepUtils.lua"
            }
        },
        {
            "name": "deferWait",
            "desc": "Yields until the frame deferral is done",
            "params": [],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 98,
                "path": "src/steputils/src/Shared/StepUtils.lua"
            }
        },
        {
            "name": "bindToStepped",
            "desc": "Binds the given update function to [RunService.Stepped]. See [StepUtils.bindToRenderStep] for details.\n\n\n:::tip\nBe sure to call the disconnect function when cleaning up, otherwise you may memory leak.\n:::",
            "params": [
                {
                    "name": "update",
                    "desc": "should return true while it needs to update",
                    "lua_type": "() -> boolean"
                }
            ],
            "returns": [
                {
                    "desc": "Connect function",
                    "lua_type": "(...) -> ()"
                },
                {
                    "desc": "Disconnect function",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 116,
                "path": "src/steputils/src/Shared/StepUtils.lua"
            }
        },
        {
            "name": "bindToSignal",
            "desc": "Binds an update event to a signal until the update function stops returning a truthy\nvalue.",
            "params": [
                {
                    "name": "signal",
                    "desc": "",
                    "lua_type": "Signal | RBXScriptSignal"
                },
                {
                    "name": "update",
                    "desc": "should return true while it needs to update",
                    "lua_type": "() -> boolean"
                }
            ],
            "returns": [
                {
                    "desc": "Connect function",
                    "lua_type": "(...) -> ()"
                },
                {
                    "desc": "Disconnect function",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 129,
                "path": "src/steputils/src/Shared/StepUtils.lua"
            }
        },
        {
            "name": "onceAtRenderPriority",
            "desc": "Calls the function once at the given priority level, unless the cancel callback is\ninvoked.",
            "params": [
                {
                    "name": "priority",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "func",
                    "desc": "Function to call",
                    "lua_type": "function"
                }
            ],
            "returns": [
                {
                    "desc": "Call this function to cancel call",
                    "lua_type": "function"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 183,
                "path": "src/steputils/src/Shared/StepUtils.lua"
            }
        },
        {
            "name": "onceAtStepped",
            "desc": "Invokes the function once at stepped, unless the cancel callback is called.\n\n```lua\n-- Sometimes you need to defer the execution of code to make physics happy\nmaid:GiveTask(StepUtils.onceAtStepped(function()\n\tpart.CFrame = CFrame.new(0, 0, )\nend))\n```\n\n:::tip\nuse `RunService.Stepped:Once()` instead\n:::",
            "params": [
                {
                    "name": "func",
                    "desc": "Function to call",
                    "lua_type": "function"
                }
            ],
            "returns": [
                {
                    "desc": "Call this function to cancel call",
                    "lua_type": "function"
                }
            ],
            "function_type": "static",
            "deprecated": {
                "version": "3.5.2",
                "desc": null
            },
            "source": {
                "line": 219,
                "path": "src/steputils/src/Shared/StepUtils.lua"
            }
        },
        {
            "name": "onceAtRenderStepped",
            "desc": "Invokes the function once at renderstepped, unless the cancel callback is called.\n\n:::tip\nuse `RunService.RenderStepped:Once()` instead\n:::",
            "params": [
                {
                    "name": "func",
                    "desc": "Function to call",
                    "lua_type": "function"
                }
            ],
            "returns": [
                {
                    "desc": "Call this function to cancel call",
                    "lua_type": "function"
                }
            ],
            "function_type": "static",
            "deprecated": {
                "version": "3.5.2",
                "desc": null
            },
            "source": {
                "line": 237,
                "path": "src/steputils/src/Shared/StepUtils.lua"
            }
        },
        {
            "name": "onceAtEvent",
            "desc": "Invokes the function once at the given event, unless the cancel callback is called.",
            "params": [
                {
                    "name": "event",
                    "desc": "",
                    "lua_type": "Signal | RBXScriptSignal"
                },
                {
                    "name": "func",
                    "desc": "Function to call",
                    "lua_type": "function"
                }
            ],
            "returns": [
                {
                    "desc": "Call this function to cancel call",
                    "lua_type": "function"
                }
            ],
            "function_type": "static",
            "deprecated": {
                "version": "3.5.2",
                "desc": null
            },
            "source": {
                "line": 252,
                "path": "src/steputils/src/Shared/StepUtils.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "StepUtils",
    "desc": "Utility functions primarily used to bind animations into update loops of the Roblox engine.",
    "source": {
        "line": 6,
        "path": "src/steputils/src/Shared/StepUtils.lua"
    }
}