Skip to content
SwizzinIRCSwizzinIRC Docs

Introduction to SwizzScript

SwizzScript is the SwizzinIRC scripting environment, powered by Luau. Scripts are ordinary Luau programs that talk to SwizzinIRC through one global table, swizzin. The Luau runtime is built into the application, so nothing needs to be installed to write or run scripts.

Quick start

Section titled “Quick start”
  1. Open Scripts on the toolbar, or type /scripts.
  2. Choose Examples to add the sample scripts, or New… to start from a template. Every script starts Off.
  3. Edit the script and choose Save, then turn it On. If it asks for permissions, the panel lists them in plain language. Approve and allow runs it.
  4. Watch the Console tab for swizzin.log output and errors.
--! name: Hello
--! description: Replies to !hello in channels
--! api: 1
--! permissions: send
swizzin.on("message", function(e)
    if e.text == "!hello" then
        swizzin.send(e.target, "Hello, " .. e.nick .. "!")
    end
end)

Where scripts live

Section titled “Where scripts live”

In the Scripts folder of your data folder (the same place as profiles and themes):

File Meaning
name.luau A native SwizzScript
name.mrc A mIRC-style script, translated to Luau when loaded
scripts.json Which scripts are on, and which permissions you approved for each
data\name.json A script’s saved values

No passwords, tokens or other secrets are written here, and scripts cannot read the places they are kept.

How scripts fit in

Section titled “How scripts fit in”
  • Commands. A script can add a /command. Precedence is protected command, then built-in command, then your own alias, then script command. /!name always bypasses aliases and scripts. Scripts cannot replace a built-in.
  • Events. Scripts react to messages, joins, parts, quits, nick changes, kicks, topics, modes, connect, disconnect and reconnecting.
  • Networks. Every event and command carries the network it came from, and a script’s actions go to that network unless it names another explicitly. With no network context an action is refused rather than guessed.
  • Toolbar. A toolbar button can be mapped to script:<command>, which runs /<command> through the normal command path.
  • Safety. Every script starts off, runs in a sandbox with time and memory limits, and needs your approval for anything beyond reading events. See Permissions.

Limits at a glance

Section titled “Limits at a glance”
What Limit
Memory per script 16 MB
One callback (event, command, timer) 250 ms
Loading a script’s top level 1 s
Messages a script may send 10 per second (burst of 20)
Pending events per script 256 (further events are dropped and counted)
Handlers / commands / timers 64 / 32 / 32
Consecutive failing callbacks before a script is stopped 10
Script size 256 KB

Each script runs on its own thread, so a slow script cannot block the window, the IRC connections or other scripts.

Licences

Section titled “Licences”

SwizzScript is powered by Luau, © Roblox Corporation, MIT licence. The embedding uses the mlua crate (MIT) and luau0-src (MIT). Their licence texts are included in the third-party notices of the packaged application.

Next steps

Section titled “Next steps”