Docs: Server Addons - SCP: Roleplay Custom Server Guide

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. This means that many functions related to the Roblox engine (e.g., creating UI, accessing services like Players or ReplicatedStorage) and modern Luau functionality will not be available. However, there is primitive support for some numerical operations (+=, -=, *=, /=) and string concatenation (..=).

Info: You can access existing Instances inside the map by referencing them through workspace (e.g., workspace.Part), but you cannot parent new Instances directly to Workspace. To add a new Instance to the map, you must use the f(Instance) function.

Caution: Functions that involve displaying messages to players undergo filtering and can only be used when the server host is present in the server.

Caution: "Run Once" executions are halted after 10 seconds for security reasons. Additionally, you may need to parent a new Instance to the map before parenting other Instances into it, as this can cause data to be discarded.

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.

API Reference

Map & Instance Functions

Function	Description
`f(name : string / instance)`	Returns the first Instance in the map matching the given name. If an Instance is passed as the argument, it will be parented to the map.
`getTagged(tag)`	Returns all Instances in the map that have the specified tag. Tag is a string.
`tween(instance : instance, tweenInfo : tweeninfo, propertyTable : table)`	Creates and plays a tween.
`raycast(origin : Vector3, direction : Vector3, params : RaycastParams)`	Performs a raycast operation and returns the result. If the ray hits a player, the `RaycastResult.Instance` property will be their username.

Player Functions

Function	Description
`kill(name : string)`	Kills the specified player.
`damage(name : string, amount : number)`	Damages the specified player by the given amount.
`heal(name : string)`	Heals the specified player to their maximum health.
`getPlayers()`	Returns a list of the usernames of all players in the server.
`getPlayerHealth(name : string)`	Returns the specified player's current health. Returns -1 if the player is not spawned in.
`setPlayerHealth(name : string, amount : number)`	Sets the specified player's health.
`getPlayerMaxHealth(name : string)`	Returns the specified player's max health. Returns -1 if the player is not spawned in.
`setPlayerMaxHealth(name : string, amount : number)`	Sets the specified player's max health.
`getPlayerScore(name : string)`	Returns the specified player's score.
`setPlayerScore(name : string, score : number (default: 0))`	Sets the specified player's score.
`getPlayerPosition(name : string)`	Returns the specified player's position (Vector3 / CFrame) in the map.
`setPlayerPosition(name : string, position : Vector3)`	Sets the specified player's position (Vector3 / CFrame).
`getPlayerKeycard(name : string)`	Returns the specified player's keycard level. (e.g. "L4").
`getTools(name : string)`	Returns a list of the names of all tools in the specified player's inventory.
`getPlayerTool(name : string)`	Returns the name of the tool currently being equipped by the specified player. Also returns a secondary value with the position of the Muzzle part, or the position of the Handle part if there is no part named Muzzle in the tool.
`giveTool(name : string, tool : string)`	Gives the specified player the specified tool. It also supports the tool argument being a Tool, where in that case it will unanchor the Handle before giving it to the player (useful for making custom tools).
`removeTool(name : string, tool : string)`	Removes the specified tool from the specified player.
`getUserId(name : string)`	Returns the specified player's UserId.
`ownsGamepass(name : string, id : number)`	Returns whether or not the specified player owns the specified gamepass.
`ownsAsset(name : string, id : number)`	Returns whether or not the specified player owns the specified asset.
`getPlayerCredits(name : string)`	Returns the specified player's credits currency amount.
`getPlayerXP(name : string)`	Returns the specified player's XP amount.
`playEmote(target : string / Instance, id : number, loop : bool (default: false))`	Plays the specified emote or animation on the specified player. You can pass a Humanoid, Animator, AnimationController or an Instance ascending a Humanoid as the target argument, allowing you to animate custom SCPs, for example. Returns a function that stops the animation and another that adjusts its speed, e.g.: `stopFunction,` `adjustSpeedFunction = playEmote(...)`.
`hasTool(name : string, tool : string)`	Returns whether the specified player has the specified tool.
`getPlayerCurrentTool(name : string)`	Returns the name of the tool the player is currently using, or `nil` if none.
`getPlayerIsInGroup(name : string, id : number)`	Returns whether the specified player is in the specified group.
`getPlayerRankInGroup(name : string, id : number)`	Returns the player's rank number (0–255) in the specified group.
`getPlayerRoleInGroup(name : string, id : number)`	Returns the player's role in the specified group.
`gunMagSize(name : string)`	Returns the number of bullets in a magazine for the specified gun.
`gunAddBullets(player : string, gun : string, amount : number)`	Adds the specified amount of bullets to the specified gun for the given player.
`gunAmmo(player : string, gun : string, mag : bool (default: false))`	Returns the amount of ammo in the specified gun. Returns the amount of bullets left in the magazine if mag is true.
`isGun(name : string)`	Returns whether or not the specified string is a gun; also returns the weapon type. Example: `local IsGun, IsPistol, IsShotgun = isGun("Golden Hawk")`

Team Functions

Function	Description
`getTeams()`	Returns all teams in the game in the `{ name, color }` format. (e.g. team[1] is the name, team[2] is the color).
`getTeamMembers(team : string / BrickColor)`	Returns the usernames of the members of the specified team.
`getTeam(name : string)`	Returns the specified player's team name and color. Example: `local name, color = getTeam("PlayerName")`
`setTeam(name : string, team : string / BrickColor)`	Sets the specified player's team.

Display & UI Functions

Function	Description
`announce(message : string, blue : bool (default: false))`	Displays the specified message to everyone in the server. Alternatively, if the second argument is a string, then the first argument will be used to send the announcement message only to the specified player.
`title(message : string, color : color3 (default: color3.new(1, 1, 1)), gradientColor : color3 (default: nil))`	Displays the specified title to everyone in the server. Alternatively, if the second argument is a string, then the first argument will be used to send the title message only to the specified player.
`subtitle(message : string, color : color3 (default: color3.new(1, 1, 1)), gradientColor : color3 (default: nil))`	Displays the specified subtitle to everyone in the server. Alternatively, if the second argument is a string, then the first argument will be used to send the subtitle message only to the specified player.
`sideinfo(message : string, color : color3 (default: color3.new(1, 1, 1)), gradientColor : color3 (default: nil))`	Displays the specified side info to everyone in the server. Alternatively, if the second argument is a string, then the first argument will be used to send the side info message only to the specified player.
`subsideinfo(message : string, color : color3 (default: color3.new(1, 1, 1)), gradientColor : color3 (default: nil))`	Displays the specified sub side info to everyone in the server. Alternatively, if the second argument is a string, then the first argument will be used to send the sub side info message only to the specified player.
`rigSay(name : string, message : string)`	Sends the specified message as a chat bubble for the specified rigs (e.g. `:load rig`).
`rigMoveTo(name : string, position : vector / bool, callback : function (default: nil))`	Makes the specified rigs move to the specified position (e.g. `:load rig`). Callback is an optional argument that gets called whenever the rig fires MoveToFinished. Sending `true` as the position argument will cause the rig to halt its movement.

World Functions

Function	Description
`playSound(sound : sound, player : string, attach : bool (default: false))`	Plays the sound. If a player is specified, plays it for them; otherwise global. attach defaults to false.
`resetLights()`	Resets the map lights using the lights system.
`colorLights(r, g, b : number)`	Colors the map lights using the lights system. RGB values default to 0.
`disableLights(amount : number)`	Disables map lights in succession by the specified amount at a time. Amount defaults to 1.
`blackoutLights(enabled : bool, emergencyPower : bool)`	Enables or disables the map lights blackout state. Enabled defaults to true, EmergencyPower defaults to false.
`getClockTime()`	Returns the world time.
`setClockTime(time : number, updateAtmosphere : bool (default: true))`	Changes the world time.
`setSignText(name : string, text : string)`	Changes the text of the first TextLabel found within the specified Instance in the map.
`setToolCooldown(tool : Instance, cooldown : number, activateOnEquip : bool (default: false))`	Sets the cooldown for using the tool. If cooldown is specified as 0 then the cooldown is removed. When activateOnEquip is set to true, the tool will act as an ability and activate upon selection instead of equipping.
`tweenGetValue(alpha : number, easingStyle : Enum.EasingStyle, easingDirection : Enum.EasingDirection)`	Calculates a new alpha given an EasingStyle and EasingDirection. https://create.roblox.com/docs/reference/engine/classes/TweenService#summary-methods
`tweenSmoothDamp(current : any, target : any, velocity : any, smoothTime : number, maxSpeed : number, dt : number)`	Calculates a value simulating a critically damped spring. See TweenService summary methods.

Server & Web Functions

Function	Description
`getHost()`	Returns the server host's UserId.
`runCommand(cmd : string)`	Executes the specified server command. Commands that broadcast text (for example announcements or titles) can only be run when the server host is present in the server. Returns whether or not the command was successful, and if it isn't successful, what the error was.
`http(url : string, method : string (default: "get"), headers : table (default: nil), body : string (default: nil), compress : Enum.HttpCompression (default: Enum.HttpCompression.None))`	Performs an HTTP request.
`jsonEncode(content : table)`	Encodes a Lua table into a JSON string.
`jsonDecode(json : string)`	Decodes a JSON string into a Lua table.

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:

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

Available Events

Event Name	Data Type / Description
`joined`	`string` (player : string) - Occurs when a player joins the server.
`left`	`string` (player : string) - Occurs when a player leaves the server.
`chatted`	`table` (player : string, message : string) - Occurs when a player sends a chat message.
`spawned`	`string` (player : string) - Occurs when a player spawns.
`interaction`	`table` (player : string, name : string) - Occurs when a player interacts with a custom interaction part.
`lightswitch`	`table` (player : string, room : string, state : bool) - Occurs when a player interacts with a light switch. Includes the player's username, room name, and new state of the light (on/off).
`death`	`string` (player : string) - Occurs when a player dies.
`kill`	`table` (killer : string, victim : string) - Occurs when one player kills another.
`usedtool`	`table` (player : string, tool : string, clickposition : vector) - Occurs when the player clicks while holding a tool.

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.

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 cooldown of 1 second.

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])