mirror-chatterino2/docs/wip-plugins.md

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.

Plugin structure

Chatterino searches for plugins in the Plugins directory in the app data, right next to Settings and Logs.

Each plugin should have its own directory.

Chatterino dir/
└── plugin_name/
    ├── index.lua
    └── info.json

index.lua will be the file loaded when the plugin is enabled. You may load other files using loadfile Lua global function.

info.json contains metadata about the plugin, like its name, description, authors, homepage link, tags, version, license name. The version field must be semver 2.0 compliant. The general idea of info.json will not change however the exact contents probably will, for example with permission system ideas. Example file:

{
  "name": "Test plugin",
  "description": "This plugin is for testing stuff.",
  "authors": "Mm2PL",
  "homepage": "https://github.com/Chatterino/Chatterino2",
  "tags": ["test"],
  "version": "0.0.0",
  "license": "MIT"
}

An example plugin is available at https://github.com/Mm2PL/Chatterino-test-plugin

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.

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:

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:

local ok = c2.system_msg("pajlada", "test")
if (not ok)
    -- channel not found
end