> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seraph.si/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

> Write your first Seraph plugin in JavaScript, then enable and reload it.

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:

| Platform | Folder                                                              |
| -------- | ------------------------------------------------------------------- |
| Windows  | `%AppData%\Seraph\plugins`                                          |
| macOS    | `~/Seraph/plugins`                                                  |
| Linux    | `$XDG_DATA_HOME/Seraph/plugins`, or `~/.local/share/Seraph/plugins` |

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:

```js theme={null}
declareModule({
    name: "hello",
    displayName: "Hello",
    description: "Says hello when you type !hi.",
    permissions: ["chat"],
});

events.on("chat", (event) => {
    if (event.isSystem) return;

    if (event.message.includes("!hi")) {
        chat.addChatMessage("§ahello world");
    }
});
```

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.

<Steps>
  <Step title="Open the settings menu">
    Run `/seraph config` (alias `/sconfig`) and go to the **Plugins** tab.
  </Step>

  <Step title="Turn the master switch on">
    The master switch controls the plugin system as a whole. With it off, nothing runs.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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:

```
/seraph plugin
```

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](/docs/features/plugin-api/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:

```json theme={null}
{
  "compilerOptions": {
    "checkJs": true,
    "target": "ES2022",
    "lib": ["ES2022"]
  },
  "include": ["*.js", "seraph.d.ts"]
}
```

## 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

<CardGroup cols={2}>
  <Card title="Manifest and permissions" icon="shield" href="/docs/features/plugin-api/manifest">
    Declare your plugin, ask for permissions and expose settings.
  </Card>

  <Card title="Scripts and modules" icon="layer-group" href="/docs/features/plugin-api/modules">
    When to use `.mod.js`, lifecycle hooks and depending on other plugins.
  </Card>

  <Card title="Events" icon="bolt" href="/docs/features/plugin-api/events">
    Every event, what it hands you and when it runs.
  </Card>

  <Card title="API reference" icon="book" href="/docs/features/plugin-api/reference">
    Every global object a plugin can reach.
  </Card>

  <Card title="Examples" icon="code" href="/docs/features/plugin-api/examples">
    Complete plugins you can drop straight into the folder.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/docs/features/plugin-api/troubleshooting">
    Why a plugin is not loading, running or drawing.
  </Card>
</CardGroup>