Skip to main content
Seraph runs plugins written in JavaScript inside the client. A plugin can read chat, register commands, draw on your screen, call an HTTP API, add anti-cheat checks and more. Nothing is granted automatically, every plugin is off until you turn it on and states up front what it intends to use.

​
Where plugins live

Drop .js files straight into the plugins folder next to the rest of Seraph’s data: Only .js files sitting directly in that folder are loaded. Subfolders are not searched, though a plugin can still require a file out of one. The folder is created for you the first time Seraph starts.

​
Your first plugin

Save this as hello.js in the plugins folder:
Every global used here, declareModule, events and chat, is provided by Seraph. There is no import to write and nothing to install.

​
Turn it on

Plugins are disabled by default, and there are two switches.
1

Open the settings menu

Run /seraph config (alias /sconfig) and go to the Plugins tab.
2

Turn the master switch on

The master switch controls the plugin system as a whole. With it off, nothing runs.
3

Enable your plugin

Each plugin has its own toggle. Expand Show what this plugin uses to see exactly which permissions it asked for and what each one allows, before you enable it.
A plugin that is listed but disabled is never run, and any gated call it tries to make is refused and logged rather than silently ignored.

​
Reloading

The plugins folder is watched, so adding, editing or deleting a .js file reloads it a moment later without restarting the client. You can also reload by hand:
Alias: /splugin. Modules, files named <name>.mod.js, are the exception. They load once per session and are not swapped out; if you edit one, Seraph tells you in chat that a restart is needed. See Scripts and modules.

​
Editor support

Every time plugins load, Seraph writes the full type definitions to plugins/seraph.d.ts. Any editor that understands TypeScript will pick that file up from the same folder and give you completion and inline documentation for the whole API, in plain JavaScript, with no build step. If you want the checking to be stricter, add a jsconfig.json beside your plugins:

​
What the engine supports

Plugins run on Rhino at ES6 with Seraph’s own transpiler and polyfills on top, so modern syntax such as classes, let/const, template literals, arrow functions, destructuring, private class fields, optional chaining and async/await all work. A plugin that never yields is stopped rather than allowed to hang the client. Loading a plugin has ten seconds, and anything Seraph dispatches into a plugin, an event, a command or a timer, has two. Passing the budget stops that plugin and leaves the rest of the client running.

​
Next

Manifest and permissions

Declare your plugin, ask for permissions and expose settings.

Scripts and modules

When to use .mod.js, lifecycle hooks and depending on other plugins.

Events

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

API reference

Every global object a plugin can reach.

Examples

Complete plugins you can drop straight into the folder.

Troubleshooting

Why a plugin is not loading, running or drawing.