Skip to content

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