API publique des addons

L’API du mod tourne dans Minecraft, sous Java 21. Elle permet d’ajouter une machine, un type de ressource ou une intégration. L’API HTTP du site ne sert que la documentation et les releases : elle ne consulte pas le réseau d’un joueur et ne lance aucun craft.

Un addon dépend de Nebula et compile contre dev.nebulastorage.api. Isolez les adaptateurs de mods optionnels pour ne pas charger leurs classes quand le mod manque. L’API 1.0.0 est indépendante du numéro de release alpha. Ces exemples d’addon ciblent Nebula Storage alpha.7 et ses nouveaux packages. Les fichiers publiés jusqu’à alpha.6 utilisent encore dev.nexusstorage. Recompilez les addons à la mise à jour ; les identifiants Minecraft et les mondes restent inchangés.

Créez une implémentation publique de NebulaExtension et inscrivez son nom de classe complet dans META-INF/services/dev.nebulastorage.api.NebulaExtension. Ce fichier doit être une ressource du JAR, sans suffixe .txt.

L’exemple déclare le procédé example:pressing. Cette déclaration n’ajoute à elle seule ni bloc ni recette. Ajoutez un adaptateur reconnaissant votre véritable item, puis une source donnant les entrées et sorties exactes de ce procédé. L’enregistrement ne doit pas accéder à un monde.

package example.nexus

import dev.nebulastorage.api.NebulaExtension
import dev.nebulastorage.api.NebulaRegistrar
import dev.nebulastorage.api.production.ProductionCapabilityId

class ExampleExtension : NebulaExtension {
    override fun register(registrar: NebulaRegistrar) {
        registrar.capability(ProductionCapabilityId("example:pressing"))
    }
}

NebulaRecipeSource.discover reçoit les procédés disponibles. Renvoyez les offres applicables avec identifiants stables, sorties garanties, durée et coût énergétique d’origine. Incluez les sous-produits ; ne remplacez pas une probabilité par son rendement moyen.

Incrémentez revision quand la source change, y compris après rechargement des datapacks. Une variation d’inventaire change la disponibilité, pas tout le catalogue. Découverte et résolution des templates doivent être pures, bornées et sans transfert de ressources.

Utilisez NebulaPlatformExtension pour un bloc Minecraft qui doit exécuter sa logique native. Résolvez seulement une machine chargée, identifiez son propriétaire persistant et exposez toutes ses entrées et sorties de traitement. Énergie, pression et autres exigences restent gérées par le mod d’origine.

Avant livraison, testez insertion partielle, sortie bloquée, annulation après consommation, déchargement, sauvegarde/reprise et remplacement du bloc. Chaque ressource garde un seul propriétaire. Une insertion simulée réussie ne garantit pas l’insertion réelle suivante.

Obtenez les requêtes pendant serverStarted et utilisez forPlayer avec l’UUID de l’acteur authentifié. Chaque lecture vérifie encore les permissions. N’acceptez jamais un UUID arbitraire envoyé par le client comme preuve d’identité.

Un instantané est une observation, pas une réservation. Revalidez lors d’une action autorisée et libérez les références à serverStopped. Un observateur sans acteur ne reçoit que des informations historiques publiques.