Revision of lua-docs.md

rootspring revisó este gist 1722932772. Ir a la revisión

1 file changed, 11 insertions

lua-docs.md

			@@ -20,6 +20,17 @@ pub const MAX_TEMPLATES_EXECUTION_TIME: std::time::Duration = std::time::Duratio
20	20
21	21		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).
22	22
	23	+	## Some key notes
	24	+
	25	+	- Each guild is assigned a dedicated Lua VM. This VM is used to execute Lua code that is used in the templates.
	26	+	- 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.
	27	+	- Execution of all scripts is timed out when the last executed script takes longer than ``MAX_TEMPLATES_EXECUTION_TIME`` (currently 5 seconds).
	28	+	- A lua VM will exist for a total of ``MAX_TEMPLATE_LIFETIME`` (currently 5 minutes) after the last access before being destroyed. This is to reduce memory+CPU usage.
	29	+	- 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 Anti-Raid uses luau sandboxing meaning that `_G` is readonly.
	30	+	- The entrypoint of any Lua template is ``function(args)``.
	31	+	- The standard ``require`` statement can be used to import Anti-Raid modules. Note that the modules are read-only and cannot be monkey-patched etc.
	32	+	- Because Lua is a single-threaded language, only one template can be executed at a time
	33	+
23	34		## Interop
24	35
25	36		Many features of Lua don't work so well when calling functions within the Anti-Raid SDK. For example, both arrays and maps are expressed as tables in Lua. However, Anti-Raid, 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.

rootspring revisó este gist 1722932230. Ir a la revisión

1 file changed, 52 insertions

lua-docs.md(archivo creado)

		@@ -0,0 +1,52 @@
1	+	# Lua Templating
2	+
3	+	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.
4	+
5	+	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](https://luau-lang.org/) for more information on the language itself. Unlike PUC Lua (the reference implementation), Luau is both faster and offers robust sandboxing capabilities allowing Anti-Raid to run scripts in as safe an environment as possible.
6	+
7	+	## Getting Started
8	+
9	+	Note that the remainder of these docs will cover Anti-Raids Lua SDKs. To learn more about Lua itself, please checkout Lua's official tutorial for Lua 5.0 [here](https://www.lua.org/pil/1.html). Other resources for Lua exist (Lua is very popular after all), including [Roblox's tutorial](https://devforum.roblox.com/t/lua-scripting-starter-guide/394618#print-5) (ignore the Studio bits), [TutorialPoint](https://www.tutorialspoint.com/lua/lua_quick_guide.htm) and [Codecademy](https://www.codecademy.com/learn/learn-lua).
10	+
11	+	## Limitations
12	+
13	+	Anti-Raid applies the following 3 global limits to all Lua templates. Note that we may provide increased limits as a Premium feature in the future:
14	+
15	+	```rust
16	+	pub const MAX_TEMPLATE_MEMORY_USAGE: usize = 1024 * 1024 * 3; // 3MB maximum memory
17	+	pub const MAX_TEMPLATE_LIFETIME: std::time::Duration = std::time::Duration::from_secs(60 * 5); // 5 minutes maximum lifetime
18	+	pub const MAX_TEMPLATES_EXECUTION_TIME: std::time::Duration = std::time::Duration::from_secs(5); // 5 seconds maximum execution time
19	+	```
20	+
21	+	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).
22	+
23	+	## Interop
24	+
25	+	Many features of Lua don't work so well when calling functions within the Anti-Raid SDK. For example, both arrays and maps are expressed as tables in Lua. However, Anti-Raid, 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.
26	+
27	+	### Arrays
28	+
29	+	To pass arrays to modules within the Anti-Raid 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.
30	+
31	+	```lua
32	+	local interop = require '@antiraid/interop'
33	+	setmetatable({a = 5}, interop.array_metatable)
34	+	```
35	+
36	+	### Null
37	+
38	+	While the Lua ``nil`` does work in many cases (and even when calling the SDK), its not the best choice. When querying Anti-Raid 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
39	+
40	+	```lua
41	+	local interop = require '@antiraid/interop'
42	+	local null = interop.null -- This is the null value
43	+	```
44	+
45	+	### Memory Usage
46	+
47	+	While not strictly useful for interop, it is often desirable to know the memory usage of a Lua template as Anti-Raid will kill your template if it exceeds the memory limit. For this, you can use the `@antiraid/interop#memusage` function.
48	+
49	+	```lua
50	+	local interop = require '@antiraid/interop'
51	+	print(interop.memusage())
52	+	```

Siguiente Anterior