How to use the new Ban API (with code examples)

Resources Community Tutorials
, , , ,
#1

Here is a brief summary of how to use roblox’s new ban API. This does not cover everything but it does cover how you could set up a simple system inside of your game.

The ban API is built into the existing Players service. It includes the new function BanAsync() which allows us to ban a list of players from their UserIds and specify a duration and reason for the ban. These parameters need to be included in a dictionary. The required parameters are shown below:

  • UserIds (List) - A list of the UserIds of the player(s) who you are banning.
  • ApplyToUniverse (Boolean) - If the ban will apply to all other places within the experience’s universe.
  • Duration (Number) - The amount of time in seconds that the player(s) will be banned for.
  • DisplayReason (String) - The reason shown to the player.
  • PrivateReason (String) - The reason which is only visible to developers.
  • ExcludeAltAccounts (Boolean) - If set to false, the player(s) alt accounts will also receive the same ban.

Tip: You can set the duration to -1 in order to ban the player permanently.

Here is an example of how the ban API could be used. In this example, any message sent by a player containing the words ‘bad game’ will cause them to be banned for 10 seconds:

local Players = game:GetService("Players")

local function Ban(Player : Player)
	Players:BanAsync({
		UserIds = {Player.UserId}, -- The user Ids of the players who you want to ban
		ApplyToUniverse = true, -- If the ban will apply to other places within your universe
		Duration = 10, -- How long the person will be banned for in seconds
		DisplayReason = 'Being unkind to developers', -- The reason shown to the player
		PrivateReason = 'The player was being unkind', -- A reason not shown to the player but can be seen by developers
		ExcludeAltAccounts = false, -- If the player's alt accounts should not be banned
	})
end

Players.PlayerAdded:Connect(function(Player)
	Player.Chatted:Connect(function(Message : string, Recipient : Player)
		if string.find(string.lower(Message), 'bad game') then -- Checks for the phrase 'bad game' in the message
			Ban(Player) -- Calls the function to carry out the BanAsync function.
		end
	end)
end)

However, sometimes, you may need to unban someone from your game. For this, we need to use the UnbanAsync() function of the Players service and provide the UserIds and if it should apply to all places in the universe as shown below:

Players:UnbanAsync({
	UserIds = {973402642}, -- The user Ids of who you are unbanning
	ApplyToUniverse = true, -- If the unban will apply to other places inside of your universe
})

This should allow you to create a simple system to ban players from you game. However, it is important to remember that players should only be banned for appropriate reasons when they have exploited or done something wrong inside of your experience.

Hope this is useful
:slight_smile:

16 Likes
#2

Small nit picky thing, Async function should be put inside a pcall just in case

Else good tutorial

4 Likes
#3

how will I get list of banned players?

4 Likes
#4

You would have to store that separately since the Ban API only allows you to get the history of a specified player

5 Likes
#6

How does the alt banning work? I hope it is actually good.

#7

Now we should get a script that allows you to type “/ban [player] [duration] [reason]”. I already tried to get the assistant to do it, but when I executed the code, nothing happened.

#8

I believe it’s tied to the client’s AppData under the C:\Users\User\AppData\Local (Could also be LocalLow, but I doubt) since I know there are a few .json config files which track the userids the roblox application.

1 Like
#9

you can do this if any1 is bullying in game

local badWords = {“trash”, “hacker”, “hacking”} – Add your bad words here

local function containsBadWord(message)
for _, badWord in ipairs(badWords) do
if string.find(message:lower(), badWord:lower()) then
return true
end
end
return false
end

local gameOwner = game.CreatorId

game.Players.PlayerAdded:Connect(function(player)
player.Chatted:Connect(function(msg)
– Check for bad words
if containsBadWord(msg) then
if player.UserId ~= gameOwner then
game.Players:BanAsync({
UserIds = {player.UserId},
ApplyToUniverse = true,
Duration = -1, – Permanent ban
DisplayReason = “You Bullied A Player”,
PrivateReason = “Inappropriate language”,
ExcludeAltAccounts = true,
})
end
end
end)
end)

1 Like
#10

local whitelistTable = {user id here} --Add your User ID here

game.Players.PlayerAdded:Connect(function(plr)
if table.find(whitelistTable,plr.UserId) then
plr.Chatted:Connect(function(msg)
if string.find(msg, "!ban ") then
local splitMessage = string.split(msg, " ")

			local userName = splitMessage[2]
			local banMessage = string.gsub(msg, "!ban "..userName.." ","")

			local userId = game.Players:GetUserIdFromNameAsync(userName)

			if userId then
				game.Players:BanAsync({
					UserIds = {userId},
					ApplyToUniverse = true,
					Duration = -1,
					DisplayReason = banMessage,
					PrivateReason = banMessage,
					ExcludeAltAccounts = false,
				})
			end
		elseif string.find(msg, "!unban ") then
			local splitMessage = string.split(msg, " ")
			local userName = splitMessage[2]
			local userId = game.Players:GetUserIdFromNameAsync(userName)

			if userId then
				game.Players:UnbanAsync({
					UserIds = {userId},
					ApplyToUniverse = true,
				})
			end
		end
	end)
end

end)