Plugins

A plugin is a bot feature any server owner can add from the dashboard, like a welcome message or a poll command. Anyone with a Weeble account can publish one. The full plugin.toml format is in the plugin.toml reference.

Create a plugin

In VS Code, open an empty folder and run Weeble: Create Plugin. It writes two files.

plugin.toml:

name = "Welcome"
slug = "welcome"
version = "0.1.0"
summary = "Says hello when someone joins."

[[settings]]
key = "channel"
type = "channel"
label = "Channel"
required = true

src/main.ts:

weeble.definePlugin((plugin) => {
  plugin.on(discord.events.GUILD_MEMBER_ADD, async (member) => {
    const channel = await discord.fetchGuildTextChannel(String(plugin.settings.channel));
    await channel?.send(`Welcome ${member.toMention()}!`);
  });
});

The slug is the plugin’s permanent ID and cannot change after the first publish.

Write the code

Put everything inside weeble.definePlugin(). It runs once when the bot starts and must be synchronous. The full discord and weeble SDK is available.

plugin.settings

The owner's values, keyed by setting key. Read-only. Settings the owner left empty and that have no default are missing.

plugin.on(event, handler)

Listens to a Discord event, like discord.on(), but an error in the handler is logged with the plugin's name and does not reach other handlers.

plugin.kv(name?)

A KV namespace private to this plugin on this server. Pass a name to keep separate kinds of data apart.

plugin.slug

The plugin's ID from plugin.toml.

plugin.version

The installed version, such as 1.2.0.

Use plugin.on() and plugin.kv() rather than discord.on() and your own KV namespace. That way errors are isolated to your plugin, and its storage doesn’t collide with the server’s script.

If the plugin registers commands, list their names in plugin.toml so two plugins on one server can’t claim the same one:

commands = ["poll"]

Packages

Add approved packages with Weeble: Add Package, like in a script. They are bundled into the plugin when you test and publish, so servers don’t install anything.

Test

Run Weeble: Test Plugin and pick a test server. This replaces the script on that server, so use one you made for testing.

Publish

Run Weeble: Publish Plugin. Each publish needs a higher version and a short changelog. Servers stay on their version until the owner presses Update.

Manage

The author sees a Manage section on the plugin page:

• Change avatar sets the plugin’s picture.

• Hide removes it from the list. Servers that have it keep running it.

• Delete removes it for good. This only works once no server has it.

Limits

Up to 10 plugins per account, 20 plugins per server, 20 settings, 25 commands, and a 1 MiB bundle.