Trace documentationRoblox moderation & administration

WithMovementException - Scoped Movement Exceptions

Run a callback inside a movement exception that is always cleaned up. The simplest way to authorize a one-shot teleport or scripted movement.

WithMovementException is the safest and most concise way to authorize a movement that happens entirely within a single block of code. You provide the player, the exception options, and a callback function. Trace creates the exception, runs your callback, and then always removes the exception when the callback finishes - even if the callback throws an error. This eliminates the category of bugs where a BeginMovementException call is not paired with a corresponding EndMovementException.

Signature

Trace.WithMovementException(player, options, callback) -> ...callback results

Parameters

playerPlayerrequired

The Player instance that should receive the movement exception for the duration of the callback.

optionstablerequired

Configuration for the exception. Accepts the same fields as BeginMovementException: Id, Duration, Reason, and Checks. Omit Checks to exempt the player from all five anticheat checks during the callback.

callbackfunctionrequired

The function to execute inside the exception window. Any values returned by this function are passed through as the return values of WithMovementException.

Returns

any

The return values of callback, forwarded directly to the caller. If the callback returns nothing, WithMovementException returns nothing.

Examples

Portal teleport

Teleport a player's character to a destination CFrame and exempt only the relevant checks for a short window:

Trace.WithMovementException(player, {
    Duration = 2,
    Reason = "Portal transfer",
    Checks = {"Teleport", "Noclip"},
}, function()
    player.Character:PivotTo(destination.CFrame)
end)

Capturing return values

The return values of your callback flow straight back to the caller, so you can use WithMovementException inline without any extra state:

local success, result = Trace.WithMovementException(player, {
    Reason = "Spawn placement",
}, function()
    player.Character:PivotTo(spawnCFrame)
    return true, "spawned"
end)