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

# Your first plugin

> Build a minimal plugin with one event and one command

This guide walks through building a minimal plugin with one event listener and one command.

## 1. Create the plugin directory

Create a folder under the proxy's plugins directory:

```text theme={null}
~/.duelsplus/plugins/hello-duels/
```

(On Windows: `C:\Users\<You>\.duelsplus\plugins\hello-duels\`)

## 2. Add package.json

Create `package.json` with a `duelsplus` field so the proxy recognizes the plugin:

```json package.json theme={null}
{
  "name": "hello-duels",
  "version": "1.0.0",
  "main": "index.js",
  "duelsplus": {
    "id": "hello-duels",
    "name": "Hello Duels"
  }
}
```

The `id` should be unique and usually matches your package name. The proxy loads the file specified by `main` (here, `index.js`).

## 3. Install the API and write the plugin

Install the API for types (and the base class, which the proxy will provide at runtime):

<CodeGroup>
  ```bash npm theme={null}
  cd ~/.duelsplus/plugins/hello-duels
  npm i @duelsplus/plugin-api
  ```

  ```bash pnpm theme={null}
  cd ~/.duelsplus/plugins/hello-duels
  pnpm add @duelsplus/plugin-api
  ```

  ```bash bun theme={null}
  cd ~/.duelsplus/plugins/hello-duels
  bun add @duelsplus/plugin-api
  ```
</CodeGroup>

```ts index.ts theme={null}
import { Plugin, PluginContext } from '@duelsplus/plugin-api';

export default class HelloDuels extends Plugin {
  id = 'hello-duels';
  name = 'Hello Duels';
  description = 'Says hello when a game starts and adds a /hello command';

  onLoad(ctx: PluginContext) {
    // React to game start
    ctx.events.on('game:start', (payload) => {
      ctx.client.sendChat(`§aGame started! §7(${payload.mode} on ${payload.map ?? 'unknown map'})`);
    });

    // Register a command: /hello
    ctx.commands.register({
      name: 'hello',
      description: 'Say hello from the plugin',
      execute: (args, sender) => {
        ctx.client.sendChat(`§bHello, ${sender.username}!`);
      },
    });
  }
}
```

## 4. Build and run

Compile TypeScript to JavaScript (e.g. with `tsc`). Your `tsconfig.json` can target `"outDir": "."` so `index.js` is written into the same folder. Then:

1. Ensure the Duels+ Proxy is running.
2. Restart the proxy (or start it) so it rescans `~/.duelsplus/plugins/` and loads your plugin.

You should see a log line like: `Loaded plugin: Hello Duels v1.0.0 (hello-duels)`.

## 5. Try it

* Join a Duels game through the proxy. When the game starts, you should see the green "Game started!" message in chat.
* Type `/hello` in chat. The plugin responds with "Hello, \<your username>!".

## Next steps

* [Events](/plugin-api/guides/events) - All available events and payloads
* [Commands](/plugin-api/guides/commands) - Registering and using commands
* [Storage](/plugin-api/guides/storage) - Persisting settings and data
* [Client and chat](/plugin-api/guides/client-and-chat) - Sending messages, titles, and sounds