An admin command is a common feature in Roblox games where a player can type a command into the chat window which will trigger a game action. This library allows for easy implementation of admin commands on top of the Roblox chat system.
This library uses ChatModules to allow you to easily link behaviors that you write to chattable commands. ChatModules listen to incoming messages on the server and can execute actions based on whatever criteria is desired.
- Roblox Studio
- Intermediate Roblox lua
- Scripts, functions, variables, tables
- Parent-child hierarchy
- The Chat system
The first step in setting up the admin commands library is to add a new Chat Module to the Chat service. It is strongly recommended that you read the Created an Admin Command tutorial as it explains the basics of working with the Roblox chat system. The library in this tutorial takes care of the heavy lifting done by a Chat Module so the only object you need to add to the Chat service is a new
ModuleScript. The name of your module script can be anything, but I suggest something intuitive like AdminCommands.
Implementing New Commands
Binding a command
Rather than implementing most of the Chat Module logic you will simply require the library module that does a bulk of the work and adds extra functionality. The simplest way to add the library into your module is to require it by its assetId at the top of your script.
This Module returns a table of functions (the complete list can be seen below ). The most important of these functions is the Run function. The library has a Run function for its Chat module. It is important that AdminCommands returns this Run function to the Chat Service. The function is indexed by its name, Run, and you can return the following as if Run was a property of our AdminCommands table representation:
Between these two lines of code is where you will be implementing your own commands and any necessary helper functions.
In order to bind a function to the library, you will use the BindCommand function of AdminCommands. When binding a command you will need to specify a table of keywords that, when spoken, will trigger the command, the function that will be triggered, a priority level, and optionally, a description of the command. If you do not specify a privilege level it will default to 0. Priority levels are numerical values used by the AdminCommands library to assign a hierarchy of permission amongst users with corresponding levels of granted privilege. When executing a command the speaker must have a privilege level that is greater than or equal to that of the command Permission Library.
To unbind you would likewise use UnbindCommand and specify a keyword to unbind.
Altogether, the content of your AdminCommands script should look like the following:
You may notice that the example function takes a parameter named commandData. This parameter is a table argument passed along to all bound admin command functions when executed by the library. The table contains useful information about the command that was spoken and the player who spoke it. It has the following fields:
It is important to always expect commandData as a parameter of command functions. For example, if you have a command named “explode’, which requires a player parameter to be specified, the function would look like explode(commandData, player).
|BindCommand()||table functionIDs, function functionToExecute, number minimumPermissionLevel, string description||bool|
The library already has a few built-in helper functions called Utilities that you can use. Store AdminCommand.Utilities in a variable or reference it directly.
Current utility functions are:
|Chat window messages:|
|SendSystemMessage()||table commandData, string content, table extraData||bool|
|SendSystemSuccessMessage()||table commandData, string content||bool|
|SendSystemWarningMessage()||table commandData, string content||bool|
|SendSystemErrorMessage()||table commandData, string content||bool|
|IncorrectValueType()||table commandData, string given, string expected|
|ValidateData()||string expectedType, ...||bool|
A useful command to have would be one that prints a list of all optional commands that users have available. This command outputs each command bound to the library and a few of its properties.
Another helpful command allows users to give themselves sparkles. This command requires one parameter when spoken – the targeted player’s name. If the player exists, the command will create a Sparkles object in the HumanoidRootPart of that player.
You can also include an explosion command from the Created an Admin Command tutorial. This command also takes a player’s name as a parameter.
If a non-admin tries to speak a command like this, which has a higher permission level than 0, it will not be triggered. The command system uses a separate Permission library, to which the game creator is automatically given the permission level math.huge. Admins can be added using the following functions on your AdminCommands module object. More functions can be found by looking at the library’s source code:
|SetUserPermission()||number requesterUserId, number targetUserId, permissionLevel||bool|
|SetGroupRankPermission()||number requesterUserId, number targetGroupId, number targetRankId, permissionLevel||bool|
For easier setup you can also use this Quick Start, which is a module that has already implemented the Admin Commands library. The model is a module with the same format as described above. Additionally, the module has a few commands already included so that you do not have to re-implement.
|“part”||Path (i.e. game.Workspace)|
|“setuserpermission”, “sup”||userId, permission|
|“setgrouprankpermission”, “sgrp”||groupid, rankId, permission|