Make a Castwell plugin
Download the example plugin (.zip)
A plugin adds a feature to Castwell Toolkit: a chat command, an overlay, a connection to another program, a tab of its own. Add one on the Castwell plugins tab (a .py or .zip file, or a GitHub link), or drop it into Castwell's plugins folder. Castwell Toolkit loads plugins when it starts, after its own parts.
A ready-to-copy example (a chat counter with a !mycount command and its own tab) is in examples/chat_counter, and as a zip on the website.
The shortest plugin
INFO = {"id": "hello", "name": "Hello", "version": "1.0", "author": "you",
"description": "Says hello back when someone types !hello."}
def setup(app):
def on_chat(d):
if d["text"].strip().lower() == "!hello":
app.module(d["platform"]).say(f"Hello @{d['user']}!")
app.bus.on("chat", on_chat)
Save it as hello.py, add it on the Castwell plugins tab, press Restart.
What a plugin file can have
| Name | What it is |
|---|---|
INFO | {"id", "name", "order", "version", "author", "description"} - id must be unique; the rest shows on the plugins tab. order (default 50) is when it starts, after lower numbers |
setup(app) | runs once at start - keep app to use later |
status() | optional: a light on the Home tab - return {"ok": bool, "label": "...", "detail": "..."} |
ROUTES | optional: web addresses - {("GET", "/api/myplugin"): fn}, fn(app, query, body) returns (200, {...}) |
TAB | optional: a tab of its own - {"label": "My plugin", "section": "Plugins", "page": "index.html"} |
| a folder named like the file | optional: myplugin/web/ holds the tab's pages, served at /p/<id>/<file> |
A plugin's pages are ordinary HTML and JavaScript and talk to its ROUTES with fetch("/api/myplugin").
What app gives you
app.log(text)- a line in the log (Help & log tab)app.bus.on(kind, fn)/app.bus.emit(kind, data)- hear and send events (below)app.module("twitch")- another part:twitch,youtube,kick,tiktok(each hassay(text)to post in that chat),obs(request(name, data)sends any obs-websocket request),alerts,commands,musicand the restapp.store.read_json(path, default)/app.store.write_json(path, data)andapp.store.DATA- keep your settings inapp.store.DATA / "myplugin.json"app.store.secret(name)/app.store.save_secret(name, value)- keys and passwords, kept encryptedapp.version- Castwell Toolkit's version
Events on the bus
| Kind | Data |
|---|---|
chat | user, login, text, platform (twitch / youtube / kick / tiktok), color, mod, sub, vip, broadcaster, msg_id, test |
alert | kind (follow, sub, resub, gift_sub, mass_gift, bits, raid, redeem, hype_begin, hype_level, hype_end, charity, superchat, member, tiktok_gift, merch), user, amount, detail (and message when there is one), platform, test |
stream | online (true when you go live, false when you stop) |
raid_in | user, login, viewers |
Your own plugin can emit its own kinds for other plugins to hear.
Sharing a plugin
- One file: share the
.py. - With pages or pictures: zip the
.pytogether with its folder (myplugin.pyandmyplugin/web/...). - On GitHub: put them in a repo; people paste its link on the Castwell plugins tab, which takes your newest release's
.zip(or the repo itself when there's no release).
Plugins are switched off by renaming them to start with _ (the tab does this for you), and go into Castwell's backup.