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

# BeginMovementException - Start a Movement Exception

> Start a named movement exception for a player. Returns a token used to end the exception. Use for vehicles, cutscenes, launch pads, and scripted flight.

Use `BeginMovementException` when you need to authorize movement that persists beyond a single callback - for example, while a player is inside a vehicle, riding a conveyor, playing through a cutscene, or under scripted flight control. The function returns a **token** you hold on to and later pass to `EndMovementException` when the movement ends. For one-shot movements that fit inside a single callback, prefer [`WithMovementException`](/api/with-movement-exception) instead.

## Signature

```lua theme={null}
Trace.BeginMovementException(player, options) -> token?, error?
```

**Alias:** `Trace.AllowMovement(player, options)`

## Parameters

<ParamField path="player" type="Player" required>
  The `Player` instance whose character should receive the movement exception. Must be a valid,
  connected player on the server.
</ParamField>

<ParamField path="options" type="table" required>
  Configuration for the exception. All fields are optional within the table, but the table itself
  must be provided.

  <ParamField path="options.Id" type="string?">
    A stable, human-readable identifier for this exception. If you call `BeginMovementException`
    again with the same `Id` for the same player, Trace **refreshes** the existing exception rather
    than creating a second one. Useful for systems that may call this function multiple times (for
    example, a vehicle seat occupant check running on a loop).
  </ParamField>

  <ParamField path="options.Duration" type="number?">
    How long, in seconds, the exception should remain active. Pass `0` to create a manual exception
    with no timer - you must call `EndMovementException` yourself. The maximum allowed value is
    **300 seconds**.
  </ParamField>

  <ParamField path="options.Reason" type="string?">
    A human-readable description of why the exception exists. This string is written to Trace's
    moderation logs and is visible in the Trace dashboard, making it easier to audit which systems
    are granting exceptions.
  </ParamField>

  <ParamField path="options.Checks" type="{string}?">
    A list of anticheat check names to exempt the player from. Valid values are `"Teleport"`,
    `"Velocity"`, `"Fling"`, `"Fly"`, and `"Noclip"`. Omit this field entirely to exempt the
    player from all five checks.
  </ParamField>
</ParamField>

## Returns

<ResponseField name="token" type="string?">
  A unique token string identifying this exception. Pass it to `EndMovementException` when the
  movement ends. Returns `nil` if the call fails (see `error` below).
</ResponseField>

<ResponseField name="error" type="string?">
  A description of what went wrong. Only present when `token` is `nil`.
</ResponseField>

## Example

```lua theme={null}
-- Grant a vehicle exception for up to 60 seconds, covering only
-- Velocity and Fly detections.
local token = Trace.BeginMovementException(player, {
    Id = "vehicle-session",
    Duration = 60,
    Reason = "Player in vehicle",
    Checks = {"Velocity", "Fly"},
})

-- ... vehicle session runs ...

Trace.EndMovementException(player, token)
```

<Warning>
  Setting `Duration = 0` creates a **manual** exception with no timer - it never expires on its own. You are responsible for calling `EndMovementException` (or `ClearMovementExceptions`) when the movement ends. If you forget, the exception will persist for the rest of the player's session. Always pair a manual exception with a cleanup path - including error cases.
</Warning>

<Note>
  Trace automatically clears all active movement exceptions when a player leaves the server, so
  there is no risk of exceptions leaking across sessions. You do not need to clean up in an
  `Players.PlayerRemoving` handler.
</Note>