---
url: /pawn/docs/guide/plugins.md
description: Writing and installing plugins that add systems, traits and observers.
---

# Plugins

A plugin extends an engine with systems, traits and world observers. Every
add-on package ships as one, and so does [`Input`](./input).

```ts
engine.use(new Input()).use(new Tween());
engine.hasPlugin(Tween.NAME); // true
engine.getPlugin<Tween>(Tween.NAME); // the installed plugin
engine.plugin(Input); // the installed Input, or a new default one
engine.plugin(Input); // the same, as a shortcut
```

`engine.use(plugin)` calls `plugin.install(engine)` once. Using the same
plugin object again does nothing; installing a different plugin with the
same name throws, and so does installing on a disposed engine. `install`
may return a cleanup function, which `engine.dispose()` runs in reverse
install order.

Plugins are classes that take one config object, keep their name in
`static NAME` (`"@pawnjs/<package>/<name>"`) and, when they add a system, its
default order in `static ORDER`. `engine.plugin(Class)` returns the
installed plugin of a class or installs one with the default config:

```ts
const pointer = engine.plugin(Pointer);
engine.plugin(Sound).tone({ frequency: 660 });
```

To configure one, `engine.use(new Pointer({ dragThreshold: 12 }))` before
anything asks for it. `engine.getPlugin(name)` only looks, by `NAME`. For
a plugin an engine may run several of, such as `CameraRig` and
`ChaseCamera`, `engine.plugin(Class)` returns the first one installed.

## Traits that bring their plugin

A trait that only works with a plugin says which one with `usesPlugin`.
An engine then installs that plugin, with its default config, when an
entity of its world first gets the trait, so nobody has to remember it.
`Label` brings `Labels`, `Model` brings `Assets`, the tween traits bring
`Tween` and `Smooth` brings `Smoothing`; behaviors bring theirs the same
way. A plugin installed before that, with a config of your own, is the
one used.

## Writing a plugin

```ts
import { type Engine, type PawnPlugin, Position } from "@pawnjs/core";
import { trait } from "koota";

export const Float = trait({ height: 0.5, speed: 2 });

export class Floating implements PawnPlugin {
  static readonly NAME = "my-game/floating";
  static readonly ORDER = 0;
  readonly name = Floating.NAME;

  install(engine: Engine) {
    return engine.addSystem(
      ({ world, elapsed }) => {
        world.query(Float, Position).updateEach(([float, p]) => {
          p.y = Math.sin(elapsed * float.speed) * float.height;
        });
      },
      { order: Floating.ORDER },
    );
  }
}
```

`engine.addSystem()` returns a function that removes the system, which makes
a fine cleanup. A plugin an engine may run several of sets
`static readonly MULTIPLE = true` and gives each instance its own `name`
(`CameraRig` uses `` `${CameraRig.NAME}#${n}` ``). `usesPlugin(Float, Floating)` after the class makes
`entity.add(Float)` install `Floating`. To react to entities gaining or losing a trait, subscribe
with koota's `engine.world.onAdd(trait, callback)` and
`engine.world.onRemove(trait, callback)`, and unsubscribe in the cleanup.

Add-on packages peer-depend on `@pawnjs/core` and `koota`, and on `three`
when they import it; the core never imports an add-on.
