[v1.7] EasyWhitelist | Game whitelisting & blacklisting made easy!

devlazerr · September 5, 2023, 2:09am

Welcome to the EasyWhitelist community resource post! In this post, I will tell you more about the resource and what you can expect to get from it. I will edit this post where necessary with any updates made to the system as well as update logs where needed!

Due to this being my first actual community resource post, I still am not entirely sure how this entire thing works so apologies if this is not the kind of quality you are used to, however, let’s get straight into what this system entails!

With EasyWhitelist, you can enjoy a simple, fast, efficient, and lightweight whitelisting system with all types of way to filter users ranging from usernames & user ids, group ranks, and even if they own a certain piece of clothing or a certain gamepass! Whitelisting has never been easier!

Whether you are a hotel looking to reserve your session centers to certain ranks within your group, or you have a game that needs early access whitelisting via gamepass, EasyWhitelist has all the features needed to set this up!

Currently EasyWhitelist supports the below ways of whitelisting, you can use as many as you want at any time and it will work the same! I expect to add more in future updates to make the experience even more customizable!

Usernames (e.g. “devlazerr”)
UserIds (e.g. 932995055)
GroupIds & Ranks
Assets (e.g. shirts, pants, accessories, etc!)
Gamepasses
Friends
Badges

For more information about how to use the above filtering methods, there is more information within the main module! Here are some things you can expect with this system:

Lightweight & optimized!

EasyWhitelist was created with optimization in mind! Enjoy a lightweight whitelisting system with no strain on the server, ever! It is also completely unexploitable making this a secure whitelist system that won’t fail to kick those who are not whitelisted!

Not obfuscated, ever!

EasyWhitelist will never be obfuscated, ever! You can be worry free knowing that nothing suspicious is going on in the background, and you can review all of the code yourself and be able to edit anything you want to!

Easy assistance

I’ll review this topic constantly to ensure any questions/concerns you may have will be answered fast so you can get back to what you do best without having to worry about whitelisting!

Why EasyWhitelist?

You may be asking yourself why use EasyWhitelist for your whitelisting needs and not other methods such as studio whitelisting or making your own script? The best way to answer this besides all the features I mentioned above is the functionality and adaptability! I plan to do many updates in the future on this resource and plan to increase the customizability of it to suit specific needs as they appear.

To end this post, if you have any feedback, concerns, or bug reports please either private message me or reply to this post and I will look into addressing it as soon as possible! Thank you for your interest in using EasyWhitelist!

Documentation/How to Use

Open Documentation

Step 1: Installation

Firstly, you must get the EasyWhitelist module from this link. From there, you have to open Roblox Studio and go to your Toolbox window and head over to the “Inventory” tab.

From there, you want to ensure you’re on the “My Models” section and then search for “EasyWhitelist” and press the model that shows up. From there, a warning will show up telling you that EasyWhitelist contains scripts. Press OK then drag the EasyWhitelist script (which should now be in Workspace) to ServerScriptService. From there, use the arrow to the left of the EasyWhitelist main script instance to open it’s children.

From there, you can open the WhitelistModule to start Step 2.

Step 2: Configuration

When you open the WhitelistModule, you’re going to be greeted with a few values. Let’s start with our flags, which are:

WhitelistActive: Whether or not the Whitelist is active
BlacklistActive: Whether or not the Blacklist is active
CanBlacklistEffectWhitelisted: Whether Whitelisted users will be affected by the Blacklist
LogPlayers: Logs in the server console when a player is kicked
ExcludeOwner: Whether the owner is absolutely excluded regardless of any configuration. For profile games, the owner will be considered the profile; for group games, the group owner.
StudioExcluded: Whether EasyWhitelist affects Studio instances (playtesting)
HideGame: Whether EasyWhitelist will hide your game parts (excluding CoreGUI) via a black screen until the whitelist/blacklist status has been determined
ExploreTime: The time in seconds players can “explore” your game before EasyWhitelist takes effect on them.
UseWebhook: Whether or not the webhook will get requests sent to it. (more info in the Webhooks tab)

All these flags can be set to either true (for on) or false for off. Feel free to configure them to your specific needs, however the default values are:

EasyWhitelist.WhitelistActive = true
EasyWhitelist.BlacklistActive = true
EasyWhitelist.CanBlacklistEffectWhitelisted = true
EasyWhitelist.LogPlayers = true
EasyWhitelist.ExcludeOwner = true
EasyWhitelist.StudioExcluded = true
EasyWhitelist.HideGame = true
EasyWhitelist.ExploreTime = 0
EasyWhitelist.UseWebhook = false

Great, now let’s move onto the kick messages, the names are self-explanatory, the NotWhitelistedKickMessage message is what’s shown if the player is not whitelisted, and the BlacklistedKickMessage is what’s shown if the player is blacklisted. The default values are below:

EasyWhitelist.NotWhitelistedKickMessage = "EasyWhitelist | You are not whitelisted!"
EasyWhitelist.BlacklistedKickMessage = "EasyWhitelist | You have been blacklisted!"

Although it would be very helpful for more people to know about this resource if you kept EasyWhitelist inside of the kick messages, it is not required!

And finally, we have to configure all the whitelist and blacklist specific data. Let’s look into what each one does. To explain this best, let me show you some example data:

-- Configuration for Whitelist and Blacklist specific data

Users = {"Player1", "Player2", "Player3"}
IDs = {123456, 234567, 345678, 456789}
Groups = {
	[1234567] = {
		{Rank = 100, Behavior = ">="}, -- Greater than or equal to Rank 100
		{Rank = 31, Behavior = "<="},  -- Less than or equal to Rank 31
		{Rank = 132, Behavior = ">"}, -- Greater than Rank 132
		{Rank = 50, Behavior = "<"},  -- Less than Rank 50
		{Rank = 80, Behavior = "=="}, -- Equal to Rank 80
		{Role = "Suspended"},         -- Check for a specific role named "Suspended"
	},
}

Clothing = {987654, 876543, 765432, 654321} -- Clothing items IDs
Bundles = {111222, 333444, 555666, 777888} -- Bundle IDs
Gamepasses = {999000, 888999, 777888} -- Gamepass IDs
Friends = {111111, 222222} -- User IDs considered as friends
Badges = {91234912, 12391231} -- Badge IDs

Let’s briefly break that all down, so, first our Users table is some Blacklisted/Whitelisted usernames, then our IDs table is some Blacklisted/Whitelisted UserIds. You can have as many or as little names/IDs as you want, as long as they are separated by a comma.

Then we have a group data table. In this case we made a data package for the group with the ID 1234567 then provided some conditions for that group to determine if the user should be Blacklisted or Whitelisted. Here’s how it works:

Groups = {
	[groupId] = {
		GREATER OR EQUAL TO EXAMPLE:
		{Rank = RankId, Behavior = ">="}
		
		EQUAL TO EXAMPLE:
		{Rank = RankId, Behavior = "=="}
		
		LESS THAN OR EQUAL TO EXAMPLE:
		{Rank = RankId, Behavior = "<="}
		
		GREATER THAN EXAMPLE:
		{Rank = RankId, Behavior = ">"}
		
		LESS THAN EXAMPLE:
		{Rank = RankId, Behavior = "<"}
		
		[NEW] RankName Example:
		{Role = "RankName"}
	},
}

You can have as many ranks & role conditions as you want and as many groups as you want. Just make sure they are all once again separated via comma.

Now when it comes to clothing, bundles, and gamepasses, these are just the asset IDs for the assets of those types. You can add as many asset IDs as you want, just ensure they are separated via comma.

Then we have the Friends table. In here you can put as many UserIDs as you want (still separated) and it will check if the user who is joining is friends with anyone in that table.

And, the newest detection method, we have the “Badges” table, where you can put as many BadgeIDs as you want (separated by comma) and it will check if the user has a badge from that table.

Now, you may notice that these values are not in the table explicitly, and that is because there are 2 types of each of these data entries. There’s one for Blacklisted & one for Whitelisted. So, for example, to blacklist anyone who is friends with any user in the table, you’d use the BlacklistedFriends table. However, to do the opposite, you’d use the WhitelistedFriends table. This logic applies for every single data type.

NEW: Custom Kick Messages

It is now possible to provide custom kick messages per user. You must create a table with the UserID as the key and another table as its value with a “Blacklisted” and “NotWhitelisted” key, with the values being strings. Confused? I will show an example of what I mean:

EasyWhitelist.CustomizedKickMessages = {
	[1] = {
		NotWhitelisted = "sorry roblox you can't join",
		Blacklisted = "no admins allowed"
	}
}

This will change the default messages for the Roblox account to “sorry roblox you can’t join” and “no admins allowed” respectively. If you want to add another user, it’s a simple as adding an additional entry, separated by comma:

EasyWhitelist.CustomizedKickMessages = {
	[1] = {
		NotWhitelisted = "sorry roblox you can't join",
		Blacklisted = "no admins allowed"
	},
	[3] = {
		NotWhitelisted = "odd numbers dont get whitelisted",
		Blacklisted = "cya"
	}
}

Now, the account with the ID 3 will also have unique messages. If a user does not have a Customized Message, then they will be kicked with the default message depending on the action taken. Furthermore, EasyWhitelist will warn you if it tries to use a customized kick message, yet the table has not been setup correctly.

Step 3: Webhooks

If you want to setup a Webhook for logging every time a player is kicked for either being blacklisted or not whitelisted, that is now possible! First you want to get your webhook URL, if you’re planning to use a Discord Webhook, keep in mind that it is blocked on roblox. To bypass this, you can use a proxy such as this one!

Once you have your Webhook URL, we’re going to open the WhitelistModule again and paste it inside of the Webhook option. It will be “Your_Webhook_Link” by default, but you can paste your webhook link inside like this:

// Paste the full link here, I did not complete it as this is just an example. If you are using a proxy, paste the proxy link there.
EasyWhitelist.Webhook = "https://discord.com/api/webhooks/1153..."

Now, we’re going to enable the UseWebhook flag, like so:

EasyWhitelist.UseWebhook = true

And… you’re done! Now whenever someone is kicked from your game, it should log there assuming everything is setup correctly. Please ensure HTTP requests are on, like so:

Step 4: What now?

Nothing! You are done setting up EasyWhitelist and it should now work. Although not recommended, you can make any edits to the functions inside of the ModuleScript to work better for you, or you can edit the looper inside of the main EasyWhitelist script. You can also edit the Verifying ScreenGUI inside of the main EasyWhitelist script to better fit your game’s UI theme. Thank you for using EasyWhitelist!

Update Log

Version 1.1

Added Blacklist
Alongside whitelisting users, you can now blacklist them as well! Have a group that has been trolling your game recently? No worries, you can now blacklist members in that group alongside the other features like clothing/accessories, gamepasses, usernames, and UserIDs!

Version 1.2

Bundles detection added
You can now detect bundles (such as the Ninja walk pack, or the Junk Bot character pack) in both blacklisted and whitelisted configurations! Simply put in the ID to the bundle desired and it will work like a charm!
Added “CanBlacklistEffectWhitelisted” flag
If enabled even if the player is whitelisted, they can still be blacklisted if they meet the requirements, but if disabled if the player is whitelisted, they will no longer be affected by the blacklist!
Some comments updated for clarity
Updated some comments in the main ModuleScript to promote a better understanding of how the module works! Table instructions are now setup so that it is not limited to whitelisted and now shows how to do both the blacklist & whitelist!

Version 1.3

Added some guard clauses (thank you to Katrist for the suggestion)
Added “ExcludeOwner” flag
It is now possible to set this flag to true (automatically the default) in order to exclude the game owner from any sort of action taken by EasyWhitelist! The game owner is either the person who published the game to their profile (if user game) or the owner of the group the game is published to (group games)!
Added “StudioExcluded” flag
If this flag is set to true (automatically the default) any studio instances (e.g. the playtesting server that Roblox Studio runs while playing the game in studio) will not have any action taken by EasyWhitelist in them!
General bug fixes
I’ve fixed a few bugs such as the “not whitelisted” message being shown despite the player being blacklisted due to the script not terminating after the player has been kicked! It should now properly display the correct kick message when taking action!

Version 1.4

Added “HideGame” flag
It is now possible to enable the HideGame flag to hide your game’s workspace (not CoreGUI, so they can still see stuff like chat as I have not setup a client-side for EasyWhitelist yet!) until a determination on whether or not a player is whitelisted or blacklisted has been made.
Added Friends detection
Ever wanted to see if a player is friends with a certain player before allowing them to join? Maybe you want to make a game where only your Roblox friends can join? That is now possible using the newly added “WhitelistedFriends” and “BlacklistedFriends” detection method. You can now add UserIDs to these tables and it will go through each one to see if the newly joined player is friends with that user.
Critical bug fix
Previously I did not realize that all the other detection methods (besides UserId, username, owner check, studio check) were inside the scope of the group check. Because of this, all the other detection methods were essentially useless unless the player was inside that group. This has now been resolved and all detection methods should now work as expected!

Version 1.5

Added “RoleName” parameter to groups
It is now possible to add a RoleName (e.g. “Suspended”) to the Group tables. Refer to the documentation for more info on how to use it!
Improved “HideGame” mechanics
I have improved the HideGame flag to never destroy the GUI (even when the player is kicked) unless the player has been cleared to join. This fixed the bug where after the player was kicked they could see a blurred version of the map.
Documentation is now on DevForum
You can now refer to the new Documentation/How to Setup section for basic instructions on how to setup and use the EasyWhitelist resource! I plan to clean it up more in the future, or potentially move it to a website made for documentations, however, this is the temporary version!

Version 1.6

Added Webhook Support
It is now possible to link in-game logging to a webhook! For more information on how to use it, please see the “Webhook” tab in the documentation above.
Added “ExploreTime” parameter
You can now set a time (in seconds) that a player can play your game for before EasyWhitelist takes action on them. This is useful if you want to give players a 10 minute “sneak peak”, for example, and then you could say to continue they have to purchase a gamepass. Keep in mind the ExploreTime does not save, players can rejoin and they will get another ExploreTime.
Documentation updates and EasyWhitelist bug fixes!

Version 1.7

Added Badge Support
It is now possible to filter users by whether they own a badge or not! The documentation has been updated to include such changes.
Added Custom Kick messages
Credit to @LeoBeomkl for the idea! It is now possible to add “custom kick messages” for a specific user! The documentation has been updated to include such changes.
Code slightly improved & cleaned
Documentation made more consistent + improved
Fixed the bug where the “Verifying” GUI would be retained despite player being exempt

Jagriel_1 · September 5, 2023, 7:22pm

Would a whitelist on a game for a certain role on a discord server be possible?

VSCPlays · September 5, 2023, 7:26pm

Do you know any use cases for this module, I would try it out (if anyone gives me)

devlazerr · September 5, 2023, 8:44pm

There are many cases where this can prove useful! Examples being:

Game Maintenance (e.g. you only want a certain group of people such as testers or developers to be able to join!)
Group Lock (e.g. you only want permitted group members to be able to join!)
Early Access (e.g. you only want people who have bought an “Early Access” gamepass to be able to join!)
Server Lock command (you can easily setup a script to toggle the Enabled value in the module to enable/disable a “server lock”!)
Many other specific instances (there are many instances where this can be used for your specific game, and I’m always looking for ways to expand the amount of ways to do just that!)

devlazerr · September 5, 2023, 8:48pm

That could potentially be possible, but unfortunately it’s not something I intend to add to this resource in specific as it requires a lot of backend work with stuff like verification & registration and then the process of reviewing a members roles. However, if I were to ever make an EasyWhitelist Premium, I would definitely consider some sort of Discord integration!

devlazerr · September 5, 2023, 9:23pm

Updated to v1.1! Blacklist has been added alongside the pre-existing whitelist.

Jagriel_1 · September 6, 2023, 3:03pm

Ok, thank you. For the roles, is it possible to include needing to be that rank and above instead of just one specific rank?

devlazerr · September 7, 2023, 9:40am

Yeah! All you’d have to use is the >= behavior, example:

{Rank = RankId, Behavior = ">="}

There are also many other useful ones, such as:

Less than or equal to:
{Rank = RankId, Behavior = “<=”}

Greater than:
{Rank = RankId, Behavior = “>”}

Less than:
{Rank = RankId, Behavior = “<”}

devlazerr · September 8, 2023, 11:44pm

Updated to Version 1.2! Update logs are in the main post under the “Version 1.2” section!

Katrist · September 9, 2023, 1:22am

Looks good, I feel that your code would really benefit from one thing though.

I noticed that you have a lot of unnecessary nesting that could be replaced by some guard clauses.

Your code:

if Player then
	--//Main code
else
	warn("EasyWhitelist | CheckWhitelist did not receieve a player argument!")
end

Guard clauses:

if not Player then
	warn("EasyWhitelist | CheckWhitelist did not receieve a player argument!")

	return
end

--//Main code

Your code:

for groupId, data in pairs(self.BlacklistedGroups) do
	if Player:IsInGroup(groupId) then
		--//Main code
	end
end

Guard clauses:

for groupId, data in pairs(self.BlacklistedGroups) do
	if not Player:IsInGroup(groupId) then
		continue
	end

	--//Main code
end

These are just a few examples. Keep in mind this is only advice, whether you choose to follow it or not is completely up to you.

devlazerr · September 11, 2023, 4:27pm

I’ll consider implementing that in the next update!

devlazerr · September 25, 2023, 8:20pm

Updated to v1.3! Update notes are included in the main post.

devlazerr · September 30, 2023, 6:03am

Updated to v1.4! Update & bug fix notes are included in the main post.

devlazerr · November 3, 2023, 8:43pm

Updated to v1.5! Update notes are included in the main post.

devlazerr · November 6, 2023, 12:13am

Updated to v1.6
Update logs included in the main post!

LeoBeomkl · March 15, 2024, 6:09pm

When is the text update gonna be? I see this as being a very useful a popular resource

LeoBeomkl · March 15, 2024, 7:02pm

You should also add more custom kick options like what info to display in the kick message

devlazerr · March 16, 2024, 6:32pm

I have an update planned to release soon!

LeoBeomkl · March 16, 2024, 6:33pm

devlazerr · March 16, 2024, 6:40pm

You can manipulate the NotWhitelistedKickMessage or BlacklistedKickMessage using just a plain string or a string using concatenation or string interpolation to make the kick messages more advanced/detailed to achieve this effect, but if you have any ideas in specific let me know!

Example:

EasyWhitelist.BlacklistedKickMessage = `You have been kicked from {game:GetService("MarketplaceService"):GetProductInfo(game.PlaceId).Name} Version {game.PlaceVersion} due to being blacklisted!`

Would give you a kick message like: You have been kicked from YourPlaceName Version 13 due to being blacklisted!