Trace documentationRoblox moderation & administration

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

Signature

Trace.BeginMovementException(player, options) -> token?, error?

Alias: Trace.AllowMovement(player, options)

Parameters

playerPlayerrequired

The Player instance whose character should receive the movement exception. Must be a valid, connected player on the server.

optionstablerequired

Configuration for the exception. All fields are optional within the table, but the table itself must be provided.

options.Idstring?

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

options.Durationnumber?

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.

options.Reasonstring?

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.

options.Checks{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.

Returns

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

string?

A description of what went wrong. Only present when token is nil.

Example

-- 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)