Introduction

NOTE: Just adding AntiRaid (or any discord bot) to your server will not do much unless you configure it first!

AntiRaid is a discord bot that takes a very unique approach to protecting servers. Instead of providing a single-size-fits-all solution, AntiRaid makes use of "structured templating" and a (work in progress/coming soon) template shop to allow servers to protect themselves in a way that is tailored to them.

Our Philosophy

While many bots like Wick provide a managed anti-raid/anti-nuke solution, these systems often provide suboptimal user experience to many servers as they may not cater to specific needs of the server. Wick, for example, is often criticized for limiting the abilities of server moderators in a way that makes moderation harder. While Wick is useful in many servers and does work quite well in the anti-raid/anti-nuke field from our experience, it may not be the best solution for all servers.

Templating, on the other hand, allows servers to tailor their needs directly without needing to go through the pain of making a custom discord bot, hosting it and then navigating the complexities of the discord API manually while reinventing concepts like stings/punishments/permissions/captchas all over again.

Permissions

Imagine. Imagine a discord bot that you could completely control. You could decide who can use any specific command, who can change the bot's settings, and who can even use the bot at all.

Thats AntiRaid...

AntiRaid has a customizable permission system that uses both Discord permissions for simplicity and kittycat permissions for more specific requirements. While AntiRaid does provide some base-line defaults, Lua scripting can be used to augment these defaults and extend Antiraid with arbitrarily complex permission systems, among other things. See the templating guide for more information on how to use Lua templates. Then, just code away!

TIP

For best results, consider limiting the server permissions of other users to the minimum required. Then, use AntiRaid for actual moderation. That's better than giving everyone admin permissions and then trying to restrict them with AntiRaid.

Templating

At AntiRaid, we prioritize flexibility and customization for our users. To this end, our bot supports advanced templating to allow for extensive personalization of embeds and messages. While many bots utilize proprietary languages or templating engines, we have chosen to leverage Lua—a renowned scripting language widely used in game development and other applications. This decision ensures that our users benefit from a powerful, well-documented, and versatile language, enhancing the capability and ease of customizing their AntiRaid experience.

Note: this documentation is still a work-in-progress and things are still being documented better and better by the day!

Lua Templating

At AntiRaid, we prioritize flexibility and customization for our users. To this end, our bot supports advanced templating to allow for extensive personalization of embeds and messages. While many bots utilize proprietary languages or templating engines, we have chosen to leverage Lua—a renowned scripting language widely used in game development and other applications. This decision ensures that our users benefit from a powerful, well-documented, and versatile language, enhancing the capability and ease of customizing their AntiRaid experience.

Specifically, Anti Raid uses a variant of Lua called Luau. If you've ever used Roblox before, this is the same variant of Lua used there too (which is why Luau is also known as Roblox Lua in many places). You can check out the Luau docs for more information on the language itself. Unlike PUC Lua (the reference implementation), Luau is both faster and offers robust sandboxing capabilities allowing AntiRaid to run scripts in as safe an environment as possible.

Getting Started

Note that the remainder of these docs will cover AntiRaids Lua SDKs. To learn more about Lua itself, please checkout Lua's official tutorial for Lua 5.0 here. Other resources for Lua exist (Lua is very popular after all), including Roblox's tutorial (ignore the Studio bits), TutorialPoint and Codecademy.

Limitations

AntiRaid applies the following 3 global limits to all Lua templates. Note that we may provide increased limits as a Premium feature in the future:

#![allow(unused)]
fn main() {
pub const MAX_TEMPLATE_MEMORY_USAGE: usize = 1024 * 1024 * 3; // 3MB maximum memory
pub const MAX_TEMPLATES_EXECUTION_TIME: std::time::Duration = std::time::Duration::from_secs(30); // 30 seconds maximum execution time
}

The above limits are in place to prevent abuse and ensure that the bot remains responsive. If you require increased limits, please contact support (once again, this may change in the future).

Some key notes

  • Each guild is assigned a dedicated Lua VM. This VM is used to execute Lua code that is used in the templates.
  • The total memory usage that a guild can use is limited to MAX_TEMPLATE_MEMORY_USAGE (currently 3MB). This is to prevent a single guild from using too much memory.
  • Execution of all scripts is timed out when the last executed script takes longer than MAX_TEMPLATES_EXECUTION_TIME (currently 30 seconds).
  • A guilds Lua VM will persist until marked as broken (either by explicitly requesting it or by exceeding memory limits)
  • The __stack table can be used to share data across templates safely while the VM is running. without affecting other templates. This is useful for sharing data between templates such as Audit Logs. Note that AntiRaid uses luau sandboxing meaning that _G is readonly.
  • The standard require statement can be used to import AntiRaid modules. Note that the modules are read-only and cannot be monkey-patched etc.
  • Because Lua is a single-threaded language, only one template can be executed at a time

In general, all AntiRaid templates should start with the following:

local args, token = ...
-- Do something
return output

Interop

Many features of Lua don't work so well when calling functions within the AntiRaid SDK. For example, both arrays and maps are expressed as tables in Lua. However, AntiRaid, being written in Rust, doesn't know this and hance needs some help to convert certain types for FFI. This is where the @antiraid/interop module comes in.

Arrays

To pass arrays to modules within the AntiRaid SDK, you need to set the metatable to @antiraid/interop#array_metatable. This will allow the SDK to convert the array to a Rust Vec internally.

local interop = require '@antiraid/interop'
setmetatable({a = 5}, interop.array_metatable)

Null

While the Lua nil does work in many cases (and even when calling the SDK), its not the best choice. When querying AntiRaid SDK, the SDK will use the @antiraid/interop#null value to represent a null value. Your Lua templates can also use this value if desired

local interop = require '@antiraid/interop'
local null = interop.null -- This is the null value

Memory Usage

While not strictly useful for interop, it is often desirable to know the memory usage of a Lua template as AntiRaid will kill your template if it exceeds the memory limit. For this, you can use the @antiraid/interop#memusage function.

local interop = require '@antiraid/interop'
print(interop.memusage())

User Error vs Runtime Error

As Lua does not have a built-in way to distinguish between user errors and runtime errors, AntiRaid provides a way to do so. Simply return a table with the key __error set, and the value set to the error message to create a user error. You can use the standard error function for runtime errors. E.g.

-- User Error
return { __error = "You have reached the maximum number of tries in this 5 minute window." }

-- Runtime Error
error("Could not parse user ID for some reason")

Events

All Lua templates are invoked via events. As such, the first argument to the template is an Event. Event is a userdata. The below will explain the most important fields exposed by Event. Note that all fields, unless stated otherwise, are read-only:

  • ``

Template Context

All Lua templates are passed both the Event (denoted by args) and a TemplateContext userdata (denoted by token). Note that like Event, TemplateContext is a userdata (not a table). As such, they cannot be manually constructed in templates themselves.

"Executors" and other sensistive APIs use the TemplateContext to read template_data including the pragma (note that template_data is also exposed to templates as a read-only field). This is what allows AntiRaids capability system to correctly sandbox templates based on what capabilities they have been given.

Examples of executors include the @antiraid/actions ActionExecutor, which allows you to perform actions such as banning/kicking/timing out users and other Discord actions and @antiraid/kv KvExecutor which allow for persistent storage via a key-value interface.

TemplateContext is guaranteed to be valid while accessible in the VM . This means that templates can choose to share their capabilities with other templates using the __stack.

It is also guaranteed that the created executor is complete and does not rely on the token itself whatsoever after creation. This means that a template executor can be used after the template has finished executing (e.g. in a coroutine).

Example

local args, token = ...
print(token)

No/unknown command specified!

start: [start the template worker itself] templatedocs: [generate template docs]

Example Templates

To help you get started with templating, we have provided a few examples below along with explanations of what/how they work

Example 1: Simple Audit Logging

Explanation

1. Pragma

The first line of the template is a pragma. This is a special statement beginning with @pragma or -- @pragma that tells AntiRaid what language the template is written in, what options to use, and how tools such as CI, websites and other automation should handle your template. The rest of the pragma is a JSON object that contains the options. Note that if you do not provide a pragma, a default one will be used, however this will not allow you to provide capabilities to your template such as sending a message on Discord etc.

In this case, we want to tell AntiRaid that we are coding a template in Lua and that we want to allow the capability to send messages to Discord. This is done by adding the allowed_caps key to the pragma and specifying the capabilities we want to allow as seen below:

-- @pragma {"lang":"lua","allowed_caps":["discord:create_message"]}

2. Creating a message

Next, we need to extract the arguments and token from the context. The arguments are passed to the template when it is executed and contain all the data we need to work with. The token is used to authenticate the template and gain access to the templates context in privileged AntiRaid API's. All of this is provided using variable arguments.

local args, token = ...

There are 3 things we want to import for this template to work. The first is the Discord module, which allows us to send messages to Discord. The second is the Interop module, which provides some functions allowing for seamless interoperability between your template and AntiRaid. The third is the promise module which lets us run asynchronous tasks like sending a message to Discord.

local discord = require "@antiraid/discord"
local interop = require "@antiraid/interop"
local promise = require "@antiraid/promise"

Next, we create the embed using the events title field as the embed title and an empty description.

-- Make the embed
local embed = {
    title = args.title, 
    description = "", -- Start with empty description
    fields = {}, -- Start with empty fields
}

NOTE: You can use the API Reference to see what functions are available in the AntiRaid SDK

A quick side track here. When coding in Lua, tables can be iterated over using the builtin pairs function like below:

for key, value in pairs(my_table) do
    -- Do something with key and value
end

3. Creating the audit log message fields etc.

The next step is to add fields to the embed by actually handling the Discord events we want properly. This is pretty annoying to do without some typing and helper methods though...

Fortunately, AntiRaid has a solution: templating-types! This does require extra effort in the form of bundling with templating-template as a template. See our guide for more information on how to do this.

Once you're done making the message as you'd like. It's time to send the message!

4. Sending the message

Finally, we can send the message using the Discord module. To do this, we need to create a message object and set the embeds property to an array containing our embed. This is also where interop comes in handy, as we need to set the metatable of the embeds array to the interop array metatable so AntiRaid knows that embeds is an array. Next, we use the Discord plugin to make a new Discord action executor which then lets us send the message to the specified channel.

setmetatable(message.embeds, interop.array_metatable)

table.insert(message.embeds, embed)

-- Send message using action executor
local discord_executor = discord.new(token);
discord_executor:create_message({
    channel_id = "CHANNEL_ID_HERE",
    message = message
})

5. (Optional) Key-value

With @antiraid/kv, you can save the channel id to a key-value store in the website and then fetch it like so:

local kv = require "@antiraid/kv"

local kvExecutor = kv.new(token)
local channelId = kvExecutor:get("auditlog_channel")

Luau Ecosystem Integration Notes

At AntiRaid, we believe that bot developers should be able to access the best tools available to them. To this end, we have integrated some popular Luau libraries into our templating environment to provide a more powerful and flexible experience while taking into account security and stability of the bot. Below, we outline the libraries that are currently available for use in your Lua templates:

Libraries

Roblox data types etc can be found in @lune/roblox. For example, you can make a Vector3 object like this:

local Vector3 = require('@lune/roblox').Vector3

AntiRaid is not affiliated with any of the libraries mentioned above. We do not claim ownership of these libraries or their trademarks whatsoever, nor do we provide any guarantees or warranties regarding their functionality. AntiRaid absolves all liability for any damages or losses incurred through the use of these libraries, both to the libraries owner and to AntiRaid itself.

Events

AntiRaid makes use of events for all communication between modules. Modules can either recieve events (e.g. from Discord) or generate their own events (such as PunishmentCreate/PunishmentExpire). This is what makes Anti-Raid so flexible and powerful, especially in templating.

Discord Events

Discord Events are special. AntiRaid uses Serenity for handling Discord events. As such, please see Serenity's Documentation for what fields are available in each event. It's much better documentation than what we can come up with.

Some notes:

  • AntiRaid does not modify the events in any way, so you can expect the same fields as what Serenity provides. Note, however, that only the fields are available to templates, not the methods provided by Serenity.
  • All event data will be wrapped in a outer table containing the enum variant name. For example, message data can be found in event.data["Message"] and not just event.data. This is for performance reasons.

Other Events

TODO: Just ask on our support server for now

Captcha

Introduction

WARNING: Captcha's are being heavily churned/rewritten into a new Lua plugin

A CAPTCHA is a security measure that can be used to try and filter out the more basic and spammy bots from accessing your server. It presents a challenge that users must complete to prove they are human. This can help protect your server from unwanted automated access and ensure that real users can interact with your community. Note that CAPTCHA's are NOT foolproof and that more sophistiated bots may still bypass them.

Of course, with the current landscape with AI everywhere, just serving a single CAPTCHA type (or config) does not really work. Furthermore, AntiRaid recognizes that different servers have different needs. Therefore, we provide a flexible CAPTCHA system, fully integrated with our Lua Templating system that allows you to completely customize the CAPTCHA experience for your users. This occurs through filters.

Examples

Sample CAPTCHA

local interop = require "@antiraid/interop"
local img_captcha = require "@antiraid/img_captcha"

local captcha_config = {}

-- Basic options
captcha_config.char_count = 7
captcha_config.filters = {}
setmetatable(captcha_config.filters, interop.array_metatable) -- Filters is an array
captcha_config.viewbox_size = { 280, 160 }
setmetatable(captcha_config.viewbox_size, interop.array_metatable) -- Viewbox size is a tuple

-- Add noise filter
local noise_filter = {
    filter = "Noise",
    prob = 0.05
}

table.insert(captcha_config.filters, noise_filter)

-- Add wave filter
local wave_filter = {
    filter = "Wave",
    f = 4.0, -- Frequency
    amp = 20.0, -- Amplitude
    d = "horizontal" -- Direction
}

table.insert(captcha_config.filters, wave_filter)

-- Add grid filter
local grid_filter = {
    filter = "Grid",
    x_gap = 10,
    y_gap = 30
}

table.insert(captcha_config.filters, grid_filter)

-- Add line filter
local line_filter = {
    filter = "Line",
    p1 = setmetatable({ 0.0, 0.0 }, interop.array_metatable),
    p2 = setmetatable({ 30.0, 100.0 }, interop.array_metatable),
    thickness = 7.0,
    color = setmetatable({ 0, 0, 0 }, interop.array_metatable)
}

table.insert(captcha_config.filters, line_filter)

-- Add color invert filter
local color_invert_filter = {
    filter = "ColorInvert"
}

table.insert(captcha_config.filters, color_invert_filter)

-- Add random line filter
local random_line_filter = {
    filter = "RandomLine"
}

table.insert(captcha_config.filters, random_line_filter)

local captcha = img_captcha.new(captcha_config)

return captcha

CAPTCHA with increasing char count with maximum of 5 tries per user

=local interop = require "@antiraid/interop"
local img_captcha = require "@antiraid/img_captcha"

local captcha_config = {}

-- Check __stack.users
if __stack._captcha_user_tries == nil then
    __stack._captcha_user_tries = {} -- Initialize users table
end

-- Check __stack._captcha_user_tries[args.user.id]
if __stack._captcha_user_tries[args.user.id] == nil then
    __stack._captcha_user_tries[args.user.id] = 0 -- Initialize user's try count
end

-- Check if user has reached maximum tries
if __stack._captcha_user_tries[args.user.id] >= 5 then
    error("You have reached the maximum number of tries in this 5 minute window.")
end

-- Basic options
captcha_config.char_count = math.min(7 + __stack._captcha_user_tries[args.user.id], 10) -- Increment the number of characters

captcha_config.filters = {}
setmetatable(captcha_config.filters, interop.array_metatable) -- Filters is an array
captcha_config.viewbox_size = { 280, 160 }
setmetatable(captcha_config.viewbox_size, interop.array_metatable) -- Viewbox size is a tuple

-- Increment the maximum number of tries
__stack._captcha_user_tries[args.user.id] += 1

captcha = img_captcha.new(captcha_config)
return captcha

Lockdowns

Lockdowns are a way to allow restricting (or 'locking down') specific channels or roles within a server when under an attack or other such crises.

Migrating from other bots

If you are coming from Wick or another anti-nuke bot like Wick, please note that AntiRaid's lockdown functionality only applies to locking down channels and roles. This means that the following Wick features are not present in AntiRaid lockdowns and are instead part of other more appropriate modules as listed below:

  • Join Auto Kick (present in Inspector Auto Response Member Join)
  • Join Auto Ban (present in Inspector Auto Response Member Join)
  • Role Lockdown (WIP, not yet implemented)
  • All / Server Wide (Most likely will not be implemented)

Note that blind lockdowns are not yet implemented in Anti-Raid.

For the sake of comparisons, here is how each lockdown mode compares to Wick's lockdown modes:

  • Quick Server Lockdown (qsl) -> Wick's Channels (sc) lockdown (general performance+requirements for use should be the same as Wick's lockdown feature)
  • Traditional Server Lockdown (tsl) -> No equivalent in Wick
  • Single-Channel Lockdown (scl) -> Wick's Channel (c) lockdown (note that locking down multiple specific channels at once is not yet implemented in AntiRaid)

Usage Notes

If you want to know more details on each type of lockdown, how they are applied and how multiple lockdown conflicts are resolved, please refer to the dev docs for lockdown

Member Roles

When you first setup lockdown for the first time, you will be prompted for a set of member roles like below:

picture of member roles screen in settings page

These roles are what AntiRaid will actually lock-down which is why they are also known as 'critical roles'.

Quick Server Lockdowns

For servers that can meet its restrictions, a quick server lockdown is the fastest way to lockdown your server in a raid. It is recommended to use this lockdown mode if possible. When using this mode, it is important to note one critical requirement:

  • All critical roles must have View Channel and Send Messages. All other roles must not have View Channel and Send Messages.

What this looks like is something like the following:

Picture of a normal role Figure 1 shows a normal role without View Channel of Send Messages permissions

Picture of a critical role Figure 2 shows a critical role with View Channel and Send Messages permissions

The above two figures are how you want to configure your critical/member and normal roles. Basically, turn off View Channel and Send Messages for all your normal roles and turn it on for your critical/member roles you set up earlier in the settings for lockdown.

To make a quick server lockdown, you can use the qsl type. For example, to lock down a server, you can use the following slash command:

/lockdown lock type:qsl reason:There is a raid going on

Traditional Server Lockdown

Traditional Server Lockdown is a more traditional lockdown method. It is more flexible than Quick Server Lockdown as it has no required prior setup. However, it is much slower and should be avoided if possible.

WARNING: Super large servers may have outages when using a traditional server lockdown that a quick server lockdown may not lead to.

To make a traditional server lockdown, you can use the tsl type. For example, to lock down a server, you can use the following slash command:

/lockdown lock type:tsl reason:There is a raid going on

Single-Channel Lockdown

In some cases, only a single channel needs to be locked down. In such a case, a single-channel lockdown is needed.

To make a single-channel lockdown, you can use the scl type. For example, to lock down a server, you can use the following slash command:

/lockdown lock type:scl/<channel_id> reason:There is a raid going on

Where <channel_id> is the ID of the channel to lockdown.

Backups

What's backed up

Guild structure (roles/channels/name/icon/other settings), some messages (Discord has limits here) and attachments (within reasonable limits).

What's not backed up?

Members and bots. Note that for members, we have something coming up soon that may allow you to 'backup/restore' (with consent + regularly re-providing consent) members.

Note that new discord features may also not be backed up/restored immediately on release.

More details

See the dev guide to learn more about the format

Go Jobserver

The Go Jobserver handles server backups, message prunes and other long running tasks on a server

Backups

Note that this document describes the technical details of the backup system

Format

A backup is an https://github.com/infinitybotlist/iblfile with the standard AutoEncryptedFile format and has the following fields:

  • backup_opts - JSON containing a types.BackupCreateOpts object
  • core/guild - The core guild data (discordgo.Guild)
  • assets/{asset_name} - The guild icon data ([]byte)
  • messages/{channel_id} - The messages in a channel along with basic attachment metadata ([]types.BackupMessage).
  • dbg/* - Debug information. This may vary across backups and MUST NOT be used in restoring a backup.
  • attachments/{attachment_id} - The attachments data itself

Definitions

  • Critical Roles: the roles which are given to members and should hence be locked down. In essence, one can define a set of critical roles (hence the name) which are either the critical roles and defaults to the @everyone role if not set.

Lockdown Types

Quick Server Lockdown

Specificity

  • 0 (Lowest specificity)

Rationale

Quickly lockdown a server as fast as possible

Syntax

  • qsl

Description

Quick Lockdown allows for quickly locking down a server given the following permission overwrite setup:

  • All critical roles must have View Channel and Send Messages. All other roles must not have View Channel and Send Messages

Internally, qsl modifies only the critical roles to the locked down set of permissions. This requires much fewer API calls and is hence much faster than traditional lockdowns.

Traditional Server Lockdown

Specificity

  • 1 (TSL > QSL as it updates all channels in a server)

Rationale

In many cases, the requirements for qsl are not feasible for servers to meet. In such a case, a traditional lockdown is needed.

Syntax

  • tsl

Description

Traditional Lockdown is a more traditional lockdown method. It is more flexible than qsl as it has no required prior setup. However, it is much slower and should be avoided if possible.

Internally, tsl works by iterating over all channels and setting the permission overwrites for all critical roles to the locked down set. This is a slow process and can take a long time for large servers. In addition, super large servers may have outages when using a tsl that a qsl may not lead to.

Single-Channel Lockdown

Specificity

  • 2 (SCL > TSL as it updates a single channel)

Rationale

In some cases, only a single channel needs to be locked down. In such a case, a single-channel lockdown is needed.

Syntax

  • scl/<channel_id>

Where <channel_id> is the ID of the channel to lockdown

Description

Single-Channel Lockdown is a lockdown method that locks down a single channel.

Internally, scl/<channel_id> works by setting the permission overwrites for all critical roles to the locked down set for the specified channel. This is a fast process and is recommended for locking down a single channel.

Specificity

When multiple lockdowns are made on the same item (which will now be called a handle from now on), there needs to be a way to know what lockdown owns/has the handle. In AntiRaid, this is controlled through specificity based on the rules:

  • Rule 0: When a handle is locked, the priority is added without replacing older priorities. When a handle is unlocked, the priority is removed leading to its previous value.
  • Rule 1: A handle is controlled unlocked by a lockdown A if the lockdown (say, lockdown B) corresponding to the largest specificity that has locked the handle is less than the specificity of lockdown A. Otherwise, it is considered locked and cannot be modified by lockdown A.
  • Rule 2: The underlying permissions or permission overwrites of a role/channel are defined as the saved permissions/permission overwrites of the role/channel of the oldest possible lockdown which has saved said data.

As an example, consider a case where a tsl is first applied and then an scl/<channel_id>. As per Rule 1, the tsl has a lower specificity than the scl/<channel_id> and so the scl/<channel_id> will also lock the channel handle. When the tsl is then removed, the channel is still locked by scl/<channel_id> which has a greater specificity. Hence, by Rule 1, the scl/<channel_id> locked channel will remain locked even after the tsl is removed as expected.

Next, consider what happens when the scl/<channel_id> is removed. As tsl stores the original channel permission overwrites of all channels and was created before the scl/<channel_id>, Rule 2 applies. Hence, the underlying permissions of the channel is considered to come from the tsl's stored data and NOT the scl/<channel_id> which was set during the lockdown. This means that when the scl/<channel_id> is removed, the channel will revert to the permissions it had before the tsl was applied which was the original channels permissions.

As such, using Rules 1 and 2, the following holds true:

tsl + scl/<channel_id> - tsl - scl/<channel_id> = 0

Silverpelt

Silverpelt provides a standard library for all Anti-Raid modules.

To create a new Anti-Raid bot making use of Anti-Raid modules, simply implement the trait modules::Module. These modules must then be added to a SilverpeltCache which is then inserted into silverpelt::Data.

Most things in silverpelt are abstracted out through traits or dispatched via events. This allows silverpelt to be used as an abstract interface allowing for Anti-Raid to quickly evolve and change/adapt to different targets.

Note: AntiRaid uses a event-driven architecture. This means that modules+the main bot process make events that are dispatched to modules. The event system is currently passive (meaning there is no continously running event loop), however this is subject to change in the future.

Interfaces

Sting

Silverpelt provides concrete structures, utilities and special events for handling stings.

Punishments

Silverpelt provides concrete structures, utilities and special events for handling punishments.

Some extra misc points

  • A command is the base unit for access control. This means that all operations with differing access controls must have commands associated with them.

  • This means that all operations (list backup, create/restore backup, delete backup) MUST have associated commands

  • Sometimes, an operation (such as a web-only operation) may not have a module/command associated with it. In such cases, a 'virtual' module should be used. Virtual modules are modules with commands that are not registered via Discord's API. They are used to group commands together for access control purposes and to ensure that each operation is tied to a command

Anti-Raid Templating System

Supported Languages

  • Lua (luau / Roblox Lua) - Tier 1

Lua is the recommended language for templating

WIP/Potential Languages

  • JavaScript (see lang_javascript_quickjs and lang_javascript_v8 for the current load experiments + integration experiments), potential but unlikely unless someone finds a solution
  • WebAssembly (potential, not yet decided)

Language Requirements

  1. All languages must export the following modules/helpers to the extent required as per the templating documentation. (TODO: Improve this spec)
  • Messages
  • Permissions
  • Captcha
  • Actions
  • Key Value API
  1. All languages must provide a way to sandbox the execution of the code. This is a security requirement. In particular, timeouts and heap/stack/memory limits are required.
  2. Callers must use the abstracted out function calls from lib.rs

My language vent

For reference on my discord vents: https://discord.com/channels/763812938875535361/1040734156327501905/1267195190100361440

Why is lua the only sane language for embedding V8 has big ffi problems with rust. If you try spawning too many isolates, you have a 100% chance of aborting your process and this issue can only be resolved by performing unsafe void* pointer casts Quickjs is a bit too slow and poorly documented Rhai is good but it’s a custom language and it’s sandboxing abilities need unsafe code to fully work (and said unsafe code involves pointer arithmetic that is not thread safe) and heap memory limits require you to manually calculate the heap usage Tera has virtually no safety features and will gladly execute an infinite recursion For starlark/skylark, go to the point on rhai but hopefully without the unsafe bits I can understand now why the game modding industry uses lua, it’s basically the only sane language for handling user input Lua is legit the only sane scripting language on this entire list

[rhai is not only slower than lua, its sandboxing (i said it above here too in a vent i think) requires actual pointer arithmetic that isnt thread safe, its also a custom lang no one knows while lua is well known in the game community. Luau is used in Roblox games so it caters to Discords target market as well]

Template Tokens

All lua templates include a special template token in addition to the template arguments. Modules requiring more privileged levels of access (or otherwise require the template state) should require this token and use it to access the required template state.

Text difference utilities

diff.rs: Taken from https://docs.rs/text-diff/latest/src/text_diff with some modernizing. All credits go to the author.

Other utilities are taken too. To be documented