Manifest & permissions

declareModule

Call declareModule once, at the top of the file, before anything else. It is what gives your plugin a name, puts it in the Plugins tab and tells Seraph what it intends to use.

declareModule({
    name: "party-greeter",
    displayName: "Party Greeter",
    version: "1.0.0",
    author: "you",
    description: "Greets people as they join your party.",
    permissions: ["chat", "commands"],
    dependsOn: [],
    config: {
        greeting: "welcome!",
        onlyInParty: true,
    },
});

Field	Required	What it does
`name`	Yes	The identifier. Used by `dependsOn`, by `require` and as the storage key.
`displayName`	No	The name shown in the Plugins tab. Falls back to `name`.
`version`	No	Shown alongside the plugin.
`author`	No	Shown alongside the plugin.
`description`	No	Shown in the Plugins tab, so write it for the person deciding to enable it.
`permissions`	No	What the plugin is allowed to do. Anything not listed here is refused.
`dependsOn`	No	Other plugins that must load first.
`config`	No	Default settings, editable in game and readable through `config`.
`secrets`	No	Config keys the menu hides behind a reveal button.

Without declareModule the file still runs, but it is named after itself and holds no permissions, so every gated call it makes is refused.

Permissions

A gated call only goes through when all three of these are true: the master switch is on, that plugin is enabled, and the plugin declared the matching permission. Ask for the least you need, users see the whole list before they enable anything.

Permission	Allows	Reached through
`chat`	Read and send chat messages	`chat`
`commands`	Register and run chat commands	`events.registerCommand`
`player`	Read and control the local player	`player`, `movement`
`world`	Read and interact with the world and entities	`world`
`network`	Make network requests	`http`, `stats`
`storage`	Read and write its own persistent storage	`storage`
`render`	Draw overlays on your screen	`render`, `nametags`
`anticheat`	Register custom checks and receive flag events	`anticheat`
`tray`	Show system tray icons and toast notifications	`tray`
`notify`	Show titles and action bar text, and play sounds	`hud`

console, scheduler, input, text, party and the event listeners themselves are ungated. A refused call is written to the log once per plugin and permission, naming what was attempted, so a plugin that quietly does nothing is usually a missing entry in permissions.

Network rate limit

The network permission is additionally rate limited to 30 requests per minute per plugin, counted across http.fetch and stats, so a plugin cannot spam an endpoint even once you have granted it access.

Config

Anything you put in config becomes a default setting. Users edit it from the plugin’s own menu in the Plugins tab, and your plugin reads it through the global config object:

declareModule({
    name: "party-greeter",
    permissions: ["chat"],
    config: {
        greeting: "welcome!",
        onlyInParty: true,
    },
});

events.on("chat", (event) => {
    if (config.onlyInParty && !party.isInParty()) return;
    chat.addChatMessage(config.greeting);
});

The object is live: read it when you need a value rather than copying it into a variable at load time, and a change made in game takes effect straight away. Writing to config is allowed, and savePluginConfig() writes the changes to disk so they survive a restart:

config.greeting = "hello again";
savePluginConfig();

Config is stored per plugin under plugins/config.

Hiding a value

Name a config key in secrets and the menu draws it as dots with an eye button beside it, the same as the API key field, so a webhook or a token is not read off the screen during a share:

declareModule({
    name: "webhook-relay",
    permissions: ["network"],
    config: {
        webhook: "",
        delay: 20,
    },
    secrets: ["webhook"],
});

Only the drawing changes. The value is stored in plugins/config and read through config like any other setting, so treat this as a guard against an accident rather than a way of keeping a secret from whoever is at the keyboard. A hidden field is still editable while it is masked, and a key that is not part of config is ignored.

Dependencies

List other plugins in dependsOn and Seraph loads them first, so their exports are ready by the time your file runs:

declareModule({ name: "stats-hud", dependsOn: ["stats-core"] });

const core = require("stats-core");

If something you depend on is missing or disabled your plugin is skipped entirely, with the reason logged, rather than failing half way through. Plugins that depend on each other in a circle are all still loaded, but the order between them is arbitrary and the circle is reported.

Welcome

Getting Started

Features

Plugin API

Settings

Legal

Manifest & permissions

declareModule

Permissions

Network rate limit

Config

Hiding a value

Dependencies

​declareModule

​Permissions

​Network rate limit

​Config

​Hiding a value

​Dependencies

declareModule

Permissions

Network rate limit

Config

Hiding a value

Dependencies