Compatibilité des plugins (v2.x)

Cette page définit comment la compatibilité des plugins est préservée entre les versions v2 de simply-xp.

Règles de stabilité

• Les champs obligatoires existants des plugins (name, initialize) sont stables en v2.x.
• Les champs XPClient existants utilisés par les plugins restent disponibles en v2.x.
• registerPlugins() reste awaitable (Promise<void>) et conserve la gestion isolée des échecs de plugins.
• Les noms et la sémantique des callbacks d'événements existants restent stables en v2.x.
• XpEvents.add(), Database.namespace(), Plugin.destroy() et unregisterPlugins() sont stables en v2.x.

Utilisez XpEvents.add() dans les plugins

XpEvents.on() ne conserve qu'un seul objet de callbacks : l'appeler remplace ce qui avait été enregistré auparavant, y compris les gestionnaires appartenant à d'autres plugins ou au bot lui-même.

XpEvents.add() ajoute un écouteur à la place et retourne une fonction qui le retire, afin que les plugins et le code du bot puissent s'abonner côte à côte. Les plugins doivent toujours utiliser add(), et appeler la fonction retournée depuis leur destroy().

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

Changements additifs autorisés

• De nouveaux champs optionnels peuvent être ajoutés au type Plugin.
• De nouveaux utilitaires d'exécution optionnels peuvent être introduits pour l'outillage des plugins.
• De nouveaux callbacks et hooks optionnels peuvent être ajoutés.

Changements reportés à la prochaine version majeure

Les éléments suivants nécessitent une version majeure :

• Supprimer ou renommer des champs obligatoires existants des plugins.
• Supprimer ou renommer des champs XPClient existants.
• Casser la sémantique de correspondance de requiredVersions.
• Passer l'enregistrement des plugins d'échecs isolés à un comportement fail-fast.

Recommandation de versionnage

Pour une meilleure compatibilité v2, préférez :

• requiredVersions: ["2"] pour les plugins qui supportent toutes les versions v2.
• requiredVersions: ["2.0"] pour les plugins liés au comportement de v2.0.x.
• Des versions exactes uniquement lorsque c'est strictement nécessaire.