¶ Introduction
Cheats need to be enabled on the server for the code to run
Function Hooks are now temporaraly accessed by typing “/hooks” into the roblox chat
Hook Functions are a way to implement custom scripts into your VIP / Community servers.
With them, you can implement custom behavior to the server such as Infection events, allowing SCPs to escape and become SH (or anything else), having CDs turn into janitors when they go in 914 on fine, etc.
¶ Syntax
¶ Data Types
¶ Booleans
Booleans are simply a bit that is either on or off; they are commonly returned by functions and properties and can be used to determine what your code should do or change the behavior of instances such as Players.
true; // Enabled.
false; // Not enabled (disabled).
¶ Numbers
Numbers are well, numbers. They are used for storing data that cant be simply stored as boolean such as player count.
1234; // An integer.
12.34; // A decimal number.
¶ Strings
Strings are a representation of letters, numbers, symbols, or all, which are declared using double quotes ".
They are used to store data such as names.
"I am a string";
""; // An empty string.
"123"; // This is a string, not a number.
¶ Vectors
Vectors are a set of 3 numbers that specify a point in 3D space or a direction.
Vec3(0,0,0);
Vec3(-94,2,64);
Vec3(1,1,1);
¶ Instances (Players,Items,Etc.)
Instances in Hook Functions are datetypes that contain data about a specific thing (such as Player Instance, which contains data about a specific player) which is represented by properties.
¶ Player Instance
Plr.Name; // String, the name of a player.
Plr.IsAlive; // Boolean, whether a player is currently alive or not.
Plr.Class; // String, the player's class.
Plr.Cuffed; // Boolean
Plr.Health; // Number
Plr.MaxHealth; // Number
Plr.Position; // Vector3
¶ Item Instance
Item.Name; // String, the name of the item.
Item.Position;
¶ Operators
An Operator is a symbol or a set of symbols that represent an action and are used with values to return a new value.
¶ Arithmetic
Arithmetic operators are simply math operations.
1 + 49; // 50 | Addition
600 - 427; // 173 | Subtraction
22 * 4; // 88 | Multiplication
100 / 5; // 20 | Division
5^2; // 25 | Exponentiation
-(-50); // 50 | Negation
¶ Comparison
Comparison Operators are Operators that compare different datatypes and can only return true or false.
// Can be used with all datatypes //
"Hello!" == "Bye" // false | "Equal to" Operator
"String" == 25 // false
25 != 8 // true | "Not equal to" Operator
"sus" != "innocent" // true
// Can be used only with numbers. //
314 > 50 // true | "Greater than" Operator
200 < 100 // false | "Less than" Operator
5 >= 5 // true | "Greater than or Equal to" Operator
16 <= 16 // true | "Less than or Equal to" Operator
¶ Logical Operators
Logical Operators are Operators that combine different values or boolean to return false or (true or a value)
// "!" Operator, This operator negates the boolean.
!true; // false
!false; // true
// "and" Operator, This operator returns true if all parts of the expression are not false.
("Hello" == "Hello") and false; // false.
true and true; // true.
((25 * 2) == 50) and (10 == 2); // false.
// "or" Operator, This operator returns true if any parts of the expression are not false.
"Hello" or false; // true.
("Hello" == "Not") and true; // true.
¶ Variables
Variables are names that have a value associated with them that can be accessed and modified at any point in time, which can be used for storing values.
var imAVariable = "here is my value";
var iAmNil;
var breakfast = "bagels";
print breakfast; // "bagels".
breakfast = "beignets";
print breakfast; // "beignets".
¶ Control Flow (Loops And If-Statements)
Control Flow is a very important part of code, as it determines which path in your code to take if a condition is met or not.
¶ If Statement
If Statements are a conditional statement that if met, will run the code inside the statement.
If the condition for the if statement is not met, the else keyword can be used to run a different path in your code.
if (2 > 1) {
print "math works";
} else {
print "uh oh, math is broken";
}
¶ While Loop
While Loops are loops that run as long as the condition for it is met, if at any point the condition is not met, the loop will stop.
var a = 1;
while (a < 10) {
print a;
a = a + 1;
}
¶ For Loop
For loops are loops that can be used to run a block of code a known number of times, unlike While Loop, which can run an indeterminate number of times.
for (var a = 1; a < 10; a = a + 1) {
print a;
}
here is an example for looping trough all players
var x = 0
var players = GetPlayers();
for (var a = 1; a < #players+1; a = a + 1) {
x = a;
var plr = players[x];
print plr.Name;
}
¶ Functions
Functions are blocks of code that can be run at any point in the script, which can receive a number of arguments and return a value at the end of the execution.
// This function will print the result of adding a and b.
function printSum(a, b) {
print a + b;
}
// This function returns the addition of a and b.
function addPair(a, b) {
return a + b;
}
// This function returns the first argument as it is.
function identity(a) {
return a;
}
// This will run the same as 'print addPair(1, 2)`,
// since the identity function will return addPair.
print identity(addPair)(1, 2); // Prints "3".
Functions can also have functions inside of them that can only be called from the first function.
function outerFunction() {
function localFunction() {
print "I'm local!";
}
localFunction(); // This will print "I'm local!"
}
localFunction(); // This will not work as localFunction is not created in the current scope.
Functions can also return functions, as seen in Identity function and the one below, However, the latter returns a function created inside which accesses a variable contained within.
function returnFunction() {
var outside = "outside";
function inner() {
print outside;
}
return inner;
}
var fn = returnFunction();
fn(); // This will print "outside"
¶ API Documentation
¶ Math Functions
¶ rand(min,max)
Returns a psuedo-random integer located between the minimum number and the maximum number.
print rand(1,10); // Returns a random number between 1 and 10
¶ clamp(num,min,max)
If num is less than min, returns min.
If num is greater than max, returns max
Returns num otherwise.
print clamp(5,1,10); // Returns 5
¶ pow(num, power)
Equivalent to num ^ power
print pow(2,5); // returns 2^5 (32)
¶ abs(num)
Returns the absolute number of num, which is the same number but positive.
print abs(-2); // returns 2
¶ floor(num)
Returns the lowest closest integer to num
print floor(2.7); // returns 2
¶ round(num)
Returns the closest integer to num,
print round(2.7); // Returns 3
¶ ceil(num)
Returns the greatest closest integer to num,
print ceil(3.1); // Returns 4
¶ Vec3(x,y,z)
print Vec3(3,6,2);
¶ Player Functions
¶ SetHealth(Plr, Num)
Sets the Player’s current HP to Num
// Assuming the player just spawned.
if (Plr.Class == "Class-D") {
SetHealth(Plr, 75);
}
¶ ModifyPlayerAmmo(Plr, Ammotype,amount)
Valid ammo types
Explosive
HeavyCaliber
MediumCaliber
SmallCaliber
Shells
// gives the player 10 shotgun shells
ModifyPlayerAmmo(Plr, "Shells",10);
}
¶ SetMaxHealth(Plr, Num)
Sets the Player’s Maximum HP to Num
// Assuming the player killed someone as SCP-096
if (Plr.Class == "SCP-096") {
SetMaxHealth(Plr, Plr.Health + 100);
}
¶ SetSpeed(Plr, Num)
Sets the Player’s current Speed to Num
SetSpeed(Plr, 25);
¶ TakeDamage(Plr, Num)
Reduces the Player’s Health by Num, but respects factors that may negate or reduce damage such as Armor.
TakeDamage(Plr, 30);
¶ SetClass(Plr, Name)
Set’s the Player’s Class to Name if Name is a valid class.
// Assuming the player just spawned as a Class-D.
if (Plr.Class == "Class-D") {
var rnum = rand(1, 4)
if (rnum == 2) {
SetClass(Plr, "Serpents Hand");
}
}
¶ Teleport(Plr, Vec3)
Teleports the Player to a position on the map, specified by Vec3.
// This will teleport the player 15 studs up.
Teleport(Plr, Plr.Position + Vec3(0, 15, 0);
¶ GetPlayerByName(Name)
Returns the player named Name if they currently exist within the server.
// assuming you want to kill someone with a "!kill" command
if (sub(Message, 1, 5) == "!kill") {
var plr = GetPlayerByName(sub(Message, 5, 500));
if (plr) {
SetClass(plr, "Lobby");
}
}
¶ GetPlayersInTeam(TeamName)
Returns a table containing all the players in TeamName if TeamName is a valid class.
var players = GetPlayersInTeam("Class-D");
¶ GiveItem(Plr, ItemName)
Gives the player the item named ItemName if ItemName is a valid item name.
// This will give the player a flashlight.
GiveItem(Plr, "Flashlight");
¶ HasItem(Plr, ItemName)
Returns true if the Plr has any item named ItemName, else returns false.
if (HasItem(Plr, "Flashlight")) {
print Plr.Name + " Has Flashlight";
}
¶ RemoveItem(Plr, ItemName)
If the Player has an item named ItemName, it will be removed.
RemoveItem(Plr, "Flashlight");
¶ CanAttack(Attacker,Target)
If the Attacker can damage the Target directly, returns true, else false.
if (CanAttack(Attacker,Target)) {
print Attacker.Name+" Can Damage "+Target.Name;
}
¶ Round Functions
¶ Announce(message,player)
Creates a popup with the specified message, if no player is specified it will be sent to all players.
Announce("This is the message!");
¶ roundlock(state)
Sets the lock state of the round to state.
Roundlock if true, prevents the round from ending if a win condition is met.
roundlock(true);
¶ SetFallDamage(state)
Sets the Fall Damage to state.
FallDamage if true, any Player falling from a height will take damage that scales with the distance they fell.
SetFallDamage(true); // Enables Fall damage
¶ SetChatType(type)
Changes Chat Type to type.
type has only 2 options: Proxy, Global
SetChatType("proxy"); // Enables proximity chat
¶ SetInfAmmo(state)
Sets Infinite Ammo to state.
Infinite Ammo if true, any Player reloading a gun without ammo for it will be able to reload it normally.
SetInfAmmo(true); // Enables infinite ammo
¶ SetDoorsEnabled(state)
Sets whether you can open or close Doors to state.
SetDoorsEnabled(false); // Disables doors
¶ SetAutoNukeEnabled(state)
Sets Auto Nuke to state.
Auto Nuke if false, Nuke will not start on its own after the round lasts for a duration.
SetAutoNukeEnabled(false); // Disables autonuke
¶ Set294CooldownEnabled(state)
Sets SCP-294’s Cooldown to state.
SCP-294 Cooldown if false, Players will be able to use SCP-294 as much as they want without the 5-minute delay between each drink.
Set294CooldownEnabled(false); // Disables 294 Cooldown
¶ SetDecontamination(state)
Sets Decontamination to state.
Decontamination if false, LCZ and SCZ will not experience Decontamination when 10 minutes pass.
SetDecontamination(false); // Disables Decontamination
¶ SetVotingEnabled(state)
Sets Voting to state.
Voting if false, Players will not be able to vote for FF mode (Friendly Fire)
SetVotingEnabled(false); // Disables FF voting
¶ SetPlayerCollisions(state)
Sets Player Collisions to state.
Player Collisions if true, Players will be able to collide with each other.
SetPlayerCollisions(true); // Enables Player Collisions
¶ SpawnItem(ItemName,Pos)
Spawns the item named ItemName if ItemName is a valid item name at Pos.
SpawnItem("Flashlight",Vec3(3,5,2));
¶ DeleteItems(ItemName)
Removes all items named ItemName from the map if ItemName is a valid item name.
DeleteItems("Janitor Keycard");
¶ ClearItems()
Removes all items that exist in the map.
ClearItems();
¶ ClearRagdolls()
Removes all corpses of players.
ClearRagdolls();
¶ SetFF(type)
Changes Friendly Fire mode for the round to type if type is a valid type.
type options: REVERSE, ON, OFF
SetFF("ON"); // REVERSE, ON, OFF
¶ Audio Functions
¶ SetAudioId(id)
Sets the audio to play using PlayAudio() to id
id must be in this format: “rbxassetid://<IDHERE>”
SetAudioId("rbxassetid://0");
¶ PlayAudio()
Plays the audio set through SetAudioId().
PlayAudio();
¶ StopAudio()
Stops the audio.
StopAudio();
¶ Tag Functions
¶ HasTag(plr,tag)
If the plr has the tag tag, returns true, else false.
if (HasTag(plr, "Juggernaut") {
SetMaxHealth(plr, 1000);
SetHealth(plr, 1000);
}
¶ GiveTag(plr,tag)
Applies the tag tag to a player.
tag has to be a string.
// assuming the player spawned
if ((!strfind(plr.Class, "SCP")) and(rand(1, 10) == 5)) {
GiveTag(plr, "Juggernaut");
}
¶ RemoveTag(plr,tag)
Removes the tag tag from a player if they have it.
// assuming the player just died
if (HasTag(plr, "Juggernaut") {
RemoveTag(plr, "Juggernaut");
}
¶ Other Functions
¶ SetGlobal(key,value)
Sets a global variable that can be accessed with GetGlobal().
SetGlobal("key",123);
¶ GetGlobal(key)
Gets a global variable with the key key if it exists.
var value = GetGlobal("key");
¶ tostring(value)
Returns value as a string if possible, else nil.
print tostring(500); // Prints "500"
¶ tonumber(str)
Returns str as a number if possible, else nil.
print tonumber("25"); // Prints 25
print tonumber("hi"); // Prints nil
¶ typeof(value)
Returns the type of value
print typeof("25"); // string
print typeof(500); // number
print typeof(tonumber("60")); // number
¶ tick()
Returns the current time.
print tick(); // Will return a different number higher than the one before everytime it's called.
¶ wait(number num)
Pauses execution of the code for a duration roughly equal to num
print "hi";
wait(2);
print "this is printed 2 seconds after";
¶ Team Functions
¶ SetTeamCanDamage(str team1,str team2, bool value)
Toggles the ability for team1 and team2 to attack each other.
SetTeamCanDamage("MTF Commander","MTF Cadet",true); // commander now damage cadet independent from the friendly fire policies
¶ RemoveCanDamage(str team1,str team2)
Resets the default attack behavior of team1 and team2
RemoveCanDamage("MTF Commander","MTF Cadet");
¶ NewTeam(str name,str color)
Creates a new team with the name name and the color color.
color has to a valid BrickColor.
NewTeam("Team Name","Fog");
¶ DeleteTeam(str name)
Removes an existing team with the name name.
DeleteTeam("MTF Cadet"); // MTF Cadet will no longer exist.
¶ String Functions
¶ split(str, separator)
Returns a table with the string split into parts based on the defined separator character(s).
var splitstring = split("Hello, this is not a split string! for now.", " ")
// this will return a table containing every word (including any symbol that next to it)
// "Hello,", "this", "is", "not", "a", "split", "string!", "for", "now."
var splitstring = split("hi||bye", "|")
// this will return a table with 3 strings: "hi", "", "bye".
¶ char(num …)
Receives zero or more integers and returns a string with length equal to the number of arguments that has each character has the internal numerical code equal to its corresponding argument.
print char(72, 101, 108, 108, 111); // prints "Hello"
¶ match(str, pattern, startinde)
Searches for any occurance of the pattern in text
If found, will return the start index of the pattern
Start parameter is optional and is used for indicating where to start searching.
if (match(Class, "MTF")) {
SetMaxHealth(Plr, 120);
SetHealth(Plr, 120);
} // Will only give the player radio if they're CI
¶ sub(str, startindex, endindex)
Returns a sub-string from startindex to endindex
print sub("abcdefghijklmnopqrstuvwxyz", 5, 10); // prints "efghij"
¶ strfind(str, pattern, startindex, plain)
Searches for any occurance of the pattern in text
If found, will return the start index of the pattern
Start parameter is optional and is used for indicating where to start searching
Plain parameters disables searching for pattern inside words
(eg: if you’re searching for like “CI” in class names, it won’t check if there’s “CI” in “Lieutenant” or "Commander, etc)
if (strfind(Class, "CI", 1, true)) {
GiveItem(Plr, "Radio");
} // Will only give the player radio if they're CI
¶ strformat(str)
Returns a formatted string.
https://developer.roblox.com/en-us/articles/Format-String
print strformat("%s is %s and has %.1f HP!", "Player", "SCP-096", 2951.492);
// Will print "Player is SCP-096 and has 2951.4 HP!"
¶ lower(str)
Returns a copy of the string with all characters lowercase
print lower("HeLLo WorLD!"); // Prints "hello world!"
¶ upper(str)
Returns a copy of the string with all characters uppercase
print upper("HeLLo WorLD!"); // Prints "HELLO WORLD!"
¶ gsub(str, pattern, replacement, max)
Returns a copy of str in which all (or up to max) occurrences of the pattern are replaced with the given replacement.
The replacement can be one of several types, each used differently to determine the actual string:
- string: The pattern is replaced with the string directly
- table: The string that matched the pattern is looked up in the table as a key, and the value (string) is what replaces it, if it exists.
An optional final argument can be provided which specifies the maximum number of substitutions to make (for example, stop after 2 replacements)
print gsub("{s} is sus", "{s}", Plr.Name);
// Will print "Player is sus"
¶ strrep(str, num)
Returns the same string repeated by num
print strrep("hi!", 5);
// Will print "hi!hi!hi!hi!hi!"
¶ strreverse(str)
Returns a reversed copy of the string
print strreverse("This text is not reversed!");
// Will print "!desrever ton si txet sihT"
¶ Credits
The Hook Functions are based on the lox language from the book Crafting Interpreters written by Robert Nystrom Most code examples listed here are either slightly modified or direct copies from the book.
https://craftinginterpreters.com/