Developers Writing a plugin
Plugin reference
Everything a plugin definition can declare. Fields marked with a pack version need that pack or newer; see Versions and stability.
The definition
The object your file default-exports.
| Field | Type | Description |
|---|---|---|
id | string, required | Lowercase letters, numbers and dashes, up to 32 characters, starting with a letter or number. Must match the file name. Never change it once published. |
name | string | Shown on the dashboard, up to 50 characters. |
version | string | major.minor.patch, like 1.2.0. Raise it with every release: the dashboard offers updates by comparing it. |
description | string | One or two sentences, shown on the dashboard, up to 300 characters. |
privacy | string | What your plugin reveals about players, shown to the owner beside its switch. Required in the catalog if it reveals anything. |
posts | string | What your plugin posts by itself, like "Playtime milestones." The owner then chooses which channels get those posts. See Posting to Discord. Pack v0.4.0. |
postKinds | array | The different kinds of post, so the owner can switch each off. See Kinds of post. Pack v0.4.2. |
platforms | array | Where it runs: ["server"], ["realm"] or ["server", "realm"]. Leave it out and it's a dedicated server only. Read by the dashboard for private plugins; catalog plugins say it in plugin.json. See Plugins on Realms. |
minPackVersion | string | For private plugins: the oldest pack it works with, like "0.4.2". See Private plugins. |
commands | array | The Discord commands, below. Up to 10. |
Anything else you add to the definition is ignored, apart from its code, which never leaves the world.
A command
| Field | Type | Description |
|---|---|---|
name | string, required | Becomes /name in Discord. Lowercase letters, numbers, dashes and underscores, up to 32 characters. relay is taken. |
description | string | Shown in Discord's command list, up to 100 characters. |
options | array | Up to 10, below. |
public | boolean | true shows the answer to everyone in the channel instead of only the person who asked. Use it for things meant to be shared, like leaderboards, and never for anything private about players. Pack v0.4.0. |
confirm | string or true | Asks "are you sure?" with Yes and Cancel buttons before running. Options fill in by name: "Kick {player}?". true asks "Run /name?". Up to 200 characters. Use it for anything that changes the world. Pack v0.4.0. |
board | { every } or true | The answer can be kept in a channel as a live board, updated every every minutes. Pack v0.4.0. |
run(args, context) | function, required | Called when someone uses the command. May be async. See Answers and context. |
Command names are shared by every plugin in a world: if two plugins declare the same name, only the first plugin loaded gets it. Choose names that say what the command does, and that another plugin is unlikely to want.
Options
type | Discord shows | run() receives |
|---|---|---|
player | Text, suggesting players online now first, then everyone who has played recently | string |
string | Text | string |
integer | A whole number | number |
number | A number | number |
boolean | True / false | boolean |
Each option also takes:
name: the key inargs, with the same rules as a command name.description: shown in Discord, up to 100 characters.required:trueif it must be given. Discord lists required options first, whatever order you declare them in. An optional option that wasn't given is missing fromargs.
Two names are reserved. server is added by BedrockRelay when two Minecraft worlds connected to the same Discord server offer the same command, so people can pick one. live is added to a command with board.
Choices
A string, integer or number option can offer fixed answers with choices: up to 25 of { name, value }, where name is what Discord shows and value is what run() receives. Pack v0.4.0.
{ name: "stat", type: "string", description: "Which statistic", required: true,
choices: [{ name: "Playtime", value: "playtime" }, { name: "Deaths", value: "deaths" }] }Still check the value you're given: an older pack sends it as plain text, and nothing stops a value you didn't expect.
Running a Minecraft world rather than building for one? The help covers everything from setup to troubleshooting.
Read the help