ModerationSystem

Getting it

local ModerationSystem = Engine:GetSystem("ModerationSystem")

Overview

ModerationSystem is a complete moderation toolkit:

• Sanctions: warnings, mutes, kicks, bans, silent violations and your own kinds, with durations, reasons and private notes. Every sanction is saved in the player's record, applies in every server, and comes back when the player rejoins.
• Roles and permissions with ranks, so a moderator can never act on someone ranked above them.
• Escalation ladders that turn repeated offences into stronger sanctions automatically.
• Reports from players, with chat logs attached and a cross-server queue of open reports.
• Chat moderation through TextChatService: mutes, filters, spam and caps checks, slow mode and chat locks.
• Roblox violations: violations Roblox reports in your experience are recorded and count toward your escalation ladders.
• Commands such as /ban, /mute and /warn, usable from the chat, from code and from the client.
• An audit log of every action, kept per day in a DataStore and optionally posted to Discord.
• Server access: lock a server, run the experience in allowlist mode, or keep out brand new accounts.

It works out of the box. The experience owner (or, for group games, members at DeveloperMinGroupRank or above in PlayerService) automatically gets the Owner role, and the built-in commands are registered in the chat.

local ModerationSystem = Engine:GetSystem("ModerationSystem")

-- Give your staff roles
ModerationSystem:DefineRole("Staff", { Rank = 60, Inherits = { "Moderator" }, GroupRoles = { [1234567] = { "Moderator" } } })

-- Ban from code, for example from an anti-cheat check
ModerationSystem:Ban(player, { Reason = "Exploiting", PrivateReason = "Speed 250 for 4s", Duration = 7 * 86400 })

-- Turn repeated offences into stronger sanctions
ModerationSystem:DefineLadder("Default", {
	Steps = {
		{ Points = 3, Kind = "Mute", Duration = 600, Reason = "Repeated rule breaking" },
		{ Points = 6, Kind = "Kick", Reason = "Repeated rule breaking" },
		{ Points = 10, Kind = "Ban", Duration = 86400, Reason = "Repeated rule breaking" },
	},
})

local ModerationSystem = Engine:GetSystem("ModerationSystem")

reportButton.Activated:Connect(function()
	ModerationSystem:ReportAsync(selectedPlayer, reasonBox.Text, { Category = "Harassment" })
		:andThen(function()
			showToast("Thanks, a moderator will look at it.")
		end)
		:catch(showToast)
end)

-- Show staff tools only to staff
adminPanel.Visible = ModerationSystem:Can("Commands")
ModerationSystem.StateChanged:Connect(function()
	adminPanel.Visible = ModerationSystem:Can("Commands")
end)

Who acts: By and permissions

Most methods take an options table with By: the Player or UserId performing the action. Leave it out for actions by your own code (the system, UserId 0), which are always allowed.

When By is a player and EnforcePermissions is on, the call checks that:

1. The actor has the permission for the action (for example Ban).
2. The actor is not targeting themselves.
3. With RequireHigherRank, the target's rank is lower than the actor's.
4. A target with the Immune permission can only be targeted by someone ranked above them.

If a check fails, the synchronous method returns nil (or false) plus a reason: "PermissionDenied", "CannotTargetSelf", "TargetOutranks", "TargetImmune" or "RoleOutranks". The Async version rejects with that reason. Denied fires either way. Pass Force = true to skip the checks.

-- A moderator's ban button in your own admin panel
local sanction, denied = ModerationSystem:Ban(target, { By = moderator, Reason = reason, Duration = duration })
if not sanction then
	warn("Not allowed:", denied)
end

Sanctions

Built-in kinds

Several warnings and violations can exist at once. For other kinds, a new sanction replaces the previous active one of the same kind.

Applying

Each returns (Sanction?, reason?) right away and has an Async version (:BanAsync, :ApplyAsync, ...) that resolves with the sanction once the record is saved. target is a Player or a UserId, so players who are offline or in another server can be sanctioned too. Passing a string instead of options is a shortcut for { Reason = text }.

Lifting

They return ({ Sanction }, reason?) with the lifted sanctions, and have Async versions. Options: By, Reason, Force, Silent. Unbanning also removes the Roblox ban. Sanctions with a duration expire on their own; Expired fires when they do.

Checking

The methods without Async use the records loaded in this server (players in the server). Use the Async versions for anyone else.

Custom kinds

ModerationSystem:DefineSanction("Jail", {
	DefaultDuration = 300,
	Points = 2,
	Apply = function(player, sanction)
		if player then sendToJail(player) end
	end,
	Lift = function(player, sanction)
		if player then releaseFromJail(player) end
	end,
})

ModerationSystem:Apply("Jail", player, { By = moderator, Reason = "Spawn killing" })

:GetSanctionKind(name), :FindSanctionKind(name) and :GetSanctionKinds() look kinds up. Custom kinds need the Sanction permission.

Events

player is the Player when they are in this server.

With UseRobloxBans on, every ban calls Players:BanAsync. When banning is turned off in Game Settings, Roblox refuses that call and RobloxBanFailed fires, but the moderation record still enforces the ban: the player is kicked when they join (KickBannedOnJoin).

Records

Every player has a record in the RecordStoreName DataStore with their sanctions, notes, roles, reports and escalation state. Records of players in the server are loaded on join (LoadRecordOnJoin).

Notes

Private notes for staff.

Roles and permissions

DefineRole

ModerationSystem:DefineRole(name: string, options: RoleOptions?): Role

Roblox groups can give a member several roles, and a rank no longer says where a role sits, so GroupRoles is the reliable way to map your group's staff. GroupRanks keeps working. Both can also be set on the roles in the Roles setting.

The roles Owner, Admin, Moderator and Helper come from the Roles setting. Players can also be granted roles, temporarily or permanently, and those grants are saved in their record.

Permissions

ModerationSystem.Permissions lists them: Warn, Mute, Unmute, Kick, Ban, Unban, Lift, Sanction (custom kinds), Notes, Reports, Records, Roles, Audit, Chat (slow mode and chat locks), ChatBypass (skip chat filters, slow mode and chat locks), Server (server lock and allowlist, and joining locked servers), Commands, Immune, and "*" for everything.

Escalation ladders

Every sanction adds points (DefaultPoints: Violation 1, Warn 1, Mute 2, Kick 3, Ban 5). A ladder applies a stronger sanction when a player's points reach a step.

ModerationSystem:DefineLadder(name: string, options: LadderOptions): Ladder

Each step fires once until the player reaches the next one. Sanctions applied by a ladder add no points themselves and fire Escalated: Signal<(sanction, trigger)>. :GetLadder, :FindLadder, :GetLadders, :RemoveLadder and :ResetLadder(target, name?) manage them. Ladders can also be defined in the Ladders setting.

Reports

Filing fails with "ReportsDisabled", "InvalidTarget", "SelfReport", "InvalidReason", "ReasonTooLong", "EvidenceTooLarge", "Cooldown" or "Duplicate" (ModerationSystem.ReportErrors). Each report carries the target's recent chat messages when AttachChatLog is on.

When ReportThreshold different players report someone within ReportWindow, ReportThresholdReached: Signal<(userId, count, player?)> fires, and ReportThresholdKind (if set) is applied automatically. ReportFiled: Signal<(report, player?)> and ReportReviewed: Signal<report> fire for every report.

Chat moderation

With ChatModeration on, the system hooks TextChatService. Each message passes these checks in order:

1. Muted: muted players cannot chat, whatever their permissions.
2. ChatLocked and SlowMode.
3. The built-in filter: TooLong (ChatMaxLength), Spam (ChatMaxMessagesPerWindow), Repeat (ChatMaxRepeats), Link (ChatBlockLinks), Blocklist (ChatBlocklist) and Caps (ChatMaxCapsRatio).
4. Your own filters.

Players with ChatBypass skip steps 2 to 4.

A blocked message is not delivered, the player is told why, and (for the reasons in ChatViolationReasons) a Violation with ChatViolationPoints is recorded. Roblox's own text filtering still applies on top.

ModerationSystem:AddChatFilter("NoTrading", function(ctx)
	if string.find(string.lower(ctx.Text), "trade me") then
		return true, "Use the trading hub."
	end
	return false
end)

Notices

:Notify(target, text, kind?) shows a message to a player (in any server); :NotifyAll(text, kind?) to everyone here. With NoticesInChat, the client shows notices as system messages in the chat.

Roblox violations

Roblox reports the violations its own moderation finds in your experience. When ModerationSystem loads, it binds one violation processor for them with ModerationService:BindViolationProcessor, unless RobloxViolations is off. Every report:

1. fires RobloxViolation: Signal<(violation, player?)>;
2. is written to the audit log as RobloxViolation;
3. records a Violation sanction worth RobloxViolationPoints on the reported user, so your escalation ladders act on Roblox's reports the same way they act on chat violations.

The sanction's reason is Roblox: followed by the report's category (or its first label), or DefaultViolationReason when the report names neither. With AcknowledgeRobloxViolations on, every handled report is acknowledged, so Roblox does not deliver it again.

violation carries Id, UserId, Category, Labels (a list of names), At and the untouched Report. player is the Player when the user is in this server.

Choosing the consequence

Set the callback OnRobloxViolation to decide per report:

ModerationSystem.OnRobloxViolation = function(violation, player)
	if player then
		return { Kind = "Mute", Duration = 600, Reason = "Roblox reported a violation" }
	end
	return nil -- not in this server: the default Violation sanction
end

With RobloxViolationKind set to an empty string, the reports your callback leaves to the default are only logged, without a sanction.

If your game binds its own violation processor too, set RobloxViolationPriority, or AcknowledgeRobloxViolations = false, so both see the report. ModerationSystem.IsViolationProcessorBound tells whether the processor is bound.

Testing in Studio

ModerationSystem:MockViolationAsync(report: { [string]: any }): Promise

Sends a test report through ModerationService:MockViolationCallbackAsync, as if Roblox reported it, so you can try your violation handling in Studio.

Commands

Commands run from the chat (with CommandPrefix, default /), from code with :ExecuteAsync, and from the client. Players only see and can run the commands their permissions allow.

Built-in commands

<user> accepts a player in the server, a username (also offline players), @username or a UserId. Durations are written like 30m, 2h, 7d, 1w, 3mo, 1y, combinations such as 1d12h, or perm. me targets yourself. Turn the built-ins off with BuiltInCommands = false.

RegisterCommand

ModerationSystem:RegisterCommand("heal", {
	Permission = "Commands",
	Description = "Heal a player.",
	Args = {
		{ Name = "target", Type = "Target" },
		{ Name = "amount", Type = "Number", Optional = true, Default = 100 },
	},
	Run = function(ctx, args)
		args.target.Character.Humanoid.Health += args.amount
		return string.format("Healed %s.", args.target.Name)
	end,
})

Failures use ModerationSystem.CommandErrors: UnknownCommand, PermissionDenied, MissingArgument, InvalidArgument, PlayerNotFound, UserNotFound, AmbiguousPlayer, CommandFailed.

Audit log

Every action (sanctions, lifts, roles, notes, reports, commands, locks) is logged with who did it, to whom, why and when.

Entries also go to StatisticsService as Moderation.<Action> custom events (LogToStatistics), and to a Discord webhook when WebhookName names a StatisticsService webhook.

Server access

With MinAccountAgeDays, accounts younger than that (and without a role) are kicked on join.

Properties

Cross-server

With CrossServerSync, sanctions, lifts, kicks, role changes, notices and reports are sent to every other server through MessagingService. Banning someone who is playing in another server kicks them there; muting them applies right away.

Client

Use it to show staff panels, a mute timer or a report button. Every request is checked again on the server.

Configuration

Types

export type Target = Player | number
export type Actor = Player | number | nil
export type Sanction
export type SanctionKind
export type SanctionKindOptions
export type SanctionOptions
export type LiftOptions
export type Record
export type Note
export type RoleGrant
export type Role
export type RoleOptions
export type GrantOptions
export type Ladder
export type LadderOptions
export type LadderStep = { Points: number, Kind: string, Duration: number?, Reason: string? }
export type EscalationTrigger
export type Report
export type ReportStatus = "Open" | "Reviewing" | "Resolved" | "Dismissed"
export type ReportFilter
export type AuditEntry
export type AuditFilter
export type ChatLogEntry
export type ChatFilterContext
export type ChatVerdict = { Blocked: boolean, Reason: string?, Filter: string? }
export type Command
export type CommandOptions
export type CommandContext
export type CommandArg
export type AccessMode = "Open" | "Allowlist"
export type RobloxViolation
export type RobloxViolationDecision
export type ClientState
export type PublicSanction
export type BanHistoryEntry