Appearance
Plugins
A plugin extends an engine with systems, traits and world observers. Every add-on package ships as one, and so does 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 shortcutengine.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.