Plugin Compatibility (v2.x)

This page defines how plugin compatibility is preserved across simply-xp v2 releases.

Stability Rules

• Existing plugin required fields (name, initialize) are stable in v2.x.
• Existing XPClient fields used by plugins remain available in v2.x.
• registerPlugins() remains awaitable (Promise<void>) and keeps isolated plugin failure handling.
• Existing event callback names and semantics remain stable in v2.x.
• XpEvents.add(), Database.namespace(), Plugin.destroy() and unregisterPlugins() are stable in v2.x.

Use XpEvents.add() in plugins

XpEvents.on() stores a single callback object — calling it replaces whatever was registered before, including handlers belonging to other plugins or to the bot itself.

XpEvents.add() appends a listener instead and returns a function that removes it again, so plugins and bot code can subscribe side by side. Plugins should always use add(), and call the returned function from their destroy().

const plugin = {
	name: "@simply-xp/example",
	requiredVersions: ["2"],
	initialize() {
		this._off = xp.XpEvents.add({ levelUp: (data, roles) => { /* ... */ } });
	},
	destroy() {
		this._off?.();
	},
};

Additive Changes Allowed

• New optional fields can be added to the Plugin type.
• New optional runtime helpers can be introduced for plugin tooling.
• New optional callbacks and hooks can be added.

Changes Deferred to Next Major

The following require a major release:

• Removing or renaming existing plugin required fields.
• Removing or renaming existing XPClient fields.
• Breaking requiredVersions matching semantics.
• Changing plugin registration from isolated failures to fail-fast behavior.

Versioning Recommendation

For best v2 compatibility, prefer:

• requiredVersions: ["2"] for plugins that support all v2 releases.
• requiredVersions: ["2.0"] for plugins tied to v2.0.x behavior.
• Exact versions only when strictly required.