Utilities

This page documents miscellaneous functions that don't belong to any library.

getVersion function

Returns the current version of Ratchet.

Syntax:

string getVersion()

getSecret function

Reads a secret from ratchet/secrets.txt to avoid storing passwords or tokens in plugin code. Empty string will be returned if a secret by the specified key is not found.

Syntax:

string getSecret( string key )

isServerLoaded function

Checks whether the server is fully loaded (mods and plugins are loaded, players can connect). This is mostly useful for a custom REST API to check whether the server is still starting.

Syntax:

bool isServerLoaded()

getType function

Returns the name of an object type for a specific object.

Syntax:

string getType( mixed object )

base64Encode function

Syntax:

string base64Encode( string input )

base64Decode function

Syntax:

string base64Decode( string input )

friendlyTime function

Converts number of seconds into human-friendly and readable format.

Syntax:

string friendlyTime( int seconds )

Example:

local time = friendlyTime(3600)
print(time) -- "1 hour"

getRealTime function

Retrieves a table of various useful values regarding current real time.

Syntax:

table getRealTime( [ bool localTimezone = false ] )

Field	Type	Range	Description
timestamp	number	-	Unix epoch in seconds
hour	number	0-23	Hour (24-hour format)
minute	number	0-59	Minute
second	number	0-60	Second (60 for leap seconds)
year	number	-	Full year (e.g. 2025)
month	number	1-12	Month
day	number	1-31	Day of month
weekday	number	0-6	Day of week (0=Sunday)
weekdayiso	number	1-7	ISO weekday (1=Monday, 7=Sunday)
yearday	number	1-366	Day of year
isdst	boolean	-	Daylight saving time
date	string	-	ISO 8601 date (YYYY-MM-DD)
time	string	-	ISO 8601 time (HH:MM:SS)
datetime	string	-	ISO 8601 datetime (YYYY-MM-DDTHH:MM:SS)
hour12	number	1-12	Hour (12-hour format)
ampm	string	-	"AM" or "PM"

Example:

print(getRealTime().time) -- "18:04:23"

traceLine function

Trace a line between two points, detecting blocking object.

Syntax:

bool, HitResult traceLine( Vector origin, Vector destination [, int|table<string> filter = 0, bool complex = false, table<Actor> ignoreList = {} ] )

Filter can be either channel index from the table below or a table of strings representing object types from the table even further below.

Index	Channel
0	Visibility
1	Camera
2	Trace_BuildingStructure
3	Trace_ProjectilePrecision
4	Trace_BuildingGhost
5	SandStormMonsterSpawn
6	Trace_Interactable
7	DamagePrevention_BlockNothing

Object Types

WorldStatic

WorldDynamic

Pawn

PhysicsBody

Vehicle

Destructible

Attack

Defense

Hitbox

Building_Structure

Projectile

WaterPhysics

Resource

Sandstorm

CollisionTrigger

Hazard

AudioTrigger

LootBag

printDebug function

Same as the native print function, except for prepending plugin name and highlighting the message with gray color in the Ratchet console. This message will also be saved to the ratchet.log file located in the server's folder.

Syntax:

void printDebug( [ string input, ... ] )

printInfo function

Same as the native print function, except for prepending plugin name and highlighting the message with blue color in the Ratchet console. This message will also be saved to the ratchet.log file located in the server's folder.

Syntax:

void printInfo( [ string input, ... ] )

printSuccess function

Same as the native print function, except for prepending plugin name and highlighting the message with green color in the Ratchet console. This message will also be saved to the ratchet.log file located in the server's folder.

Syntax:

void printSuccess( [ string input, ... ] )

printWarning function

Same as the native print function, except for prepending plugin name and highlighting the message with gold color in the Ratchet console. This message will also be saved to the ratchet.log file located in the server's folder.

Syntax:

void printWarning( [ string input, ... ] )

printError function

Same as the native print function, except for prepending plugin name and highlighting the message with red color in the Ratchet console. This message will also be saved to the ratchet.log file located in the server's folder.

Syntax:

void printError( [ string input, ... ] )

dumpAllObjects function

Writes a list of all persistent actors and all their actor components into a ratchet/dump.txt file. This is potentially heavy operation and mostly only useful for advanced debugging.

Syntax:

void dumpAllObjects()