Skip to main content
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

Alias: Trace.AllowMovement(player, options)

​
Parameters

​
Player
required
The Player instance whose character should receive the movement exception. Must be a valid, connected player on the server.
​
table
required
Configuration for the exception. All fields are optional within the table, but the table itself must be provided.
​
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).
​
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.
​
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.
​
{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

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