Rataj's Mods

Ratchet / Documentation

Ratchet is a script extender that enables modders and server admins to create server-side mods called plugins.

Players don't have to install these plugins, neither do they have to install Ratchet itself - everything lives on the server.

Plugins

Ratchet plugins are collections of Lua scripts that can be reloaded at any time without restarting the server.

Every plugin starts with a main.lua file which is processed as the plugin is loaded.

Plugins directory is determined by config.json (key plugins). As the server starts, it will look for plugins.txt within that directory and load every plugin listed.

Not every plugin has to be loaded with server start. They can be loaded and unloaded at runtime.

Lua Events

Events are one of the core mechanics of Ratchet. They're called when something happens on the server, or when Workshop mods or other Lua plugins call them.

You can create your own events, however there are also some built into Ratchet that enable working with most common mods such as Roleplay Redux.

Syntax

on( string event, function callback )

Subscribes to an event. Callback function will be called every time event is triggered. Arguments will be passed into the function.

Syntax

off( string event, function callback )

Unsubscribes from an event. Callback function has to be a variable reference that was used when subscribing, do not use anonymous functions.

Syntax

once( string event, function callback )

Subscribes to an event but unsubscribes automatically once the event is triggered. This is useful to catch an event only once.

Syntax

emit( string event [, arguments... ] )

Triggers an event. Any number of arguments can be provided - these will be passed into the callback function.

Roleplay Redux

Ratchet automatically triggers these events based on actions in Roleplay Redux mod.

RPR_useAbility

Callback

function( Character player, int ability, table targets )

Whenever anyone uses any ability in RPR, the RPR_useAbility event is triggered.

Example

function useAbility(player, ability, targets)
    local targetNames = {}
    for _,target in ipairs(targets)do
        table.insert(targetNames, target:GetName())
    end

    print(player:GetName() .. " used ability #" .. ability .. " on " .. table.concat(targetNames, ", ") .. ".")
end
on("RPR_useAbility", useAbility)

RPR_updateRunes

Callback

function( Character character, table runes )

Whenever anyone (un)equips any rune in RPR, the RPR_updateRunes event is triggered.

Lua Timers

Timers are used for delayed execution or even regular execution of a code.

Syntax

int setTimer( function callback, int milliseconds, int repeat )

Triggers a callback once milliseconds pass. Can be repeated any amount of times. Use zero for infinite interval. Returns an integer representing a timer handle that you can use to stop it.

Example

setTimer(function() print("Hello") end, 5000, 5)

Syntax

killTimer( int handle )

Use a timer handle returned from the setTimer function to stop a timer.

Example

local timer = setTimer(doStuff, 1000, 1)
killTimer(timer)

Lua Objects

Objects are special data types, classes or structures that exist in Ratchet on top of basic Lua types.

Character

Character is an object representing a specific online player. It cannot be constructed inside Lua, it has to come from an event.

Syntax

Character {
    int ID
    function GetName()
}

Example

function runesChanged(player, runes)
    local id = player.ID -- we can get database ID of a character like this
    local name = player:GetName() -- and their current display name like this (/act name will be used if applied)
    TotChat.SendLocal(player, name .. " (un)equipped something.", 10)
end
on("RPR_updateRunes", runesChanged)

CharacterSheet

CharacterSheet is returned as a result of RPR.GetSheet function. It cannot be constructed inside Lua.

Syntax

CharacterSheet {
    string name
    table<string> skills
    table<int> skillsAllocated
    table<int> skillsTotal
    table<string> stats
    table<int> statsCurrent
    table<int> statsMax
    table<string> perksActive
    table<string> perksCategories
    table<string> perksAssigned
    table<string> statuses
    table<string> buffs
    table<string> zones
    table<int> runes
};

Example

local sheet = RPR.GetSheet(player)
for _,v in ipairs(perksActive)do -- print all active perks into console
    print(v)
end

Lua Functions

Ratchet implements plenty of functions that can be generally useful to simplify common patterns, or to work with game functions and communicate with most popular mods.

Global

These functions can be used anywhere and do not belong to any particular library.

Syntax

bool fileExists( string relativePath )

Returns true if the specified file path exists or false if it does not.

Example

if(fileExists("config.json"))then
    print("Config exists!")
end

Syntax

any hotLoad( string relativePath )

Loads and executes a Lua code file by relative path and returns module. This can be used for hot-loading parts of the plugin, as it always loads the file instead of using cache like requiring packages.

Example

local module = hotLoad("helloworld.lua")
module:HelloWorld()

Dice

Dice is a simple library for generating random numbers by rolling dice.

Syntax

int Dice.Roll( int count, int sides )

Rolls a sides sided die count number of times.

Example

local result = Dice.Roll(2,6) -- roll a 2d6

Syntax

int Dice.D4()
int Dice.D6()
int Dice.D8()
int Dice.D10()
int Dice.D12()
int Dice.D20()

Shortcut functions for most common dice rolls.

JSON

The ability to save and load JSON files can be essential, that's what this library is for.

Syntax

table JSON.load( string filePath )
table JSON.parse( string json )
bool JSON.save( string filePath, table data )
string JSON.stringify( table data)

TotChat

A library to communicate with the most popular roleplay chat mod made by Tot.

Syntax

TotChat.Alert( string message )

Sends a red bold message into a global chat channel.

Example

TotChat.Alert("Server restart in 10 minutes!")

Syntax

TotChat.Broadcast( string message )

Sends a green message into a global chat channel.

Example

TotChat.Broadcast("Hello world!")

Syntax

TotChat.SendLocal( Character player, string message, float distance )

Sends a yellow message to players near player, visible in radius of distance tiles.

Example

TotChat.SendLocal(player, player:GetName() .. " used an ability!", 10)

Syntax

TotChat.Notify( Character player, string message )

Sends a green message into a player's currently open chat channel, only visible for them.

Example

TotChat.Notify("Hey you!")

Syntax

TotChat.NotifyLocal( Character player, string message )

Sends a grey message into a local chat channel, only visible for specific player.

Example

TotChat.NotifyLocal("Only you can see this.")

Syntax

TotChat.Warn( Character player, string message )

Sends a warning message into a player's currently open chat channel, only visible for them.

Example

TotChat.Warn("Uh oh, it's an error!")

TotSudo

A library to work with roles and charvars in Tot's Sudo mod.

Syntax

bool TotSudo.HasRole( Character player, string role )
table<string> TotSudo.GetRoles( Character player )
bool TotSudo.HasPermission( Character player, string permission )
bool TotSudo.HasCharTag( Character player, string name )
bool TotSudo.AddCharTag( Character player, string name )
bool TotSudo.RemoveCharTag( Character player, string name )
float TotSudo.GetCharFloat( Character player, string name )
bool TotSudo.SetCharFloat( Character player, string name, float value )
bool TotSudo.RemoveCharFloat( Character player, string name )
string TotSudo.GetCharString( Character player, string name )
bool TotSudo.SetCharString( Character player, string name, string value )
bool TotSudo.RemoveCharString( Character player, string name )

RPR

A library to communicate with Roleplay Redux mod.

Syntax

bool RPR.HasPerk( Character player, string name )
bool RPR.AddPerk( Character player, string name )
bool RPR.RemovePerk( Character player, string name )
bool RPR.ModifySkill( Character player, string name, int modifier )
bool RPR.ModifyStat( Character player, string name, int modifier )
bool RPR.SetStat( Character player, string name, int value )
bool RPR.SetStatMax( Character player, string name, int value )
bool RPR.HasRune( Character player, int itemId )
bool RPR.HasBuff( Character player, string category )
bool RPR.RemoveBuff( Character player, string category )
bool RPR.GiveBuff( Character player, string category, int type, string target, int modifier, int duration, int delay )
bool RPR.ResetSheet( Character player )
int, int RPR.GetSkill( Character player, string name )
int, int RPR.GetStat( Character player, string name )
bool RPR.BuffSkill( Character player, string category, string skill, int modifier, int duration )
bool RPR.BuffStat( Character player, string category, string stat, int modifier, int duration )
bool RPR.BuffPerk( Character player, string category, string perk, int duration )
bool RPR.BuffAbility( Character player, string category, string ability, int duration )
bool RPR.BuffStatus( Character player, string category, string status, int duration )
bool RPR.HasItem( Character player, int itemId, int quantity )
void RPR.TakeItem( Character player, int itemId, int quantity )
void RPR.GiveItem( Character player, int itemId, int quantity )
table<string> RPR.GetBuffs( Character player )
CharacterSheet RPR.GetSheet( Character player )
string RPR.ExportSheet( Character player )
bool RPR.ImportSheet( Character player, string sheetData )
bool RPR.HasSpell( Character player, string name )
bool RPR.LearnSpell( Character player, string name )
bool RPR.ForgetSpell( Character player, string name )

Complete Examples

Example

function useAbility(player, ability, targets)
    if(ability == 331)then
        local target = targets[1]
        local targetName = target:GetName()
        local damage = Dice.D6()

        local message = player:GetName() .. " attacked " .. targetName .. "!"
        message = message .. "\nPoor " .. targetName .. " will now lose <span style=\"bold\" color=\"#ffb231\">" .. damage .. "</> HP!"

        TotChat.SendLocal(player, message, 10)
        RPR.ModifyStat(player, "Hit Points", -damage)

        setTimer(function()
            TotChat.SendLocal(player, "<span color=\"#33aaff\">Timer triggered after 2 seconds!</>", 10)
        end, 2000, 1)

        TotChat.Notify(target, "You lost " .. damage .. " HP!")

        if(RPR.HasPerk(player, "Class: Barbarian"))then
            TotChat.NotifyLocal(player, "You are a Barbarian.")
        end

        if(RPR.HasPerk(player, "Class: Fighter"))then
            TotChat.NotifyLocal(player, "You are a Fighter.")
        end
    elseif(ability == 332)then
        local STR = RPR.GetSkill(player, "Strength")
        local DEX = RPR.GetSkill(player, "Dexterity")

        local roll = Dice.D20() + STR
        local damage = 1 + STR
        if(RPR.HasPerk(player, "Class: Monk"))then
            roll = Dice.D20() + math.max(STR, DEX)
            damage = Dice.D4() + math.max(STR, DEX)
        end

        local AC = RPR.GetStat(target, "Armor Class")
        if(roll >= AC)then
            RPR.ModifyStat(target, "Hit Points", -damage)
        end
    end
end
on("RPR_useAbility", useAbility)

This is just a random example to show how you can use various functions in code. In real world scenario it would be a terrible practice to put all abilities into one file.

You can find more examples and plugins created by others on GitHub.

ratajmods

Ratchet / Documentation

Plugins

Lua Events

Roleplay Redux

RPR_useAbility

RPR_updateRunes

Lua Timers

Lua Objects

Character

CharacterSheet

Lua Functions

Global

Dice

JSON

TotChat

TotSudo

RPR

Complete Examples