Examples

Every plugin below is a whole file. Save it into your plugins folder, enable it in /seraph config under Plugins, and it runs. Nothing here needs a build step or an install.

Lobby greeter

Watches the tab list and welcomes people as they arrive, with the greeting and a quiet mode exposed as settings.

declareModule({
    name: "lobby-greeter",
    displayName: "Lobby Greeter",
    version: "1.0.0",
    description: "Greets players as they join your lobby.",
    permissions: ["chat"],
    config: {
        greeting: "welcome",
        onlyInParty: false,
    },
});

events.on("playerJoin", (data) => {
    if (!data.name) return;
    if (config.onlyInParty && !party.isInParty()) return;

    chat.addChatMessage("§8[§bGreeter§8] §7" + config.greeting + " §f" + data.name);
});

config is live, so a change made in game takes effect on the next join without a reload.

Health overlay

Draws a small readout in the corner of the screen, toggled with a key.

declareModule({
    name: "health-hud",
    displayName: "Health HUD",
    permissions: ["render", "player"],
    config: { visible: true },
});

events.on("renderOverlay", () => {
    if (!config.visible) return;

    const line = "§c" + player.getHealth().toFixed(1) + "§7/§c" + player.getMaxHealth().toFixed(1);
    const width = render.getTextWidth(line);
    const x = render.getScreenWidth() - width - 8;
    const y = render.getScreenHeight() - 20;

    render.drawRect(x - 3, y - 3, width + 6, 14, 0x80000000);
    render.drawText(line, x, y, 0xFFFFFF, true);
});

let wasDown = false;

events.on("tick", () => {
    const down = input.isKeyDown("H");
    if (down && !wasDown) {
        config.visible = !config.visible;
        savePluginConfig();
    }
    wasDown = down;
});

renderOverlay runs every frame and only while no screen is open, so the readout hides itself whenever you open your inventory. Keep the body cheap: work out anything expensive in tick and draw the result here.

Webhook relay

Forwards matching chat lines to a Discord webhook, with the URL hidden in the menu.

declareModule({
    name: "webhook-relay",
    displayName: "Webhook Relay",
    permissions: ["network", "chat"],
    config: {
        webhook: "",
        match: "has joined",
    },
    secrets: ["webhook"],
});

events.on("chat", (event) => {
    if (!config.webhook) return;
    if (!event.message.includes(config.match)) return;

    http.fetch(config.webhook, "POST", { content: event.message }, {
        "Content-Type": "application/json",
    })
        .then((response) => {
            if (response.responseCode >= 400) {
                console.warn("Webhook refused: " + response.responseCode);
            }
        })
        .catch((reason) => console.error("Webhook failed: " + reason));
});

Naming webhook in secrets draws it as dots with a reveal button, so it is not read off the screen during a share. See Manifest and permissions.

The network permission is limited to 30 requests a minute per plugin. A chat listener can fire far faster than that in a busy lobby, so match narrowly, or collect lines and send them on a timer rather than one request per message.

A custom anti-cheat check

Flags a player whose view snaps further in a tick than a person could turn. Seraph’s own flag message and report pipeline takes over from there.

declareModule({
    name: "snap-check",
    displayName: "Snap Aim",
    permissions: ["anticheat"],
    config: { threshold: 90 },
});

const lastYaw = {};

anticheat.registerCheck("snap-aim", (data) => {
    const previous = lastYaw[data.uuid];
    lastYaw[data.uuid] = data.rotationYaw;

    if (previous === undefined) return false;

    let delta = Math.abs(data.rotationYaw - previous) % 360;
    if (delta > 180) delta = 360 - delta;

    return delta > config.threshold && data.isSwingInProgress;
}, "Snap Aim");

anticheat.onFlag((uuid, checkId, name) => {
    console.info(uuid + " flagged for " + name + " (" + checkId + ")");
});

The tick function runs once per tick for every observed player, so it is the hottest code a plugin can write. Keep it to arithmetic, and never call the network from inside it.

A stats command

Registers /whois, resolves a name through Seraph’s own API layer and tags the player in the world.

declareModule({
    name: "whois",
    displayName: "Who Is",
    permissions: ["commands", "chat", "network", "render"],
});

events.registerCommand(
    "whois",
    (args) => {
        const target = args[0];
        if (!target) {
            chat.addChatMessage("§cusage: /whois <player>");
            return;
        }

        stats.getPlayer(target)
            .then((profile) => {
                if (!profile) {
                    chat.addChatMessage("§7no such player: §f" + target);
                    return;
                }

                chat.addChatMessage(
                    chat.createBuilder()
                        .text("[whois] ")
                        .color("b")
                        .text(profile.name)
                        .color("f")
                        .hoverText("§7" + profile.uuid)
                        .clickSuggest("/whois " + profile.name),
                );

                nametags.set(profile.name, "§b[?] ");
            })
            .catch((reason) => chat.addChatMessage("§clookup failed: " + reason));
    },
    (args) => events.completePlayers(args),
);

stats.getPlayer shares the mod’s caching and proxy handling, so repeated lookups of the same player in a lobby cost nothing extra. nametags only ever clears decorations your own plugin added.

A module with a schedule

Modules are compiled, stay loaded for the session and get enable and disable hooks, which is what anything with a cron schedule wants. Save this as standup.mod.js.

declareModule({
    name: "standup",
    displayName: "Standup",
    permissions: ["chat", "notify"],
    config: { hourly: true },
});

const listeners = [];
const schedules = [];
let seen = 0;

exports.enable = () => {
    listeners.push(events.on("playerJoin", () => { seen += 1; }));

    if (config.hourly) {
        schedules.push(cron("0 * * * *", () => {
            hud.actionBar("§7" + seen + " players seen this hour");
            seen = 0;
        }));
    }
};

exports.disable = () => {
    for (const id of listeners) events.off(id);
    for (const id of schedules) clearCron(id);
    listeners.length = 0;
    schedules.length = 0;
};

Editing a .mod.js file does not hot reload it. Seraph tells you in chat that a restart is needed instead, and ordinary scripts carry on reloading around it. See Scripts and modules. Put the shared half in its own plugin, name it in dependsOn and require it:

declareModule({ name: "colours" });

exports.tag = (text) => "§8[§b" + text + "§8] §7";

declareModule({ name: "greeter", dependsOn: ["colours"], permissions: ["chat"] });

const colours = require("colours");

chat.addChatMessage(colours.tag("greeter") + "ready");

Anything that is not the name of a loaded plugin is treated as a path relative to the requiring file, so require("./lib/helpers") keeps shared code in a subfolder even though only top level .js files are discovered.

Events

Every event, what it hands you and when it runs.

Troubleshooting

Why a plugin is not loading, running or drawing.

Welcome

Getting Started

Features

Plugin API

Settings

Legal

Lobby greeter

Health overlay

Webhook relay

A custom anti-cheat check

A stats command

A module with a schedule

Next

Events

Troubleshooting

​Lobby greeter

​Health overlay

​Webhook relay

​A custom anti-cheat check

​A stats command

​A module with a schedule

​Sharing code between plugins

​Next

Events

Troubleshooting

Lobby greeter

Health overlay

Webhook relay

A custom anti-cheat check

A stats command

A module with a schedule

Sharing code between plugins

Next