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

​
Parameters

​
Player
required
The Player instance to punish.
​
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.
​
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.

​
Returns

​
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.
​
string?
A description of what went wrong. Only present when success is false.

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

​
Immediate ban for a high-confidence rule violation

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.

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