# Actions

Actions are code snippets that are executed when a log event is imported from the game server. They can be used to process the data and perform various operations on it.

The actions are written in Lua, a lightweight, high-level, multi-paradigm programming language designed primarily for embedded use in applications.

All actions must have a main function that takes a single argument, the data of the log event. To preview the data, you can print it to the console using the print function.

Here is an example of a simple action that prints the log event data to the console:

function main(data)
print(data);
end

To customize the action taken on a new log entry, we are providing a couple functions to the lua environment. The code editor provides you with a searchable auto complete feature, when you use the key combination [CTRL] + [SPACE].

The following functions are available to use in the actions:

Prints the data to the console.

print({name = "John", age = 30}); -- this will be printed as json
print("Hello, World!");

The server namespace contains all server-related functions.

Returns the name of the server.

print(server.name);

Returns the current time on the server.

print(server.current_time);

Bans the player with the given username.

server.ban_player("John");
server.ban_player("John", "Cheating");
server.ban_player("John", "Cheating", "1 day");

The discord namespace contains all Discord-related functions.

Attention: All Discord ID must be represented as strings (encapsulated in quotes), otherwise the programming language will interpret it as a Number and represents ints mathematically instead of the raw number and your action will fail.

Sends a message to the player with the given username.

discord.send_to_player("John", "Hello, John!");
discord.send_to_player("h3eh23ieuh3ei2he3", "Hello, John!"); -- throws an "player not found" exception that stops the action

Sends a message to the channel with the given ID.

discord.send_to_channel("1234567890", "Hello, World!");

Returns the mention string for the player with the given username. This can be used within discord messages to reference the discord account. If no player is found, it will return the username with no formatting.

print(discord.mention("John")); -- returns "<@1234567890>"
print(discord.mention("h3eh23ieuh3ei2he3")); -- returns "h3eh23ieuh3ei"

The player namespace contains all player-related functions.

Changes the balance of the player with the given username.

player.change_balance("John", 100);
player.change_balance("John", 100, "Nice shot!");
player.change_balance("John", -100, "Terrible shot!"); -- negative amount to subtract

Outputs the statistics of the player with the given username.

player.statistics("John");
player.statistics("h3eh23ieuh3ei2he3"); -- throws an "player not found" exception that stops the action

example output data:

{
"pvp_kills": 8,
"last_pvp_kill": "2024-06-19 22:32:23", // might be null
"pvp_deaths": 23,
"last_pvp_death": "2024-06-19 22:49:19", // might be null
"deaths": 58,
"kill_streak": 0,
"death_streak": 0,
"longest_kill": 44.78
}

Outputs the faction id (as a string) of the player with the given username or null when either no player was found or the player is not in a faction.

player.get_faction("John"); -- outputs the faction id of the player, e.g. "1234567890"
player.get_faction("h3eh23ieuh3ei2he3"); -- throws an "player not found" exception that stops the action

Resolves the player’s display name. If no name is set for the user or no matching user is found, it returns the input username.

player.get_name("johnnyboy420"); -- outputs the display name of the player: "John Doe"
player.get_faction("nouserwiththatusername"); -- user is not found, so it returns the input: "nouserwiththatusername"

Checks if the player with the given username has the specified Discord role. Accepts both the role name and the role ID.

player.has_discord_role("John", "6553535632356535564"); -- works with role IDs
player.has_discord_role("John", "Admin"); -- works with role names as well

The faction namespace contains all faction related action functions.

Changes the balance of the faction with the given id.

faction.change_balance("123", 100);
faction.change_balance("123", 100, "Good guys!");
faction.change_balance("123", -100, "Rule penalty!"); -- negative amount to subtract