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
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()defer function
Defer execution of a function to one of the next ticks, giving it a very tiny delay (~50ms on default config). This also ensures that no two deferred functions are executed at the same time (they are executed in order as they were requested).
You can use this function to improve performance of heavy operations, by atomizing them into multiple functions that are chain-linked with defer.
Syntax:
void defer( function func [, ... ] )batch function
Execute multiple game thread operations in bulk without blocking Lua thread with round-trips. For example, changing 20 RPR stats at once without batch can take ~100ms, while with batch it might only take ~5ms.
This might be one of the most useful functions when it comes to improving performance of your heavy plugins, as long as you know what you're doing. Keep in mind that this is a double-edged sword and can also cause issues by overloading the game thread tick.
Only use this for writing/executing, never read data or expect a return. All operations within batch function are executed in bulk at the same time. Without batch, every function influencing game thread is called in order and waiting to be fully executed before allowing Lua code to progress further, this is called a round-trip.
Syntax:
void batch( function func )Example:
batch(function()
RPR.ModifyStat(player, "Stat1", 1)
RPR.ModifyStat(player, "Stat2", 1)
RPR.ModifyStat(player, "Stat3", 1)
-- many more calls, all executing at once
end)
-- all stats are set by here, back to synchronous code, safe to read