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

# Punish - Apply a Trace Warning or Ban to a Player

> Programmatically apply a Trace warning or ban to a player from a trusted server script. Automatically escalates to a ban after the configured warning limit.

`Trace.Punish` records a warning against a player and applies a full Trace ban when the configured warning threshold is reached. It runs through the same code path as manual moderation actions in the panel, so the resulting warning, ban, replay, and audit-log entries are indistinguishable from a human moderator's action. Use it to attach automated consequences to detections your own scripts run - for example, custom exploit heuristics, in-game rule enforcement, or scripted anti-grief actions.

## Signature

```lua theme={null}
Trace.Punish(player, reason, isManual?) -> success, error?
```

## Parameters

<ParamField path="player" type="Player" required>
  The `Player` instance to punish.
</ParamField>

<ParamField path="reason" type="string" required>
  A human-readable reason for the punishment. Recorded to Trace's audit log, shown to reviewing staff, and - filtered - included in the notification the player receives.
</ParamField>

<ParamField path="isManual" type="boolean?">
  When `true`, treats the call as a manual staff action and bans the player immediately rather than incrementing the warning count. Defaults to `false`. Use `true` sparingly and only for high-confidence cases; automated systems should almost always let Trace apply escalation via the warning threshold.
</ParamField>

## Returns

<ResponseField name="success" type="boolean">
  `true` when the punishment was recorded successfully. `false` when Trace could not process the call - for example, the player is not tracked, the license has not been accepted yet, or the detection subsystem is disabled.
</ResponseField>

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

## Behavior

* The player's stored warning count is incremented (unless `isManual` is `true`, in which case a ban is issued immediately).
* A short movement recording is captured and saved as a replay attached to the event.
* Trace applies auto-actions if the player's recent detection window matches one of your configured [auto-action rules](/configuration/protection-presets).
* If the resulting warning count meets or exceeds the `MaxWarnings` setting from `TraceConfig`, Trace issues a full Roblox ban through the Ban API and updates its own restriction records.
* A Discord webhook payload is dispatched if webhooks are configured and the corresponding event category is enabled.
* The player receives a filtered warning or ban dialog through the Trace client UI.

## Examples

### Escalating a custom exploit detection

```lua theme={null}
local Trace = _G.Trace

local function onExploitDetected(player, detail)
    local ok, err = Trace.Punish(player, "Custom detector: " .. detail)
    if not ok then
        warn("Trace.Punish failed for", player, err)
    end
end
```

### Immediate ban for a high-confidence rule violation

```lua theme={null}
local Trace = _G.Trace

Trace.Punish(player, "Exploiting protected admin remote", true)
```

<Warning>
  `isManual = true` skips warning escalation and issues a Roblox universe ban on the next server frame. Reserve it for cases where you are certain no false positive is possible - a bug in your detector can result in an incorrect ban that a moderator has to appeal.
</Warning>

## Security model

Call `Trace.Punish` only from trusted server scripts. Never expose it directly to clients through a `RemoteEvent` - an attacker with access to such an endpoint could ban any player at will. All parameter validation happens server-side, but your calling code is responsible for confirming the identified behavior actually merits a punishment.