From 31cb63dc9fee56d566e04b85a21b0e669c92817a Mon Sep 17 00:00:00 2001
From: Mm2PL <miau@mail.kotmisia.pl>
Date: Thu, 2 Feb 2023 19:09:57 +0100
Subject: [PATCH] Add a markdown doc explaining the lua environment

---
 docs/wip-plugins.md | 76 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 docs/wip-plugins.md

diff --git a/docs/wip-plugins.md b/docs/wip-plugins.md
new file mode 100644
index 000000000..1e257455f
--- /dev/null
+++ b/docs/wip-plugins.md
@@ -0,0 +1,76 @@
+# Plugins
+
+If Chatterino is compiled with the `CHATTERINO_PLUGINS` CMake option, it can
+load and execute Lua files. Note that while there are attempts at making this
+decently safe, we cannot guarantee safety.
+
+## API
+
+The following parts of the Lua standard library are loaded:
+ - `_G` (all globals)
+ - `table`
+ - `string`
+ - `math`
+ - `utf8`
+
+The official manual for them is available [here](https://www.lua.org/manual/5.4/manual.html#6).
+
+### Chatterino API
+
+All Chatterino functions are exposed in a global table called `c2`. The following functions are available
+
+### `register_command(name, handler)`
+
+Registers a new command called `name` which when executed will call `handler`.
+Returns `true` if everything went ok, `false` if there already exists another
+command with this name.
+
+Example:
+```lua
+function cmdWords(ctx)
+    -- ctx contains:
+    -- words - table of words supplied to the command including the trigger
+    -- channelName - name of the channel the command is being run in
+    c2.system_msg(ctx.channelName, "Words are: " .. table.concat(ctx.words, " "))
+end
+
+c2.register_command("/wordsl", cmdWords)
+```
+
+Limitations/known issues:
+ - commands registered in functions, not in the global scope might not show up in the settings UI,
+   rebuilding the window content caused by reloading another plugin will solve this
+ - spaces in command names aren't handled very well (https://github.com/Chatterino/chatterino2/issues/1517)
+
+### `send_msg(channel, text)`
+
+Sends a message to `channel` with the specified text. Also executes commands.
+
+Example:
+```
+function cmdShout(ctx)
+    table.remove(ctx.words, 1)
+    local output = table.concat(ctx.words, " ")
+    c2.send_msg(ctx.channelName, string.upper(output))
+end
+c2.register_command("/shout", cmdShout)
+```
+
+Limitations/Known issues:
+ - it is possible to trigger your own Lua command with this causing a potentially infinite loop
+
+### `system_msg(channel, text)`
+
+Creates a system message and adds it to the twitch channel specified by
+`channel`. Returns `true` if everything went ok, `false` otherwise. It will
+throw an error if the number of arguments received doesn't match what it
+expects.
+
+Example:
+```lua
+local ok = c2.system_msg("pajlada", "test")
+if (not ok)
+    -- channel not found
+end
+```
+