Addons (AGMS_Addons)

Extend AGMS with custom commands via the addon ModuleScript API.

AGMS loads optional ModuleScripts from ReplicatedStorage/AGMS_Addons at server startup. Each addon registers commands without editing core AGMS files. A failure in one addon does not block others.

Folder layout

ReplicatedStorage/
├── AGMS               (panel — do not rename)
└── AGMS_Addons        (Folder — create if missing)
    ├── MyCommands     (ModuleScript)
    └── EconomyTools   (ModuleScript)

Only ModuleScript children of AGMS_Addons are loaded. Other instance types are ignored.

Module return shape

Each addon ModuleScript must return a table with these fields:

Field	Type	Required	Description
Commands	{ Command }	Yes	Command definitions (same shape as built-ins).
Init	(context) -> ()	No	Runs once after commands register; see below.

Minimal example:

--!strict
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local AGMS = ReplicatedStorage:WaitForChild("AGMS")
local Constants = require(AGMS:WaitForChild("Constants"))

return {
    Commands = {
        {
            Name = "shout",
            Aliases = { "broadcast" },
            Description = "Send a server-wide chat message.",
            Usage = ";shout <text>",
            Category = Constants.Category.Server,
            Level = Constants.AdminLevel.HeadAdmin,
            Icon = "megaphone",
            Execute = function(admin: Player, args: { string })
                local message = table.concat(args, " ")
                if message == "" then
                    return false, "Message required"
                end
                -- your logic here
                return true, "Sent"
            end,
        },
    },
}

Command definition (Command)

Field	Type	Required	Description
Name	string	Yes	Primary command name (lowercase in registry).
Aliases	{ string }	No	Alternate names resolved to Name.
Description	string	Yes	Shown in Commands page and autocomplete.
Usage	string	Yes	Help text, e.g. ;shout <text>.
Category	string	Yes	One of Constants.Category values.
Level	number	Yes	Minimum admin level (1–6).
Icon	string	No	Lucide icon id for the UI.
Args	{ CommandArg }	No	Structured arg metadata (optional).
Execute	function	Yes	Server handler; see below.

CommandArg (optional metadata)

Field	Type	Description
Name	string	Argument label.
Type	string	Hint for docs/UI.
Required	boolean	Whether the arg is required.
Description	string?	Short help string.

Execute(admin, args)

Parameter	Type	Description
admin	Player	The player who ran the command.
args	{ string }	Tokenized arguments after the command name.

Return: (success: boolean, message: string?)

• success = true — command succeeded; optional message for the admin.
• success = false — command failed; message is shown as an error.

Commands run on the server with the same permission checks, rate limits, and logging pipeline as built-in commands. Use Constants.AdminLevel and Constants.Category so levels stay consistent with the panel.

Admin levels

Level	Role
6	Owner
5	Co-Owner
4	Head Admin
3	Super Admin
2	Admin
1	Moderator

An admin can only run commands at or below their own level.

Optional Init(context)

If your addon defines Init, AGMS calls it once per addon after commands register:

Init = function(context)
    local Commands = context.Commands
    -- e.g. cache references, connect signals, preload data
end,

context field	Description
Commands	The server Commands module (same as built-ins use).

Init runs inside task.spawn; errors are logged and do not stop other addons.

Registration and conflicts

• Commands register through Commands.Register (called automatically for each entry in Commands).
• Duplicate Name values log a warning; the last registration wins.
• Aliases map to the primary Name (case-insensitive).

Player selectors in args

Addon commands can use the same <player> selectors as built-ins (me, all, others, @username, numeric UserId, radius-N, etc.). Resolve targets on the server inside Execute — the client only sends intent.

Security notes

• Never trust client input beyond the args array; validate targets and levels server-side.
• Do not store secrets in ReplicatedStorage; webhook URLs belong in ServerStorage (see Game settings).
• Keep addon ModuleScripts in AGMS_Addons only — AGMS does not load remote or dynamic require paths outside that folder.

Related docs

• Commands — built-in command reference and categories.
• Admin levels — permission tiers and promotion rules.
• Configuration — Config.Admins and runtime overrides.