Server Addons

Server Addons allow you to extend and customize server functionality using custom Lua scripts. This page details the scripting environment, available API, and provides examples.

Scripting Environment

Server Addons run on a sandboxed version of Lua 5 with specific syntax extensions. Many Roblox engine functions (e.g., creating UI or accessing services like Players or ReplicatedStorage) and the full Luau feature set are not available. The sandbox supports compound assignment (+=, -=, /=, *=, ..=), the continue keyword, and basic type annotations on local variables, function parameters, and return values.

User-settable text and templates

In Server Addons, text users can set is subject to a 1 minute (60-second) cooldown for Roblox compliance. Design addons to reuse prepared text-bearing instances rather than repeatedly creating instances and setting their text.

1. During setup, prepare the necessary instances, such as custom Tools, as reusable templates with their names and other required text already set.
2. When giving a tool, clone the prepared template and give that clone to the player. Keep the original template available for later grants instead of creating a new Tool and assigning its name each time.
3. Keep text initialization out of repeated grant, spawn, interaction, and command callbacks. Do not rewrite text on each clone.

Cloning a prepared template reuses its existing text; it does not exempt new or changed text from the cooldown or filtering requirements. Existing filtering and host-presence requirements still apply. The separate Addon Commands registration limit is described in its API section; setToolCooldown controls tool use, not this text-setting cooldown.

You can use F3X to view a part's position, which is useful for coding logic that occurs when a player enters a specific region in the map.

Loading SKILL.md…

API Reference

Map & Instance Functions

Player Functions

Team Functions

Addon Commands

Use the :addoncommands command to open the addon commands menu, which contains buttons registered by addons:

• registerAddonCommand("id", "title", callback) adds a command button with a filtered title capped at 32 characters. The callback is invoked when the command is selected.
• registerAddonCommand("id", false) disables the command.
• registerAddonCommand("id", true) re-enables the command.
• registerAddonCommand("id", nil) removes the command.

By default, only moderators and above can access the panel. Expand this access with registerAddonCommand(whitelist), where whitelist is a table of player names or user IDs. You can implement your own restrictions and cooldowns in each command's callback.

For compliance reasons, registerAddonCommand is unavailable for 60 seconds after its latest batch. You can still assign multiple commands within the same execution frame.

Addon commands reset when the map changes, during loading and before addons are loaded. Register the commands needed for the new map when its addons load.

Example: register commands to turn ragdoll on and off.

registerAddonCommand("a", "ragdoll on", function(player) toggleRagdoll(player) end)
registerAddonCommand("b", "ragdoll off", function(player) toggleRagdoll(player, false) end)

Display & UI Functions

Rig Functions

World Functions

Server & Web Functions

Events

Events have to be handled uniquely due to the sandboxed environment. You can use didEventHappen(name) to determine whether an event has been triggered since the last check and to update a local cache.

To simplify this process, server addons provide a special event() function that can be used to listen for changes in the cache and execute a callback function:

This example only reads the callback fields; it does not print or display a message.

event("joined", function(data)
    local When = data.When
    local Value = data.Value
    -- Value contains the player's name
end)

Available Events

Code Examples

Kill Part

Retrieves a part named "Part" from the map and makes it kill any player who touches it.

f("Part").Touched:Connect(function(Player)
    if Player then
        kill(Player)
    end
end)

Play Sound on Interaction

Listens for a custom interaction event and plays a sound globally when a part named "SoundPart" is triggered.

event("interaction", function(Data)
    local Player = Data.Value[1]
    local Interaction = Data.Value[2]
    
    if Interaction == "SoundPart" then
        local Sound = Instance.new("Sound")
        Sound.SoundId = "rbxassetid://157636218"
        
        playSound(Sound)
    end
end)

Custom Tool

Creates a simple custom Tool with a safe, hidden Handle and gives it to the first player in the server. This is a one-off creation example. For repeated grants, prepare a template once and clone it as described in User-settable text and templates; do not recreate and rename the Tool on every grant.

local function GiveTool(Player)
  local Tool = Instance.new("Tool")
  Tool.CanBeDropped = false
  Tool.Name = "Custom Tool"
  
  local Part = Instance.new("Part")
  Part.Name = "Handle"
  Part.Anchored = true
  Part.CanCollide = false
  Part.CFrame = CFrame.new(999, 9999, 999)
  
  f(Tool)
  Part.Parent = Tool
  
  giveTool(Player, Tool)
end

GiveTool(getPlayers()[1])

Tool With a Cooldown

Creates a simple custom Tool that changes the Handle color upon activation, with a tool-use cooldown of 1 second. This is separate from the text-setting cooldown. For repeated grants, use prepared templates rather than recreating and renaming the Tool on every grant.

local function GiveTool(Player)
  local Tool = Instance.new("Tool")
  Tool.CanBeDropped = false
  Tool.Name = "Custom Tool"
  
  local Part = Instance.new("Part")
  Part.Name = "Handle"
  Part.CanCollide = false
  Part.CFrame = CFrame.new(999, 9999, 999)
  
  Tool.Activated:Connect(function()
      Part.Color = Color3.new(math.random(), math.random(), math.random())
  end)

  setToolCooldown(Tool, 1)
  
  f(Tool)
  Part.Parent = Tool
  
  giveTool(Player, Tool)
end

GiveTool(getPlayers()[1])

Cross Addon Communication

Sets up a signal loop that works across multiple addons.

-- Addon 1
signalReceived("loop", function(n)
  print("current number:", n)
end)

-- Addon 2
local n = 0

while true do
  task.wait(1)
  
  n = n + 1
  
  signal("loop", n)
end

Exporting Variables / Functions

Makes use of signals to export variables and functions.

-- Addon 1
local var1 = "Hello world!"

function func()
  return var1
end

signalReceived("var1", function() return var1 end)
signalReceived("func", function() return func end)

-- Addon 2
local var1 = signalAsync("var1")
local func = signalAsync("func")