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

# Movement Exceptions: Authorize Scripted Movement in Trace

> Use the Trace movement exceptions API to prevent portals, vehicles, launch pads, and scripted flight from triggering anticheat detections.

Trace's anticheat systems monitor player movement in real time. When your game intentionally moves a player - through portals, launch pads, vehicles, cutscenes, or scripted flight - those movements can resemble the patterns Trace is designed to catch. Movement exceptions are a server-side API that let your trusted scripts temporarily authorize intentional movement so it is never flagged as cheating.

<Note>
  All movement exception calls must be made from trusted server scripts. Client scripts cannot grant exceptions to themselves or to any other player.
</Note>

## Accessing the API

Before calling any movement exception method, obtain the Trace API table from `_G.Trace`. Because Trace initializes asynchronously at runtime, assert its presence so your script fails loudly if it runs too early.

```lua theme={null}
local Trace = _G.Trace
assert(Trace, "Trace must be initialized before movement integrations")
```

***

## Short Scripted Movement - `WithMovementException`

Use `WithMovementException` for one-shot movements wrapped in a single callback - portal transfers, spawn placement, and similar discrete teleports are ideal candidates.

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

Trace grants the exception, runs your callback, then cleans it up - even if the callback throws an error. You never need to manually close the window.

***

## Teleport Helper - `AllowTeleport`

For simple character teleports, `AllowTeleport` is a convenience wrapper that opens a short exception window and returns immediately so you can move the character on the next line.

```lua theme={null}
Trace.AllowTeleport(player, 2, "Round spawn teleport")
player.Character:PivotTo(roundSpawn.CFrame)
```

The three arguments are: the `Player` instance, a duration in seconds, and a human-readable reason logged with the exception.

***

## Longer Movement - `BeginMovementException` / `EndMovementException`

For sustained movement events - vehicles, launch pads, scripted flight, or long cutscenes - open a named exception with `BeginMovementException` and close it explicitly with `EndMovementException`.

```lua theme={null}
local token = Trace.BeginMovementException(player, {
    Id = "launch-pad",
    Duration = 8,
    Reason = "Launch pad impulse",
    Checks = {"Velocity", "Fling", "Fly"},
})

-- Your authorized movement code runs here

Trace.EndMovementException(player, token)
```

Keep the following rules in mind:

* **`Duration = 0`** creates a manual exception with no timer. The exception stays open until you call `EndMovementException`. Always pair manual exceptions with a corresponding close call.
* **Timed exceptions** are capped at **300 seconds**. Use a manual exception for anything that may run longer, and close it when the sequence ends.
* **`Id` reuse** refreshes the named exception rather than creating a duplicate. If your launch pad fires again before the first exception expires, passing the same `Id` resets the timer cleanly.

***

## Movement Zones

Movement zones let you associate an exception with a physical region in your Workspace. Any player whose `HumanoidRootPart` enters the zone automatically receives the exception; the exception is removed when they leave.

Register a `BasePart` or `Model` as a zone:

```lua theme={null}
local zoneId = Trace.RegisterMovementZone(workspace.LaunchArea, {
    Id = "launch-area",
    Reason = "Authorized launch pad",
    Checks = {"Velocity", "Fling", "Fly"},
    GraceAfterExit = 2,
    Padding = 3,
})
```

| Option           | Description                                                                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `Id`             | Optional stable identifier. Reuse refreshes the zone instead of creating a duplicate.                                                       |
| `Reason`         | Human-readable reason recorded with each exception grant.                                                                                   |
| `Checks`         | Anticheat checks to suppress while inside the zone.                                                                                         |
| `GraceAfterExit` | Seconds the exception stays active after a player leaves the zone. Useful for launch pads where momentum continues beyond the pad boundary. |
| `Padding`        | Expands every side of the zone's bounding box by this many studs.                                                                           |

Rotated parts are handled automatically using oriented bounding boxes - you do not need to align your zone parts to world axes.

### Managing Registered Zones

```lua theme={null}
-- Temporarily disable a zone without removing it
Trace.SetMovementZoneEnabled(zoneId, false)

-- Re-enable it
Trace.SetMovementZoneEnabled(zoneId, true)

-- Permanently remove a zone
Trace.UnregisterMovementZone(zoneId)
```

If the `BasePart` or `Model` you registered is destroyed in the data model, Trace unregisters the zone automatically.

***

## Valid Check Names

The `Checks` array accepts any combination of the following five names:

| Check Name | What it suppresses              |
| ---------- | ------------------------------- |
| `Teleport` | Sudden large position changes   |
| `Velocity` | Abnormal movement speed         |
| `Fling`    | Rapid uncontrolled acceleration |
| `Fly`      | Sustained airborne movement     |
| `Noclip`   | Passing through geometry        |

Omitting the `Checks` field entirely enables all five checks, which is equivalent to passing `{"Teleport", "Velocity", "Fling", "Fly", "Noclip"}`.

<Tip>
  For full parameter descriptions, default values, and return types, open the **API Reference** tab in the Trace documentation sidebar.
</Tip>