> ## Documentation Index
> Fetch the complete documentation index at: https://pure.saauf.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

<Tip>
  Prefer `WithMovementException` over manually pairing `BeginMovementException` and
  `EndMovementException` whenever your movement logic fits inside a single callback. It guarantees
  cleanup and produces shorter, easier-to-review code.
</Tip>

## Signature

```lua theme={null}
Trace.WithMovementException(player, options, callback) -> ...callback results
```

## Parameters

<ParamField path="player" type="Player" required>
  The `Player` instance that should receive the movement exception for the duration of the callback.
</ParamField>

<ParamField path="options" type="table" required>
  Configuration for the exception. Accepts the same fields as
  [`BeginMovementException`](/api/begin-movement-exception): `Id`, `Duration`, `Reason`, and
  `Checks`. Omit `Checks` to exempt the player from all five anticheat checks during the callback.
</ParamField>

<ParamField path="callback" type="function" required>
  The function to execute inside the exception window. Any values returned by this function are
  passed through as the return values of `WithMovementException`.
</ParamField>

## Returns

<ResponseField name="...results" type="any">
  The return values of `callback`, forwarded directly to the caller. If the callback returns
  nothing, `WithMovementException` returns nothing.
</ResponseField>

## Examples

### Portal teleport

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

```lua theme={null}
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:

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